docs: reconcile the spec with Phase 4

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 <noreply@anthropic.com>
This commit is contained in:
poli0981andClaude Opus 5 committed 2026-07-26 13:03:05 +07:00
1 parent 372741142e
commit c44c813aec
8 files changed
+158 -18

No files matched your search

+3 -1
View File
@@ -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
+5 -5
View File
@@ -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)
---
+14
View File
@@ -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 → <a download>
│ │ │ ├── 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/
+16 -1
View File
@@ -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 `<SettingRow>` 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 `<LegalGate>` 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)
+63 -6
View File
@@ -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). `<LegalGate>` 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.
`<LegalGate>` 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
`<main>`, 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 `<SettingRow>`s: Language (EN/VI/JA select) · Theme
Single column of **six** `<SettingRow>`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 `<ConfirmDialog>` (six preferences is enough to be worth a confirm).
### 3.5 #about
`<AboutCard>`: 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 <date> · version n".
GitHub `legal/` file; "Legal terms accepted on <date> · 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 `<Toast>` 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
+20
View File
@@ -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`).
+10 -1
View File
@@ -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.
+27 -4
View File
@@ -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 `<a target="_blank" rel="noopener noreferrer">`; 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 |