From c44c813aec755c25fc505247a8a544c712f5b3ae Mon Sep 17 00:00:00 2001 From: poli0981 <127664709+poli0981@users.noreply.github.com> Date: Sun, 26 Jul 2026 13:03:05 +0700 Subject: [PATCH] docs: reconcile the spec with Phase 4 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The docs are binding, so where Phase 4 diverged from them the divergence has to be written down rather than left as an undocumented difference between spec and code. Three owner decisions recorded: six settings rows (markdownStyle was persisted but only editable as a transient #export control), all five donate handles in About, and a three-way segmented theme control rather than a cycling glyph. One genuine conflict resolved: docs/06 §3 called the Legal Gate "a full overlay" while docs/14 §2 -- echoed in docs/03 §4 and the decision log -- requires #settings and #about to stay reachable while it is up. Those cannot both be satisfied literally, so docs/06 now says the gate fills the content region and explains why. Also: docs/02's directory tree had been stale since Phase 2 (it predated lib/edit, lib/export and lib/import entirely); docs/03 §4 documented a five-field Settings shape that had six fields in code; docs/07 §3 now names where the Intl helpers live and, more usefully, the three sites that deliberately do NOT use them; docs/11 §5 gains the QA items Phase 4 created. The decision log gains fifteen rows, including the cross-tab sync limitation, recorded as a known limitation rather than left to be rediscovered in review. Co-Authored-By: Claude Opus 5 --- CLAUDE.md | 4 ++- docs/00_PROJECT_OVERVIEW.md | 10 +++--- docs/02_ARCHITECTURE.md | 14 ++++++++ docs/03_DATA_FLOW.md | 17 ++++++++- docs/06_UI.md | 69 +++++++++++++++++++++++++++++++++---- docs/07_I18N.md | 20 +++++++++++ docs/11_TESTING.md | 11 +++++- docs/15_ROADMAP.md | 31 ++++++++++++++--- 8 files changed, 158 insertions(+), 18 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index a3df23c..d37e3f8 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -87,7 +87,9 @@ performance budgets docs/11 §6, CI workflows per docs/12 §2 (explicit `permissions:` blocks on every caller — and note the ops repo has **no** `browser-extension-*` family), CHANGELOG, README (badges, screenshots ⚠, install, privacy summary, donate), full manual QA (docs/11 §5), `wxt zip` -clean-install test. +clean-install test. Also: point About's "Changelog" link at `CHANGELOG.md` +once it exists (`src/lib/links.ts` currently targets `/releases`), and split +`EditTab.svelte`, which is past the 500-line hard limit. **Exit:** ready for the docs/13 §1 runbook (human performs store submission). ## Working style diff --git a/docs/00_PROJECT_OVERVIEW.md b/docs/00_PROJECT_OVERVIEW.md index 38aa8b5..f846964 100644 --- a/docs/00_PROJECT_OVERVIEW.md +++ b/docs/00_PROJECT_OVERVIEW.md @@ -5,11 +5,11 @@ > **Owner:** poli0981 (GitHub) / SkullMute > **Repo:** `poli0981/bookmarkmagic` ✔ > **License:** GPL-3.0-or-later -> **Status:** In development — **Phases 0–3 complete** (scaffold, core library, -> browser layer + import, export + edit). Verified working on real Chrome and -> Brave, 2026-07-25. Next: Phase 4 (i18n wiring, theming, Settings, About, -> Legal Gate). Sequencing lives in `/CLAUDE.md`. -> **Doc suite version:** 1.2 (2026-07-25 — reality pass) +> **Status:** In development — **Phases 0–4 complete** (scaffold, core library, +> browser layer + import, export + edit, and i18n/theming/Settings/About/Legal +> Gate). Verified working on real Chrome and Brave, 2026-07-25. Next: Phase 5 +> (hardening + release prep). Sequencing lives in `/CLAUDE.md`. +> **Doc suite version:** 1.3 (2026-07-26 — Phase 4 reconciliation) --- diff --git a/docs/02_ARCHITECTURE.md b/docs/02_ARCHITECTURE.md index a176cb3..c309b1e 100644 --- a/docs/02_ARCHITECTURE.md +++ b/docs/02_ARCHITECTURE.md @@ -77,20 +77,34 @@ bookmarkmagic/ │ │ │ ├── dedupe.ts │ │ │ ├── diff.ts │ │ │ ├── detect-format.ts +│ │ │ ├── plan.ts # buildImportPlan → segments (§4) +│ │ │ ├── search.ts # #edit filter + ancestor expansion +│ │ │ ├── select.ts # tri-state export selection → subtree +│ │ │ ├── csv-path.ts # folder-path encoding shared by CSV both ways │ │ │ └── limits.ts # MAX_FILE_BYTES, MAX_NODES, MAX_DEPTH, LEGAL_VERSION │ │ ├── browser/ │ │ │ ├── bookmarks.ts # getTree/create/move/update/remove wrappers │ │ │ ├── write-queue.ts # sequential tree writer + progress + abort │ │ │ ├── storage.ts # typed settings/legal accessors │ │ │ ├── download.ts # Blob → +│ │ │ ├── app-info.ts # manifest version — the ONE source (06 §3.5) +│ │ │ ├── errors.ts # BmBrowserError / BmBackupError / BmAborted (§7) │ │ │ └── open-manager.ts # getContexts() focus-or-create +│ │ ├── import/run-import.ts # the import pipeline (03 §1) +│ │ ├── export/run-export.ts # the export pipeline (03 §2) +│ │ ├── edit/ # patch-tree, move-target, tree-keyboard (03 §3) +│ │ ├── settings/options.ts # the six Settings choice tables (06 §3.4) +│ │ ├── links.ts # repo / legal / donate URLs (14 §4, §5) │ │ ├── stores/ # Svelte 5 runes state (.svelte.ts) │ │ │ ├── settings.svelte.ts # locale, theme, defaults (persisted) │ │ │ ├── legal.svelte.ts # acceptedVersion +│ │ │ ├── toast.svelte.ts # transient status queue + its timers (06 §4) │ │ │ ├── route.svelte.ts # location.hash + hashchange wrapper (§5) │ │ │ └── import-session.svelte.ts │ │ ├── i18n/ # runtime UI i18n (see 07_I18N.md) │ │ │ ├── index.svelte.ts +│ │ │ ├── format.ts # pure Intl number/date helpers (07 §3) +│ │ │ ├── resolve-locale.ts │ │ │ └── locales/{en,vi,ja}.ts │ │ └── components/ # shared Svelte components (see 06_UI.md) │ └── styles/ diff --git a/docs/03_DATA_FLOW.md b/docs/03_DATA_FLOW.md index 5333022..62cfdff 100644 --- a/docs/03_DATA_FLOW.md +++ b/docs/03_DATA_FLOW.md @@ -129,7 +129,18 @@ import) appear without reload. Listeners attach on tab enter, detach on leave. - Settings writes go through `stores/settings.svelte.ts` → `chrome.storage.local` (debounced 200 ms). Shape: - `{ locale, theme, defaultExportFormat, defaultMergeMode, csvDelimiter }`. + `{ locale, theme, defaultExportFormat, defaultMergeMode, csvDelimiter, + markdownStyle }` — **six** fields, one `` each (`06 §3.4`). +- `updateSettings(patch)` returns a `SaveOutcome` that resolves when the + debounced write has **settled**, and never rejects. UI feedback follows the + write; it never precedes it, or a failed save still says "Saved". +- The store object is **mutated in place**, never replaced, so a component that + reads `getSettings()` into a local cannot silently go stale. Writes pass a + plain snapshot — `chrome.storage.local.set` structured-clones its argument and + a Svelte `$state` proxy is not cloneable. +- `flushSettings()` runs on `visibilitychange` → hidden (not `beforeunload`, + which is cancellable). It shrinks the window in which an unwritten change is + lost from 200 ms to roughly nothing — not to zero. - Legal gate: on Manager mount read `legal.acceptedVersion`; if `< LEGAL_VERSION` render `` overlay blocking **#import / #export / #edit** — **#settings and #about stay reachable**, so a VI/JA user can switch @@ -137,6 +148,10 @@ import) appear without reload. Listeners attach on tab enter, detach on leave. switcher of its own. Accept → write version + timestamp → unlock. This three-route set is normative; `14 §2` states the same list. Details: `14_LEGAL_GATE.md`. +- The gate's accept path writes **first**, awaits, and only then reflects + acceptance in state. Dismissing optimistically would leave the user accepted + in the UI and unaccepted on disk, so the gate would silently reappear next + launch. A storage read failure fails **closed** (gate shown). ## 5. State machines (informal) diff --git a/docs/06_UI.md b/docs/06_UI.md index 65d42b2..3d05cf2 100644 --- a/docs/06_UI.md +++ b/docs/06_UI.md @@ -58,7 +58,24 @@ there). No heavy work in the popup, ever. ``` Max content width 960px, centered. Settings/About open as tabs too (footer -links = same routes). `` renders as a full overlay when required. +links = same routes, and both are disabled while an import is writing — see +`03 §5`). The version in the footer is read from the manifest at runtime +(`browser/app-info.ts`), never hardcoded. + +The header's theme control is a **three-way segmented control** +(System · Light · Dark), not the single `◐` glyph the sketch above draws. +Rationale: one code path shared with the `#settings` row, and the current +choice is visible rather than inferred — a cycling button conflates "what am I" +with "what will I become", which fights §5. + +`` fills the **content region**, not the viewport. `docs/14 §2` +(echoed in `03 §4` and the `15` decision log) requires `#settings` and `#about` +to stay reachable while the gate is up, and a literal `inset: 0` scrim would +bury the footer links that get you there. So: a full-bleed panel inside +`
`, with the header and footer still live and the three blocked tabs +disabled via `TabBar`'s `blocked` prop. A side effect worth keeping — the +Import/Export/Edit tabs never mount before acceptance, so nothing touches +`chrome.bookmarks` until the user has agreed to the terms. ### 3.1 #import @@ -106,19 +123,44 @@ Empty state: friendly illustration + "Import some bookmarks →". ### 3.4 #settings -Single column of ``s: Language (EN/VI/JA select) · Theme +Single column of **six** ``s: Language · Theme (System/Light/Dark segmented) · Default export format · Default import mode · -CSV delimiter. Auto-save + saved toast. Footer: "Reset to defaults". +CSV delimiter · Markdown layout. + +- The Language select offers **four** options, not three: `Settings.locale` is + `'auto' | 'en' | 'vi' | 'ja'` and `DEFAULT_SETTINGS.locale === 'auto'`, so + "Automatic (follow the browser)" has to be selectable or the default is + unreachable. The three language labels are **endonyms**, identical in all + three dictionaries — a Japanese user hunting for Vietnamese looks for + "Tiếng Việt". +- Markdown layout is the sixth row because `markdownStyle` is a persisted + field; without it the only place to change it was a transient `#export` + control that never wrote back. +- Four of the six rows reuse the Export/Import tabs' own i18n keys rather than + inventing parallel wording, so the two surfaces cannot describe the same + choice differently. + +Auto-save + saved toast — the toast reports the resolved `SaveOutcome`, so a +failed write says so rather than claiming success. Footer: "Reset to defaults", +behind a `` (six preferences is enough to be worth a confirm). ### 3.5 #about ``: logo, name, version (from manifest at runtime), tagline; links: **GitHub repo ↗** · Report an issue ↗ · Changelog ↗; **Third-party dependencies: None 🎉** (statement, satisfies the requirement); -Donate: GitHub Sponsors (`poli0981`) ↗ · Ko-fi (`skullmute`) ↗ — full handle -list in `14 §5`, sourced from `.github/FUNDING.yml`; +Donate: **all five** handles from `14 §5` / `.github/FUNDING.yml` — GitHub +Sponsors · Ko-fi · Buy Me a Coffee · Patreon · PayPal (platform names are brand +names and stay untranslated, `07 §4`); Legal block: EULA · License (GPL-3.0) · Disclaimer · Privacy Policy — each → -GitHub `legal/` file; "Legal terms accepted on · version n". +GitHub `legal/` file; "Legal terms accepted on · version n" — where `n` +is the version the user **accepted**, from the stored record, not the current +`LEGAL_VERSION` constant. Reachable before acceptance (`14 §2`), so it also has +a not-yet-accepted state, and a dateless variant for a stored record whose +timestamp is missing or unparseable. + +"Changelog" points at the repo's **releases** page until `CHANGELOG.md` exists +(Phase 5) — an empty releases page beats a 404 opened from a legal surface. ## 4. Component inventory (`src/lib/components/`) @@ -132,6 +174,21 @@ auto-dismiss 4s, ARIA `status`) · `SettingRow` · `AboutCard` · `LegalGate` · Rule: components ≤ 300 lines; recursive tree logic isolated in `TreeNode`. +As built, some inventory names map differently — recorded so the list is not +read as a list of missing files: + +| Inventory name | Realized as | +|---|---| +| `AboutCard` | `AboutTab.svelte`, for symmetry with the other four tab shells | +| `TreeView` | inline in `EditTab.svelte`; the row is `TreeRow.svelte` and the flattening lives in `edit/tree-keyboard.ts` | +| `TreeNode` | `TreePreviewNode.svelte` (import preview) + `FolderPickNode.svelte` (export picker) | +| `ResultCard` / `SearchInput` | inline in `ImportTab` / `EditTab` | +| — | plus `SettingsTab.svelte`, the fifth tab shell | + +`Toast`'s queue and timers live in `stores/toast.svelte.ts`, not the component: +one `` mounts at the App root while the route chain below it unmounts on +every navigation, so component-owned timers would leak by construction. + ## 5. Accessibility & keyboard - Tree uses `role="tree"/"treeitem"`, `aria-expanded`, `aria-level`; arrow diff --git a/docs/07_I18N.md b/docs/07_I18N.md index 99be67e..07f7043 100644 --- a/docs/07_I18N.md +++ b/docs/07_I18N.md @@ -88,6 +88,26 @@ export function setLocale(l: Locale) { locale = l; } // settings store persists - Dates in UI: `new Intl.DateTimeFormat(localeTag, { dateStyle:'medium', timeStyle:'short' })` with tags `en-US` / `vi-VN` / `ja-JP`. - Numbers (counts): `Intl.NumberFormat(localeTag)` — VI uses `.` thousands. + +Where these live: pure `localeTag` / `formatCount` / `formatDateTime` in +`src/lib/i18n/format.ts` (formatters cached per tag — `StatsCard` alone formats +four counts per paint), plus reactive `num()` / `dateTime()` wrappers in +`index.svelte.ts` that read the current locale. `formatDateTime` returns +`undefined` rather than a string on an unparseable input: `readLegal` coerces a +missing `acceptedAt` to `''`, and `Intl.format(new Date(''))` throws a +`RangeError` *inside a render*, which would blank the About tab. + +Three rendered numbers deliberately do **not** go through `num()`, each with a +comment at the site so the next reader does not "finish the job": + +| Site | Why | +|---|---| +| `ProgressBar`'s `{n}%` | 0–100; no locale groups two digits, and it is the hottest render path in the app | +| `import.folderName`'s date | this bullet list already pins it to the localized *word* + an **ISO** date; localizing it would rename folders written into the user's browser | +| Export filenames and file contents | locale-independent so a file means the same thing whoever opens it | + +ARIA numeric attributes (`aria-level`, `aria-valuenow`) are not display text and +stay raw. - File names & file contents stay locale-independent (ISO dates, English "Imported" folder prefix? **No** — the auto-folder title uses the localized word + ISO date, e.g. `Đã nhập 2026-07-03`, key `import.folderName`). diff --git a/docs/11_TESTING.md b/docs/11_TESTING.md index 4ad7229..4578ef6 100644 --- a/docs/11_TESTING.md +++ b/docs/11_TESTING.md @@ -130,8 +130,17 @@ generate-huge.ts # script: emits 100k+1 node file on demand panel bulk-keep-first. - [ ] Keyboard-only pass of the tree (WAI-ARIA pattern) + dialogs. - [ ] Language switch EN→VI→JA live-updates all tabs; dates/numbers - localized; restart persists. + localized; restart persists. Header switcher and the `#settings` row + agree at all times (one state, two views). - [ ] Theme: system/light/dark; contrast spot-check. +- [ ] Settings auto-save: change a value, close the tab immediately, reopen — + the value stuck. The "Saved" toast appears only *after* the write + confirms, and a failure says so instead. +- [ ] Legal Gate "Close tab" either closes the tab or shows the + manual-close message — never appears to do nothing. +- [ ] Two Manager tabs open: accepting or changing a setting in one is + reflected in the other (or record it as the known limitation it is — + `15` decision log). - [ ] chrome://extensions → no errors logged during the whole pass. - [ ] Edge (or Brave): smoke test install + import/export. diff --git a/docs/15_ROADMAP.md b/docs/15_ROADMAP.md index f3a90ca..4fadd09 100644 --- a/docs/15_ROADMAP.md +++ b/docs/15_ROADMAP.md @@ -16,19 +16,28 @@ Build-phase breakdown lives in `CLAUDE.md` (single source for sequencing). | 1 — Core library | ✔ 2026-07-25 | 3 parsers, 4 serializers, dedupe/diff/plan; 600 seeded round-trips | | 2 — Browser layer + #import | ✔ 2026-07-25 | adapter, write queue, stores, full import flow incl. forced backup | | 3 — #export + #edit | ✔ 2026-07-25 | tri-state picker, tree CRUD, search, duplicates, DnD + keyboard parity | -| 4 — i18n, theming, Settings, About, Legal Gate | next | dictionaries already exist in EN/VI/JA; the switcher UI does not | -| 5 — Hardening + release prep | pending | CI stubs per `12 §2`, CHANGELOG, README, full QA, `wxt zip` clean install | +| 4 — i18n, theming, Settings, About, Legal Gate | ✔ 2026-07-26 | switcher + theme controls, six-row `#settings`, `#about`, first-run gate; Intl retrofit; store-backed Toast | +| 5 — Hardening + release prep | next | CI stubs per `12 §2`, CHANGELOG, README, full QA, `wxt zip` clean install | **Verified on real browsers 2026-07-25:** Chrome and Brave, unpacked build. Until that point every phase had been tested only against a hand-rolled `chrome.bookmarks` mock, because WXT's `fakeBrowser` stubs that API with "not implemented" throws (`11 §4`). -Each of phases 1–3 was adversarially reviewed after implementation and each -review found real defects (7, 13 and 14 respectively) — several in the paths +Each of phases 1–4 was adversarially reviewed after implementation and each +review found real defects (7, 13 and 14 in phases 1–3) — several in the paths that delete bookmarks. Budget that review into the remaining phases; a green test run has not once meant "done" on this project. +Phase 4 found three latent defects in code that 338 green tests had already +signed off, all of them unreachable until Phase 4 gave them a caller: +`writeSettings` handed a `$state` proxy to `chrome.storage.local.set` (would +throw `DataCloneError` in a real browser — `fakeBrowser` stores the reference +without cloning, so the suite could not see it); `updateSettings` replaced the +settings object rather than mutating it, which would strand any component that +captured it; and footer navigation during `attesting` stranded the import's +attestation resolver, deadlocking it until reload. + ## v1.0.x — stabilization - Parser-tolerance fixes from real user files (fixture + test per report). @@ -93,3 +102,17 @@ test run has not once meant "done" on this project. | 2026-07-25 | CI: ops repo has no `browser-extension-*` family; callers use `reusable-chrome-extension.yml` + a local quality job, release is standalone | 12 §2 | | 2026-07-25 | Replace deletes nothing until the backup is **proven** — picker `close()` resolving, or an explicit user attestation on the anchor fallback | 03 §1 6b | | 2026-07-25 | Every `#edit` mutation resyncs from the browser on rejection; roots and `unmodifiable` nodes offer no destructive affordance at all | 03 §3 | +| 2026-07-26 | Legal Gate renders **inside the content region**, not as a viewport overlay — `06 §3`'s "full overlay" reconciled in favour of `14 §2`'s reachable `#settings`/`#about` | 06 §3 | +| 2026-07-26 | Settings state mutates **in place**; every storage write passes a plain snapshot (a `$state` proxy is not structured-cloneable, so the old code would have thrown `DataCloneError` in a real browser) | 03 §4 | +| 2026-07-26 | `updateSettings` / `acceptLegal` return non-rejecting outcomes; UI feedback follows the write, never precedes it | 03 §4 | +| 2026-07-26 | Toast queue + timers live in a store, so they survive the route chain unmounting | 06 §4 | +| 2026-07-26 | Static outbound links use ``; imported bookmark URLs keep `tabs.create` (`09` T3 unchanged). Two mechanisms for two trust classes — do not harmonize | 09 T3 | +| 2026-07-26 | `#settings` has **six** rows: `markdownStyle` was persisted but only editable as a transient `#export` control | 06 §3.4 | +| 2026-07-26 | `locale: 'auto'` is a first-class fourth option in the switcher — it is the default, so it must be selectable | 06 §3.4 | +| 2026-07-26 | Language labels are endonyms, duplicated identically across the three dicts (the `common.appName` precedent) | 07 §4 | +| 2026-07-26 | Theme control is a three-way segmented control in both header and `#settings`, not a cycling `◐` | 06 §3 | +| 2026-07-26 | Version comes from the manifest at runtime; three hardcoded `0.1.0` literals removed (footer, `run-export`, `run-import`) | 06 §3.5 | +| 2026-07-26 | About's "Changelog" points at GitHub Releases until `CHANGELOG.md` exists in Phase 5 | 06 §3.5 | +| 2026-07-26 | The gate's acceptance checkbox deliberately resets if the user navigates away and back — an un-submitted legal affirmation is not worth persisting | 14 §2 | +| 2026-07-26 | Both entrypoints await settings (Manager also legal) **before** `mount()`, trading a blank frame for no locale/theme/gate flicker | 02 §2 | +| 2026-07-26 | **Known limitation:** two open Manager tabs do not sync settings or acceptance to each other; last write wins. No `storage.onChanged` listener in v1 | 03 §4 |