EditTab.svelte was 589 lines against the 500-line hard limit in docs/10 §1 -- the one place in the codebase that broke it. Now 459. Extracted, in each case because the thing was genuinely cohesive rather than to hit a number: - src/lib/edit/edit-node.ts -- toEditNode, flattenTree, isEditable, resolveNewFolderParent, countDescendants, extraCopyIds. All pure, all previously inline and therefore untestable. resolveNewFolderParent in particular encodes a fixed bug (a focused root resolving to the synthetic root "0", which every create rejects) that nothing was pinning. - src/lib/browser/open-url.ts -- the docs/09 T3 scheme allowlist, which is the only thing between a crafted `javascript:` bookmark in someone's import file and the browser acting on it. It had NO test. It does now, including the case-shouting dodge and data:/file:/chrome:. - EditToolbar.svelte and MoveToDialog.svelte -- presentational, with their styles copied verbatim. This is a move, not a redesign. The script block is still 279 lines against docs/10 §1's 150-line guidance. The remainder is the mutation layer (guardEdit and the six operations), which is coupled to reactive state and would need accessor indirection to move. Adding that indirection to the app's delete paths immediately before a release is a worse trade than the line count, so it stays and is recorded in CLAUDE.md rather than quietly ignored. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
14 KiB
02 — Architecture
1. High-level shape
Two UI surfaces, no background service worker, one pure-logic core:
┌───────────────┐ opens ┌─────────────────────────────────┐
│ Popup (mini) │ ─────────────▶ │ Manager (full-tab SPA) │
│ 3 actions │ │ #import #export #edit │
└───────────────┘ │ #settings #about (+ LegalGate) │
└───────────┬─────────────────────┘
│ calls
┌──────────────▼──────────────┐
│ src/lib/browser (adapters) │ chrome.bookmarks
│ thin async wrappers │ chrome.storage
└──────────────┬──────────────┘ chrome.i18n
│ uses
┌──────────────▼──────────────┐
│ src/lib/core (PURE TS) │ ← 90%+ test coverage
│ parse · serialize · dedupe │ ← zero browser APIs
│ diff · normalize · plan │
└─────────────────────────────┘
Why no background worker: every feature runs while an extension page is open. Long imports run in the Manager tab (popups die on blur — never run work there). Fewer moving parts, fewer review questions.
2. Directory layout (WXT conventions)
wxt.config.ts sets srcDir: 'src', so WXT resolves entrypoints/,
components/ and assets/ under src/, and its @ alias points at
src/ — i.e. @/lib/core/model → src/lib/core/model.ts.
(The WXT default, srcDir: '.', would put entrypoints/ at the repo root and
is incompatible with keeping library code under src/lib/.)
⚠️ publicDir must also be set explicitly — WXT resolves it against the
project root, not srcDir (resolve-config.mjs: path.resolve(root, publicDir ?? 'public')). Without publicDir: 'src/public' the build silently
omits _locales/ and icon/, and Chrome then refuses to load the extension
because __MSG_appName__ and the declared icons resolve to nothing. The build
log gives no warning — verify the output tree, not just the exit code.
bookmarkmagic/
├── CLAUDE.md # AI build instructions (root)
├── wxt.config.ts # srcDir + manifest + svelte module
├── biome.json / knip.json / tsconfig.json / vitest.config.ts
├── .nvmrc # 24
├── scripts/
│ ├── guard.mjs # canonical grep gate (08 §3), run by npm run guard
│ └── gen-icons.mjs # zero-dep placeholder PNG writer (16/32/48/128)
├── docs/ # this suite (00–15)
├── legal/ # EULA.md, DISCLAIMER.md, PRIVACY.md, THIRD_PARTY_NOTICES.md
├── src/
│ ├── public/
│ │ ├── icon/ # 16/32/48/128 png
│ │ └── _locales/{en,vi,ja}/messages.json # manifest-level strings only
│ ├── entrypoints/
│ │ ├── popup/ # index.html + App.svelte + main.ts
│ │ └── manager/ # index.html + App.svelte + main.ts (unlisted page)
│ ├── lib/
│ │ ├── core/ # PURE — see below
│ │ │ ├── model.ts # BookmarkNode, ImportPlan, Stats types
│ │ │ ├── parse/
│ │ │ │ ├── netscape-html.ts
│ │ │ │ ├── bm-json.ts
│ │ │ │ └── csv.ts
│ │ │ ├── serialize/
│ │ │ │ ├── netscape-html.ts
│ │ │ │ ├── bm-json.ts
│ │ │ │ ├── csv.ts
│ │ │ │ └── markdown.ts
│ │ │ ├── normalize-url.ts
│ │ │ ├── timestamps.ts
│ │ │ ├── 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-url.ts # http(s) allowlist before tabs.create (09 T3)
│ │ │ └── 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/ # edit-node, 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/
│ ├── tokens.css # CSS custom properties, themes
│ └── base.css
└── tests/
├── fixtures/ # real exports: chrome/edge/firefox/safari + malformed
└── unit/ # mirrors src/lib/core structure
3. Layer rules (enforced in review)
core/imports nothing frombrowser/,stores/, Svelte, orchrome.*. It may useDOMParser(available in extension pages). Tests provide it via jsdom, which is required rather than optional: the Netscape walk depends on HTML5 "generate implied end tags" (the<DL>nesting inside an unclosed<DT>) and on:scope > h3from an element root. jsdom uses parse5 and is spec-compliant on both; happy-dom implements neither reliably, so a suite run there would validate a DOM the browser never produces.11 §3carries a canary test so an environment swap fails loudly instead of silently.browser/may importcore/. Never the reverse.- Svelte components never call
chrome.*directly — always throughbrowser/wrappers (mockability + one place for error mapping). - Stores hold state; components render;
browser/performs effects. - One file = one responsibility. Format converters are one file per format per direction.
4. Core data model
// src/lib/core/model.ts
export interface BookmarkNode {
title: string;
url?: string; // undefined ⇒ folder
addDate?: number; // epoch SECONDS (normalized, see timestamps.ts)
lastModified?: number; // epoch SECONDS
toolbar?: boolean; // Netscape PERSONAL_TOOLBAR_FOLDER
children?: BookmarkNode[];
}
export interface ParseResult {
roots: BookmarkNode[]; // top-level nodes from the file
stats: TreeStats; // bookmarks, folders, maxDepth
warnings: ParseWarning[]; // tolerated anomalies (dropped ICON, bad dates…)
}
export type MergeMode = 'new-folder' | 'merge' | 'replace';
export interface PlanSegment {
rootId: string; // chrome folder id to write this subtree under
nodes: BookmarkNode[];
}
export interface ImportPlan {
mode: MergeMode;
dedupe: boolean;
segments: PlanSegment[]; // final, post-dedupe trees + their destinations
stats: {
toCreate: number; // total nodes across ALL segments (folders + bookmarks)
bookmarkCount: number; // bookmarks only — the "Import n bookmarks" button label
skippedExisting: number; // dropped because the URL is already in the browser
skippedInFile: number; // dropped because the URL repeats within the file
};
}
Why segments and not a single root. 03 §1 maps toolbar: true nodes to
Bookmarks Bar and everything else to Other Bookmarks, and Replace deletes the
children of both roots before writing. A single destination cannot express
that, and would leave the toolbar permanently empty after a Replace.
Segment construction per mode — spelled out so it is not left to interpretation:
| Mode | Segments |
|---|---|
new-folder |
Exactly one. rootId = Other Bookmarks; nodes = the single Imported <date> wrapper folder containing the whole parsed tree. toolbar is informational only (03 §1). |
merge / replace |
At most two. Subtrees rooted at a toolbar: true node → { rootId: <Bookmarks Bar> }; everything else → { rootId: <Other Bookmarks> }. A segment with no nodes is omitted, not emitted empty. |
stats.toCreate is the total across all segments — progress and the final
report keep one denominator and one done counter for the whole import
(05 §6).
Chrome root mapping (Chromium ids are stable): Bookmarks Bar = "1",
Other Bookmarks = "2", Mobile = "3". browser/bookmarks.ts resolves them
via getTree() rather than hardcoding — segment rootIds always come from
that resolution, never a literal — but tests may rely on these ids.
Note the live tree is not BookmarkNode. BookmarkNode is the file
model (no ids — core/ may not know about chrome.*, layer rule 1). Anything
touching the browser tree (#edit, the duplicate panel, live sync) works with
chrome.bookmarks.BookmarkTreeNode, which already carries id, parentId,
index. Export maps the latter down to the former (03 §2).
5. Manager routing
Hash-based, zero-dependency: #import (default) · #export · #edit ·
#settings · #about. A tiny route.svelte.ts store wraps
location.hash + hashchange. options_ui in the manifest points to
manager.html#settings (open_in_tab: true).
⚠️ Right-click → Options lands on #settings only when no Manager tab is
already open. With open_in_tab: true, Chrome opens the options page via
singleton-tab matching, which ignores the fragment — so if a Manager tab is
already sitting on #edit, Chrome just activates that tab and no navigation
occurs. Whether the view then switches depends entirely on route.svelte.ts
reacting to hashchange. A URL fragment in options_ui.page is also
undocumented (the Chrome reference defines the value as a path); it works in
current Chromium, so keep it, but treat it as behaviour to re-verify at each
submission (08 §8).
6. Popup → Manager handoff
browser/open-manager.ts:
browser.runtime.getContexts({ contextTypes: ['TAB'] })→ find an existing manager context (requires Chrome 116+; we target 120+).- Found →
browser.tabs.update(tabId, { active: true })+browser.windows.update(windowId, { focused: true })(notabspermission needed for these calls). - Not found →
browser.tabs.create({ url: browser.runtime.getURL('/manager.html') + hash }).
Popup may pass an intent (#import / #export / #edit) via the hash.
7. Error handling strategy
-
core/throws typed errors (BmParseError { code, line?, detail }). The code set is closed — add to this table before adding to the code:Code Raised when NOT_NETSCAPENo NETSCAPE-Bookmark-file-1doctype and no<DL>foundNOT_BM_JSONLeading {parses, butformat !== "bookmarkmagic"MALFORMED_JSONJSON.parsethrowsINVALID_NODEStructural check fails (missing/non-string title, non-stringurl,childrenon a bookmark)BAD_CSV_HEADERHeader row missing or columns not in the fixed order CSV_ROW_MISMATCHRow field count ≠ header field count UNKNOWN_FORMATdetect-format.tsmatched nothingFILE_TOO_LARGESize > MAX_FILE_BYTESTOO_MANY_NODESNode count > MAX_NODESTOO_DEEPNesting depth > MAX_DEPTHNon-fatal anomalies are
ParseWarnings, never errors — includingNO_BOOKMARKS(valid doctype, zero<DL>), dropped<DD>descriptions, ignoredICONattributes, and invalid timestamps. -
browser/addsBmBackupError { code }for the forced safety backup (03 §1step 6b) andBmAborted { done }for a cancelled write. -
browser/mapschrome.runtime.lastError/ promise rejections into typed results; never lets raw errors reach components. -
UI shows human-readable, localized messages + a copyable technical detail block (for GitHub issue reports).
-
The write queue is abortable (AbortController) and reports
{ done, total, currentPath }progress events.