From 355443ef6bd0b30244c7bb01140606a7e0238739 Mon Sep 17 00:00:00 2001 From: poli0981 <127664709+poli0981@users.noreply.github.com> Date: Wed, 18 Nov 2026 21:03:23 +0700 Subject: [PATCH] docs: specify Firefox (AMO) and Edge Add-ons support for v1.3.0 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Docs first, as CLAUDE.md requires; the code follows in this branch. - 08: the manifest per target (two packages from one source, MV3 for both); Firefox's gecko id, data-collection declaration, floor 140 and source-code submission; Edge takes the Chrome package unchanged. - 02 §4, 03 §1/§3, 04, 05 §10: Firefox's GUID roots and fourth root, the Bookmarks Menu (`root: "menu"`, unmarked entries routed into it on Firefox); separators recognised by type, kept out of the file model and shown as untouchable lines in #edit; the move index sent by each browser's own rule and checked against the reply; addresses Firefox refuses dropped before planning; separators a file holds counted. - 06/07: the About link follows the install; three strings that blamed Chrome for what every browser does are reworded; new keys listed. - 11: a Firefox flavour of the fake, and a manual pass on real Firefox and Edge (including Edge signed in with sync) before the first submissions. - 12/13: three store jobs, each in its own environment with only its own secrets and a four-package install; CWS API v2 (v1.1 died 2026-10-15); AMO and Edge runbooks for the first, manual uploads. - 09/14 and legal/: three stores named; a clarification, not a LEGAL_VERSION bump. Co-Authored-By: Claude Opus 5.5 --- docs/00_PROJECT_OVERVIEW.md | 11 ++++- docs/01_TECH_STACK.md | 9 ++-- docs/02_ARCHITECTURE.md | 21 +++++++- docs/03_DATA_FLOW.md | 45 +++++++++++++++-- docs/04_FILE_FORMATS.md | 33 ++++++++++--- docs/05_ALGORITHMS.md | 25 +++++++--- docs/06_UI.md | 22 +++++++-- docs/07_I18N.md | 19 ++++++++ docs/08_MV3_COMPLIANCE.md | 85 ++++++++++++++++++++++++++++++-- docs/09_SECURITY_PRIVACY.md | 9 +++- docs/11_TESTING.md | 52 ++++++++++++++++++++ docs/12_CI_CD.md | 77 +++++++++++++++++++++-------- docs/13_RELEASE_PUBLISHING.md | 91 ++++++++++++++++++++++++++++++++++- docs/14_LEGAL_GATE.md | 12 ++++- legal/DISCLAIMER.md | 10 ++-- legal/EULA.md | 7 +-- legal/PRIVACY.md | 23 ++++++--- 17 files changed, 480 insertions(+), 71 deletions(-) diff --git a/docs/00_PROJECT_OVERVIEW.md b/docs/00_PROJECT_OVERVIEW.md index 4e65ce0..b2d00d3 100644 --- a/docs/00_PROJECT_OVERVIEW.md +++ b/docs/00_PROJECT_OVERVIEW.md @@ -126,6 +126,12 @@ v1.0's scope): - A redesigned UI with a self-drawn icon set, all motion behind `prefers-reduced-motion` (`06`). +**v1.3.0 adds** two stores: **Firefox Add-ons** (its own package from the same +source — the Bookmarks Menu as a fourth root, separators shown and protected, +Firefox's own move-index rule, `02 §4`, `03`) and **Microsoft Edge Add-ons** +(the Chromium package, unchanged). Release automation for all three stores, +each off until its owner switches it on (`12 §3`). + **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 @@ -222,7 +228,10 @@ Derived identifiers (canonical across docs and code): the four is already known — `CHROME_EXTENSION_ID` is the item id in §9. The other three come from `npx wxt submit init` (`12 §3`). Note there is no dry-run: the first time that step executes it makes a real submission. -7. **Untested:** `npm run dev:firefox`. No gate exercises it (Firefox is a +7. ~~**Untested:** `npm run dev:firefox`.~~ Since v1.3.0 the Firefox package is + built and checked by CI and the release (`12 §2.1`, `12 §2.3`) and its logic + is tested against a Firefox-shaped fake (`11 §4`). Still ⚠️: nothing has run + it in a real Firefox until the owner's `11 §5` pass. Historical text: No gate exercises it (Firefox is a non-goal, §7). The `overrides` block that used to threaten it is gone (`09 §3.1`), but do not assume it works. 8. **Unmeasured:** the 2 s parse budget on a real browser (`11 §6`). The diff --git a/docs/01_TECH_STACK.md b/docs/01_TECH_STACK.md index 1c8300b..879651d 100644 --- a/docs/01_TECH_STACK.md +++ b/docs/01_TECH_STACK.md @@ -10,7 +10,8 @@ | Item | Choice | Rationale | |---|---|---| -| Browser | Chrome / Chromium, **Manifest V3** | MV2 is fully retired. Edge/Brave/Vivaldi/Opera work from the same build. | +| Browser | Chrome / Chromium, **Manifest V3** — and since v1.3.0 **Firefox**, MV3 too | MV2 is fully retired. Edge/Brave/Vivaldi/Opera run the Chromium package; Edge Add-ons publishes that same package (`08 §10`). Firefox gets its own package from the same source (`wxt build -b firefox`, MV3 forced by `manifestVersion: 3`, `08 §9`). | +| Min Firefox | `strict_min_version: "140.0"` (since v1.3.0) | The first Firefox that accepts `data_collection_permissions`, which AMO requires of new extensions; every ES2025 built-in is older (134). Vite targets `firefox140` for that package. Desktop only — Firefox for Android has no `bookmarks` API. | | Min Chrome | `minimum_chrome_version: "136"` (was `"120"` through v1.0.1) | The ES2025 floor: 136 is the first Chrome with every ES2025 built-in (`RegExp.escape` 136, `Float16Array` 135, `Promise.try` 128, iterator helpers and Set methods 122). The manifest floor, Vite's `build.target` (`chrome136`) and tsconfig's `lib: ["ES2025", …]` are one number stated three times — `wxt.config.ts` derives two of them from `CHROME_FLOOR`, and `tests/unit/manifest.test.ts` pins all three. Users on Chrome 120–135 keep the version they have and stop receiving updates; nothing is uninstalled. `scheduler.yield()` (129+) is now always present, though the write queue keeps its fallback because the test environment has no `scheduler`. | | Runtime deps | **0 (zero)** | `DOMParser`, `Blob`, `URL`, `showSaveFilePicker` and `navigator.clipboard` cover all needs. "Zero" means no npm `dependencies`: the compiled Svelte runtime still ships inside the bundle — see `legal/THIRD_PARTY_NOTICES.md`. | @@ -60,7 +61,9 @@ "scripts": { "postinstall": "wxt prepare", // generates .wxt/tsconfig.json — 10 §2 extends it "dev": "wxt", - "dev:firefox": "wxt -b firefox", // build sanity only, no store release + "dev:firefox": "wxt -b firefox", // MV3 since v1.3.0 (manifestVersion: 3) + "build:firefox": "wxt build -b firefox", // .output/firefox-mv3 + "zip:firefox": "wxt zip -b firefox", // the AMO package + its sources archive "build": "wxt build", "zip": "wxt zip", "check": "svelte-check --tsconfig ./tsconfig.json --fail-on-warnings && tsc --noEmit && tsc -p tsconfig.scripts.json", @@ -76,7 +79,7 @@ "test:watch": "vitest", "coverage": "vitest run --coverage", "verify": "npm run lint && npm run check && npm run knip && npm run guard && npm run check:licenses && npm run test", - "verify:full": "npm run verify && npm run coverage && npm run build && npm run check:manifest" + "verify:full": "npm run verify && npm run coverage && npm run build && npm run check:manifest && npm run build:firefox && npm run check:manifest -- --browser firefox" } } ``` diff --git a/docs/02_ARCHITECTURE.md b/docs/02_ARCHITECTURE.md index 39c3653..d7c1631 100644 --- a/docs/02_ARCHITECTURE.md +++ b/docs/02_ARCHITECTURE.md @@ -174,7 +174,7 @@ export interface BookmarkNode { addDate?: number; // epoch SECONDS (normalized, see timestamps.ts) lastModified?: number; // epoch SECONDS toolbar?: boolean; // Netscape PERSONAL_TOOLBAR_FOLDER - root?: 'other' | 'mobile'; // folder IS that browser root (since v1.1.0; toolbar wins) + root?: 'other' | 'mobile' | 'menu'; // folder IS that browser root (since v1.1.0; 'menu' since v1.3.0; toolbar wins) children?: BookmarkNode[]; } @@ -220,7 +220,7 @@ Segment construction per mode — spelled out so it is not left to interpretatio | Mode | Segments | |---|---| | `new-folder` | Exactly one. `parentId` = Other Bookmarks; `nodes` = the single `Imported ` wrapper folder containing the whole parsed tree, root folders included. Markers are informational only (`03 §1`). | -| `merge` | Top-level nodes are routed first (`core/route.ts`, `03 §1` step 7): a `toolbar` folder's children → the bar; a `root: "other"` folder's children → Other, in its place in the order; a `root: "mobile"` folder's children → Mobile (an ordinary folder under Other when the profile has no Mobile root); everything else → Other. Each root's list is then matched against that root's live children (`core/merge.ts`, `05 §5`): a folder with the exact title of a writable live child folder is **reused** — not created — and its children are matched one level down; everything else becomes a node in the segment of the live folder it lands in. One segment per live folder that receives anything, in first-use order. | +| `merge` | Top-level nodes are routed first (`core/route.ts`, `03 §1` step 7): a `toolbar` folder's children → the bar; a `root: "other"` folder's children → Other, in its place in the order; a `root: "mobile"` folder's children → Mobile (an ordinary folder under Other when the profile has no Mobile root); a `root: "menu"` folder's children → the Bookmarks Menu (an ordinary folder under Other where there is none — every Chromium browser); everything else → the Bookmarks Menu where the browser has one (Firefox — what Firefox's own HTML import does with loose entries), else Other. Each root's list is then matched against that root's live children (`core/merge.ts`, `05 §5`): a folder with the exact title of a writable live child folder is **reused** — not created — and its children are matched one level down; everything else becomes a node in the segment of the live folder it lands in. One segment per live folder that receives anything, in first-use order. | | `replace` | As `merge`, but planned against **emptied** roots, so nothing matches and every node is created. | A root nothing is bound for gets no segment. `stats.toCreate` is the total @@ -229,6 +229,18 @@ one `done` counter for the whole import (`05 §6`). Every node is accounted for: `toCreate + reusedFolders + unwrapped root folders` equals the deduped tree (asserted over 200 random trees in `merge.test.ts`). +**Firefox (since v1.3.0).** Firefox has no `folderType`, its roots are GUIDs — +`menu________`, `toolbar_____`, `unfiled_____`, `mobile______`, in that order — +and it has a fourth root Chromium lacks, the **Bookmarks Menu**. `getRoots()` +tries those GUIDs after the Chromium ids and before position, so the position +fallback (which on Firefox would take the Menu for the bar) is never reached, +and returns the Menu as a fourth destination that Replace also empties. +**Separators** exist only in Firefox's live tree: `type: "separator"` and, for +historical reasons, `url: "data:"`. They are recognised by `type`, never by +the url; `toBookmarkNodes` drops them, so the file model never holds one, and +`#edit` shows them as lines no command can touch (`03 §3`). Counting helpers +in `browser/bookmarks.ts` keep them out of every bookmark count. + Chrome root mapping: `browser/bookmarks.ts` `getRoots()` resolves the three destinations by `folderType` (`bookmarks-bar`, `other`, `mobile`, Chrome 134+), among this device's roots only — a signed-in account's own roots @@ -240,6 +252,11 @@ that fails do Mobile-marked folders land under Other. Segment `parentId`s always come from that resolution or from live folders found in the same read, never a literal — but tests may rely on the ids. +**Address length inside the browser.** Firefox refuses an address longer than +65 536 characters (and shortens titles past 4 096). The import drops such +addresses before planning, as `URL_TOO_LONG`, using a limit the browser layer +passes in — Chromium has none, so nothing changes there (`03 §1`). + **Depth inside the browser** is capped separately from the parse cap: `MAX_WRITE_DEPTH` (90 levels below a root). Chrome stores its bookmarks as JSON it reads back with a 200-level nesting limit, two levels per folder, so a tree diff --git a/docs/03_DATA_FLOW.md b/docs/03_DATA_FLOW.md index 910f33a..afb942b 100644 --- a/docs/03_DATA_FLOW.md +++ b/docs/03_DATA_FLOW.md @@ -45,7 +45,12 @@ - Steps 1–7 touch nothing in the browser. The first write happens at step 8. - Replace = delete children of Bookmarks Bar + Other Bookmarks (+ Mobile if - present), then write. Roots themselves are never deleted (API forbids it). + present, + the Bookmarks Menu on Firefox), then write. Roots themselves are + never deleted (API forbids it). On Firefox the deletion includes the + **separators** in those roots, and nothing restores them — no format + BookmarkMagic writes keeps one — so the confirmation says how many will go + (`import.replace.separators`, shown only when there are any). The counts in + that confirmation never include separators among the bookmarks. - **Root routing** (`core/route.ts`), top-level nodes only — deeper, markers are data. A folder that *is* a browser root is **unwrapped**: its children go into that root and the folder itself is never written. @@ -55,7 +60,15 @@ the order; - `root: "mobile"` folder → its children into Mobile Bookmarks; a profile with no Mobile root keeps it as an ordinary folder under Other; - - everything else → Other Bookmarks. + - `root: "menu"` folder (since v1.3.0) → its children into Firefox's + Bookmarks Menu; every Chromium browser, which has no menu root, keeps it + as an ordinary folder under Other; + - everything else → the **Bookmarks Menu on Firefox**, Other Bookmarks + everywhere else. Firefox's own HTML export leaves the menu's contents loose + at the top level, and Firefox's own import puts loose entries back into + the menu; doing the same is what makes a Firefox file round-trip in + Firefox. New-folder mode is not routing and stays the same on every + browser: `Other Bookmarks/Imported /…`. The markers come from our own exports and backups (`04 §1.1`, §2), from Firefox's HTML export (`UNFILED_BOOKMARKS_FOLDER`), and from the two browser @@ -65,6 +78,13 @@ the whole tree, root folders included, goes under `Other Bookmarks/Imported /…` (markers recorded in the preview as informational). +- **What Firefox refuses is dropped before planning** (since v1.3.0): an + address longer than 65 536 characters (`URL_TOO_LONG`, counted; the limit + comes from the browser layer, and Chromium has none). Firefox also shortens + titles past 4 096 characters on its own; that is a documented limit, not a + warning. Separators a file holds — `
` in HTML, separator entries in a + Firefox JSON backup — are counted as `SEPARATORS_SKIPPED`: the file model has + no separator, on any browser. - **Merge reuses folders** (`core/merge.ts`, `05 §5`). Below each destination root, a file folder with the exact, case-sensitive title of a writable child folder of the live folder its parent matched is reused — never created, @@ -193,14 +213,31 @@ tree key was ignored. | Move | drag & drop onto a row — before, after or into (`planDrop`, `05 §10`) → `bookmarks.move(id, { parentId, index })`, or `{ parentId }` alone into a folder; "Move to…" (row button, menu key / Shift+F10) → modal folder list with a filter → `bookmarks.move(id, { parentId })`, appended; **Alt+↑ / Alt+↓** on the tree (since v1.2.1) → `nudgeTarget` picks the sibling shown above or below, then the same `planDrop` (before / after) and the same `moveTo` as a drag — no second write path. One move at a time. The command reports the row's new place among the siblings on screen — the same "n of m" as its `aria-posinset` — which the tab speaks (`06 §5`) | | Delete | Del or the row button → confirm dialog (folder shows descendant count) → `removeTree` / `remove`; when the deleted row had focus, focus moves to the next row, else the previous. A copy deleted from the duplicate panel leaves the tree's focus where it was | | New folder | toolbar button → `bookmarks.create({ parentId, title })` in the focused folder, beside a focused bookmark, else in the first writable root → inserted at once unless its live event got there first (Chrome fires `onCreated` before `create` resolves, so either may win), a search that would hide it cleared, and every folder above it opened as the user's own — so clearing the search cannot close them again → inline rename | -| Sort A→Z | toolbar (the focused folder, or the focused bookmark's folder) or a folder row's button → `planSort` (`05 §10`) → confirm stating how many items move → one awaited `bookmarks.move(id, { parentId, index })` per planned move, yielding every 25, under the write lock (§5). Refused part-way → "moved d of t" and a re-read: there is no undo | +| Sort A→Z | toolbar (the focused folder, or the focused bookmark's folder) or a folder row's button → `planSort` (`05 §10`; on Firefox each run between two separators is sorted on its own, and separators stay where they are) → confirm stating how many items move → one awaited `bookmarks.move(id, { parentId, index })` per planned move, yielding every 25, under the write lock (§5). Refused part-way → "moved d of t" and a re-read: there is no undo | | Open bookmark | Enter, double-click, or the row's Open button → `tabs.create({ url })` for `http:`/`https:` only (`09` T3); anything else is refused with a toast | | Copy link | the row button, or Ctrl/⌘+C on the focused row → `navigator.clipboard.writeText` (`09` T8) | | Duplicate finder | toolbar toggles the panel → groups by normalized URL, computed **only while the panel or its confirmation is showing**, policy-managed copies left out (the browser refuses to delete them) → per-copy delete, or "keep first in each group" (confirm with the exact count) under the write lock; stopped part-way → "deleted d of t" and a re-read | +**Separators (Firefox, since v1.3.0)** are rows of their own in the tree: a +line at the depth of its siblings, outside the accessibility tree +(`aria-hidden`), never focused, matched, counted, opened, renamed, deleted, +dragged or dropped into — and never offered as a duplicate of each other, +which their shared `data:` address would otherwise make them. They are still +siblings, so positions stay the browser's: a drag lands where it was dropped, +and Alt+↑ above a separator moves the row past it, one place. + +**The move index is the browser's own rule.** `planDrop` computes a target +twice (`05 §10`): Chromium's `bookmarks.move` counts a move to the right as if +the node were still in place (`position.api`), Firefox's counts after removing +it (`position.local`). The adapter sends the one its browser expects, and the +move's own reply (the node's new `index`) is checked against `position.local`: +a mismatch re-reads the tree rather than leave it disagreeing with the browser. + **Live sync** (`edit/live-sync.ts`, `05 §11`). `#edit` subscribes on enter and unsubscribes on leave: `bookmarks.onCreated/onRemoved/onChanged/onMoved`, plus -`onChildrenReordered` and Chrome's own importer's `onImportBegan/onImportEnded`. +`onChildrenReordered` and Chrome's own importer's `onImportBegan/onImportEnded` +where the browser has them (Firefox has neither; its own sort and import send +one `onMoved`/`onCreated` per node, which the burst rule below absorbs). Events are queued and applied together **once per animation frame**, in arrival order. An import running in another tab sends one `onCreated` per node — 1.0.x patched the tree, and rescanned it for duplicates, on every one — so past 500 diff --git a/docs/04_FILE_FORMATS.md b/docs/04_FILE_FORMATS.md index 2dd5970..db5bd0b 100644 --- a/docs/04_FILE_FORMATS.md +++ b/docs/04_FILE_FORMATS.md @@ -84,6 +84,16 @@ winning: | Bookmarks Bar | `PERSONAL_TOOLBAR_FOLDER="true"` | every browser | | Other Bookmarks | `UNFILED_BOOKMARKS_FOLDER="true"` | Firefox (its own exporter writes it), and us | | Mobile Bookmarks | `MOBILE_BOOKMARKS_FOLDER="true"` | us — importers ignore attributes they do not know | +| Bookmarks Menu (Firefox) | *none* — its contents are written **loose at the top level** | every browser, the way Firefox's own exporter writes it (since v1.3.0) | + +The Bookmarks Menu has no attribute of its own in Firefox's format: Firefox +exports the menu's entries as the file's top level and imports loose +top-level entries back into the menu. A BM JSON `root: "menu"` folder (§2) +is therefore written to HTML by unwrapping it — its children appear at the +top level, before the marked roots — and reading that file in Firefox puts +them back where they were (`03 §1`). Chromium has no menu root, so in Chrome +or Edge those entries land in Other Bookmarks, as they do from Firefox's own +export. ### 1.2 Parse tolerance (import) @@ -116,7 +126,11 @@ Must accept, with a warning where noted: space in the host) → skipped, `INVALID_URL`, because `chrome.bookmarks.create` rejects it mid-write, after a Replace has already cleared the tree; Firefox `place:` smart bookmarks → skipped, `PLACE_QUERIES_SKIPPED` (Chrome's own - importer drops them too; in Chrome they are dead links). `javascript:`, + importer drops them too; in Chrome they are dead links, and on Firefox + BookmarkMagic still does not write them — the notice says "skipped", not + "dead", since v1.3.0). On Firefox, an address longer than 65 536 characters + → skipped before planning, `URL_TOO_LONG` (applied after parsing, with the + limit the browser layer passes in, so every format is covered by one rule). `javascript:`, `data:` and `file:` addresses are kept verbatim (`09` T3). Fixture: `weird/invalid-urls.html`. - **Empty titles are kept empty** (since v1.1.0), counted as `EMPTY_TITLE`. @@ -146,8 +160,11 @@ Must accept, with a warning where noted: The older `chrome-131-export.html` wraps them in an `Other bookmarks` folder that Chrome itself never writes; it is kept as a third-party shape, not as a record of Chrome. -- `
` separator elements (Firefox) → skipped, no warning. These are - *elements*, so "unknown attributes ignored" does not cover them. +- `
` separator elements (Firefox) → skipped and **counted**, + `SEPARATORS_SKIPPED` (no warning until v1.3.0; once Firefox users could + import, a silent loss stopped being acceptable). These are *elements*, so + "unknown attributes ignored" does not cover them. The file model has no + separator: none of the four formats BookmarkMagic writes carries one. - Empty folders → preserved. - **Root list selection.** Do **not** pick a single root `
` — `document.querySelector('dl')` and "the outermost `
`" are both lossy. @@ -214,9 +231,9 @@ not an anomaly, and must not raise a warning (`05 §4`). omit `children` (⇒ empty). Unknown extra keys are ignored on import (forward compatibility); `version > 1` → warning "newer file, best-effort"; an absent `version` is read as 1. -- `"root": "other" | "mobile"` (since v1.1.0, folders only, never beside - `"toolbar"`) marks a folder that IS that browser root — the JSON form of - §1.1's markers. Additive: v1 readers ignore unknown keys, so the version stays +- `"root": "other" | "mobile" | "menu"` (since v1.1.0; `"menu"`, Firefox's + Bookmarks Menu, since v1.3.0; folders only, never beside `"toolbar"`) marks a + folder that IS that browser root — the JSON form of §1.1's markers. Additive: v1 readers ignore unknown keys, so the version stays 1, and a 1.0.x reader simply nests as before. - **Legacy backups.** A 1.0.x safety backup has exactly the shape of a Chromium profile — `generator` `BookmarkMagic 1.0.x`, no `root` keys, three top-level @@ -309,7 +326,9 @@ item — `15`). One line of `JSON.stringify` output: ``` - Nodes: `type` `text/x-moz-place` (bookmark: `title`, `uri`), `…-container` - (folder: `title`, `children`), `…-separator` (skipped silently, as `
` is). + (folder: `title`, `children`), `…-separator` (skipped and counted, + `SEPARATORS_SKIPPED`, as `
` is — so a backup and its HTML twin still + give the same result, which the parity rule requires). A node with no `type` falls back to `typeCode` 1/2/3. Dates are **PRTime** — integer microseconds since the Unix epoch — converted explicitly and truncated, as Firefox's own HTML export does (`microsToSeconds`). diff --git a/docs/05_ALGORITHMS.md b/docs/05_ALGORITHMS.md index 0c96f84..c3b596d 100644 --- a/docs/05_ALGORITHMS.md +++ b/docs/05_ALGORITHMS.md @@ -335,11 +335,22 @@ froze the tab. ## 10. Reordering — `edit/sort.ts`, `edit/move-target.ts` -Both write through `chrome.bookmarks.move`, whose index has one trap: **within -one parent, a move to the right counts the target index as if the node were -still in place**, while `onMoved` — and `patch-tree`'s `moveNode` — count after -its removal. Moving `a` after `c` in `[a, b, c]` is `move(a, { index: 3 })`, and -`onMoved` then reports index 2. A move to the left needs no adjustment. +Both write through `bookmarks.move`, whose index has one trap, and it is not +the same trap in every browser. **Chromium**: within one parent, a move to the +right counts the target index as if the node were still in place, while +`onMoved` — and `patch-tree`'s `moveNode` — count after its removal. Moving `a` +after `c` in `[a, b, c]` is `move(a, { index: 3 })`, and `onMoved` then reports +index 2. **Firefox** (since v1.3.0) counts after removal in the call too — +`move(a, { index: 2 })` — as Places stores the final position. A move to the +left is the same number in both. `planDrop` returns both numbers; the adapter +(`browser/bookmarks.ts` `move`) sends `api` to Chromium and `local` to Firefox, +and compares the node's index in the call's reply with `local`, re-reading the +tree on a mismatch (`03 §3`). + +**Separators** (Firefox) are children like any other here: they occupy +indices, `planDrop` may place a node before or after one, and Alt+↑/↓ steps +past one as a single place. They are never a drop target *into*, and Sort A→Z +leaves them where they are and sorts each run between them on its own. **Sort A→Z** (`planSort`), planned before anything moves so the confirmation can state the number: @@ -347,7 +358,9 @@ can state the number: ``` sortedOrder(children, locale): collator = Intl.Collator(locale, { numeric: true, sensitivity: 'base' }) - stable sort: folders before bookmarks, then collator.compare(key), then current position + split children into runs at each separator (Firefox; Chromium has none — one run) + each run: stable sort, folders before bookmarks, then collator.compare(key), then current position + result = run₀ sorted, separator₀, run₁ sorted, separator₁, … — every separator keeps its index key(node) = node.title — or the URL, for a bookmark whose title is blank (as Chrome shows it) planSort(children, locale): diff --git a/docs/06_UI.md b/docs/06_UI.md index ecd31f5..9b6d542 100644 --- a/docs/06_UI.md +++ b/docs/06_UI.md @@ -363,7 +363,7 @@ behind a `` (six preferences is enough to be worth a confirm). ``: logo, name, version (from manifest at runtime), tagline; links: **GitHub repo ↗** · Report an issue ↗ · Changelog ↗ · Accessibility ↗ · -Chrome Web Store ↗; +Store listing ↗; **Third-party code:** no runtime dependencies are installed, and the two MIT-licensed pieces the build compiles in are named — the Svelte runtime and WXT's one-line browser shim — with their notices shipped in the package as @@ -392,9 +392,15 @@ use a screen has no other route from inside the product to either, and the tree's keys are shown nowhere in the UI. The same test pins its URL and the file's existence. -"Chrome Web Store" points at the published listing (item id in `00 §9`), added -once the item went public. It is the only route a user has from inside the -product to rate or review it, which `13 §6` depends on. +"Store listing" points at the listing the running copy came from — it is the +only route a user has from inside the product to rate or review it, which +`13 §6` depends on. Since v1.3.0 one package serves the Chrome Web Store and +Edge Add-ons, so the link is chosen at run time (`links.ts` `storeUrlFor`): +the Firefox build → the AMO listing, addressed by the gecko id; a Chromium +copy whose `runtime.id` is the Chrome Web Store item id (`00 §9`) → that +listing; anything else — an Edge Add-ons install, an unpacked build → the +README's install section, which lists every store. The label was "Chrome Web +Store" until then. **No email address appears anywhere in the product.** Since v1.1.0 the project's addresses are per purpose (`security@` in `SECURITY.md`, `privacy@` in @@ -485,6 +491,14 @@ held failures at the head of the one queue instead, and every later toast — the panel's close button, the delete buttons having gone with the copies. After a confirmed **Sort A→Z** from the toolbar — whose button is disabled while the sort runs, which is what dropped it — focus goes to the tree. +- **Separators (Firefox, since v1.3.0)** render as a line inside a + `role="none"`, `aria-hidden` list item between the `treeitem`s, so the tree + still owns only tree items. They take no focus, so ↑/↓, Home/End and + type-ahead pass over them, and `aria-posinset`/`aria-setsize` count the + items around them, not the separators. Alt+↑/↓ does step past one, one place + at a time, as a drag would — and since the separator is not counted, the + spoken "position n of m" does not change on that step. A known limitation + (`ACCESSIBILITY.md`): a screen reader is not told where the separators are. - **The tree says what Alt+↑/↓ did.** One always-present polite live region in the tab speaks ": position n of m" after each move — n and m being the row's own `aria-posinset` and `aria-setsize`, so under a search they diff --git a/docs/07_I18N.md b/docs/07_I18N.md index 8e4e2af..6e792fe 100644 --- a/docs/07_I18N.md +++ b/docs/07_I18N.md @@ -229,6 +229,25 @@ stay raw. (`00 §10`), and translation reports arrive through `.github/ISSUE_TEMPLATE/translation.yml`. +### Browser-neutral wording (since v1.3.0) + +Since the same strings run in Chrome, Edge and Firefox, a sentence may name a +browser only when it is about that browser's own thing — "Chrome's Bookmarks +file", "Firefox JSON backups", "Firefox smart bookmarks". A sentence about what +"the browser" does or allows says "the browser". v1.3.0 reworded the three +that were not true everywhere, in all five languages: + +| Key | Was | Is | +|---|---|---| +| `import.dateNotice` | "Chrome does not let an extension set…" | "The browser does not let an extension set…" | +| `about.store` | "Chrome Web Store listing" | "Store listing" (the URL follows the install, `06 §3.5`) | +| `warnings.PLACE_QUERIES_SKIPPED` | "…skipped — here they would be dead links." | "…skipped." (on Firefox they are not dead links; BookmarkMagic still does not write them) | + +and added, with Romanian's `few` form where a count is involved (§5): +`warnings.URL_TOO_LONG`, `warnings.SEPARATORS_SKIPPED` and +`import.replace.separators`. The JA, ZH-CN and RO versions are best-effort and +carry the usual `TODO(review-…)` marker. + ## 5. Locale-sensitive edge cases - **Pluralization.** A plural key is an object of CLDR plural forms. Every diff --git a/docs/08_MV3_COMPLIANCE.md b/docs/08_MV3_COMPLIANCE.md index d4c6384..a1bb2dd 100644 --- a/docs/08_MV3_COMPLIANCE.md +++ b/docs/08_MV3_COMPLIANCE.md @@ -1,6 +1,9 @@ -# 08 — Manifest V3 & Chrome Web Store Compliance +# 08 — Manifest V3 & Store Compliance -Goal: pass review fast and stay listed. Every item here is a hard requirement. +Goal: pass review fast and stay listed — on the Chrome Web Store, Firefox +Add-ons (AMO) and Microsoft Edge Add-ons. Every item here is a hard +requirement. §1–§8 were written for Chrome and still hold for every store; +§9 (Firefox) and §10 (Edge) add what differs. ## 1. Manifest (generated by WXT from `wxt.config.ts`) @@ -20,6 +23,18 @@ export default defineConfig({ }); ``` +Since v1.3.0 the manifest is a function of the target browser (`wxt.config.ts`, +`manifestVersion: 3` for every target — WXT would otherwise build Firefox as +MV2). Two packages are built from one source: + +| Package | For | Differs from the above | +|---|---|---| +| `bookmarkmagic-X.Y.Z-chrome.zip` (`.output/chrome-mv3`) | Chrome Web Store **and Microsoft Edge Add-ons** | nothing — this is the manifest above (§10) | +| `bookmarkmagic-X.Y.Z-firefox.zip` (`.output/firefox-mv3`) + `…-sources.zip` | Firefox Add-ons | no `minimum_chrome_version`; adds `browser_specific_settings.gecko` (§9) | + +Permissions, CSP, pages and icons are **identical** in both; `check:manifest` +holds each package to its own exact key set (§3, layer 2). + ## 2. Permissions — justification table (paste into CWS review notes) | Permission | Justification (single purpose) | @@ -97,7 +112,8 @@ governed by a page CSP and is not a request the extension makes (`09 §1`). #### Layer 2 — the built-artifact gate `npm run check:manifest` (`scripts/check-manifest.mjs`) scans every `.js` file -in `.output/chrome-mv3` for the network identifiers the source gate bans, as +in `.output/chrome-mv3` — and, with `--browser firefox`, in `.output/firefox-mv3` +(since v1.3.0, each against its own key set, §1) — for the network identifiers the source gate bans, as bare words — including code that arrived through a dependency, which no source gate can see — and pins the manifest: MV3, the permission list, the exact key set, the Chrome floor, the exact CSP, that every file the manifest and the @@ -205,3 +221,66 @@ any of them changes (`09 §4`). - [ ] Privacy tab answers unchanged, or updated + re-certified. - [ ] Store listing screenshots regenerated if the UI changed (`scripts/screenshots.mjs --shoot` — `13 §2`). +- [ ] Firefox: `check:manifest --browser firefox` passes; the gecko id is + still `bookmarkmagic@poli0981.dev`; the sources zip and `BUILD.md` + rebuild the package (§9). +- [ ] Edge: the package uploaded is the Chrome Release asset (§10). + +## 9. Firefox Add-ons (AMO) — since v1.3.0 + +```ts +browser_specific_settings: { + gecko: { + id: 'bookmarkmagic@poli0981.dev', // permanent after the first AMO upload + strict_min_version: '140.0', + data_collection_permissions: { required: ['none'] }, + }, +}, +``` + +- **The id is permanent.** AMO requires one for MV3 and never lets it change; + every installed copy and every update is tied to it. It is an id, not a + mailbox, and no page of the extension shows it (`15`, 2026-11-18). +- **`data_collection_permissions: { required: ['none'] }`** is Firefox's own + consent system, mandatory for new extensions since 2025-11-03. "None" is the + accurate answer for the same reason §5's privacy answers are "No": nothing is + collected or transmitted. Changing it is the Firefox equivalent of changing + the CWS privacy tab — a minor-version event (`09 §4`). +- **Floor: Firefox 140** — the first release that understands + `data_collection_permissions` (older ones reject the key), and above every + ES2025 built-in the code relies on (`RegExp.escape` and `Promise.try` are + 134). Vite's `build.target` for this package is `firefox140`, the + counterpart of `chrome136`. Like the Chrome floor, never raise it in a patch. +- **Desktop only.** Firefox for Android has no `bookmarks` API, so the + manifest declares no `gecko_android` and the listing and every API upload + declare Firefox desktop compatibility only. +- **The extension-page CSP is the same string**, in MV3's object form, and + Firefox enforces it the same way; `check:manifest` pins it in both packages. +- **No background script** on Firefox either, so Firefox's MV3 event-page + model never comes into it. +- **Source code is part of every submission.** The bundle is minified, so AMO + requires the sources and instructions that rebuild the same files. `wxt zip + -b firefox` writes `…-sources.zip` beside the package (dotfiles excluded — + `.nvmrc` among them, so the instructions state Node 26 explicitly), and + `/BUILD.md` is those instructions. AMO's reviewers build on their own + machine and diff the result against the uploaded package. +- **Obfuscation is prohibited** on AMO too; minification is allowed. +- What the code does differently on Firefox — the roots, the separators, the + move index — is `02 §4`, `03 §1` and `05 §10`; none of it is a manifest + matter. + +## 10. Microsoft Edge Add-ons — since v1.3.0 + +- **The Chrome package, unchanged.** Edge accepts Chrome's MV3 manifest keys, + `minimum_chrome_version` included (Edge versions follow Chromium's, so + 136 means Edge 136). The zip uploaded to Edge is the same Release asset as + the Chrome one, with the same checksum. +- Partner Center rejects a listing whose name or description sells it as a + Chrome extension; the Edge listing copy (`13 §3`) is reworded to name + Chromium-based browsers where it has to mention Chrome's file format. +- Edge's bookmarks API is Chromium's: the same roots ("Favorites bar", "Other + favorites"), `folderType` included. Whether Edge marks the roots of a + signed-in, syncing profile with `syncing: true` — which would leave no + writable root (`NO_WRITABLE_ROOTS`) — is **unverified**; `11 §5` checks it + on a real Edge with sync on before the first submission. +- Privacy answers in Partner Center are §5's. diff --git a/docs/09_SECURITY_PRIVACY.md b/docs/09_SECURITY_PRIVACY.md index 2de325b..d053abe 100644 --- a/docs/09_SECURITY_PRIVACY.md +++ b/docs/09_SECURITY_PRIVACY.md @@ -177,8 +177,13 @@ a **minor-version** event at minimum. CRC32. The archives' SHA-256 hashes still differ, because `wxt zip` records file mtimes and nothing normalizes them (there is no `SOURCE_DATE_EPOCH` support). Do not claim byte-identical rebuilds. -- GitHub Releases attach the exact zip uploaded to CWS + `SHA256SUMS.txt` - so users can verify store build ↔ source correspondence. That works on the +- GitHub Releases attach the exact zips uploaded to the stores + `SHA256SUMS.txt` + (since v1.3.0: the Chrome package, which is also what Edge Add-ons receives, + the Firefox package and its sources archive) so users can verify store build + ↔ source correspondence. The stores re-sign or repackage what they receive + (Chrome and Edge into a signed CRX, AMO signs the XPI), so a file installed + from a store does not hash like the Release asset; the checksum vouches for + what was uploaded. That works on the released artifact itself, which is the same file in both places — it is not a claim that a third party can rebuild the same hash. - Tags are signed (GPG) — consistent with the tracker-repo signing practice. diff --git a/docs/11_TESTING.md b/docs/11_TESTING.md index 7c35263..b139e7b 100644 --- a/docs/11_TESTING.md +++ b/docs/11_TESTING.md @@ -189,6 +189,22 @@ Also in `tests/unit/browser/` (v1.1.0): code with its URL-bearing detail absent; crash hooks record names only, and stop after teardown. +**Firefox flavour (since v1.3.0).** There is no Firefox in CI, so +`tests/helpers/fake-bookmarks.ts` takes `{ flavour: 'firefox' }` and then +behaves the way Firefox's source says its API does +(`browser/components/extensions/parent/ext-bookmarks.js`, Places' +`Bookmarks.sys.mjs`): GUID roots in the order Menu, Toolbar, Other, Mobile, +all four always present; no `folderType`; separators as +`{ type: 'separator', url: 'data:' }`; a same-folder `move` that takes the +final position; no `onChildrenReordered` or `onImport*`; `get('3')` +rejected; addresses over 65 536 characters refused. The root, separator, move, +Replace and export suites run over both flavours (`describe.each`) — which is +also how the position fallback in `getRoots`, never reached by the Chromium +fake, got its first test. ⚠️ The fake is built from reading Firefox's source; +a sanitized `getTree()` dump from a real Firefox 140+ profile, committed as a +fixture the fake is checked against, would turn that reading into evidence +(`00 §10`). + ### #edit logic, stores, styles and scripts The components have no test framework (§1), so everything that can move out of @@ -445,6 +461,42 @@ failure mode that would hit every installed user at once. smoke it. This is the only check that the artifact users receive is the artifact that was tested (`13 §1b` step 10). +### Firefox and Edge (since v1.3.0) — before the first submission to each + +Firefox (140 or later; about:debugging → Load Temporary Add-on → +`.output/firefox-mv3/manifest.json`, on a profile you can afford to lose): + +- [ ] The four roots are where they belong: an import in Merge mode of a + BookmarkMagic HTML export puts the bar's entries in the **Bookmarks + Toolbar**, Other's in **Other Bookmarks**, loose entries in the + **Bookmarks Menu**; New-folder mode puts `Imported <date>` under Other + Bookmarks. +- [ ] **Replace, then restore the safety backup with Replace twice**: menu, + toolbar, Other and Mobile come back in their own roots, never nested; the + confirmation counted the separators it was about to delete and said they + would not come back. +- [ ] Export all four formats: no `data:` entry where a separator was; HTML + re-imports into Firefox with the menu restored; an import of Firefox's + own HTML export reports the separators it skipped. +- [ ] #edit: separators are lines that ↑/↓ and type-ahead skip; Alt+↑/↓ steps + past one; a drag before/after a row lands exactly there (the move-index + rule, `05 §10`); Sort A→Z leaves separators where they are; the + duplicate panel never lists separators. +- [ ] Replace's backup on Firefox goes through the **anchor download and the + "I have the backup" confirmation** (no `showSaveFilePicker`). +- [ ] About → "Store listing" opens the AMO listing; right-click → Options + lands on #settings (a second Manager tab here is expected, `08 §9`). +- [ ] The Manager in every language; Firefox's own locale fallback. + +Edge (the Chrome package, Load unpacked from `.output/chrome-mv3`): + +- [ ] **Signed in with sync on**: #edit loads and Merge writes — no + `NO_WRITABLE_ROOTS` (`08 §10`, unverified until this item is done). +- [ ] The Chrome items above that touch roots: Favorites bar / Other + favorites receive what Bookmarks bar / Other bookmarks would. +- [ ] About → "Store listing" opens the README's install section (the Edge + listing's address is not known until it exists). + ## 6. Performance budgets (checked manually in v1) - Parse 25 MB / 100k HTML file: < 2 s. diff --git a/docs/12_CI_CD.md b/docs/12_CI_CD.md index f1b7928..5b9ca82 100644 --- a/docs/12_CI_CD.md +++ b/docs/12_CI_CD.md @@ -68,8 +68,10 @@ Three jobs. The two whose names branch protection requires (§5) are `a11y_*` checks a gate, `10 §3` — then the TS 7 `tsc`), `knip`, `coverage` (`11 §1` thresholds), `guard` (`08 §3`), `check:licenses` (every licence in the lockfile, `09 §3.2`), `npm audit --omit=dev --audit-level=low` (the - zero-runtime-dependencies claim, `09 T5`), `build`, `check:manifest`. The last - two exist because the unit test over `wxt.config.ts` proves what we *asked* + zero-runtime-dependencies claim, `09 T5`), `build`, `check:manifest`, and since + v1.3.0 `build:firefox` + `check:manifest -- --browser firefox` — the second + package, held to its own key set (`08 §1`, `08 §9`). The build/check pairs + exist because the unit test over `wxt.config.ts` proves what we *asked* for and only the built manifest proves what WXT *emitted* — a dev build of the same config carries `tabs`/`scripting`/`host_permissions`. - **`windows` — "Windows smoke (guard + unit tests)".** Not required. The owner @@ -116,13 +118,14 @@ Standalone, **not** the ops reusable: the reusable's `release` job only does by `09 §5`), performs no store submission, and exposes no `outputs:`, so a caller cannot reference the zip it built. -Four jobs, least privilege first (split 2026-10-28): +Jobs, least privilege first (split 2026-10-28; the store job became three in +v1.3.0): | Job | Token | Does | |---|---|---| -| `build` "Gate + package" | `contents: read` | install, **every CI gate again** (a tag skips the branch triggers, and must never ship what a PR would have blocked), `zip`, `check:manifest`, the tag ↔ manifest version check, `SHA256SUMS.txt`; copies both files into a plain `dist/` and uploads that as the artifact `release-<tag>` — `upload-artifact` skips hidden paths such as `.output/` by default, which failed the first v1.1.0 tag run before any Release existed | +| `build` "Gate + package" | `contents: read` | install, **every CI gate again** (a tag skips the branch triggers, and must never ship what a PR would have blocked), `zip` and (since v1.3.0) `zip:firefox` — the Chrome/Edge package, the Firefox package and its sources archive — `check:manifest` on both packages, the tag ↔ manifest version check on both, `SHA256SUMS.txt` over all three files, each staged by its exact name so a missing one fails the run (a glob would pass with one of three); copies both files into a plain `dist/` and uploads that as the artifact `release-<tag>` — `upload-artifact` skips hidden paths such as `.output/` by default, which failed the first v1.1.0 tag run before any Release existed | | `publish` "GitHub Release" | `contents: write` | downloads the artifact, `sha256sum -c` it, creates the Release with `--verify-tag` (or re-uploads to an existing one). Installs nothing and runs no repository code — the only job that ever holds a write token | -| `store` "Publish to Chrome Web Store" | `contents: read` | only when the repo variable `CWS_AUTOPUBLISH` is `'true'`: `./node_modules/.bin/wxt submit` with the Release asset — the local binary, never `npx wxt`, which may fetch an unpinned package into an environment holding the four `CHROME_*` secrets (SonarCloud S6505/S8543) | +| `store-chrome`, `store-firefox`, `store-edge` | `contents: read` | since v1.3.0, one job per store, each only when its own repo variable is `'true'` (`CWS_AUTOPUBLISH`, `AMO_AUTOPUBLISH`, `EDGE_AUTOPUBLISH`) and each in its own GitHub **Environment** holding only that store's secrets (§3). They install `tools/publish/` — `publish-browser-extension` and its three dependencies, from their own lockfile, scripts off — instead of the whole dev toolchain, check the downloaded files against `SHA256SUMS.txt`, and run its `publish-extension` binary. Before v1.3.0 a single `store` job ran `wxt submit` after a full `npm ci`: four Chrome secrets shared a runner with ~320 packages | | `announce` | `contents: read` | Discord, only when `DISCORD_ANNOUNCE` is `'true'` | Before the split, one job ran `npm ci` — every dependency's install script plus @@ -297,23 +300,52 @@ pull requests, a weekly schedule and `workflow_dispatch`. Configuration is defect and switched off, with its reason, when it is a convention; it is never left standing to be ignored. -## 3. Chrome Web Store publishing automation +## 3. Store publishing automation (Chrome Web Store, Firefox Add-ons, Edge Add-ons) -WXT ships publishing built-in: **`wxt submit`** (wrapping -`publish-browser-extension`). One-time local setup: `npx wxt submit init` -→ walks through creating the Google Cloud OAuth client + refresh token → -produces the four values above → store as **repo Actions secrets**. +Since v1.3.0 the release workflow can submit to all three stores, each step +**off until its owner switches it on** with a repo variable. Uploaded builds +still go through each store's review; automation removes the clicking, not the +review. -**Gating policy:** +| Job | Gate (repo variable) | Environment | Secrets in that environment | Uploads | +|---|---|---|---|---| +| `store-chrome` | `CWS_AUTOPUBLISH=true` | `chrome-web-store` | `CHROME_PUBLISHER_ID`, `CHROME_EXTENSION_ID` (= the item id, `00 §9`), `CHROME_SERVICE_ACCOUNT_CLIENT_EMAIL`, `CHROME_SERVICE_ACCOUNT_PRIVATE_KEY` | the Chrome package | +| `store-firefox` | `AMO_AUTOPUBLISH=true` | `firefox-add-ons` | `FIREFOX_EXTENSION_ID` (= the gecko id), `FIREFOX_JWT_ISSUER`, `FIREFOX_JWT_SECRET` | the Firefox package and its sources, `listed`, Firefox desktop only | +| `store-edge` | `EDGE_AUTOPUBLISH=true` | `edge-add-ons` | `EDGE_PRODUCT_ID`, `EDGE_CLIENT_ID`, `EDGE_API_KEY` | the Chrome package | + +- **The tool is `publish-browser-extension`** (6.2.0 — what `wxt submit` + wraps), installed from `tools/publish/`'s own lockfile: four packages, not + the dev toolchain. A job's secrets are readable by everything on its runner + for the whole job (§2.5), and these can push an update to every user. +- **One job per store**, so a store's credentials never share a runner with + another's, and one store refusing an upload does not stop the others. +- **Environments** carry the secrets, not the repository, so nothing else in + any workflow can read them; give each one a required reviewer (the owner) to + approve every upload. +- **Chrome Web Store API v2.** v1.1 — what the old `store` job's + client-id/secret/refresh-token secrets used — was shut down on 2026-10-15; + that job would have failed the day `CWS_AUTOPUBLISH` was set. v2 takes a + publisher id and a Google Cloud **service account** (`CHROME_API_VERSION=v2` + is set by the job, never left to the tool's default). +- **AMO: the first version must be created by hand.** The API (and the tool) + can add a version to an add-on that exists, not create one; `13 §8`. AMO + JWT credentials come from addons.mozilla.org/developers/addon/api/key/. +- **Edge: the first submission is made in Partner Center**, by hand (`13 §9`). + API keys (v1.1, with a Client ID) **expire every 72 days** — a scheduled + chore, not an incident; until rotated, `store-edge` fails and the others do + not. +- **No re-run of a store job that succeeded**: every store refuses a version + number it has seen. Re-run only the failed job (`13 §7`). | Version | Method | |---|---| -| v1.0.x | **Manual**, per the `13 §1b` runbook: download the zip from the GitHub Release (not the CI artifact — the Release asset is the one `SHA256SUMS.txt` covers) → Dashboard → Package → upload new package → submit. The original rationale was "first reviews often ask questions"; in the event the first review asked nothing. It stays manual because none of the four `CHROME_*` secrets exists yet and `CWS_AUTOPUBLISH` is unset. | -| v1.1+ | **Automated**: the `Publish to Chrome Web Store` step in §2.3 runs after the Release succeeds, gated on the repo variable `CWS_AUTOPUBLISH=true` so it can be flipped off instantly if a review dispute is ongoing. | +| v1.0.x–v1.2.x | Chrome Web Store by hand (`13 §1b`) — the `CHROME_*` secrets never existed. | +| v1.3.0 | The first AMO and Edge versions **must** be uploaded by hand (`13 §8`, `13 §9`); the Chrome one by hand until the owner sets up §3's environment. | +| later | Each store automated once its environment has its secrets and its variable is `true`; switch a variable off to stop submitting there instantly (a review dispute, a rollout to watch). | -Notes: uploaded builds still go through CWS review before rollout (automation -removes the clicking, not the review). Consider Dashboard "staged rollout" -manually for risky releases. +Consider a staged (percentage) rollout on the Chrome Web Store for anything +touching the write paths — `CHROME_DEPLOY_PERCENTAGE` for the automated job, +the dashboard otherwise. ## 4. Branch/version flow @@ -359,9 +391,13 @@ means "unknown", not "not done". - [x] CodeQL **Default setup DISABLED** (Settings → Advanced Security) — confirmed 2026-07-26; `codeql.yml` uploads SARIF cleanly, which is only possible with it off (§2.2). -- [ ] ⚠️ Actions secrets: the four `CHROME_*` values (after `wxt submit init`). - `CHROME_EXTENSION_ID` is already known — it is the published item id in - `00 §9`. Required before `CWS_AUTOPUBLISH` can be flipped for v1.1. +- [ ] ⚠️ Store environments (§3), each with the owner as required reviewer and + only its own secrets: `chrome-web-store` (the four API v2 values; + `CHROME_EXTENSION_ID` is the item id in `00 §9`), `firefox-add-ons` + (`FIREFOX_EXTENSION_ID` = `bookmarkmagic@poli0981.dev` and the AMO JWT + pair), `edge-add-ons` (product id, Client ID, API key — rotate every 72 + days). GitHub creates an environment the first time a job names it, with + no protection; add the reviewer and secrets in Settings → Environments. - [x] Actions secrets for Discord notifications — **present as of 2026-10-28:** `DISCORD_CI_WEBHOOK`, `RELEASES_WEBHOOK`, `REPO_WEBHOOK` (the last two under names the reusable does not read; `release.yml` maps them, §2.3). @@ -374,7 +410,8 @@ means "unknown", not "not done". scan errors out. The owner agreed to switch it off on 2026-10-28. - [x] Private vulnerability reporting **enabled** (verified 2026-10-28 via the API) — `SECURITY.md` and the issue chooser send reporters there first. -- [ ] ⚠️ Repo variable `CWS_AUTOPUBLISH=false` initially. Note that when the +- [ ] ⚠️ Repo variables `CWS_AUTOPUBLISH`, `AMO_AUTOPUBLISH`, + `EDGE_AUTOPUBLISH` — unset, so no store job runs. Note that when a variable does not exist the expression is simply false, so "not configured" and "configured off" are indistinguishable from a run's output. - [ ] ⚠️ Repo variables `DISCORD_ANNOUNCE` and `DISCORD_CI_NOTIFY` — both still diff --git a/docs/13_RELEASE_PUBLISHING.md b/docs/13_RELEASE_PUBLISHING.md index 9246f71..246cafc 100644 --- a/docs/13_RELEASE_PUBLISHING.md +++ b/docs/13_RELEASE_PUBLISHING.md @@ -1,6 +1,9 @@ # 13 — Release & Store Publishing -Developer account: registered & fee paid ✔. +Chrome Web Store developer account: registered & fee paid ✔. Since v1.3.0 +there are two more stores — Firefox Add-ons (§8) and Microsoft Edge Add-ons +(§9) — and §1b is still the procedure for every release; §8 and §9 add what +is different there. ## 1. First-submission runbook (v1.0.0) — ✔ completed 2026-07-26 @@ -62,7 +65,9 @@ privacy and distribution tabs are already filled; you are replacing the package. `release.yml` re-runs every gate, builds, zips, verifies tag↔manifest, writes `SHA256SUMS.txt`, and creates the GitHub Release. 5. Download the **Release asset**, not the CI artifact — `SHA256SUMS.txt` covers - the Release asset only (`12 §3`). Verify with `sha256sum -c`. + the Release assets only (`12 §3`). Verify with `sha256sum -c --ignore-missing + SHA256SUMS.txt` (since v1.3.0 it lists three files; `--ignore-missing` lets + you check only the one you downloaded). 6. Dashboard → the existing item → **Package → Upload new package** → the zip. Do *not* create a new item. 7. Fill the "why this update" / what-changed note. Listing text and the privacy @@ -81,6 +86,19 @@ Chrome auto-updates installed extensions once the new version passes review; users do nothing and, notably, get no prompt. That is why the upgrade test matters more than any other single check here. +## 1c. Which file goes where (since v1.3.0) + +| Store | Upload | Notes | +|---|---|---| +| Chrome Web Store | `bookmarkmagic-X.Y.Z-chrome.zip` | §1b | +| Microsoft Edge Add-ons | the **same** `…-chrome.zip` | §9 | +| Firefox Add-ons | `bookmarkmagic-X.Y.Z-firefox.zip` **and** `…-sources.zip` | §8 | + +A store that re-signs or repackages what it receives (all three do, in some +form) serves users a file whose hash is not the Release asset's. What +`SHA256SUMS.txt` vouches for is that the uploaded file is the Release asset +(`09 §5`). + ## 2. Asset checklist ⚠️ ### Store assets (submitted — source of truth is the CWS dashboard) @@ -242,6 +260,15 @@ superseding version has to pass review too. answers must agree with the code exactly. `npm run guard` and `npm run check:manifest` are the evidence that they do. +### A store job failed after the Release was published (since v1.3.0) + +Re-run **only the failed job** from the run page. Every store refuses a +version number it has already accepted, so re-running the whole workflow would +turn the stores that succeeded red; and nothing before the store jobs needs +redoing — the Release and its checksums are already published. The usual +causes: an expired Edge API key (72 days, `12 §3`), a review hold, a token +revoked in a store dashboard. + ### A tag was pushed and the release run failed `release.yml` runs `gh release create` with no existence check, so a failure @@ -255,3 +282,63 @@ on) leaves a published Release that a re-run cannot recreate. `git push --delete origin vX.Y.Z`, then re-tag. Only safe while nothing has consumed the assets. - Never move a tag that has already been announced or submitted. + +## 8. Firefox Add-ons (AMO) — runbook (since v1.3.0) + +**First version — by hand, once** (the API and `publish-browser-extension` +can only add versions to an add-on that exists): + +1. The `11 §5` pass on a **real Firefox** (140 or later): about:debugging → + This Firefox → Load Temporary Add-on → `.output/firefox-mv3/manifest.json` + (or the Release's `…-firefox.zip`). Its Firefox section covers the + Bookmarks Menu, separators and Alt+↑/↓. +2. addons.mozilla.org/developers → **Submit a New Add-on** → *On this site* + (listed) → upload `bookmarkmagic-X.Y.Z-firefox.zip` from the Release. +3. **Compatibility: Firefox only** — untick Firefox for Android (no + `bookmarks` API there, `08 §9`). +4. **Source code: yes** → upload `bookmarkmagic-X.Y.Z-sources.zip` from the same + Release. In *Notes to reviewer* paste the short version of `/BUILD.md`: + Node.js 26 and npm 11 (the sources archive drops `.nvmrc`), `npm ci`, + `npm run zip:firefox`, the package lands in `.output/`. Reviewers diff their + build against the upload, file by file. +5. Listing: from `store/listing.<lang>.md`'s **AMO** block — name, summary + (≤ 250 characters), description, category *Bookmarks*, licence *GNU General + Public License v3.0* (the code is GPL-3.0-or-later), privacy policy + `https://github.com/poli0981/bookmarkmagic/blob/main/legal/PRIVACY.md`, + homepage the repository, support site the repository's issues. No support + email (`09 §6`). +6. Submit, and record the review's outcome in `15`. The add-on's page is + `https://addons.mozilla.org/firefox/addon/bookmarkmagic@poli0981.dev/` + (AMO resolves the gecko id; the slug it picks works too). + +**Later versions:** by hand, the same way (*Upload New Version*), or +automatically from `release.yml`'s `store-firefox` job once +`firefox-add-ons` has its secrets and `AMO_AUTOPUBLISH` is `true` +(`12 §3`) — the job uploads the package and the sources together. + +**Rollback:** AMO can disable a version in the Developer Hub, which sends +users back to the previous approved one — a recall Chrome does not offer. +Still ship the fix forward. + +## 9. Microsoft Edge Add-ons — runbook (since v1.3.0) + +**First submission — by hand, once:** + +1. A Partner Center developer account (no fee) — ⚠️ owner. +2. The `11 §5` pass on a real **Edge**, including a profile **signed in with + sync on** — the case `08 §10` could not verify (`NO_WRITABLE_ROOTS` if + Edge marks syncing roots). +3. Partner Center → Edge → **Create new extension** → upload the Release's + `bookmarkmagic-X.Y.Z-chrome.zip` — the Chrome package, unchanged. +4. Listing from `store/listing.<lang>.md`'s **Edge** block (it avoids selling + the extension as a Chrome one, `08 §10`); category *Productivity*; privacy + answers as `08 §5`; privacy policy URL as above; screenshots from + `store/screenshots/`. +5. Submit; record the outcome in `15`. Note the **Product ID** on the + extension's overview page — `EDGE_PRODUCT_ID` — and the listing URL, which + the About link and the README can then use (`06 §3.5`). + +**Later versions:** by hand (*Update* → upload the new package), or from +`release.yml`'s `store-edge` job once `edge-add-ons` has its secrets and +`EDGE_AUTOPUBLISH` is `true`. The API key expires every **72 days**; put the +renewal in a calendar. diff --git a/docs/14_LEGAL_GATE.md b/docs/14_LEGAL_GATE.md index 6e0009e..1116fd2 100644 --- a/docs/14_LEGAL_GATE.md +++ b/docs/14_LEGAL_GATE.md @@ -89,12 +89,22 @@ its `clsx` helper and WXT's browser shim, which the build always compiled in. ** every change clarifies or corrects a description of what was already true, or removes an obligation; none adds one or a data flow. +**Precedent (2026-11-18, v1.3.0):** Firefox Add-ons and Microsoft Edge Add-ons +become distribution channels. EULA clause 5 says updates come "through the +store you installed the Extension from"; PRIVACY names all three stores and +Firefox's data-consent declaration ("none"), and calls the settings store by +both browsers' names; DISCLAIMER's note on dates no longer blames Chrome alone, +and the non-affiliation line adds Microsoft and Edge. THIRD_PARTY_NOTICES (same +day, Phase 10) corrected its description of the build tooling's licences. +**Not a bump:** a new channel to receive the same software is not a new data +flow from the Extension, and nothing asks more of the user. + **What each `LEGAL_VERSION` means** — the text a user who accepted that number agreed to: | `LEGAL_VERSION` | Accepted text | Notes | |---|---|---| -| 1 | The four `legal/` files as published 2026-07-26, with the clarifications of 2026-08-03 and 2026-10-29 | The clarifications are listed above; git history has each wording | +| 1 | The four `legal/` files as published 2026-07-26, with the clarifications of 2026-08-03, 2026-10-29 and 2026-11-18 | The clarifications are listed above; git history has each wording | ### 3.2 `LICENSE` diff --git a/legal/DISCLAIMER.md b/legal/DISCLAIMER.md index a72a889..2e700cd 100644 --- a/legal/DISCLAIMER.md +++ b/legal/DISCLAIMER.md @@ -1,6 +1,6 @@ # Disclaimer — BookmarkMagic -Terms version 1 · Effective 2026-07-26 · Last updated 2026-10-29 +Terms version 1 · Effective 2026-07-26 · Last updated 2026-11-18 - Provided "AS IS", without warranty of any kind (see LICENSE §15–16). - Bookmark operations modify your browser's bookmark data. The "Replace @@ -10,14 +10,14 @@ Terms version 1 · Effective 2026-07-26 · Last updated 2026-10-29 Extension could read back. If the browser stops part-way, what was already deleted can be restored by importing that backup. You remain responsible for keeping backups of data you care about. -- Imported bookmarks are created with the current date and time. Chrome's - extension API does not allow an extension to set a bookmark's original - creation date, so original dates are preserved in your exported *files* but +- Imported bookmarks are created with the current date and time. The + browsers' extension APIs do not allow an extension to set a bookmark's + original creation date, so original dates are preserved in your exported *files* but not when writing back into the browser. - Import files come from outside this Extension; verify you trust their source. Bookmarked URLs are stored as-is and are not vetted by the Extension. - This project is not affiliated with or endorsed by Google, Chrome, Mozilla, - Firefox or any browser vendor. Browser names are trademarks of their + Firefox, Microsoft, Edge or any browser vendor. Browser names are trademarks of their respective owners. - The BookmarkMagic name and icon identify this project, published by skullmute (poli0981). The GPL lets anyone fork the code; it does not let a fork present diff --git a/legal/EULA.md b/legal/EULA.md index 623643d..18b4f39 100644 --- a/legal/EULA.md +++ b/legal/EULA.md @@ -1,6 +1,6 @@ # End User License Agreement — BookmarkMagic -Terms version 1 · Effective 2026-07-26 · Last updated 2026-10-29 +Terms version 1 · Effective 2026-07-26 · Last updated 2026-11-18 Copyright © 2026 skullmute ([poli0981](https://github.com/poli0981)). @@ -17,8 +17,9 @@ Copyright © 2026 skullmute ([poli0981](https://github.com/poli0981)). allow one, and your rights under the GPL do not depend on it. 4. **Your data.** The software processes bookmark data locally on your device only, and sends nothing anywhere (see PRIVACY.md). -5. **Updates.** Updates are delivered via the Chrome Web Store and may change - functionality. Material legal changes trigger re-acceptance in-app. +5. **Updates.** Updates are delivered through the store you installed the + Extension from — the Chrome Web Store, Firefox Add-ons or Microsoft Edge + Add-ons — and may change functionality. Material legal changes trigger re-acceptance in-app. 6. **Contact.** Questions about these terms: **legal@poli0981.dev**. Formal copyright infringement (DMCA) notices: **dmca@poli0981.dev**. diff --git a/legal/PRIVACY.md b/legal/PRIVACY.md index cc00516..d94aa96 100644 --- a/legal/PRIVACY.md +++ b/legal/PRIVACY.md @@ -1,6 +1,6 @@ # Privacy Policy — BookmarkMagic -Terms version 1 · Effective 2026-07-26 · Last updated 2026-10-29 +Terms version 1 · Effective 2026-07-26 · Last updated 2026-11-18 BookmarkMagic ("the Extension") is designed to work entirely on your device. @@ -16,9 +16,10 @@ contains no analytics, telemetry, or crash reporting. device. - **Local settings** (permission: `storage`): your language, theme, preferences, and the date you accepted these terms are stored locally via - `chrome.storage.local`. They are not transmitted anywhere and are removed by - Chrome when you uninstall the Extension. The Extension does not use - `chrome.storage.sync`, so even your settings stay off any vendor cloud. + `chrome.storage.local` (Firefox calls the same store `browser.storage.local`). + They are not transmitted anywhere and are removed by the browser when you + uninstall the Extension. The Extension does not use `storage.sync`, so even + your settings stay off any vendor cloud. The Extension requests no other permissions. It has no host permissions, no content scripts, and no background service worker. It contains no code that @@ -48,10 +49,12 @@ see THIRD_PARTY_NOTICES.md) contain no network code. Two things happen outside the Extension and are worth knowing: -- **The Chrome Web Store** (Google) distributes the Extension and its updates. - Installing and updating it are governed by Google's own privacy policy, not - this one, and Google gives the developer only aggregate counts such as the - number of users. +- **The store you install it from** — the Chrome Web Store (Google), Firefox + Add-ons (Mozilla) or Microsoft Edge Add-ons (Microsoft) — distributes the + Extension and its updates. Installing and updating it are governed by that + store's own privacy policy, not this one, and each gives the developer only + aggregate counts such as the number of users. On Firefox the Extension + declares that it collects no data, in Firefox's own data-consent system. - **Opening a bookmark.** When you open a bookmark from the Edit tab, your browser loads that page exactly as when you click any link: the request is the browser's, made on your instruction, to the site you chose. The @@ -85,6 +88,10 @@ of practice: it describes handling of material you choose to send us, which was never part of what the Extension itself collects — which remains nothing. No re-acceptance was requested.* +*Clarified on 2026-11-18: the Extension is also distributed through Firefox +Add-ons and Microsoft Edge Add-ons. That adds no data flow — the Extension +still collects nothing — so no re-acceptance is requested (`docs/14 §3.1`).* + *Clarified on 2026-10-29: the diagnostics log, the Chrome Web Store, opening a bookmark, and what the build compiles in are now described, and the contact address changed. None of it changes what the Extension collects — still