docs: specify Firefox (AMO) and Edge Add-ons support for v1.3.0
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 <noreply@anthropic.com>
This commit is contained in:
1 parent
8519e7c39e
commit
355443ef6b
17 files changed
+480
-71
No files matched your search
@@ -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
|
||||
|
||||
@@ -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"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
+19
-2
@@ -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 <date>` 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
|
||||
|
||||
+41
-4
@@ -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 <date>/…`.
|
||||
|
||||
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 <date>/…` (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 — `<HR>` 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
|
||||
|
||||
+26
-7
@@ -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.
|
||||
- `<HR>` separator elements (Firefox) → skipped, no warning. These are
|
||||
*elements*, so "unknown attributes ignored" does not cover them.
|
||||
- `<HR>` 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 `<DL>` —
|
||||
`document.querySelector('dl')` and "the outermost `<DL>`" 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 `<HR>` is).
|
||||
(folder: `title`, `children`), `…-separator` (skipped and counted,
|
||||
`SEPARATORS_SKIPPED`, as `<HR>` 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`).
|
||||
|
||||
+19
-6
@@ -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):
|
||||
|
||||
+18
-4
@@ -363,7 +363,7 @@ behind a `<ConfirmDialog>` (six preferences is enough to be worth a confirm).
|
||||
|
||||
`<AboutCard>`: 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 "<title>: 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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
+57
-20
@@ -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
|
||||
|
||||
@@ -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.
|
||||
+11
-1
@@ -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`
|
||||
|
||||
|
||||
+5
-5
@@ -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
|
||||
|
||||
+4
-3
@@ -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**.
|
||||
|
||||
|
||||
+15
-8
@@ -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
|
||||
|
||||
Reference in new issue
Block a user