Firefox Add-ons approved the first version. The owner reported it on 2026-11-21. AMO's public API shows the add-on public, version 1.3.0, Firefox 140 or later, slug "bookmarkmagic". Both the slug URL and the gecko-id URL the About link uses answer 200. - README: the Firefox install row links the listing, with an AMO version badge beside the Chrome Web Store and Edge ones. - docs/00: the Type line, the 1.3.0 status (live on all three stores), §9 (gecko id, slug, listing), §10 item 21 done and item 24 done. Item 23's automation state was re-checked and is unchanged: firefox-add-ons still does not exist. - docs/13 §8 and store/listing.*.md: the licence to pick is "GNU General Public License v3.0 or later". AMO offers "v3.0 only" beside it, and that is what the listing ended up with (GPL-3.0-only, per the API) — the docs only said "v3.0". Item 21 keeps it open, along with the empty support site. - docs/15 and CLAUDE.md: Firefox Add-ons live; 1.3.0 is on all three. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
17 KiB
CLAUDE.md — Build Instructions (BookmarkMagic)
A Chrome MV3 extension — and since v1.3.0 a Firefox one, and on Edge Add-ons —
for offline bookmark import/export/edit.
This file is the entry point; the docs/ suite is the specification.
When code and docs disagree, docs win — or stop and ask.
⚠️ This is shipped software
BookmarkMagic is published on the Chrome Web Store and has real users (v1.0.0 live by 2026-08-03; v1.0.1 live, confirmed on the listing 2026-10-28; v1.1.0 live, confirmed on the listing 2026-11-06; v1.2.0 live, confirmed on the listing 2026-11-10; v1.2.1 released on GitHub 2026-11-10, never submitted on its own; v1.3.0 — Firefox and Edge, 1.2.1 included — released on GitHub and submitted to all three stores 2026-11-18, live on Edge Add-ons and the Chrome Web Store 2026-11-19 and on Firefox Add-ons by 2026-11-21). Phases 0–9 are complete; since 2026-11-18 the project is in maintenance mode —
/MAINTENANCE.mdis the policy (Phase 10 below). That changes the rules of the game:
- New work must fit
/MAINTENANCE.md: dependency and security updates, major platform upgrades, bug/UI/UX/accessibility/translation fixes, and features only when they are ondocs/15's roadmap or genuinely needed. A feature that is not on the roadmap needs a decision-log row before code.- Every change now reaches installed users through a store review. It needs a semver bump, a
CHANGELOG.mdentry and an update submission —13 §1b.- Breaking something is no longer a local cost. The 1.0.0 → 1.0.x upgrade over an existing profile (
11 §5) is the one test whose failure hits every user at once.- Bumping
LEGAL_VERSIONre-shows the first-run gate to everybody. It is a deliberate, documented act (14 §2), never a side effect.- Read
docs/15's build-progress table and decision log before planning anything;docs/00 §10is the live open-items list.
Doc index (read 00–02 fully before writing any code)
| Doc | Contents |
|---|---|
| docs/00_PROJECT_OVERVIEW.md | Vision, scope, non-goals, naming ⚠, manual action items |
| docs/01_TECH_STACK.md | Pinned versions, rejected deps, npm scripts |
| docs/02_ARCHITECTURE.md | Layout, layer rules, data model, routing, error strategy |
| docs/03_DATA_FLOW.md | Import/export/edit pipelines, state machine |
| docs/04_FILE_FORMATS.md | Netscape HTML / BM JSON / CSV / Markdown specs |
| docs/05_ALGORITHMS.md | Parser walk, normalize, dedupe, diff, write queue |
| docs/06_UI.md | Tokens, layouts per tab, component inventory, a11y (§5 is the spec behind /ACCESSIBILITY.md) |
| docs/07_I18N.md | chrome.i18n vs runtime store split, EN/VI/JA rules |
| docs/08_MV3_COMPLIANCE.md | Manifest, permissions (bookmarks+storage ONLY), CWS rules; Firefox §9, Edge §10 |
| docs/09_SECURITY_PRIVACY.md | Threat model T1–T8, secure-coding bans |
| docs/10_CODING_STANDARDS.md | Size limits, tsconfig, biome.json, knip.json, conventions |
| docs/11_TESTING.md | Coverage gates, fixtures, suites, manual QA |
| docs/12_CI_CD.md | Ops-repo caller stubs, release automation |
| docs/13_RELEASE_PUBLISHING.md | Store runbook + listing copy |
| docs/14_LEGAL_GATE.md | Gate spec + legal file drafts |
| docs/15_ROADMAP.md | Version plan, never-list, decision log |
Hard rules (violations = stop and ask)
- Permissions are exactly
["bookmarks", "storage"]. - Zero runtime dependencies. New dep ⇒ ask first (docs/01 §4).
- No
fetch/network calls, noeval, no{@html}, noinnerHTMLwrites. The canonical gate is docs/08 §3, run asnpm run guard. src/lib/core/never imports browser APIs, Svelte, orsrc/lib/browser.- Files ≤300 lines (hard 500); functions ≤50 (hard 80).
- Every string user-visible ⇒ i18n key in every shipped locale —
LOCALESinsrc/lib/i18n/resolve-locale.ts: en, vi, ja, zh-CN, ro (en is schema; the otherssatisfies Dict, whereDict = Localized<typeof dict>is exported fromlocales/en.ts). Neveras conston a locale file — docs/07 §2. Romanian plural keys carry a third form,few(docs/07 §5). - TypeScript strict; no
any; casts need// SAFETY:comments. - Conventional Commits;
npm run verifygreen before every commit — andnpm run verify:fullbefore anything release-bearing.verifyomits three gates the tag run enforces (coverage,build,check:manifest), so a core change that drops branch coverage passes locally and fails only after the tag is pushed, whengh release createmay already have run.
Build phases (each ends with npm run verify green + a commit)
Phase 0 — Scaffold
npx wxt@latest init (svelte template) → apply docs/01 versions & scripts
(incl. postinstall: wxt prepare), srcDir: 'src' per docs/02 §2, docs/10
configs (tsconfig/biome/knip/vitest), directory skeleton per docs/02,
tokens.css per docs/06 §1, manifest per docs/08 §1, empty locale dicts per
docs/07. Also land up front, because later phases link to them from the first
screens: .nvmrc, .gitignore, .github/FUNDING.yml (copy from
switch-every-tab-hotkey), SECURITY.md, the four legal/ drafts from
docs/14 §3, scripts/guard.mjs (docs/08 §3) and scripts/gen-icons.mjs
(placeholder PNGs so the manifest loads).
Exit: npm run dev loads popup+manager; verify green.
Phase 1 — Core library (pure TS + tests FIRST-CLASS)
Implement src/lib/core/ per docs/04+05: model, limits, timestamps,
normalize-url, detect-format, parsers (netscape-html, bm-json, csv),
serializers (all four), dedupe, diff. Commit fixtures per docs/11 §2 and the
full unit suites incl. round-trip + randomized trees.
Exit: coverage ≥90% on core; all fixtures parse; round-trips pass.
Phase 2 — Browser layer + Import tab
src/lib/browser/ (bookmarks wrapper, write-queue + tests, storage,
download, open-manager), stores, hash routing, Manager shell + TabBar,
full #import flow per docs/03 §1 (DropZone → preview → options → backup →
progress → report) and popup buttons.
Exit: manual: import chrome fixture on fresh profile in all 3 modes;
cancel works; 10k file stays responsive.
Phase 3 — Export + Edit tabs
#export per docs/03 §2 (FolderPickTree tri-state, format cards, download). #edit per docs/03 §3 + docs/06 §3.3 (TreeView CRUD, DnD + Move-to parity, search, duplicate panel, live event sync, ARIA tree keyboard nav). Exit: QA checklist items for export/edit pass; exported HTML re-imports losslessly.
Phase 4 — i18n, theming, Settings, About, Legal Gate
Full dictionaries (en→vi→ja), language switcher, theme toggle+persistence, #settings, #about (links, donate handles per docs/14 §5, "Third-party: None"), LegalGate per docs/14 §2 — blocks #import/#export/#edit only. Exit: language/theme QA items pass; gate blocks/persists correctly.
Phase 5 — Hardening + release prep
Security pass against docs/09 T1–T8 (incl. injection fixtures manually),
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. Also carried in from the Phase 4 review:
- ✔ About's "Changelog" link now targets
CHANGELOG.md, pinned bytests/unit/links.test.ts; - ✔
EditTab.sveltesplit (589 → 459, under the hard limit). It grew back to 481, and in v1.1.0 its state and commands moved into three stores —edit-view(181 lines),edit-commands(226),edit-session(133) — and its key handling intosrc/lib/edit/tree-keys.ts. As of the 1.1.0 review the component is 259 lines with a 144-line script,TreeRow.svelte276,ImportTab.svelte266 and the Manager'sApp.svelte237: every file is under the 300 target again. Extract before adding; - ✔ contrast tokens fixed, and
tests/unit/styles/contrast.test.tsnow fails the build on any text pair under 4.5:1. Two blind spots to know about: it is token-level, so it cannot see theopacity-on-text bypass it was written to catch, and its pair list is hand-maintained. Exit: ✔ v1.0.0 submitted and published.
Phase 6 — Post-launch stabilization → v1.0.1
The first phase written for shipped software. In order, because the docs are
binding and three of the code changes need the spec to say the new thing first:
docs reconciliation (this suite had frozen at "in review") → user-intake
machinery (.github/ISSUE_TEMPLATE, CONTRIBUTING.md, the sanitizer — docs/15
§v1.0.x's "fixture + test per report" had no intake at all) → import failure
reporting and the routing deadlock → localized #edit/#export failures and
bounded search expansion → cross-tab settings/legal sync → dependency bumps and
CI hardening → the About store link → cut 1.0.1.
Exit: ✔ v1.0.1 tagged and released 2026-08-03, live on the store
(confirmed 2026-10-28).
Phase 7 — v1.1.0: toolchain, import redesign, new formats, technical UI
Two PRs. PR-A (toolchain): Node 26, TypeScript 7 beside the TS 6 API,
ES2025 with Chrome ≥ 136, SonarCloud in CI, a browser-enforced zero-network
CSP, gates that cannot be talked past. PR-B (product): the import pipeline
redesigned — every entry a file holds read, addresses Chrome would refuse
skipped up front, Chrome's Bookmarks file and Firefox JSON backups imported,
root markers so restores stop nesting, a Merge that reuses folders, a Replace
that plans first and refuses an unrestorable backup; the Edit tab rebuilt
around a store, with Sort A→Z, drag to reorder and batched live sync; a
technical redesign of every surface; local diagnostics; a cross-tab write
lock; docs and legal synced (clarifications only — LEGAL_VERSION stays 1);
contact aliases per purpose.
Exit: ✔ v1.1.0 tagged and released 2026-10-29 (signed tag on 9040f84,
checksum-verified zip). Still human-only: the docs/11 §5 manual pass on real
Chrome including the 1.0.1 → 1.1.0 upgrade over an existing profile ⚠️,
then the zip uploaded to the store ⚠️.
Phase 8 — v1.2.0: Simplified Chinese and Romanian
Real installs in Chinese and Romanian browsers (CWS dashboard) made two UI
languages the next minor. In order: docs first (07 gains §6 "Adding a
locale") → one LOCALES list and a third plural form (few), with no new
language yet → zh-CN → ro → manifest _locales, store listings, the
translation form, the screenshot harness → visual sweep in both languages and
an adversarial review of code and translations → 1.2.0. Both ship
best-effort (TODO(review-zh), TODO(review-ro)). A Traditional Chinese
browser on "Automatic" gets English.
Exit: ✔ v1.2.0 tagged and released 2026-11-06 (signed tag on e2f36bc,
checksum-verified zip). A finding worth keeping: on this Windows machine the
process-spawning script tests time out intermittently under load (main's
too), so CI — whose Windows smoke job passed — was the gate.
✔ Live on the store, confirmed on the listing 2026-11-10 (5 languages).
Human-only ⚠️, still open: the native review passes, and 13 §1b step 10 —
the published build installed on a clean profile — which has no recorded
result for any version.
Phase 9 — v1.2.1: accessibility
The owner's keyboard-only and Narrator pass over 1.2.0 found nothing; an audit
of src/ then found what such a pass cannot see. In order: dependency sync
after Dependabot (the biome.json $schema and docs/01 do not move
with its PRs) → docs first (06 §5) → ACCESSIBILITY.md at the repository
root with its intake (issue form, PR checklist, accessibility@) → the fixes:
a focus ring that was drawn in the colour of the fill under it, forced-colours
support, Alt+↑/↓ to reorder (through the drag's own planDrop), focus that
fell to <body> in three places, 24 px targets, an About link to the
statement → adversarial review → 1.2.1.
Two things to carry forward. ACCESSIBILITY.md is a public promise: a UI
change that makes its key table or its known-limitations list false has to
change the file in the same PR (11 §5 has the check). And the statement's
goal is WCAG 2.2 AA as a goal — never write "conforms" or "compliant"
without an audit to cite. The review found the first draft of the statement
overclaiming in nine places ("every clickable target", "nothing times out"):
check each sentence of it against the source, not against the intention.
A third: code moved out of a component starts counting. SonarCloud's
new-code gate (80 %) failed the first push because the live-sync wiring left
EditTab for a .ts module with no test. Extracting to stay under a size
limit is half the job; the test is the other half.
Exit: ✔ v1.2.1 tagged and released 2026-11-10 (signed tag on d61318a,
checksum-verified zip). Human-only ⚠️: the 11 §5 pass with the
1.2.0 → 1.2.1 upgrade over an existing profile, a real Windows contrast
theme and a screen-reader pass over Alt+↑/↓, the zip upload, and the native
review of the two new strings.
Phase 10 — maintenance mode; Firefox and Edge → v1.3.0
The owner put the project into maintenance mode and asked for the last
roadmap item, the other two stores. In order: Dependabot #39–#41 and the
hand sync they always need → the picomatch advisory recorded (no fix
exists) → a licence gate over the lockfile (check:licenses) → the policy
(/MAINTENANCE.md, a feature form that asks which kind of change it is, and
triage.yml, which closes requests for something new) → Qodana (qodana-js,
Ultimate) beside SonarCloud → then Firefox (AMO) and Edge: the docs first,
then the port, then CI, review and 1.3.0.
One thing to carry forward: triage.yml runs on pull_request_target,
with a write token, for pull requests from forks. It checks out the base
branch and only compares event text with constants. Never add a checkout of
the pull request's head, a step that runs its code, or a ${{ }} of a title
or body inside a run: line to that file.
Two more, from the port. There is no Firefox in CI: the fake's Firefox
flavour (11 §4) is a reading of Firefox's source, not evidence, so a change
to roots, separators or move indices needs a real Firefox before an AMO
upload. And every change now ships in two packages: verify:full builds
and checks both (build:firefox, check:manifest -- --browser firefox), and a
string that names Chrome is false in one of them.
Exit: ✔ v1.3.0 tagged and released 2026-11-18 (signed tag on 80c7190,
three checksum-verified packages; PR #44 merged at the reviewed head).
Human-only ⚠️ (00 §10 items 19–26): the 11 §5 passes — Chrome with the
1.2.0 → 1.3.0 upgrade over an existing profile, a real Firefox 140+, Edge
signed in with sync on — then the Chrome Web Store upload of 1.3.0 in place
of 1.2.1, the first Firefox Add-ons version and the first Edge submission by
hand, the store environments if automation is wanted, and native review.
The three uploads went up 2026-11-18; Edge and the Chrome Web Store approved
2026-11-19, Firefox Add-ons by 2026-11-21 — 1.3.0 is on all three stores. An Edge copy's About link is chosen
by its CRX ID (links.ts), so the listing ids in 00 §9 are code, not
trivia. And since 2026-11-19 a pushed v* tag is a store submission:
every *_AUTOPUBLISH variable is true, and no store environment has a
required reviewer yet (00 §10 item 23 has the state). Treat a tag as an
upload to users' browsers, and have the owner's go for that release before
pushing one.
Working style
- Small commits per module; tests land with (or before) implementation.
- A git worktree needs its own
npm ciandnpx wxt prepare. With an emptynode_modules/packages resolve upward from the parent repo and most things appear to work, but knip reports every devDependency unused andverifyfails;tsconfig.jsonextends./.wxt/tsconfig.json, whichwxt preparegenerates. Type resolution walks up too, and it does so even after a correctnpm ci. A worktree underE:\bookmarkmagic\.claude\worktrees\inheritsE:\bookmarkmagic\node_modules\@types\*, sonpm run checkcan pass locally on types the package does not declare and CI does not have. That is exactly how a missing@types/nodesurvived a green localverifyand failed CI on the first push. A green local type-check in a worktree is weaker evidence than it looks. - TypeScript 7 runs beside the TS 6 API.
tscis TS 7 (@typescript/native, aliasednpm:typescript@~7); thetypescriptpackage is aliased to@typescript/typescript6for svelte-check, which needs the classic API TS 7 does not have yet.npm run checkruns svelte-check (TS 6,.sveltefiles) and thentsc(TS 7,.tsandscripts/*.mjs). Never "fix" one by removing the other. - Installs run with
--ignore-scripts, in CI and locally when in doubt:npm ci --ignore-scripts && npx --no-install wxt prepare. Thepostinstallhook only runswxt prepare; every other package's install script is untrusted code. - When a browser fixture contradicts the format spec: add the fixture, make the parser tolerant, note the quirk in code + docs/04 §1.2, then continue.
- Do not invent features not in docs; park ideas as
docs/15roadmap PRs. - Anything marked ⚠️ is human-only — surface it in your summary, don't fake it.
- Every phase so far has been adversarially reviewed after implementation and every review found real defects. A green test run has never once meant "done" on this project. Budget the review.