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:
8 files changed
+158
-18
No files matched your search
@@ -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,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)
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -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
@@ -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
@@ -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
|
||||
|
||||
@@ -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
@@ -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
@@ -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 |
|
||||
Reference in new issue
Block a user