Recorded now rather than with the port, because the maintenance announcement names it (docs/15, docs/00 §7). Settled with the owner: gecko id bookmarkmagic@poli0981.dev, desktop only (Firefox for Android has no bookmarks API), MV3 everywhere, and Firefox separators shown, protected and warned about rather than stored in a file format. The roadmap is pruned to what MAINTENANCE.md allows: scheduled snapshots need the alarms permission and leave it; the permission rule joins the never list; the fflate zip export, the duplicate auto-merge assistant and bookmarklet notes are not planned; the old v1.3 "resilience" becomes v1.4. MAINTENANCE.md no longer lists "a dependency advisory" as a release trigger on its own: with no runtime dependencies, an advisory against the build tools needs a release only if it changed what ships. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
16 KiB
00 — Project Overview
Project: BookmarkMagic Type: Chrome/Chromium MV3 browser extension (open source, Chrome Web Store) Owner: poli0981 (GitHub) / SkullMute Repo:
poli0981/bookmarkmagic✔ License: GPL-3.0-or-later Status: v1.0.0 is PUBLISHED on the Chrome Web Store and has real users. Submitted 2026-07-26, approved and live by 2026-08-03 (⚠️ exact approval date to be recorded by the owner). Listing: https://chromewebstore.google.com/detail/bookmarkmagic/eghnciphhegekmnofffpgbdfefckdhmg. Signed tagv1.0.0, GitHub Release with a checksum-verified zip. Verified working on real Chrome and Brave.v1.0.1 is PUBLISHED. Tagged, released and submitted 2026-08-03; the listing was observed showing version 1.0.1 (
Updated: August 3, 2026, 5 users) on 2026-10-28. ⚠️ The exact approval date was never recorded — the owner can read it from the dashboard. Installed users are on 1.0.1.v1.1.0 is PUBLISHED. Tagged and released 2026-10-29 (signed tag on
9040f84, checksum-verified zip); the listing showed version 1.1.0 on 2026-11-06. It raised the floor to Chrome 136 (08 §7); permissions are unchanged.v1.2.0 is PUBLISHED. Tagged and released 2026-11-06 (signed tag on
e2f36bc); the listing was observed showing version 1.2.0 (Updated: November 7, 2026, 5 languages) on 2026-11-10. Installed users are on 1.2.0.v1.2.1 — accessibility — is RELEASED on GitHub, not yet on the store. Tagged and released 2026-11-10 (signed tag on
d61318a, checksum-verified zip): an accessibility statement (/ACCESSIBILITY.md) and the fixes an audit found (06 §5). ⚠️ It still needs the owner's manual pass, including the 1.2.0 → 1.2.1 upgrade over an existing profile, and a hand upload to the store (13 §1b); until it clears review, installed users stay on 1.2.0.The project is now in maintenance, not construction: every change from here reaches installed users through a store review, so it needs a version bump, a CHANGELOG entry and an update submission (
13 §1b). Sequencing lives in/CLAUDE.md; what is still open is in §10 below.Since 2026-11-18 that is a written policy: maintenance mode (
/MAINTENANCE.md). Dependency and security updates, major platform upgrades, bug/UI/UX/accessibility/translation fixes, and features only when they are on15's roadmap or genuinely needed; requests for anything else are closed bytriage.yml(12 §2.6). Doc suite version: 1.12 (2026-11-18 — maintenance mode)
1. Vision
A 100% offline bookmark toolbox: import, export, and edit bookmarks and full folder trees between different browsers — without accounts, without cloud sync, without vendor lock-in.
The user's data never leaves their device. The extension is the "USB stick" for bookmarks: plug a file in, get a file out.
2. Problem statement
Moving bookmarks between browsers (Chrome ↔ Edge ↔ Brave ↔ Firefox ↔ Safari) or between machines normally requires either:
- signing in to each vendor's sync service (privacy cost, account friction), or
- each browser's buried, inconsistent native import/export screens, with no preview, no merge control, no dedupe, and no editing.
3. Solution
One extension page with three capabilities:
| Capability | Summary |
|---|---|
| Import | Validate a bookmark file → preview the tree + stats → choose merge mode + dedupe → write into the browser with progress reporting. |
| Export | Pick scope (all / specific folders) → pick format → download a file compatible with every major browser. |
| Edit | Full tree manager: search, rename, move and reorder (drag & drop), sort A→Z, delete, create folders, find duplicates. |
4. Product principles
- Offline-first, always. No network requests at runtime. No analytics. No telemetry. This is a hard rule, not a default.
- Minimal permissions.
bookmarks+storageonly. No host permissions, no content scripts, notabs. - Zero runtime dependencies. Parsing/serializing uses platform APIs
(
DOMParser,Blob,URL). Dev-time dependencies only. - Never destroy data silently. Destructive operations (Replace) force an automatic safety backup first. Default import mode is non-destructive ("into a new folder").
- Reviewable code. Open source, minified-only builds (no obfuscation — prohibited by CWS anyway), small files, tested core.
5. Target users
- People migrating browsers or machines.
- Privacy-conscious users who refuse vendor sync accounts.
- Power users maintaining large curated bookmark trees (1k–50k items).
- The SkullMute community (bilingual EN/VI audience; JP as third locale).
6. Scope — v1.0
- Import: Netscape HTML, BM JSON, CSV.
- Export: Netscape HTML, BM JSON, CSV, Markdown (export-only).
- Merge modes: New folder (default) / Merge / Replace all (with forced backup).
- Optional dedupe on import (by normalized URL).
- Tree editor: expand/collapse, search, rename, move, delete, new folder, drag & drop, duplicate finder.
- i18n: EN (default), VI, JA. Dark/light theme.
- First-run Legal Gate (EULA, GPL-3.0, Disclaimer, Privacy Policy → GitHub links).
- About tab: version, GitHub repo, third-party list ("None"), donate links.
v1.1.0 adds (the list above stays as v1.0 shipped it — 15 cites it as
v1.0's scope):
- Import: Chrome's profile
Bookmarksfile and Firefox JSON backups, both recognised by content, not extension (04 §2a/§2b). Backups restore into the right roots instead of nesting them (03 §1). - Merge that merges: folders the user already has are reused level by level,
and new items are appended to them (
03 §1,05 §5). - Replace asks first, with exact counts, and refuses a backup it could not
read back (
09T4); one writer across Manager tabs (03 §5). - Tree editor: Sort A→Z per folder, drag to reorder (before / after / into),
a real "Move to…" dialog, bounded rendering (
03 §3,05 §9–§11). - About: the third-party statement names the two MIT pieces the build compiles
in instead of "None"; Copy diagnostics, a local log for bug reports
(
09 §7). - A redesigned UI with a self-drawn icon set, all motion behind
prefers-reduced-motion(06).
v1.2.0 adds two UI languages, chosen from the CWS dashboard's install and
usage figures: Simplified Chinese (zh-CN) and Romanian (ro) — in the
app, in the manifest and in the store listing (07). Traditional Chinese is
not shipped; a Traditional Chinese browser on "Automatic" gets English.
7. Non-goals (v1.0)
- ❌ Cloud sync, accounts, or any server component.
- ❌ Favicon migration (Chrome's
bookmarksAPI cannot write favicons;ICONattributes are tolerated on parse and dropped — documented limitation). - ❌ Dead-link checking (requires host permissions — deferred, see Roadmap).
- ❌ Firefox/Safari store releases (WXT keeps the door open; see Roadmap).
Firefox and Edge became goals on 2026-11-18 (v1.3,
15); Safari stays out. - ❌ Editing browser-native root folders themselves (Bookmarks Bar / Other Bookmarks cannot be deleted/renamed — enforced by API anyway).
8. Success criteria
- ✔ Chrome Web Store approval on first or second review pass — approved
between 2026-07-26 and 2026-08-03, with no rejection recorded (⚠️ owner: note
which pass, since it is the only evidence that the
08 §5privacy answers and permission justifications landed correctly, and the baseline against which a future update rejection would be judged). - Round-trip fidelity at the file level:
parse(serialize(tree))reproduces the tree, per-format and minus each format's documented losses — verified by the automated suite (11 §3). Note what the platform does not allow:chrome.bookmarks.create()takes nodateAdded, so bookmarks written into the browser are stamped with the import time. Titles, URLs and structure survive a browser import; original dates do not (05 §6). - 10,000-bookmark import completes with responsive UI and live progress.
- Lighthouse-style sanity: manager page interactive < 1s on mid-range hardware.
9. Naming — resolved ✔ (2026-07-03)
Final name: BookmarkMagic — one word, PascalCase, consistent with the portfolio (CommandForge, AutoClickForge, IconForge, JSONPrism). The earlier working title "Bookmark Sync Magic" was dropped because "Sync" implied cloud syncing — the one thing this product deliberately does not do.
Derived identifiers (canonical across docs and code):
| Context | Value |
|---|---|
| Manifest / store / UI name | BookmarkMagic (identical in every locale) |
| Repo slug | poli0981/bookmarkmagic ✔ |
| Own JSON schema | "BM JSON v1", "format": "bookmarkmagic" |
| Code prefix | Bm* (BmParseError, BmAborted) |
| Safety-backup filename | bookmarkmagic-backup-YYYYMMDD-HHmm.json |
| Chrome Web Store item id | eghnciphhegekmnofffpgbdfefckdhmg (also the value CHROME_EXTENSION_ID needs — 12 §3) |
| Store listing URL | https://chromewebstore.google.com/detail/bookmarkmagic/eghnciphhegekmnofffpgbdfefckdhmg |
10. Manual action items (human-only) ⚠️
- ✔ Name decided: BookmarkMagic. ✔ Repo slug confirmed —
github.com/poli0981/bookmarkmagic. - ✔ Repo created,
LICENSEcommitted. Variant resolved: GPL-3.0-or-later, matchingpoli0981/switch-every-tab-hotkey. - ✔ Icon set (16/32/48/128 px) — the owner adopted the
scripts/gen-icons.mjsoutput as final on 2026-07-26, so the generator is the source of truth rather than a placeholder. Regenerate withnpm run iconsafter any change. ⚠️ Store assets are unreconciled. The listing is live, so whatever13 §2requires was supplied — but nothing in the repo records what, or where the originals live. Since 1.1.0 the screenshot harness writes 1280×800 candidates tostore/screenshots/(13 §2); there is still no 440×280 promo tile of any size. Owner: record where the submitted assets live, or correct13 §2. - ✔ Donate URLs resolved from
.github/FUNDING.yml(14 §5). ✔ Contact addresses: since v1.1.0, one alias per purpose (privacy@inlegal/PRIVACY.md,security@,legal@,dmca@,copyright@,takedown@,code@— README "Contact");contact@is retired. ⚠️ Owner: if the CWS dashboard's developer contact still sayscontact@, change it toprivacy@orcode@there. - ✔ Chrome Web Store: developer account paid, item created, submitted
2026-07-26 and approved — the listing is public and has users. Listing
copy and the Privacy tab answers came from
13 §3and08 §5. The store URL landed in the README on 2026-07-27 (ea246aa) and the item id is now in the §9 identifiers table.store/listing.{en,vi,ja}.mdnow hold the listing copy13 §4always asked for — ⚠️ reconstructed from13 §3after the listing went live, so diff them against the dashboard and correct the files. Still open: the asset reconciliation in item 3. - Repo secrets + settings per
12 §5. ✔ CodeQL "Default setup" is already disabled (the advanced workflow uploads SARIF cleanly). Still open:DISCORD_CI_WEBHOOKis not optional in practice.notify-ci-failure.ymlcalls a reusable that declares itrequired: true, so with the secret unset that workflow fails on every CI completion — success or failure. Either set it or accept the caller-side tolerance in12 §2.4.DISCORD_RELEASES_WEBHOOK/DISCORD_REPO_WEBHOOKgenuinely are optional; the announce job is skipped unless the repo variableDISCORD_ANNOUNCEistrue. (It used to saycontinue-on-error, which GitHub rejects on a reusable-workflow caller — see12 §2.3.)- The four
CHROME_*secrets are now a concrete v1.1 prerequisite, not a maybe:15lists automated CWS publishing as the first v1.1 item. One of the four is already known —CHROME_EXTENSION_IDis the item id in §9. The other three come fromnpx wxt submit init(12 §3). Note there is no dry-run: the first time that step executes it makes a real submission.
- Untested:
npm run dev:firefox. No gate exercises it (Firefox is a non-goal, §7). Theoverridesblock that used to threaten it is gone (09 §3.1), but do not assume it works. - Unmeasured: the 2 s parse budget on a real browser (
11 §6). The recorded 2869 ms is a jsdom figure and settles nothing.scripts/gen-fixture.mjsnow produces the file needed to measure it.
Post-launch (added 2026-08-03)
- JA native review pass.
src/lib/i18n/locales/ja.tscarries the repo's onlyTODO— "owner reviews VI; JA is best-effort until a native pass". It was acceptable pre-launch; it is now shipping to users.15 §v1.0.xtracks it, and thetranslationissue form is the intake for it. - The published build has never been installed from the store and smoke
tested.
13 §1step 8 became due at approval and no result is recorded. It is the only check that the artifact users actually receive matches what was tested. Now folded into11 §5as a standing pre/post-submission item. - ✔ v1.0.1 cleared review — the listing showed 1.0.1 when checked on
2026-10-28, and the "published" row is in
15's progress table. ⚠️ Still open: the exact approval date, and13 §1bstep 10 against the published build (install on a clean profile, re-run the upgrade check) — no result is recorded for either. - ✔ v1.1.0 cleared review — the listing showed 1.1.0 ("Updated October
29, 2026", 6 users, 3 languages) when checked on 2026-11-06. ⚠️ Still
open, as for 1.0.1:
13 §1bstep 10 against the published build — no result is recorded. Also unverified outside the harness: the account-storage roots of a signed-in profile and the hidden empty Mobile root (02 §4), and theMAX_WRITE_DEPTHrationale against a real Chrome.
v1.2.0 (added 2026-11-06)
- ⚠️ ZH-CN and RO native review passes. Both locales ship best-effort
(
07 §4), written from Chrome's own terminology in each language but read by no native speaker. Each file's header carriesTODO(review-zh)/TODO(review-ro). Thetranslationissue form lists both languages. - ✔ v1.2.0 to the store — live, observed 2026-11-10 (version 1.2.0,
Updated: November 7, 2026, 5 listing languages). ⚠️ Still unrecorded, as for 1.0.1 and 1.1.0:13 §1bstep 10, the clean-profile install of the published build and the upgrade re-check against it.
v1.2.1 (added 2026-11-10)
- ⚠️ v1.2.1 to the store. The GitHub Release exists and is verified
(
15's progress table). The usual11 §5pass plus the 1.2.0 → 1.2.1 upgrade over an existing profile, then the Release zip uploaded in the dashboard. No listing change: a patch (13 §5). - ⚠️ The accessibility checks no script can run (
11 §5): a Windows contrast theme over the tree, the tabs, the theme control and a running import; a screen-reader pass over Alt+↑/↓ (does the new position get spoken, once); 200 % zoom. The fixes were verified in a headless Chrome withforced-colorsemulated, which is not the same as a real theme. - ⚠️ Other screen readers.
ACCESSIBILITY.mdsays Narrator with Chrome on Windows 11 was tested and NVDA, JAWS, VoiceOver and ChromeVox were not. Any pass with one of those moves it from the second list to the first. - ⚠️ Native review of the new strings — the About link label and the spoken position — in JA, ZH-CN and RO, with the passes in items 9 and 13.
11. Reading order
For humans: this file → 15_ROADMAP.md → the rest as needed.
For Claude Code: start at /CLAUDE.md (build phases + doc index).