Compare commits
48
Commits
No files matched your search
@@ -0,0 +1,106 @@
|
||||
name: Something is hard or impossible to use
|
||||
description: A barrier with the keyboard, a screen reader, a contrast theme, zoom, or voice control.
|
||||
title: '[a11y] '
|
||||
labels: [accessibility]
|
||||
body:
|
||||
- type: markdown
|
||||
attributes:
|
||||
value: |
|
||||
Thank you — a report like this is treated as a defect, not a wish.
|
||||
[ACCESSIBILITY.md](https://github.com/poli0981/bookmarkmagic/blob/main/ACCESSIBILITY.md)
|
||||
lists what is already known not to work well; it is fine to report
|
||||
something on that list if it is in your way.
|
||||
|
||||
You do not need to explain why you use the tools you use.
|
||||
|
||||
**Please do not attach your real bookmarks file**, and check a
|
||||
screenshot or recording for bookmark titles first — your bookmarks are
|
||||
your browsing history.
|
||||
|
||||
- type: textarea
|
||||
id: task
|
||||
attributes:
|
||||
label: What were you trying to do, and what happened instead?
|
||||
placeholder: |
|
||||
I tabbed to the tree on the Edit tab and pressed F2 to rename a
|
||||
folder. Nothing was announced and I could not tell whether …
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: dropdown
|
||||
id: severity
|
||||
attributes:
|
||||
label: How badly does it get in the way?
|
||||
options:
|
||||
- Blocked — I could not finish what I was doing
|
||||
- Hard — I finished, but only with a workaround
|
||||
- Annoying — it works, but badly
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: dropdown
|
||||
id: area
|
||||
attributes:
|
||||
label: Where does it happen?
|
||||
options:
|
||||
- Import
|
||||
- Export
|
||||
- Edit
|
||||
- Settings
|
||||
- About / legal gate
|
||||
- The toolbar popup
|
||||
- Everywhere
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: textarea
|
||||
id: assistive-tech
|
||||
attributes:
|
||||
label: Assistive technology and settings
|
||||
description: >-
|
||||
Whatever applies, with a version if you know it — a screen reader
|
||||
(Narrator, NVDA, JAWS, VoiceOver, ChromeVox, Orca), a contrast theme,
|
||||
zoom level, reduced motion, voice control, switch access, a keyboard
|
||||
only. "None, keyboard only" is a complete answer.
|
||||
placeholder: NVDA 2026.3, Windows contrast theme "Night sky", 150 % zoom
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: input
|
||||
id: version
|
||||
attributes:
|
||||
label: BookmarkMagic version
|
||||
description: Shown in the About tab, and on chrome://extensions.
|
||||
placeholder: '1.2.1'
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: input
|
||||
id: browser
|
||||
attributes:
|
||||
label: Browser and operating system
|
||||
placeholder: Chrome 142 on Windows 11
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: textarea
|
||||
id: steps
|
||||
attributes:
|
||||
label: Steps to reproduce
|
||||
description: The keys you pressed are as useful as anything else here.
|
||||
placeholder: |
|
||||
1. Open the manager, go to Edit
|
||||
2. Tab to the tree, press ↓ three times
|
||||
3. …
|
||||
validations:
|
||||
required: false
|
||||
|
||||
- type: checkboxes
|
||||
id: confirmations
|
||||
attributes:
|
||||
label: Before submitting
|
||||
options:
|
||||
- label: >-
|
||||
Anything I attached contains no real addresses, titles or personal
|
||||
data.
|
||||
required: true
|
||||
@@ -10,6 +10,10 @@ body:
|
||||
"A bookmark file will not import correctly" form instead — it asks for
|
||||
the one thing that makes those fixable.
|
||||
|
||||
If something is hard or impossible to use with a **keyboard, a screen
|
||||
reader, a contrast theme or zoom**, the "Something is hard or
|
||||
impossible to use" form asks better questions for that.
|
||||
|
||||
If this is a **security** problem, do not file it here. See
|
||||
[SECURITY.md](https://github.com/poli0981/bookmarkmagic/blob/main/SECURITY.md).
|
||||
|
||||
|
||||
@@ -6,6 +6,13 @@
|
||||
blank_issues_enabled: false
|
||||
|
||||
contact_links:
|
||||
- name: An idea, to talk through first
|
||||
url: https://github.com/poli0981/bookmarkmagic/discussions/categories/ideas
|
||||
about: >-
|
||||
BookmarkMagic is in maintenance mode (MAINTENANCE.md). A new idea is
|
||||
welcome here, where it can be discussed without an issue that has to be
|
||||
accepted or refused.
|
||||
|
||||
- name: Security vulnerability
|
||||
url: https://github.com/poli0981/bookmarkmagic/security/advisories/new
|
||||
about: Report privately, never as a public issue. See SECURITY.md.
|
||||
@@ -14,6 +21,12 @@ contact_links:
|
||||
url: https://chromewebstore.google.com/detail/bookmarkmagic/eghnciphhegekmnofffpgbdfefckdhmg
|
||||
about: Reviews are read, but a bug reported here gets fixed faster.
|
||||
|
||||
- name: Accessibility barrier, by email
|
||||
url: mailto:accessibility@poli0981.dev
|
||||
about: >-
|
||||
The "Something is hard or impossible to use" form above is the quickest
|
||||
route; email works too. See ACCESSIBILITY.md.
|
||||
|
||||
- name: Question, or no GitHub account
|
||||
url: mailto:code@poli0981.dev
|
||||
about: >-
|
||||
|
||||
@@ -1,20 +1,50 @@
|
||||
name: Suggest a feature
|
||||
description: An idea for something BookmarkMagic should do.
|
||||
description: BookmarkMagic is in maintenance mode — read what that means before asking for something new.
|
||||
title: '[feature] '
|
||||
labels: [enhancement]
|
||||
body:
|
||||
- type: markdown
|
||||
attributes:
|
||||
value: |
|
||||
Before writing: this project has a short, deliberate
|
||||
[never list](https://github.com/poli0981/bookmarkmagic/blob/main/docs/15_ROADMAP.md).
|
||||
Cloud sync, accounts, analytics of any kind, and anything that would
|
||||
require new browser permissions are out of scope permanently — not
|
||||
because they are hard, but because "offline, two permissions, no
|
||||
network" is the entire point of the extension.
|
||||
**BookmarkMagic is in maintenance mode**
|
||||
([MAINTENANCE.md](https://github.com/poli0981/bookmarkmagic/blob/main/MAINTENANCE.md)).
|
||||
A feature is added only when it is already on the
|
||||
[roadmap](https://github.com/poli0981/bookmarkmagic/blob/main/docs/15_ROADMAP.md),
|
||||
or when it is genuinely needed to fix a defect or remove a barrier.
|
||||
|
||||
Everything else is genuinely open. The roadmap in that same file lists
|
||||
what is already planned.
|
||||
**The first question below decides what happens to this issue.** A
|
||||
request for something new is closed automatically and labelled
|
||||
`maintenance-mode` — not deleted, and read; the
|
||||
[Ideas discussions](https://github.com/poli0981/bookmarkmagic/discussions/categories/ideas)
|
||||
are the place to talk one through. The other two answers keep the issue
|
||||
open for the maintainer.
|
||||
|
||||
Out of scope permanently, whatever the mode: cloud sync, accounts,
|
||||
analytics of any kind, and anything that would need a new browser
|
||||
permission. "Offline, two permissions, no network" is the point of the
|
||||
extension.
|
||||
|
||||
- type: dropdown
|
||||
id: kind
|
||||
attributes:
|
||||
label: Which kind of change is this?
|
||||
description: See MAINTENANCE.md. Please answer honestly — a mislabelled request is closed by hand.
|
||||
options:
|
||||
- Something already on the roadmap (docs/15)
|
||||
- Needed to fix a bug, a UI/UX defect or an accessibility barrier
|
||||
- Something new — not on the roadmap
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: input
|
||||
id: reference
|
||||
attributes:
|
||||
label: Which roadmap item, or which defect?
|
||||
description: >-
|
||||
The line in docs/15, or the issue or behaviour it fixes. Leave empty
|
||||
for something new.
|
||||
validations:
|
||||
required: false
|
||||
|
||||
- type: textarea
|
||||
id: problem
|
||||
@@ -52,5 +82,5 @@ body:
|
||||
permission, and does not involve a server, an account, or sending
|
||||
data anywhere.
|
||||
required: true
|
||||
- label: I checked the roadmap and the never list.
|
||||
required: false
|
||||
- label: I read MAINTENANCE.md and checked the roadmap and the never list.
|
||||
required: true
|
||||
@@ -1,5 +1,5 @@
|
||||
name: A translation is wrong or awkward
|
||||
description: Vietnamese or Japanese wording that is incorrect, unnatural, or untranslated.
|
||||
description: Vietnamese, Japanese, Chinese or Romanian wording that is incorrect, unnatural, or untranslated.
|
||||
title: '[i18n] '
|
||||
labels: [i18n]
|
||||
body:
|
||||
@@ -7,9 +7,9 @@ body:
|
||||
attributes:
|
||||
value: |
|
||||
Native speakers are the only people who can catch this. English is the
|
||||
source language; Vietnamese is reviewed by the maintainer and Japanese
|
||||
is best-effort until a native pass, so JA reports are especially
|
||||
welcome.
|
||||
source language; Vietnamese is reviewed by the maintainer. Japanese,
|
||||
Simplified Chinese and Romanian are best-effort until a native pass,
|
||||
so reports in those three are especially welcome.
|
||||
|
||||
You do **not** need to open a pull request or install anything — just
|
||||
tell us the wording. If you would rather send the change yourself,
|
||||
@@ -23,6 +23,8 @@ body:
|
||||
options:
|
||||
- Tiếng Việt (vi)
|
||||
- 日本語 (ja)
|
||||
- 简体中文 (zh-CN)
|
||||
- Română (ro)
|
||||
validations:
|
||||
required: true
|
||||
|
||||
|
||||
@@ -7,6 +7,13 @@ a translation fix does not need the parser section, and vice versa.
|
||||
|
||||
<!-- What changes, and what problem it solves. Link the issue if there is one. -->
|
||||
|
||||
**Kind of change** ([MAINTENANCE.md](https://github.com/poli0981/bookmarkmagic/blob/main/MAINTENANCE.md) — the project
|
||||
is in maintenance mode): <!-- bug fix · UI/UX fix · accessibility · translation
|
||||
· dependency or security update · roadmap item (which?) -->
|
||||
|
||||
A pull request titled `feat…` from outside the project is closed automatically
|
||||
unless its feature is on the roadmap — open a feature request first.
|
||||
|
||||
## Checklist
|
||||
|
||||
- [ ] `npm run verify` is green. (Release-bearing? `npm run verify:full` —
|
||||
@@ -22,10 +29,34 @@ a translation fix does not need the parser section, and vice versa.
|
||||
|
||||
### If it touches user-visible text
|
||||
|
||||
- [ ] The key exists in **all three** locales — `en`, `vi`, `ja`. `en.ts` is the
|
||||
schema; `vi`/`ja` use `satisfies Dict`, so a missing key fails the type
|
||||
check. Never add `as const` to a locale file.
|
||||
- [ ] Interpolation tokens (`{n}`, `{name}`) match across all three.
|
||||
- [ ] The key exists in **every** locale — `en`, `vi`, `ja`, `zh-CN`, `ro`
|
||||
(`LOCALES`). `en.ts` is the schema; the others use `satisfies Dict`, so a
|
||||
missing key fails the type check. Never add `as const` to a locale file.
|
||||
- [ ] Interpolation tokens (`{n}`, `{name}`) match across every locale, and a
|
||||
plural key carries the forms its language needs (`few` in Romanian —
|
||||
`docs/07 §5`).
|
||||
|
||||
### If it changes the interface
|
||||
|
||||
`ACCESSIBILITY.md` is a public promise and `docs/06 §5` is its specification.
|
||||
|
||||
- [ ] Everything new works from the **keyboard alone**, and focus is visible
|
||||
on it — including on a control with a filled background.
|
||||
- [ ] Focus goes somewhere sensible when the thing that had it disappears
|
||||
(a closed dialog, a removed row, a replaced step). It never falls to
|
||||
the top of the page.
|
||||
- [ ] Every control has an accessible **name**; an icon-only button takes a
|
||||
`label`. Text a screen reader speaks is an i18n key like any other.
|
||||
- [ ] No state is shown by **colour alone**, and a state shown by a fill or a
|
||||
shadow has a `@media (forced-colors: active)` equivalent
|
||||
(`tests/unit/styles/forced-colors.test.ts` holds the list).
|
||||
- [ ] Anything that moves sits inside
|
||||
`@media (prefers-reduced-motion: no-preference)`; pointer targets are at
|
||||
least 24 × 24 CSS px.
|
||||
- [ ] One pass with a **screen reader** over the changed screen (Narrator,
|
||||
NVDA or VoiceOver) — or the PR says that it was not done.
|
||||
- [ ] `ACCESSIBILITY.md` is still true: its key table and its known
|
||||
limitations.
|
||||
|
||||
### If it is a parser fix
|
||||
|
||||
|
||||
@@ -56,6 +56,22 @@ updates:
|
||||
- dependency-name: '@types/node'
|
||||
update-types: [version-update:semver-major]
|
||||
|
||||
# The store-upload tool release.yml installs on its own (docs/12 §3): four
|
||||
# packages, kept apart from the toolchain because they run beside store
|
||||
# credentials. Its own directory, so its bumps arrive as their own PRs.
|
||||
- package-ecosystem: npm
|
||||
directory: /tools/publish
|
||||
schedule:
|
||||
interval: weekly
|
||||
day: monday
|
||||
open-pull-requests-limit: 2
|
||||
cooldown:
|
||||
default-days: 7
|
||||
commit-message:
|
||||
prefix: chore
|
||||
prefix-development: chore
|
||||
include: scope
|
||||
|
||||
- package-ecosystem: github-actions
|
||||
directory: /
|
||||
schedule:
|
||||
|
||||
@@ -45,6 +45,9 @@ jobs:
|
||||
- run: npm run knip
|
||||
- run: npm run coverage # vitest --coverage, thresholds per docs/11 §1
|
||||
- run: npm run guard # the zero-network / no-raw-HTML gate, docs/08 §3
|
||||
# Every licence in the lockfile, shipped packages held to the stricter
|
||||
# list (docs/09 §3.2). Reads package-lock.json only — no network.
|
||||
- run: npm run check:licenses
|
||||
|
||||
# Zero runtime dependencies is a public claim (README, docs/09 T5); this
|
||||
# is the check that keeps it true. Dev-only advisories are tracked by
|
||||
@@ -56,6 +59,9 @@ jobs:
|
||||
# tabs/scripting/host_permissions that never appear in the config file.
|
||||
- run: npm run build
|
||||
- run: npm run check:manifest
|
||||
# The second package (docs/08 §9), held to its own key set and floor.
|
||||
- run: npm run build:firefox
|
||||
- run: npm run check:manifest -- --browser firefox
|
||||
|
||||
windows:
|
||||
# Not a required check. The owner develops on Windows, and the paths that
|
||||
|
||||
@@ -0,0 +1,129 @@
|
||||
# Qodana — docs/12 §2.7.
|
||||
#
|
||||
# A separate workflow, like SonarCloud's: a Qodana outage or opinion must never
|
||||
# change the colour of CI, which is what branch protection reads. Not a
|
||||
# required check.
|
||||
#
|
||||
# Two jobs, least privilege first:
|
||||
# - `scan` runs the analysis. qodana-js resolves types through node_modules,
|
||||
# so the dev dependencies are installed here (install scripts off) — which
|
||||
# means they share a runner with QODANA_TOKEN. That is the documented
|
||||
# exception to docs/12 §2.5's "a token job installs nothing": the token
|
||||
# only uploads reports to one Qodana Cloud project (rotate it in
|
||||
# qodana.cloud if a dependency is ever found compromised), and this job's
|
||||
# GITHUB_TOKEN is read-only — no PR comments, no check runs from here.
|
||||
# - `publish` installs and runs nothing: it takes the SARIF report from
|
||||
# `scan` and uploads it to GitHub code scanning, where the findings appear
|
||||
# beside CodeQL's under "Security and quality" and on pull requests.
|
||||
name: Qodana
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main]
|
||||
pull_request:
|
||||
workflow_dispatch:
|
||||
schedule:
|
||||
- cron: '0 15 * * 1' # weekly, Monday — an hour after CodeQL
|
||||
|
||||
permissions:
|
||||
contents: read
|
||||
|
||||
concurrency:
|
||||
group: qodana-${{ github.ref }}
|
||||
cancel-in-progress: ${{ github.event_name == 'pull_request' }}
|
||||
|
||||
jobs:
|
||||
scan:
|
||||
name: Qodana for JS
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 30
|
||||
permissions:
|
||||
contents: read
|
||||
outputs:
|
||||
ran: ${{ steps.token.outputs.present }}
|
||||
steps:
|
||||
# Dependabot and fork pull requests get no repository secrets: skip with
|
||||
# a notice instead of failing, before installing anything.
|
||||
- name: Check for QODANA_TOKEN
|
||||
id: token
|
||||
env:
|
||||
QODANA_TOKEN: ${{ secrets.QODANA_TOKEN }}
|
||||
run: |
|
||||
if [ -n "$QODANA_TOKEN" ]; then
|
||||
echo "present=true" >> "$GITHUB_OUTPUT"
|
||||
else
|
||||
echo "present=false" >> "$GITHUB_OUTPUT"
|
||||
echo "::notice::Qodana skipped — QODANA_TOKEN is not available to this run (Dependabot or fork PR)."
|
||||
fi
|
||||
|
||||
# The default ref — on a pull request, its merge commit — which is the
|
||||
# commit code scanning attributes an upload from this run to.
|
||||
- uses: actions/checkout@v7
|
||||
if: steps.token.outputs.present == 'true'
|
||||
with:
|
||||
fetch-depth: 0
|
||||
persist-credentials: false
|
||||
|
||||
- uses: actions/setup-node@v7
|
||||
if: steps.token.outputs.present == 'true'
|
||||
with:
|
||||
node-version-file: .nvmrc
|
||||
cache: npm
|
||||
|
||||
# --ignore-scripts: no dependency runs code at install time (docs/12 §2).
|
||||
- if: steps.token.outputs.present == 'true'
|
||||
run: npm ci --ignore-scripts
|
||||
- if: steps.token.outputs.present == 'true'
|
||||
run: npx --no-install wxt prepare
|
||||
|
||||
- name: Qodana scan
|
||||
if: steps.token.outputs.present == 'true'
|
||||
# Pinned to a commit, not the moving `v2026.2` branch the vendor's
|
||||
# snippet uses: this step holds a token. v2026.2.2 rather than the
|
||||
# newest tag, which is younger than the repo's 7-day cooldown.
|
||||
uses: JetBrains/qodana-action@3e8d76ff0e0241618abd808682f426afe84bab3f # v2026.2.2
|
||||
with:
|
||||
# Whole project every time — it is small, and a PR that touches only
|
||||
# docs would otherwise scan nothing.
|
||||
pr-mode: false
|
||||
# Both need write permissions this job deliberately does not have;
|
||||
# `publish` reports the findings through code scanning instead.
|
||||
post-pr-comment: false
|
||||
use-annotations: false
|
||||
# The SARIF report as the `qodana-report` artifact.
|
||||
upload-result: true
|
||||
env:
|
||||
QODANA_TOKEN: ${{ secrets.QODANA_TOKEN }}
|
||||
QODANA_ENDPOINT: 'https://qodana.cloud'
|
||||
|
||||
publish:
|
||||
name: Findings to code scanning
|
||||
needs: scan
|
||||
# !cancelled(), not the implicit success(): with failureConditions in
|
||||
# qodana.yaml, a scan that FINDS something fails — and those are exactly
|
||||
# the findings that must reach code scanning and the pull request.
|
||||
if: ${{ !cancelled() && needs.scan.outputs.ran == 'true' }}
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 10
|
||||
permissions:
|
||||
contents: read
|
||||
security-events: write
|
||||
steps:
|
||||
- uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
|
||||
with:
|
||||
name: qodana-report
|
||||
path: qodana-report
|
||||
|
||||
# The artifact holds one zip, qodana-report.zip, whose entries carry
|
||||
# absolute names ("/qodana.sarif.json"). Take only the report, by its
|
||||
# exact name, to a fixed path — nothing else is unpacked.
|
||||
- name: Extract the SARIF report
|
||||
run: |
|
||||
set -euo pipefail
|
||||
unzip -p qodana-report/qodana-report.zip /qodana.sarif.json > qodana.sarif.json
|
||||
test -s qodana.sarif.json || { echo "::error::no qodana.sarif.json in the report"; exit 1; }
|
||||
|
||||
- uses: github/codeql-action/upload-sarif@33d7b85da1a04171e211befe2c739303b9a4c066 # v4.39.3
|
||||
with:
|
||||
sarif_file: qodana.sarif.json
|
||||
category: qodana
|
||||
+190
-37
@@ -5,11 +5,16 @@
|
||||
# (required by docs/09 §5), performs no store submission, and exposes no
|
||||
# `outputs:`, so a caller cannot reference the zip it built.
|
||||
#
|
||||
# Three jobs, least privilege first. `build` installs, runs every gate and
|
||||
# packages with a READ-ONLY token; only `publish`, which installs nothing and
|
||||
# runs no repository code, ever holds `contents: write`. Before this split one
|
||||
# job ran `npm ci` — every dependency's install script plus our own tests —
|
||||
# while holding a write token that checkout had also left in .git/config.
|
||||
# Least privilege first. `build` installs, runs every gate and packages with a
|
||||
# READ-ONLY token; only `publish`, which installs nothing and runs no
|
||||
# repository code, ever holds `contents: write`. Before the split one job ran
|
||||
# `npm ci` — every dependency's install script plus our own tests — while
|
||||
# holding a write token that checkout had also left in .git/config.
|
||||
#
|
||||
# Since v1.3.0 there are three release files: the Chromium package (the Chrome
|
||||
# Web Store AND Edge Add-ons take it), the Firefox package, and the sources
|
||||
# archive AMO reviews (docs/08 §9, docs/13 §1c). And three store jobs, one per
|
||||
# store, each off until its repo variable says otherwise (docs/12 §3).
|
||||
name: Release
|
||||
|
||||
on:
|
||||
@@ -44,32 +49,48 @@ jobs:
|
||||
- run: npm run knip
|
||||
- run: npm run coverage
|
||||
- run: npm run guard
|
||||
- run: npm run check:licenses
|
||||
- run: npm audit --omit=dev --audit-level=low
|
||||
|
||||
- run: npm run zip # wxt zip → .output/<name>-<version>-chrome.zip
|
||||
- run: npm run zip # → .output/<name>-<version>-chrome.zip (Chrome Web Store, Edge Add-ons)
|
||||
- run: npm run zip:firefox # → …-firefox.zip and …-sources.zip (Firefox Add-ons)
|
||||
|
||||
# Gate the artifact, not just the config it was built from. A tag is the
|
||||
# last point at which an unintended permission can still be stopped.
|
||||
# Gate the artifacts, not just the config they were built from. A tag is
|
||||
# the last point at which an unintended permission can still be stopped.
|
||||
- run: npm run check:manifest
|
||||
- run: npm run check:manifest -- --browser firefox
|
||||
|
||||
- name: Verify tag matches manifest version
|
||||
- name: Verify tag matches both manifests
|
||||
run: |
|
||||
set -euo pipefail
|
||||
MANIFEST_VERSION=$(jq -r '.version' .output/chrome-mv3/manifest.json)
|
||||
TAG_VERSION="${GITHUB_REF_NAME#v}"
|
||||
test "$MANIFEST_VERSION" = "$TAG_VERSION" \
|
||||
|| { echo "::error::tag $TAG_VERSION != manifest $MANIFEST_VERSION"; exit 1; }
|
||||
for target in chrome firefox; do
|
||||
MANIFEST_VERSION=$(jq -r '.version' ".output/${target}-mv3/manifest.json")
|
||||
test "$MANIFEST_VERSION" = "$TAG_VERSION" \
|
||||
|| { echo "::error::tag $TAG_VERSION != $target manifest $MANIFEST_VERSION"; exit 1; }
|
||||
done
|
||||
|
||||
- name: SHA256SUMS
|
||||
working-directory: .output
|
||||
run: sha256sum *-chrome.zip > SHA256SUMS.txt
|
||||
# Staged in a plain directory: upload-artifact skips hidden paths by
|
||||
# default, and `.output` is one. Each file by its exact name: a glob would
|
||||
# pass with one of the three missing.
|
||||
- name: Stage the release files
|
||||
run: |
|
||||
set -euo pipefail
|
||||
VERSION="${GITHUB_REF_NAME#v}"
|
||||
mkdir dist
|
||||
for file in "bookmarkmagic-${VERSION}-chrome.zip" \
|
||||
"bookmarkmagic-${VERSION}-firefox.zip" \
|
||||
"bookmarkmagic-${VERSION}-sources.zip"; do
|
||||
test -f ".output/$file" || { echo "::error::missing release file $file"; exit 1; }
|
||||
cp ".output/$file" dist/
|
||||
done
|
||||
(cd dist && sha256sum bookmarkmagic-*.zip > SHA256SUMS.txt)
|
||||
cat dist/SHA256SUMS.txt
|
||||
|
||||
- uses: actions/upload-artifact@v7
|
||||
with:
|
||||
name: release-${{ github.ref_name }}
|
||||
path: |
|
||||
.output/*-chrome.zip
|
||||
.output/SHA256SUMS.txt
|
||||
path: dist/
|
||||
if-no-files-found: error
|
||||
retention-days: 90
|
||||
|
||||
@@ -92,9 +113,9 @@ jobs:
|
||||
run: sha256sum -c SHA256SUMS.txt
|
||||
|
||||
# Idempotent on purpose. `gh release create` fails outright if a Release
|
||||
# for the tag already exists, so any failure AFTER this step — realistically
|
||||
# the store job below, once CWS_AUTOPUBLISH is on — used to strand the tag:
|
||||
# re-running could not get past this line (docs/13 §7).
|
||||
# for the tag already exists, so any failure AFTER this step — a store
|
||||
# job, realistically — used to strand the tag: re-running could not get
|
||||
# past this line (docs/13 §7).
|
||||
- name: Create or update the Release
|
||||
env:
|
||||
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
@@ -103,45 +124,177 @@ jobs:
|
||||
set -euo pipefail
|
||||
if gh release view "$GITHUB_REF_NAME" >/dev/null 2>&1; then
|
||||
echo "Release $GITHUB_REF_NAME exists — re-uploading assets."
|
||||
gh release upload "$GITHUB_REF_NAME" dist/*-chrome.zip dist/SHA256SUMS.txt --clobber
|
||||
gh release upload "$GITHUB_REF_NAME" dist/*.zip dist/SHA256SUMS.txt --clobber
|
||||
else
|
||||
gh release create "$GITHUB_REF_NAME" dist/*-chrome.zip dist/SHA256SUMS.txt \
|
||||
gh release create "$GITHUB_REF_NAME" dist/*.zip dist/SHA256SUMS.txt \
|
||||
--verify-tag --generate-notes
|
||||
fi
|
||||
|
||||
store:
|
||||
# v1.0.x/v1.1.x are published by hand (docs/12 §3). Flipping the repo
|
||||
# variable CWS_AUTOPUBLISH to 'true' turns this on once the four CHROME_*
|
||||
# secrets exist. A variable, not a secret: only variables are allowed here.
|
||||
# --- Stores (docs/12 §3) -------------------------------------------------
|
||||
#
|
||||
# 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. Each
|
||||
# runs in a GitHub Environment that holds only its own secrets (give it the
|
||||
# owner as required reviewer), is off until its repo VARIABLE is 'true' (a
|
||||
# secret is not allowed in a job-level `if:`), and installs only
|
||||
# tools/publish — publish-browser-extension and its three dependencies, from
|
||||
# their own lockfile, scripts off — not the dev toolchain: a job's secrets
|
||||
# are readable by everything on its runner. Never re-run a store job that
|
||||
# succeeded: every store refuses a version number it has already seen.
|
||||
|
||||
# A sparse checkout of tools/publish still brings the repository's root files
|
||||
# (cone mode), .nvmrc among them.
|
||||
store-chrome:
|
||||
name: Publish to Chrome Web Store
|
||||
needs: publish
|
||||
if: vars.CWS_AUTOPUBLISH == 'true'
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 15
|
||||
environment: chrome-web-store
|
||||
permissions:
|
||||
contents: read
|
||||
steps:
|
||||
- uses: actions/checkout@v7
|
||||
with:
|
||||
persist-credentials: false
|
||||
sparse-checkout: tools/publish
|
||||
- uses: actions/setup-node@v7
|
||||
with:
|
||||
node-version-file: .nvmrc
|
||||
cache: npm
|
||||
- run: npm ci --ignore-scripts
|
||||
- run: npm ci --ignore-scripts --prefix tools/publish
|
||||
- uses: actions/download-artifact@v8
|
||||
with:
|
||||
name: release-${{ github.ref_name }}
|
||||
path: dist
|
||||
- name: Submit the Release asset
|
||||
# Against the SHA256SUMS.txt of the published Release — not the copy that
|
||||
# travelled in the same artifact — and by exact name, so a missing file
|
||||
# fails here rather than passing a check that skipped it.
|
||||
- name: Check against the published checksums
|
||||
env:
|
||||
GH_TOKEN: ${{ github.token }}
|
||||
GH_REPO: ${{ github.repository }}
|
||||
run: |
|
||||
set -euo pipefail
|
||||
VERSION="${GITHUB_REF_NAME#v}"
|
||||
gh release download "$GITHUB_REF_NAME" --pattern SHA256SUMS.txt --dir published
|
||||
cd dist
|
||||
for file in "bookmarkmagic-${VERSION}-chrome.zip"; do
|
||||
grep -F " $file" ../published/SHA256SUMS.txt | sha256sum -c -
|
||||
done
|
||||
- name: Submit
|
||||
env:
|
||||
# API v2: v1.1 was shut down on 2026-10-15. Set explicitly — the tool
|
||||
# still defaults to v1.1.
|
||||
CHROME_API_VERSION: v2
|
||||
CHROME_PUBLISHER_ID: ${{ secrets.CHROME_PUBLISHER_ID }}
|
||||
CHROME_EXTENSION_ID: ${{ secrets.CHROME_EXTENSION_ID }}
|
||||
CHROME_CLIENT_ID: ${{ secrets.CHROME_CLIENT_ID }}
|
||||
CHROME_CLIENT_SECRET: ${{ secrets.CHROME_CLIENT_SECRET }}
|
||||
CHROME_REFRESH_TOKEN: ${{ secrets.CHROME_REFRESH_TOKEN }}
|
||||
# The locally installed wxt, never `npx wxt`: npx may fetch and run an
|
||||
# unpinned package with these four secrets in its environment.
|
||||
run: ./node_modules/.bin/wxt submit --chrome-zip dist/*-chrome.zip
|
||||
CHROME_SERVICE_ACCOUNT_CLIENT_EMAIL: ${{ secrets.CHROME_SERVICE_ACCOUNT_CLIENT_EMAIL }}
|
||||
CHROME_SERVICE_ACCOUNT_PRIVATE_KEY: ${{ secrets.CHROME_SERVICE_ACCOUNT_PRIVATE_KEY }}
|
||||
run: |
|
||||
set -euo pipefail
|
||||
./tools/publish/node_modules/.bin/publish-extension \
|
||||
--chrome-zip "dist/bookmarkmagic-${GITHUB_REF_NAME#v}-chrome.zip"
|
||||
|
||||
store-firefox:
|
||||
name: Publish to Firefox Add-ons
|
||||
needs: publish
|
||||
if: vars.AMO_AUTOPUBLISH == 'true'
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 30
|
||||
environment: firefox-add-ons
|
||||
permissions:
|
||||
contents: read
|
||||
steps:
|
||||
- uses: actions/checkout@v7
|
||||
with:
|
||||
persist-credentials: false
|
||||
sparse-checkout: tools/publish
|
||||
- uses: actions/setup-node@v7
|
||||
with:
|
||||
node-version-file: .nvmrc
|
||||
- run: npm ci --ignore-scripts --prefix tools/publish
|
||||
- uses: actions/download-artifact@v8
|
||||
with:
|
||||
name: release-${{ github.ref_name }}
|
||||
path: dist
|
||||
# Against the SHA256SUMS.txt of the published Release — not the copy that
|
||||
# travelled in the same artifact — and by exact name, so a missing file
|
||||
# fails here rather than passing a check that skipped it.
|
||||
- name: Check against the published checksums
|
||||
env:
|
||||
GH_TOKEN: ${{ github.token }}
|
||||
GH_REPO: ${{ github.repository }}
|
||||
run: |
|
||||
set -euo pipefail
|
||||
VERSION="${GITHUB_REF_NAME#v}"
|
||||
gh release download "$GITHUB_REF_NAME" --pattern SHA256SUMS.txt --dir published
|
||||
cd dist
|
||||
for file in "bookmarkmagic-${VERSION}-firefox.zip" "bookmarkmagic-${VERSION}-sources.zip"; do
|
||||
grep -F " $file" ../published/SHA256SUMS.txt | sha256sum -c -
|
||||
done
|
||||
- name: Submit
|
||||
env:
|
||||
FIREFOX_EXTENSION_ID: ${{ secrets.FIREFOX_EXTENSION_ID }}
|
||||
FIREFOX_JWT_ISSUER: ${{ secrets.FIREFOX_JWT_ISSUER }}
|
||||
FIREFOX_JWT_SECRET: ${{ secrets.FIREFOX_JWT_SECRET }}
|
||||
FIREFOX_CHANNEL: listed
|
||||
# Desktop only: Firefox for Android has no bookmarks API (docs/08 §9).
|
||||
FIREFOX_COMPATIBILITY: firefox
|
||||
run: |
|
||||
set -euo pipefail
|
||||
VERSION="${GITHUB_REF_NAME#v}"
|
||||
./tools/publish/node_modules/.bin/publish-extension \
|
||||
--firefox-zip "dist/bookmarkmagic-${VERSION}-firefox.zip" \
|
||||
--firefox-sources-zip "dist/bookmarkmagic-${VERSION}-sources.zip"
|
||||
|
||||
store-edge:
|
||||
name: Publish to Microsoft Edge Add-ons
|
||||
needs: publish
|
||||
if: vars.EDGE_AUTOPUBLISH == 'true'
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 30
|
||||
environment: edge-add-ons
|
||||
permissions:
|
||||
contents: read
|
||||
steps:
|
||||
- uses: actions/checkout@v7
|
||||
with:
|
||||
persist-credentials: false
|
||||
sparse-checkout: tools/publish
|
||||
- uses: actions/setup-node@v7
|
||||
with:
|
||||
node-version-file: .nvmrc
|
||||
- run: npm ci --ignore-scripts --prefix tools/publish
|
||||
- uses: actions/download-artifact@v8
|
||||
with:
|
||||
name: release-${{ github.ref_name }}
|
||||
path: dist
|
||||
# Against the SHA256SUMS.txt of the published Release — not the copy that
|
||||
# travelled in the same artifact — and by exact name, so a missing file
|
||||
# fails here rather than passing a check that skipped it.
|
||||
- name: Check against the published checksums
|
||||
env:
|
||||
GH_TOKEN: ${{ github.token }}
|
||||
GH_REPO: ${{ github.repository }}
|
||||
run: |
|
||||
set -euo pipefail
|
||||
VERSION="${GITHUB_REF_NAME#v}"
|
||||
gh release download "$GITHUB_REF_NAME" --pattern SHA256SUMS.txt --dir published
|
||||
cd dist
|
||||
for file in "bookmarkmagic-${VERSION}-chrome.zip"; do
|
||||
grep -F " $file" ../published/SHA256SUMS.txt | sha256sum -c -
|
||||
done
|
||||
- name: Submit
|
||||
env:
|
||||
# API v1.1 keys expire every 72 days (docs/12 §3).
|
||||
EDGE_PRODUCT_ID: ${{ secrets.EDGE_PRODUCT_ID }}
|
||||
EDGE_CLIENT_ID: ${{ secrets.EDGE_CLIENT_ID }}
|
||||
EDGE_API_KEY: ${{ secrets.EDGE_API_KEY }}
|
||||
run: |
|
||||
set -euo pipefail
|
||||
# Edge Add-ons takes the Chromium package unchanged (docs/08 §10).
|
||||
./tools/publish/node_modules/.bin/publish-extension \
|
||||
--edge-zip "dist/bookmarkmagic-${GITHUB_REF_NAME#v}-chrome.zip"
|
||||
|
||||
# A job INSIDE this workflow, not an `on: release: [published]` caller.
|
||||
# A Release created by `gh release create` under the default GITHUB_TOKEN
|
||||
@@ -163,7 +316,7 @@ jobs:
|
||||
# `on: push: tags` — so without this the job exits 1 and never announces.
|
||||
tag_override: ${{ github.ref_name }}
|
||||
# Named, not `inherit`: the reusable is pinned to a moving branch, so it gets
|
||||
# only the two webhooks it reads — never the CHROME_* or SONAR secrets. The
|
||||
# only the two webhooks it reads — never the store or SONAR secrets. The
|
||||
# names also differ: this repo stores RELEASES_WEBHOOK / REPO_WEBHOOK, while
|
||||
# the reusable reads DISCORD_* — with `inherit` it received neither and would
|
||||
# have failed on "No webhooks configured" the day DISCORD_ANNOUNCE was set.
|
||||
|
||||
@@ -107,7 +107,7 @@ jobs:
|
||||
if: steps.token.outputs.present == 'true'
|
||||
# Pinned to a commit, not a moving tag: this step holds a token. Dependabot
|
||||
# proposes updates (with the repo's 7-day cooldown).
|
||||
uses: SonarSource/sonarqube-scan-action@d209202bc7d53ff1cc128f7f907dac145c9d6ae9 # v8.3.0
|
||||
uses: SonarSource/sonarqube-scan-action@e805d875275f728fac1885b413934be6d7c63f65 # v8.4.1
|
||||
env:
|
||||
SONAR_TOKEN: ${{ secrets.SONAR_TOKEN }}
|
||||
with:
|
||||
|
||||
@@ -0,0 +1,94 @@
|
||||
# Maintenance-mode triage — MAINTENANCE.md, docs/12 §2.6.
|
||||
#
|
||||
# scripts/triage.mjs decides (a pure, unit-tested function of the event); this
|
||||
# file only carries the decision out with the `gh` CLI the runner ships. No
|
||||
# third-party action holds the write token.
|
||||
#
|
||||
# Security, because `pull_request_target` runs with a write token even for a
|
||||
# pull request from a fork:
|
||||
# - the checkout is the DEFAULT BRANCH (what pull_request_target checks out
|
||||
# unless told otherwise) — never the pull request's head, and nothing from
|
||||
# the pull request is executed;
|
||||
# - the payload reaches the script as the runner's event FILE; no title, body
|
||||
# or label is ever interpolated into a shell line with `${{ }}`;
|
||||
# - the decision the shell reads back is constants: an action from a fixed
|
||||
# set, an integer, a label from a fixed list, a comment the script wrote.
|
||||
name: Triage
|
||||
|
||||
on:
|
||||
issues:
|
||||
types: [opened, labeled]
|
||||
pull_request_target:
|
||||
types: [opened]
|
||||
|
||||
permissions: {}
|
||||
|
||||
# A new issue from the feature form fires `opened` and `labeled` together; one
|
||||
# at a time per number, and the second re-reads the live state before acting.
|
||||
concurrency:
|
||||
group: triage-${{ github.event.issue.number || github.event.pull_request.number }}
|
||||
cancel-in-progress: false
|
||||
|
||||
jobs:
|
||||
triage:
|
||||
name: Maintenance-mode triage
|
||||
runs-on: ubuntu-latest
|
||||
timeout-minutes: 5
|
||||
permissions:
|
||||
contents: read
|
||||
issues: write
|
||||
pull-requests: write
|
||||
steps:
|
||||
# Pinned to commits, unlike the other workflows: these two run with a
|
||||
# write token on events anyone can trigger, fork pull requests included.
|
||||
# No `cache:` on setup-node — a cache written here could be read back by
|
||||
# a job that trusts it.
|
||||
- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
|
||||
with:
|
||||
persist-credentials: false
|
||||
- uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
|
||||
with:
|
||||
node-version-file: .nvmrc
|
||||
|
||||
- name: Decide
|
||||
run: node scripts/triage.mjs > "$RUNNER_TEMP/decision.json"
|
||||
|
||||
- name: Act
|
||||
env:
|
||||
GH_TOKEN: ${{ github.token }}
|
||||
GH_REPO: ${{ github.repository }}
|
||||
run: |
|
||||
set -euo pipefail
|
||||
decision="$RUNNER_TEMP/decision.json"
|
||||
action=$(jq -r '.action' "$decision")
|
||||
echo "triage: $action — $(jq -r '.reason' "$decision")"
|
||||
[ "$action" = none ] && exit 0
|
||||
|
||||
kind=$(jq -r '.kind' "$decision")
|
||||
number=$(jq -r '.number' "$decision")
|
||||
label=$(jq -r '.label' "$decision")
|
||||
case "$kind" in issue|pr) ;; *) echo "::error::unexpected kind"; exit 1 ;; esac
|
||||
[[ "$number" =~ ^[0-9]+$ ]] || { echo "::error::unexpected number"; exit 1; }
|
||||
|
||||
# Re-read the live state: the second of two events for one issue
|
||||
# finds the first one's label and does nothing.
|
||||
live=$(gh "$kind" view "$number" --json state,labels \
|
||||
--jq '[.state] + [.labels[].name] | join(" ")')
|
||||
case " $live " in
|
||||
*" maintenance-mode "*|*" needs-triage "*|*" roadmap "*)
|
||||
echo "already triaged: $live"; exit 0 ;;
|
||||
esac
|
||||
case "$live" in OPEN*) ;; *) echo "not open: $live"; exit 0 ;; esac
|
||||
|
||||
# Comment and close FIRST, label last: the label is what a re-run
|
||||
# reads as "done", so it must not exist before the work it stands for.
|
||||
if [ "$action" = close ]; then
|
||||
jq -r '.comment' "$decision" > "$RUNNER_TEMP/comment.md"
|
||||
gh "$kind" comment "$number" --body-file "$RUNNER_TEMP/comment.md"
|
||||
if [ "$kind" = issue ]; then
|
||||
gh issue close "$number" --reason "not planned"
|
||||
else
|
||||
gh pr close "$number"
|
||||
fi
|
||||
fi
|
||||
gh "$kind" edit "$number" --add-label "$label"
|
||||
@@ -0,0 +1,259 @@
|
||||
# Accessibility
|
||||
|
||||
BookmarkMagic should be usable by anyone who has bookmarks to move — with a
|
||||
keyboard and no mouse, with a screen reader, with a contrast theme, with the
|
||||
page zoomed, or with animation switched off. This file says what that means
|
||||
today: what the goal is, what has actually been tested, what is known not to
|
||||
work well yet, and how to tell us about a barrier.
|
||||
|
||||
**Last reviewed:** 2026-11-18, for version 1.3.0.
|
||||
|
||||
## The goal
|
||||
|
||||
The target is the [Web Content Accessibility Guidelines (WCAG) 2.2](https://www.w3.org/TR/WCAG22/)
|
||||
at **Level AA**.
|
||||
|
||||
That is a goal, not a claim. BookmarkMagic has not been audited by an
|
||||
accessibility specialist, and it does not claim to conform to WCAG. It is
|
||||
built and tested by one person, and the testing that has been done is listed
|
||||
below so you can judge it for yourself.
|
||||
|
||||
The priorities, in order:
|
||||
|
||||
1. **Everything works from the keyboard.** No task needs a mouse.
|
||||
2. **A screen reader is told what is on screen and what just happened** —
|
||||
names, roles, states, and the result of an import.
|
||||
3. **Nothing depends on colour, motion or a pointer's precision alone.**
|
||||
4. **Every shipped language is treated the same** — English, Tiếng Việt, 日本語,
|
||||
简体中文 and Română. The page's language is declared to the browser, so a
|
||||
screen reader picks the right voice.
|
||||
|
||||
## Supported environments
|
||||
|
||||
| Environment | Status |
|
||||
|---|---|
|
||||
| Chrome 136 or later on Windows | Supported, and where the testing below was done |
|
||||
| Chrome 136 or later on macOS, Linux and ChromeOS | Supported; expected to work the same, not tested for accessibility |
|
||||
| Edge, Brave, Vivaldi and Opera (the same package as Chrome) | Best effort — the extension runs there, and accessibility is untested |
|
||||
| Firefox 140 or later on the desktop (since 1.3.0, its own package) | Best effort — the extension runs there, and accessibility is untested |
|
||||
| Chrome on Android or iOS | Not applicable: Chrome there does not run extensions |
|
||||
| Firefox for Android | Not applicable: it has no bookmarks API for extensions |
|
||||
|
||||
## What is in place
|
||||
|
||||
### Keyboard
|
||||
|
||||
Every control is either a tab stop or has a key of its own, and every dialog
|
||||
can be closed with Esc. Focus shows as a 2-pixel ring on controls; inside the
|
||||
bookmark tree, the current row is marked by a highlight and a bar at its left
|
||||
edge.
|
||||
|
||||
The bookmark tree on the **Edit** tab is a single tab stop. Inside it:
|
||||
|
||||
| Key | What it does |
|
||||
|---|---|
|
||||
| ↑ / ↓ | Move to the previous or next row |
|
||||
| Home / End | Move to the first or last row |
|
||||
| → | Open a closed folder, or step into an open one |
|
||||
| ← | Close an open folder, or step out to its parent |
|
||||
| A letter or digit | Jump to the next row whose title starts with it |
|
||||
| Enter | Open a bookmark in a new tab; open or close a folder |
|
||||
| F2 | Rename (Enter saves, Esc cancels) |
|
||||
| Delete (Fn+Delete on a Mac laptop) | Delete, after a confirmation |
|
||||
| Menu key, or Shift+F10 | **Move to…** — pick a destination folder from a filterable list |
|
||||
| Alt+↑ / Alt+↓ | Move the row up or down one place inside its folder |
|
||||
| Ctrl+C (⌘C on macOS) | Copy the focused bookmark's address |
|
||||
| Ctrl+F (⌘F on macOS) | Go to the search box, from anywhere on the Edit tab |
|
||||
|
||||
The small buttons that appear on a row are shortcuts for the mouse, and are
|
||||
deliberately not tab stops: Open, Copy link, Rename, Move to… and Delete each
|
||||
have a key in the table above, and Sort A→Z is also a button on the toolbar.
|
||||
|
||||
Alt+↑ and Alt+↓ move a row past the neighbour you can see. While a search is
|
||||
filtering the tree, that also carries it past any hidden items in between.
|
||||
|
||||
Elsewhere: the theme control is a radio group (arrow keys change the choice),
|
||||
the file drop zone is a button that opens the file picker, and the folder
|
||||
lists in the import preview and the export picker are ordinary lists with
|
||||
buttons and checkboxes — Tab, Enter and Space.
|
||||
|
||||
### Screen readers
|
||||
|
||||
- The Edit tree is an ARIA tree: each row announces its name, its level, its
|
||||
position ("3 of 12") and whether it is expanded.
|
||||
- Dialogs are native `<dialog>` elements. Focus moves in when one opens and
|
||||
returns when it closes; a confirmation reads its title and its body, and
|
||||
opens with **Cancel** focused, so Enter never confirms a deletion.
|
||||
- An import is spoken as it goes: reading the file, backing up, writing,
|
||||
progress every 10 %, and the result. Failures are announced as alerts.
|
||||
- Moving a row with Alt+↑ or Alt+↓ announces its new position ("Docs:
|
||||
position 2 of 5"). This is new in 1.2.1 and has not yet been checked with a
|
||||
screen reader — see "What has been tested".
|
||||
- When an import moves to its next step, focus moves to that step's heading.
|
||||
When a page change removes the control that had focus, focus moves to the
|
||||
page's main content rather than back to the top of the page.
|
||||
- Every icon-only button has a name. Icons themselves are hidden from
|
||||
assistive technology.
|
||||
- The page title names the current section, and the page's language follows
|
||||
the language you chose.
|
||||
|
||||
### Seeing the page
|
||||
|
||||
- **Contrast.** Text is at least 4.5:1 against its background, and control
|
||||
borders and the focus ring at least 3:1, in the light and the dark theme. A
|
||||
test fails the build if a colour pair drops below that.
|
||||
- **Contrast themes** (Windows "Contrast themes", `forced-colors`). Since
|
||||
1.2.1, the states that were shown only by a fill or a shadow — the focused
|
||||
row, where a dragged item will land, the selected theme, the current
|
||||
section, the selected option cards, the progress bar, the edge of the file
|
||||
drop zone — are drawn with the theme's own colours instead.
|
||||
- **Zoom.** The layout reflows as the window narrows or the page is zoomed.
|
||||
- **Light and dark** themes follow the system, or your choice in Settings.
|
||||
- **Disabled buttons** are marked by colour and cursor, never by fading the
|
||||
text until it cannot be read. (Two kinds of button are an exception; see
|
||||
the limitations.)
|
||||
- **Target size.** Since 1.2.1, every button is at least 24 × 24 CSS pixels,
|
||||
including the small icon buttons. Checkboxes, radio buttons and links in
|
||||
text keep their natural size; their labels are part of the target.
|
||||
|
||||
### Motion
|
||||
|
||||
If your system asks for reduced motion, nothing moves: no sliding, spinning or
|
||||
travelling stripes. A test fails the build if an animation is added outside
|
||||
that rule. Nothing flashes. An error message stays until you dismiss it;
|
||||
short confirmations leave by themselves after four seconds (see the
|
||||
limitations below).
|
||||
|
||||
## What has been tested
|
||||
|
||||
| Check | With | When |
|
||||
|---|---|---|
|
||||
| Keyboard only, mouse unplugged | Chrome on Windows 11 | November 2026, version 1.2.0 |
|
||||
| Screen reader | **Narrator** with Chrome on Windows 11 | November 2026, version 1.2.0 |
|
||||
| Contrast themes | Chrome with `forced-colors` emulated — not yet a real Windows theme | November 2026, version 1.2.1 |
|
||||
| What 1.2.1 changed: focus, Alt+↑/↓, button sizes | A scripted keyboard run in Chrome — no screen reader | November 2026, version 1.2.1 |
|
||||
| Colour contrast of the theme colours, reduced motion, the tree's key handling | Automated tests, on every change | Continuous |
|
||||
|
||||
**Not tested**, so we cannot tell you how well they work: anything in Firefox
|
||||
or Edge; anything on macOS, Linux or ChromeOS; NVDA, JAWS, VoiceOver, ChromeVox and Orca; voice control
|
||||
(Dragon, Voice Access, Voice Control); switch access; screen magnifiers; and
|
||||
zoom at 200 %. Narrator has not yet been run over what 1.2.1 added.
|
||||
If you use one of these, a report of what you found — good or bad — is
|
||||
genuinely useful.
|
||||
|
||||
## Known limitations
|
||||
|
||||
These are known, and none of them is by design.
|
||||
|
||||
- **Most edits are not announced.** Alt+↑/↓ announces the result; a rename, a
|
||||
move to another folder, a sort and a new folder succeed silently. Search
|
||||
does not announce how many rows match. A key that cannot act — Alt+↑ on the
|
||||
first item of a folder, Delete on one of the three top-level folders — does
|
||||
nothing and says nothing.
|
||||
- **Folders and bookmarks sound alike in the tree.** They differ by an icon a
|
||||
screen reader does not read. A folder with something in it announces
|
||||
"expanded" or "collapsed"; an empty folder announces neither. The lock on a
|
||||
bookmark your organisation manages is also only an icon, and a folder's
|
||||
item count is read as a bare number.
|
||||
- **A focused row may read out its buttons** ("Open, Copy link, Rename…")
|
||||
after its name. It is noisy, not broken.
|
||||
- **Reordering with a pointer needs a drag.** There is a keyboard way
|
||||
(Alt+↑/↓) and Sort A→Z, but no click-only way to place one item before
|
||||
another.
|
||||
- **Separators in Firefox are only drawn.** A line in a Firefox folder is
|
||||
shown in the tree, but a screen reader is not told it is there, and the
|
||||
"position n of m" counts bookmarks and folders only — so Alt+↑ or Alt+↓ past
|
||||
a separator moves the row without changing the position you hear.
|
||||
- **Alt+↑/↓ may not reach the page on a Chromebook**, where the system can turn
|
||||
those keys into Page Up and Page Down. On a Mac there is no Menu key (use
|
||||
Shift+F10), and the laptop's delete key is Backspace, which the tree does
|
||||
not act on (use Fn+Delete).
|
||||
- **The tree's keys are not shown inside the extension**, apart from Ctrl+F on
|
||||
the search box. The table above is the list; the About tab links to this
|
||||
file.
|
||||
- **The toolbar above the tree is announced as a toolbar**, but its buttons are
|
||||
reached with Tab, not with the arrow keys a toolbar usually offers.
|
||||
- **Some hints appear only on mouse hover**: the notes in the status bar, where
|
||||
a top-level folder of an imported file will go, and the reason a section is
|
||||
unavailable while an import is writing.
|
||||
- **A section that is unavailable while an import is writing looks the same as
|
||||
one that is available**; only the cursor and the hover hint differ. The same
|
||||
goes for a tree row's small buttons while a sort or a bulk delete is
|
||||
running. A screen reader does announce both as unavailable.
|
||||
- **Long titles are cut short with "…"** in the tree, and there is no way to
|
||||
read the whole title there other than renaming (F2).
|
||||
- **Headings are sparse.** Sections are landmarks, but the pages have few
|
||||
headings to jump between, and there is no "skip to content" link past the
|
||||
header's controls.
|
||||
- **Descriptions in Settings are not tied to their controls**, so a screen
|
||||
reader reads the control's name but not the sentence under it.
|
||||
- **Short notices disappear after four seconds** ("Saved", "Link copied",
|
||||
the name of an exported file). They are announced, but they cannot be
|
||||
paused. An error stays, though a second error replaces the first.
|
||||
- **Text size follows zoom, not the browser's font-size setting.** Use
|
||||
Ctrl and + to enlarge the page.
|
||||
- **On the Edit tab, Ctrl+F always goes to BookmarkMagic's own search box**
|
||||
rather than the browser's Find.
|
||||
- **The Japanese, Chinese and Romanian translations have not been reviewed by
|
||||
native speakers**, which includes the text a screen reader speaks.
|
||||
|
||||
## Reporting a barrier
|
||||
|
||||
If something stops you, or just gets in your way, please say so. An
|
||||
accessibility report is treated as a defect, not a feature request.
|
||||
|
||||
- **With a GitHub account:** open an
|
||||
[accessibility report](https://github.com/poli0981/bookmarkmagic/issues/new?template=accessibility.yml).
|
||||
- **Without one:** write to **accessibility@poli0981.dev**.
|
||||
|
||||
It helps to include:
|
||||
|
||||
- what you were trying to do, and what happened instead;
|
||||
- the BookmarkMagic version (About tab, `chrome://extensions`, or
|
||||
`about:addons` in Firefox);
|
||||
- your browser and operating system;
|
||||
- the assistive technology you use and its version, if any — a screen reader,
|
||||
a contrast theme, zoom level, voice control;
|
||||
- how badly it gets in the way: **blocked** (you could not finish),
|
||||
**hard** (you finished, with a workaround), or **annoying**.
|
||||
|
||||
You do not need to explain why you use the tools you use, and nobody will ask.
|
||||
|
||||
**Please do not send your real bookmarks file**, and check a screenshot or a
|
||||
recording for bookmark titles before attaching it — your bookmarks are your
|
||||
browsing history. [`CONTRIBUTING.md`](CONTRIBUTING.md) explains how to
|
||||
sanitize a file if a particular one is needed.
|
||||
|
||||
### What happens next
|
||||
|
||||
BookmarkMagic has one maintainer, so these are honest intentions rather than
|
||||
guarantees:
|
||||
|
||||
- A report is acknowledged within about a week.
|
||||
- A **blocking** barrier is fixed ahead of other work and shipped in its own
|
||||
patch release; your browser then updates installed copies by itself,
|
||||
usually within days of the store's review.
|
||||
- Anything else is scheduled, and added to the list above until it is fixed,
|
||||
so the next person can see it is known.
|
||||
- If a fix is not possible or not planned, you will be told why.
|
||||
- When a fix ships, you will be asked whether it actually works for you. Your
|
||||
answer counts for more than our test.
|
||||
|
||||
## For contributors
|
||||
|
||||
A change to the interface has to keep the above true.
|
||||
[`CONTRIBUTING.md`](CONTRIBUTING.md) and the pull-request checklist list what
|
||||
to check: keyboard, visible focus, names and labels, no meaning carried by
|
||||
colour alone, reduced motion, contrast themes, and one pass with a screen
|
||||
reader. The specification behind this statement is
|
||||
[`docs/06_UI.md` §5](docs/06_UI.md); if a change makes this file wrong, the
|
||||
same pull request has to correct it.
|
||||
|
||||
## Who is responsible
|
||||
|
||||
The maintainer, [@poli0981](https://github.com/poli0981), triages
|
||||
accessibility reports, keeps the limitations list current, and reviews this
|
||||
statement at every release.
|
||||
|
||||
Suggestions for the statement itself are welcome the same way as any other
|
||||
report.
|
||||
@@ -0,0 +1,63 @@
|
||||
# Building BookmarkMagic from source
|
||||
|
||||
How to rebuild the packages attached to each
|
||||
[GitHub Release](https://github.com/poli0981/bookmarkmagic/releases) — for
|
||||
Firefox Add-ons reviewers, who must be able to reproduce the submitted package
|
||||
from its sources, and for anyone who wants to check that a store build matches
|
||||
this repository.
|
||||
|
||||
## Requirements
|
||||
|
||||
| Tool | Version | Where |
|
||||
|---|---|---|
|
||||
| Node.js | **26** (the version in `.nvmrc`; tested with 26.13) | <https://nodejs.org/en/download> |
|
||||
| npm | the one bundled with Node.js 26 (11.x) | ships with Node.js |
|
||||
| OS | any — Windows 11, macOS and Ubuntu all build the same files | |
|
||||
|
||||
No other tool, account, network service or environment variable is needed
|
||||
beyond what `npm ci` installs from `package-lock.json`.
|
||||
|
||||
> **The Firefox sources archive omits dotfiles**, so `.nvmrc` and `.npmrc` are
|
||||
> not in it. Use Node.js 26: an older Node may install but is not what the
|
||||
> package was built with, and `package.json` says `"engines": { "node": ">=26" }`.
|
||||
|
||||
## Steps
|
||||
|
||||
```bash
|
||||
npm ci # exactly the versions in package-lock.json
|
||||
npm run zip:firefox # the Firefox package (and a sources archive)
|
||||
npm run zip # the Chromium package (Chrome Web Store, Edge Add-ons)
|
||||
```
|
||||
|
||||
`npm ci` runs one install script of this project's own, `wxt prepare`, which
|
||||
generates the TypeScript configuration the build reads. (CI installs with
|
||||
`--ignore-scripts` and runs `npx --no-install wxt prepare` itself; the result
|
||||
is the same.)
|
||||
|
||||
## Output
|
||||
|
||||
| Command | Unpacked build | Package |
|
||||
|---|---|---|
|
||||
| `npm run zip:firefox` | `.output/firefox-mv3/` | `.output/bookmarkmagic-<version>-firefox.zip` |
|
||||
| `npm run zip` | `.output/chrome-mv3/` | `.output/bookmarkmagic-<version>-chrome.zip` |
|
||||
|
||||
Compare the **files inside** the package with the submitted one, not the
|
||||
archives themselves: a zip records file times, so two builds of the same
|
||||
commit hash differently while every entry is identical (`docs/09 §5`).
|
||||
|
||||
## What the build does
|
||||
|
||||
- [WXT](https://wxt.dev) bundles `src/` with Vite into plain JavaScript, CSS
|
||||
and HTML. The code is **minified, not obfuscated**.
|
||||
- The only third-party code compiled in is the Svelte runtime, its `clsx`
|
||||
helper and WXT's one-line browser shim, all MIT
|
||||
([`legal/THIRD_PARTY_NOTICES.md`](legal/THIRD_PARTY_NOTICES.md)); the build
|
||||
fails if anything else would ship.
|
||||
- Nothing is downloaded at build time beyond `npm ci`, and the built extension
|
||||
makes no network requests at all — its content security policy forbids them
|
||||
([`docs/08_MV3_COMPLIANCE.md`](docs/08_MV3_COMPLIANCE.md) §3).
|
||||
|
||||
To check a build the way CI does: `npm run check:manifest` (Chromium) and
|
||||
`npm run check:manifest -- --browser firefox` (Firefox) verify the manifest,
|
||||
the permissions, the CSP, the file inventory and that no network API is in the
|
||||
bundle.
|
||||
+150
-5
@@ -5,13 +5,155 @@ All notable changes to BookmarkMagic are documented here.
|
||||
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
|
||||
and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
||||
|
||||
Per `docs/12 §4`: **patch** = fixes and translations · **minor** = features, and
|
||||
any change to the permission list or the store privacy tab · **major** =
|
||||
breaking format or schema changes (a BM JSON version bump).
|
||||
Per `docs/12 §4`: **patch** = fixes and translation fixes · **minor** =
|
||||
features, a new UI language, and any change to the permission list or the
|
||||
store privacy tab · **major** = breaking format or schema changes (a BM JSON
|
||||
version bump).
|
||||
|
||||
## [Unreleased]
|
||||
|
||||
Nothing yet.
|
||||
### Changed
|
||||
|
||||
- **About → Store listing** on a copy installed from Microsoft Edge Add-ons now
|
||||
opens BookmarkMagic's Edge Add-ons page, live since 2026-11-19. Until now it
|
||||
opened the install section of the project's README.
|
||||
|
||||
## [1.3.0] — 2026-11-18
|
||||
|
||||
Firefox and Microsoft Edge, and maintenance mode. Permissions are unchanged
|
||||
(`bookmarks` and `storage`), nothing is asked of you again, and on Chrome
|
||||
there is nothing to do — your browser updates itself. This version also
|
||||
carries everything listed under 1.2.1, which never reached the Chrome Web
|
||||
Store on its own.
|
||||
|
||||
### Added
|
||||
|
||||
- **Firefox** (desktop, 140 or later), with a package of its own for Firefox
|
||||
Add-ons — listing to come. The same features, the same two permissions and
|
||||
the same no-network policy, which Firefox enforces just as Chrome does.
|
||||
Firefox's **Bookmarks Menu** is a root like the others: Merge and Replace put
|
||||
entries back where they came from. Whatever a file leaves loose at its top
|
||||
level goes into the menu, as Firefox's own import does — the menu itself in
|
||||
a Firefox export, but also Other's and Mobile's contents in Chrome's own
|
||||
HTML export, which Chrome writes loose. BookmarkMagic's exports and backups
|
||||
name every root and are not affected.
|
||||
- **Microsoft Edge Add-ons** — the Chrome package, unchanged; listing to come.
|
||||
Until then Edge installs from the Chrome Web Store.
|
||||
- **Firefox separators** show in the Edit tab as lines. Nothing acts on them:
|
||||
they are not focused, searched, counted, sorted across, or offered as
|
||||
duplicates of each other. Sort A→Z sorts each run between two separators on
|
||||
its own.
|
||||
- Replace on Firefox says how many separators it will delete — no file
|
||||
BookmarkMagic writes can keep one, so they do not come back with the backup.
|
||||
- An import says how many separators the file held, and on Firefox skips — and
|
||||
counts — any address longer than the 65,536 characters Firefox accepts,
|
||||
before anything is written.
|
||||
|
||||
### Changed
|
||||
|
||||
- The About tab's store link is now **"Store listing"** and opens the store
|
||||
your copy came from: the Chrome Web Store for the Chrome Web Store's copy,
|
||||
Firefox Add-ons in Firefox, and otherwise the README's list of stores.
|
||||
- Sentences that blamed Chrome for what every browser does now say "the
|
||||
browser" — "The browser does not let an extension set a bookmark's original
|
||||
date" — in all five languages; the note about skipped Firefox smart
|
||||
bookmarks no longer calls them dead links.
|
||||
- Copy diagnostics names the browser and its version (`"browser": "Firefox
|
||||
160"`) instead of only Chrome's.
|
||||
- The project is in **maintenance mode** ([`MAINTENANCE.md`](MAINTENANCE.md)):
|
||||
fixes, accessibility, translations, security and dependency updates, and
|
||||
features that are already on the roadmap.
|
||||
|
||||
### Fixed
|
||||
|
||||
- Since 1.1.0, in a Chrome signed in with account bookmarks (Chrome 134 or
|
||||
later), Replace's confirmation counted the account's own bar, Other and
|
||||
Mobile among what it would delete. Replace has never touched them; the count
|
||||
now covers exactly what it deletes.
|
||||
|
||||
### Packages
|
||||
|
||||
Each GitHub Release now carries three files: `…-chrome.zip` (the Chrome Web
|
||||
Store and Edge Add-ons), `…-firefox.zip` and `…-sources.zip` (what Firefox
|
||||
Add-ons reviews), with `SHA256SUMS.txt` over all three. [`BUILD.md`](BUILD.md)
|
||||
explains how to rebuild them.
|
||||
|
||||
## [1.2.1] — 2026-11-10
|
||||
|
||||
Accessibility. Permissions are unchanged (`bookmarks` and `storage`), nothing
|
||||
is asked of you again, and there is nothing to do — Chrome updates itself.
|
||||
|
||||
### Added
|
||||
|
||||
- **An accessibility statement**,
|
||||
[`ACCESSIBILITY.md`](ACCESSIBILITY.md): what works with a keyboard and a
|
||||
screen reader, what was tested and with what, what is known not to work
|
||||
well yet, every key the Edit tree understands, and how to report a barrier.
|
||||
About links to it.
|
||||
- **Reorder with the keyboard.** On the Edit tab, **Alt+↑** and **Alt+↓** move
|
||||
the focused bookmark or folder one place up or down inside its folder — until
|
||||
now only a drag could do that. The new position is announced for screen
|
||||
readers (not yet checked with one).
|
||||
- **Windows contrast themes.** The focused row, the line that shows where a
|
||||
dragged item will land, the selected theme, the current section, the
|
||||
selected import mode and export format, the progress bar and the drop zone's
|
||||
outline are now drawn in the theme's own colours; before, they disappeared.
|
||||
Checked with Chrome's emulation so far, not yet with a real theme.
|
||||
|
||||
### Fixed
|
||||
|
||||
- The theme switch showed no focus ring: it was drawn in the same colour as
|
||||
the button under it.
|
||||
- Keyboard focus is no longer thrown back to the top of the page after "Open
|
||||
in Edit", after "Keep the first of each", or after sorting a folder from the
|
||||
toolbar.
|
||||
- Clicking a row's button or its arrow no longer stops the arrow keys from
|
||||
working in the tree.
|
||||
- Clicking a row in a long, scrolled tree no longer jumps the tree back to the
|
||||
top.
|
||||
- Small buttons — the ones on a tree row, the folder arrows, the close buttons
|
||||
on dialogs and notices, the popup's gear, "Show more" — are at least
|
||||
24 × 24 pixels to click or tap.
|
||||
- The focus ring was cut off on "Show earlier / Show more" in the tree and on
|
||||
the folders in "Move to…"; the selected theme lost its label on hover; and
|
||||
the search box's placeholder text was fainter than the rest.
|
||||
|
||||
### Notes
|
||||
|
||||
- The goal is WCAG 2.2 AA; it is a goal, not a claim — nobody has audited the
|
||||
extension. If something is hard or impossible to use, the "Something is hard
|
||||
or impossible to use" form on GitHub, or accessibility@poli0981.dev, reaches
|
||||
the maintainer.
|
||||
- The two new pieces of text are best-effort in Japanese, Chinese and Romanian,
|
||||
like the rest of those translations.
|
||||
|
||||
## [1.2.0] — 2026-11-06
|
||||
|
||||
Two new languages. Permissions are unchanged (`bookmarks` and `storage`), and
|
||||
there is nothing to do — Chrome updates itself.
|
||||
|
||||
### Added
|
||||
|
||||
- **简体中文 (Simplified Chinese)** and **Română (Romanian)**, in the extension
|
||||
and in its name and description in `chrome://extensions`. Pick one under
|
||||
Settings → Language, or leave it on Automatic.
|
||||
- Romanian counts read the way Romanian does: "1 marcaj", "5 marcaje",
|
||||
"20 de marcaje".
|
||||
- Sort A→Z follows the language you use: pinyin order in Chinese, and `ș`/`ț`
|
||||
as letters of their own in Romanian.
|
||||
|
||||
### Changed
|
||||
|
||||
- **If your browser is set to Simplified Chinese or Romanian and the language
|
||||
setting is Automatic** (the default), BookmarkMagic switches from English to
|
||||
that language after this update. A browser in Traditional Chinese stays in
|
||||
English; 简体中文 can still be chosen by hand.
|
||||
|
||||
### Notes
|
||||
|
||||
- Both translations are best-effort, written from Chrome's own wording in each
|
||||
language but not yet read by a native speaker. If something reads wrong,
|
||||
the translation form on GitHub takes a sentence — no code needed.
|
||||
|
||||
## [1.1.0] — 2026-10-29
|
||||
|
||||
@@ -215,7 +357,10 @@ from 2026-08-03.
|
||||
- Parsing is bounded: 25 MB per file, 100 000 nodes, 200 levels of nesting.
|
||||
- No network access of any kind at runtime, enforced by a grep gate in CI.
|
||||
|
||||
[Unreleased]: https://github.com/poli0981/bookmarkmagic/compare/v1.1.0...HEAD
|
||||
[Unreleased]: https://github.com/poli0981/bookmarkmagic/compare/v1.3.0...HEAD
|
||||
[1.3.0]: https://github.com/poli0981/bookmarkmagic/compare/v1.2.1...v1.3.0
|
||||
[1.2.1]: https://github.com/poli0981/bookmarkmagic/compare/v1.2.0...v1.2.1
|
||||
[1.2.0]: https://github.com/poli0981/bookmarkmagic/compare/v1.1.0...v1.2.0
|
||||
[1.1.0]: https://github.com/poli0981/bookmarkmagic/compare/v1.0.1...v1.1.0
|
||||
[1.0.1]: https://github.com/poli0981/bookmarkmagic/compare/v1.0.0...v1.0.1
|
||||
[1.0.0]: https://github.com/poli0981/bookmarkmagic/releases/tag/v1.0.0
|
||||
@@ -1,6 +1,7 @@
|
||||
# CLAUDE.md — Build Instructions (BookmarkMagic)
|
||||
|
||||
A Chrome MV3 extension: offline bookmark import/export/edit.
|
||||
A Chrome MV3 extension — and since v1.3.0 a Firefox one, and on Edge Add-ons —
|
||||
for offline bookmark import/export/edit.
|
||||
This file is the entry point; the `docs/` suite is the specification.
|
||||
**When code and docs disagree, docs win — or stop and ask.**
|
||||
|
||||
@@ -8,9 +9,20 @@ This file is the entry point; the `docs/` suite is the specification.
|
||||
>
|
||||
> **BookmarkMagic is published on the Chrome Web Store and has real users**
|
||||
> (v1.0.0 live by 2026-08-03; v1.0.1 live, confirmed on the listing
|
||||
> 2026-10-28). Phases 0–6 are complete; the project is in **maintenance**.
|
||||
> 2026-10-28; v1.1.0 live, confirmed on the listing 2026-11-06; v1.2.0 live,
|
||||
> confirmed on the listing 2026-11-10; v1.2.1 released on GitHub 2026-11-10,
|
||||
> never submitted on its own; v1.3.0 — Firefox and Edge, 1.2.1 included —
|
||||
> released on GitHub and submitted to all three stores 2026-11-18, **live on
|
||||
> Edge Add-ons 2026-11-19**, ⚠️ in review on the Chrome Web Store and Firefox
|
||||
> Add-ons).
|
||||
> Phases 0–9 are complete; since 2026-11-18 the project is in **maintenance
|
||||
> mode** — `/MAINTENANCE.md` is the policy (Phase 10 below).
|
||||
> That changes the rules of the game:
|
||||
>
|
||||
> - **New work must fit `/MAINTENANCE.md`**: dependency and security updates,
|
||||
> major platform upgrades, bug/UI/UX/accessibility/translation fixes, and
|
||||
> features only when they are on `docs/15`'s roadmap or genuinely needed. A
|
||||
> feature that is not on the roadmap needs a decision-log row before code.
|
||||
> - Every change now reaches installed users through a store review. It needs a
|
||||
> semver bump, a `CHANGELOG.md` entry and an update submission — `13 §1b`.
|
||||
> - Breaking something is no longer a local cost. The 1.0.0 → 1.0.x **upgrade
|
||||
@@ -31,9 +43,9 @@ This file is the entry point; the `docs/` suite is the specification.
|
||||
| docs/03_DATA_FLOW.md | Import/export/edit pipelines, state machine |
|
||||
| docs/04_FILE_FORMATS.md | Netscape HTML / BM JSON / CSV / Markdown specs |
|
||||
| docs/05_ALGORITHMS.md | Parser walk, normalize, dedupe, diff, write queue |
|
||||
| docs/06_UI.md | Tokens, layouts per tab, component inventory, a11y |
|
||||
| docs/06_UI.md | Tokens, layouts per tab, component inventory, a11y (§5 is the spec behind `/ACCESSIBILITY.md`) |
|
||||
| docs/07_I18N.md | chrome.i18n vs runtime store split, EN/VI/JA rules |
|
||||
| docs/08_MV3_COMPLIANCE.md | Manifest, permissions (bookmarks+storage ONLY), CWS rules |
|
||||
| docs/08_MV3_COMPLIANCE.md | Manifest, permissions (bookmarks+storage ONLY), CWS rules; Firefox §9, Edge §10 |
|
||||
| docs/09_SECURITY_PRIVACY.md | Threat model T1–T8, secure-coding bans |
|
||||
| docs/10_CODING_STANDARDS.md | Size limits, tsconfig, biome.json, knip.json, conventions |
|
||||
| docs/11_TESTING.md | Coverage gates, fixtures, suites, manual QA |
|
||||
@@ -50,9 +62,11 @@ This file is the entry point; the `docs/` suite is the specification.
|
||||
The canonical gate is docs/08 §3, run as `npm run guard`.
|
||||
4. `src/lib/core/` never imports browser APIs, Svelte, or `src/lib/browser`.
|
||||
5. Files ≤300 lines (hard 500); functions ≤50 (hard 80).
|
||||
6. Every string user-visible ⇒ i18n key in en+vi+ja (en is schema; vi/ja
|
||||
`satisfies Dict`, where `Dict = typeof dict` is exported from
|
||||
`locales/en.ts`). **Never `as const` on a locale file** — docs/07 §2.
|
||||
6. Every string user-visible ⇒ i18n key in **every shipped locale** — `LOCALES`
|
||||
in `src/lib/i18n/resolve-locale.ts`: en, vi, ja, zh-CN, ro (en is schema;
|
||||
the others `satisfies Dict`, where `Dict = Localized<typeof dict>` is
|
||||
exported from `locales/en.ts`). **Never `as const` on a locale file** —
|
||||
docs/07 §2. Romanian plural keys carry a third form, `few` (docs/07 §5).
|
||||
7. TypeScript strict; no `any`; casts need `// SAFETY:` comments.
|
||||
8. Conventional Commits; `npm run verify` green before every commit — and
|
||||
**`npm run verify:full` before anything release-bearing**. `verify` omits
|
||||
@@ -148,9 +162,86 @@ around a store, with Sort A→Z, drag to reorder and batched live sync; a
|
||||
technical redesign of every surface; local diagnostics; a cross-tab write
|
||||
lock; docs and legal synced (clarifications only — `LEGAL_VERSION` stays 1);
|
||||
contact aliases per purpose.
|
||||
**Exit:** `main` tag-ready with `verify:full` green; the human runs the
|
||||
docs/11 §5 manual pass on real Chrome including the **1.0.1 → 1.1.0 upgrade
|
||||
over an existing profile** ⚠️, then uploads the release zip to the store ⚠️.
|
||||
**Exit:** ✔ v1.1.0 tagged and released 2026-10-29 (signed tag on `9040f84`,
|
||||
checksum-verified zip). Still human-only: the docs/11 §5 manual pass on real
|
||||
Chrome including the **1.0.1 → 1.1.0 upgrade over an existing profile** ⚠️,
|
||||
then the zip uploaded to the store ⚠️.
|
||||
|
||||
### Phase 8 — v1.2.0: Simplified Chinese and Romanian
|
||||
Real installs in Chinese and Romanian browsers (CWS dashboard) made two UI
|
||||
languages the next minor. In order: docs first (`07` gains §6 "Adding a
|
||||
locale") → one `LOCALES` list and a third plural form (`few`), with no new
|
||||
language yet → `zh-CN` → `ro` → manifest `_locales`, store listings, the
|
||||
translation form, the screenshot harness → visual sweep in both languages and
|
||||
an adversarial review of code *and* translations → 1.2.0. Both ship
|
||||
best-effort (`TODO(review-zh)`, `TODO(review-ro)`). A Traditional Chinese
|
||||
browser on "Automatic" gets English.
|
||||
**Exit:** ✔ v1.2.0 tagged and released 2026-11-06 (signed tag on `e2f36bc`,
|
||||
checksum-verified zip). A finding worth keeping: on this Windows machine the
|
||||
process-spawning script tests time out intermittently under load (`main`'s
|
||||
too), so CI — whose Windows smoke job passed — was the gate.
|
||||
✔ Live on the store, confirmed on the listing 2026-11-10 (5 languages).
|
||||
Human-only ⚠️, still open: the native review passes, and `13 §1b` step 10 —
|
||||
the published build installed on a clean profile — which has no recorded
|
||||
result for any version.
|
||||
|
||||
### Phase 9 — v1.2.1: accessibility
|
||||
The owner's keyboard-only and Narrator pass over 1.2.0 found nothing; an audit
|
||||
of `src/` then found what such a pass cannot see. In order: dependency sync
|
||||
after Dependabot (the `biome.json` `$schema` and `docs/01` do **not** move
|
||||
with its PRs) → docs first (`06 §5`) → `ACCESSIBILITY.md` at the repository
|
||||
root with its intake (issue form, PR checklist, `accessibility@`) → the fixes:
|
||||
a focus ring that was drawn in the colour of the fill under it, forced-colours
|
||||
support, Alt+↑/↓ to reorder (through the drag's own `planDrop`), focus that
|
||||
fell to `<body>` in three places, 24 px targets, an About link to the
|
||||
statement → adversarial review → 1.2.1.
|
||||
Two things to carry forward. **`ACCESSIBILITY.md` is a public promise**: a UI
|
||||
change that makes its key table or its known-limitations list false has to
|
||||
change the file in the same PR (`11 §5` has the check). And the statement's
|
||||
goal is WCAG 2.2 AA **as a goal** — never write "conforms" or "compliant"
|
||||
without an audit to cite. The review found the first draft of the statement
|
||||
overclaiming in nine places ("every clickable target", "nothing times out"):
|
||||
check each sentence of it against the source, not against the intention.
|
||||
A third: **code moved out of a component starts counting.** SonarCloud's
|
||||
new-code gate (80 %) failed the first push because the live-sync wiring left
|
||||
`EditTab` for a `.ts` module with no test. Extracting to stay under a size
|
||||
limit is half the job; the test is the other half.
|
||||
**Exit:** ✔ v1.2.1 tagged and released 2026-11-10 (signed tag on `d61318a`,
|
||||
checksum-verified zip). Human-only ⚠️: the `11 §5` pass with the
|
||||
**1.2.0 → 1.2.1 upgrade over an existing profile**, a real Windows contrast
|
||||
theme and a screen-reader pass over Alt+↑/↓, the zip upload, and the native
|
||||
review of the two new strings.
|
||||
|
||||
### Phase 10 — maintenance mode; Firefox and Edge → v1.3.0
|
||||
The owner put the project into maintenance mode and asked for the last
|
||||
roadmap item, the other two stores. In order: Dependabot #39–#41 and the
|
||||
hand sync they always need → the `picomatch` advisory recorded (no fix
|
||||
exists) → a licence gate over the lockfile (`check:licenses`) → the policy
|
||||
(`/MAINTENANCE.md`, a feature form that asks which kind of change it is, and
|
||||
`triage.yml`, which closes requests for something new) → Qodana (`qodana-js`,
|
||||
Ultimate) beside SonarCloud → then Firefox (AMO) and Edge: the docs first,
|
||||
then the port, then CI, review and 1.3.0.
|
||||
One thing to carry forward: **`triage.yml` runs on `pull_request_target`,
|
||||
with a write token, for pull requests from forks.** It checks out the base
|
||||
branch and only compares event text with constants. Never add a checkout of
|
||||
the pull request's head, a step that runs its code, or a `${{ }}` of a title
|
||||
or body inside a `run:` line to that file.
|
||||
Two more, from the port. **There is no Firefox in CI**: the fake's Firefox
|
||||
flavour (`11 §4`) is a reading of Firefox's source, not evidence, so a change
|
||||
to roots, separators or move indices needs a real Firefox before an AMO
|
||||
upload. And **every change now ships in two packages**: `verify:full` builds
|
||||
and checks both (`build:firefox`, `check:manifest -- --browser firefox`), and a
|
||||
string that names Chrome is false in one of them.
|
||||
**Exit:** ✔ v1.3.0 tagged and released 2026-11-18 (signed tag on `80c7190`,
|
||||
three checksum-verified packages; PR #44 merged at the reviewed head).
|
||||
Human-only ⚠️ (`00 §10` items 19–26): the `11 §5` passes — Chrome with the
|
||||
**1.2.0 → 1.3.0 upgrade over an existing profile**, a real Firefox 140+, Edge
|
||||
signed in with sync on — then the Chrome Web Store upload of 1.3.0 in place
|
||||
of 1.2.1, the first Firefox Add-ons version and the first Edge submission by
|
||||
hand, the store environments if automation is wanted, and native review.
|
||||
The three uploads went up 2026-11-18; Edge approved 2026-11-19, the other two
|
||||
are in review. **An Edge copy's About link is chosen by its CRX ID**
|
||||
(`links.ts`), so the listing ids in `00 §9` are code, not trivia.
|
||||
|
||||
## Working style
|
||||
|
||||
|
||||
+66
-12
@@ -7,6 +7,21 @@ stop reading here — the forms ask for what is needed.
|
||||
|
||||
Security problems go through [`SECURITY.md`](SECURITY.md), never a public issue.
|
||||
|
||||
**The project is in maintenance mode** ([`MAINTENANCE.md`](MAINTENANCE.md)).
|
||||
What it takes: bug, UI/UX and accessibility fixes; translation fixes (wording
|
||||
wrong for a language or region, misleading spelling); dependency and security
|
||||
updates; major platform upgrades; and features that are already on the
|
||||
roadmap or genuinely needed. A feature request for something new, or a pull
|
||||
request titled `feat…` from outside the project, is closed automatically and
|
||||
labelled `maintenance-mode` — read, not deleted, and reopened if it fits.
|
||||
Ideas belong in
|
||||
[Discussions › Ideas](https://github.com/poli0981/bookmarkmagic/discussions/categories/ideas).
|
||||
|
||||
If something is hard or impossible to use — with a keyboard, a screen reader, a
|
||||
contrast theme, zoom — that is a defect, and it has its own form.
|
||||
[`ACCESSIBILITY.md`](ACCESSIBILITY.md) says what is already known and how a
|
||||
report is handled.
|
||||
|
||||
## Reporting a bookmark file that will not import
|
||||
|
||||
This is the most valuable report this project gets, because a sample becomes a
|
||||
@@ -51,8 +66,9 @@ Anything you attach to a GitHub issue is public and permanent; see
|
||||
|
||||
You do not need to clone anything. Use the translation issue form: the language,
|
||||
where the text appears, what it says now, and what it should say. Vietnamese is
|
||||
reviewed by the maintainer; **Japanese is best-effort until a native pass**, so
|
||||
JA corrections are especially welcome.
|
||||
reviewed by the maintainer; **Japanese, Simplified Chinese and Romanian are
|
||||
best-effort until a native pass**, so corrections in those three are especially
|
||||
welcome.
|
||||
|
||||
One constraint if you send the change yourself: placeholders like `{n}` or
|
||||
`{name}` must appear in the translation exactly as in English — same names, same
|
||||
@@ -60,7 +76,7 @@ count. A build gate enforces it.
|
||||
|
||||
## Setting up to write code
|
||||
|
||||
Node **24 or newer** (see `.nvmrc`).
|
||||
Node **26 or newer** (see `.nvmrc`).
|
||||
|
||||
```bash
|
||||
npm ci
|
||||
@@ -80,7 +96,8 @@ which does not exist until it has run.
|
||||
Then `npm run dev` and load `.output/chrome-mv3` at `chrome://extensions` with
|
||||
Developer mode on.
|
||||
|
||||
`npm run verify` runs lint, type-check, knip, the grep gate and the tests. It
|
||||
`npm run verify` runs lint, type-check, knip, the grep gate, the licence gate
|
||||
(`npm run check:licenses`) and the tests. It
|
||||
must be green before every commit. For anything release-bearing use
|
||||
`npm run verify:full`, which additionally runs coverage, the build, and the gate
|
||||
that inspects the *built* manifest — `verify` alone is weaker than what CI and a
|
||||
@@ -101,13 +118,41 @@ so they are not style preferences:
|
||||
- `src/lib/core/` is pure: it imports nothing from `browser/`, `stores/`, Svelte
|
||||
or `chrome.*`.
|
||||
- Files stay under 300 lines (hard limit 500), functions under 50 (hard 80).
|
||||
- Every user-visible string is an i18n key present in **all three** locales.
|
||||
- Every user-visible string is an i18n key present in **every** locale (en, vi,
|
||||
ja, zh-CN, ro — `LOCALES` in `src/lib/i18n/resolve-locale.ts`).
|
||||
|
||||
[`CLAUDE.md`](CLAUDE.md) is the entry point and [`docs/`](docs/) is the binding
|
||||
specification — **where code and docs disagree, the docs win.** A behaviour
|
||||
change that skips its doc leaves the spec lying, which is why the PR checklist
|
||||
asks about it.
|
||||
|
||||
## Changing the interface
|
||||
|
||||
[`ACCESSIBILITY.md`](ACCESSIBILITY.md) tells users what works; `docs/06 §5`
|
||||
is the specification behind it. A change to a component has to keep both true:
|
||||
|
||||
- **Keyboard.** Whatever a pointer can do, a key can do. A control that is not
|
||||
a tab stop on purpose (the tree's row buttons) has its key documented.
|
||||
- **Focus.** Always visible — check it on a control with a filled background,
|
||||
where the default ring can vanish into the fill — and never dropped: when
|
||||
the focused thing goes away, focus is put somewhere deliberate
|
||||
(`src/lib/components/focus-heading.ts` has the helpers).
|
||||
- **Names.** Icons are decorative; the control carries the name. Anything a
|
||||
screen reader speaks is an i18n key in every locale.
|
||||
- **Not colour alone, not motion.** A state shown by a fill or a shadow needs
|
||||
a `forced-colors` equivalent; anything that moves sits behind
|
||||
`prefers-reduced-motion: no-preference`. Tests enforce the second
|
||||
(`tests/unit/styles/motion.test.ts`) and hold the list for the first
|
||||
(`forced-colors.test.ts`).
|
||||
- **Native first.** A `<button>`, a `<dialog>`, a `<fieldset>` before an ARIA
|
||||
role. A role is a promise of that role's keyboard behaviour: the previews
|
||||
lost `role="tree"` because they did not have the arrow keys.
|
||||
- **Try it.** Unplug the mouse, then run one screen reader over the screen you
|
||||
changed. Say in the PR which one, or that you could not.
|
||||
|
||||
There is no component test framework here, so logic that can leave a component
|
||||
does, and is tested where it lands (`src/lib/edit/`, `src/lib/stores/`).
|
||||
|
||||
## Turning a reported file into a regression test
|
||||
|
||||
The full ritual, in order, because it is easy to do four fifths of it:
|
||||
@@ -134,17 +179,26 @@ a real regression into a passing test.
|
||||
|
||||
## Translations, in code
|
||||
|
||||
`src/lib/i18n/locales/en.ts` is the schema; `vi.ts` and `ja.ts` are typed
|
||||
`satisfies Dict` against it, so a missing key is a compile error.
|
||||
`src/lib/i18n/locales/en.ts` is the schema; every other locale (`vi.ts`,
|
||||
`ja.ts`, `zh-CN.ts`, `ro.ts`, each with its `-notices` and `-import` parts) is
|
||||
typed `satisfies Dict` against it, so a missing key is a compile error.
|
||||
|
||||
**Never add `as const` to `en.ts`.** It would make `Dict` a tree of string
|
||||
*literal* types, and every correct translation would become a type error — the
|
||||
only way to make the build pass would be leaving VI and JA in English.
|
||||
only way to make the build pass would be leaving every other locale in English.
|
||||
|
||||
Four gates run on every change: identical key paths across the three locales,
|
||||
identical interpolation tokens per string, no empty leaves, and plural keys
|
||||
carrying exactly `{one, other}` everywhere. See `docs/07` for register and tone
|
||||
(VI: neutral-friendly, "bạn"; JA: です/ます with katakana loanwords).
|
||||
The gates that run on every change:
|
||||
- identical key paths across the locales;
|
||||
- identical interpolation tokens per string;
|
||||
- no empty leaves;
|
||||
- plural keys carrying exactly the forms the language needs: `{one, other}`
|
||||
everywhere, plus `few` in Romanian ("1 marcaj", "5 marcaje", "20 de
|
||||
marcaje");
|
||||
- language names written as endonyms, identical in every dictionary;
|
||||
- for Romanian, comma-below `ș ț` only, never the cedilla look-alikes.
|
||||
|
||||
See `docs/07` for register and tone in each language. Adding a whole new
|
||||
language has its own checklist: `docs/07 §6`.
|
||||
|
||||
## Commits and pull requests
|
||||
|
||||
|
||||
@@ -0,0 +1,89 @@
|
||||
# Maintenance
|
||||
|
||||
**Status: maintenance mode, since 2026-11-18.**
|
||||
|
||||
BookmarkMagic does what it set out to do: import, export and edit bookmarks
|
||||
between browsers — offline, with two permissions and no network access. From
|
||||
here the project is **maintained, not extended**. That is not abandonment: it
|
||||
means keeping the extension correct, safe and current matters more than adding
|
||||
to it, and every change still reaches people through a store review.
|
||||
|
||||
This file is the policy. The reasoning behind it is in the decision log of
|
||||
[`docs/15_ROADMAP.md`](docs/15_ROADMAP.md).
|
||||
|
||||
## What is still done
|
||||
|
||||
1. **Dependencies, on a schedule.** Dependabot proposes updates weekly, for npm
|
||||
and for the GitHub Actions the workflows use, and only for releases that
|
||||
have been public for at least seven days. Each is merged after CI and the
|
||||
follow-up the docs ask for ([`docs/01 §6`](docs/01_TECH_STACK.md)).
|
||||
2. **Security, urgently.** An advisory rated **high or critical** against any
|
||||
dependency — or a serious security problem in the toolchain itself, Node.js
|
||||
for example — is fixed as soon as a fixed version exists. While none exists,
|
||||
[`docs/09 §3.1`](docs/09_SECURITY_PRIVACY.md) records the advisory and why it
|
||||
cannot reach a user, until the fix lands. To report a vulnerability, follow
|
||||
[`SECURITY.md`](SECURITY.md).
|
||||
3. **Major upgrades of the platform.** A new major of the language, runtime or
|
||||
framework — Node.js 24 → 26, TypeScript 6 → 7, a major of WXT or Svelte — is
|
||||
adopted on purpose, in its own pull request, with the docs updated first.
|
||||
4. **Defects.** Bugs, UI/UX defects and accessibility barriers
|
||||
([`ACCESSIBILITY.md`](ACCESSIBILITY.md)). A bookmark file that will not
|
||||
import is the most useful report there is
|
||||
([`CONTRIBUTING.md`](CONTRIBUTING.md)).
|
||||
5. **Language.** Translation fixes: wording that is wrong for a language, or
|
||||
for a region's culture or usage, and spelling mistakes that could mislead
|
||||
someone. The translation form is the way in.
|
||||
6. **Roadmap features, and necessary ones.** A feature that is already on the
|
||||
roadmap ([`docs/15`](docs/15_ROADMAP.md)) can still land, and so can a change
|
||||
that is genuinely needed — to fix a defect, to remove a barrier, or to keep
|
||||
the extension working in a browser it is published for.
|
||||
|
||||
## What is not
|
||||
|
||||
**New features outside the roadmap.** Requests for them are closed
|
||||
automatically, by [`.github/workflows/triage.yml`](.github/workflows/triage.yml):
|
||||
|
||||
- An issue opened with the **Suggest a feature** form whose first answer is
|
||||
"Something new — not on the roadmap" is labelled `maintenance-mode`, gets a
|
||||
comment that links here, and is closed as *not planned*. The form's other two
|
||||
answers — on the roadmap, or needed for a fix — keep the issue open, labelled
|
||||
`needs-triage`, for the maintainer to read.
|
||||
- A pull request from outside the project whose title starts with `feat`
|
||||
(Conventional Commits) is labelled and closed the same way. Open a feature
|
||||
request first.
|
||||
- The maintainer can label any issue `enhancement` to close it the same way.
|
||||
|
||||
Nothing is deleted. Every closed request is read, and one that fits this
|
||||
policy is reopened and labelled `roadmap`, which the automation leaves alone.
|
||||
|
||||
**Ideas** are welcome in
|
||||
[Discussions › Ideas](https://github.com/poli0981/bookmarkmagic/discussions/categories/ideas),
|
||||
where they can be talked through without an issue that has to be accepted or
|
||||
refused.
|
||||
|
||||
Out of scope permanently, maintenance mode or not: cloud sync, accounts,
|
||||
analytics of any kind, and anything that would need a new browser permission —
|
||||
the never list in [`docs/15`](docs/15_ROADMAP.md).
|
||||
|
||||
## Releases
|
||||
|
||||
A **patch** ships when there is something to fix: a file that will not import,
|
||||
a data-integrity defect or a dead end, an accessibility barrier, a batch of
|
||||
translation fixes, or a security problem that reaches what ships. (The
|
||||
extension has no runtime dependencies, so an advisory against the build tools
|
||||
is fixed in the repository and needs no release unless it changed the
|
||||
built extension.) A **minor** carries a roadmap
|
||||
feature, a new UI language or a change to the permissions
|
||||
([`docs/12 §4`](docs/12_CI_CD.md)). There is no fixed schedule.
|
||||
|
||||
Your browser updates the extension by itself once a new version passes store
|
||||
review; there is nothing to do.
|
||||
|
||||
## Supported versions
|
||||
|
||||
The latest version published on each store. See [`SECURITY.md`](SECURITY.md).
|
||||
|
||||
## Changing this policy
|
||||
|
||||
Through a pull request like any other, recorded in `docs/15`'s decision log
|
||||
and announced in Discussions.
|
||||
@@ -1,18 +1,30 @@
|
||||
# BookmarkMagic
|
||||
|
||||
[](MAINTENANCE.md)
|
||||
[](LICENSE)
|
||||
[](https://github.com/poli0981/bookmarkmagic/actions/workflows/ci.yml)
|
||||
[](https://github.com/poli0981/bookmarkmagic/actions/workflows/codeql.yml)
|
||||
[](https://github.com/poli0981/bookmarkmagic/actions/workflows/qodana.yml)
|
||||
[](https://sonarcloud.io/summary/new_code?id=poli0981_bookmarkmagic)
|
||||
[](https://sonarcloud.io/summary/new_code?id=poli0981_bookmarkmagic)
|
||||
[](https://chromewebstore.google.com/detail/bookmarkmagic/eghnciphhegekmnofffpgbdfefckdhmg)
|
||||
[](https://microsoftedge.microsoft.com/addons/detail/nchfchjnlihbifggooggpmmacighmdjg)
|
||||
[](#privacy)
|
||||
|
||||
Move your bookmarks between browsers the simple way: with a file. No account,
|
||||
no cloud sync, 100% offline.
|
||||
|
||||
A Chrome (MV3) extension for importing, exporting and editing bookmarks and
|
||||
folder trees. English · Tiếng Việt · 日本語.
|
||||
A browser extension (Manifest V3) for importing, exporting and editing
|
||||
bookmarks and folder trees — for Chrome and the other Chromium browsers, and,
|
||||
since 1.3.0, for Firefox. English · Tiếng Việt · 日本語 · 简体中文 · Română.
|
||||
|
||||
## Project status
|
||||
|
||||
**Maintenance mode** since 2026-11-18 — see [`MAINTENANCE.md`](MAINTENANCE.md).
|
||||
Bug, UI/UX, accessibility and translation fixes, dependency and security
|
||||
updates, and features already on the roadmap still land; requests for new
|
||||
features beyond that are closed automatically. Ideas are welcome in
|
||||
[Discussions › Ideas](https://github.com/poli0981/bookmarkmagic/discussions/categories/ideas).
|
||||
|
||||
## Screenshots
|
||||
|
||||
@@ -45,17 +57,28 @@ from anyone's real profile.
|
||||
A→Z, create folders, delete, and find duplicate links — every action
|
||||
reachable from the keyboard.
|
||||
|
||||
## Accessibility
|
||||
|
||||
Everything works without a mouse, a screen reader is told what is on screen
|
||||
and what an import did, contrast themes and reduced motion are respected, and
|
||||
the page declares the language you chose. The goal is WCAG 2.2 AA; it is a
|
||||
goal, not a claim — nobody has audited it.
|
||||
|
||||
[`ACCESSIBILITY.md`](ACCESSIBILITY.md) has the detail: the keys, what was
|
||||
tested and with which screen reader, what is known not to work well yet, and
|
||||
how to report a barrier.
|
||||
|
||||
## Privacy
|
||||
|
||||
This is the whole point of the project, so it is worth being precise.
|
||||
|
||||
- **No network access at all.** Not analytics, not telemetry, not update pings.
|
||||
There is no server, and the code makes no network calls. The browser backs
|
||||
that up: the extension's content security policy makes Chrome refuse fetch,
|
||||
XHR, WebSocket, EventSource and beacon requests, and remote images, fonts,
|
||||
media and frames. On top of that, `npm run check:manifest` scans the shipped
|
||||
bundle for network APIs (WebRTC included, which no CSP directive covers) and
|
||||
`npm run guard` scans the source.
|
||||
that up: the extension's content security policy — the same in Chrome, Edge
|
||||
and Firefox — makes the browser refuse fetch, XHR, WebSocket, EventSource and
|
||||
beacon requests, and remote images, fonts, media and frames. On top of that,
|
||||
`npm run check:manifest` scans both shipped packages for network APIs (WebRTC
|
||||
included, which no CSP directive covers) and `npm run guard` scans the source.
|
||||
- **Exactly two permissions**: `bookmarks` and `storage`. No host permissions,
|
||||
no content scripts, no background worker. Two gates enforce it: a unit test
|
||||
over `wxt.config.ts`, and `npm run check:manifest`, which CI runs against the
|
||||
@@ -77,28 +100,45 @@ Full policy: [`legal/PRIVACY.md`](legal/PRIVACY.md).
|
||||
## Honest limitations
|
||||
|
||||
- Favicons cannot be imported — the bookmarks API has no favicon field.
|
||||
- Imported bookmarks get today's date. Chrome does not let an extension set a
|
||||
- Imported bookmarks get today's date. Browsers do not let an extension set a
|
||||
bookmark's original creation date. Your **exported** files keep the real ones.
|
||||
- **Firefox separators are not kept.** They show in the Edit tab as lines, but
|
||||
no file BookmarkMagic writes can hold one: exports and backups leave them out,
|
||||
imports skip the ones a file holds and say how many, and Replace — which
|
||||
deletes them with everything else — tells you so before it starts.
|
||||
- Firefox refuses bookmark addresses longer than 65,536 characters (they are
|
||||
skipped, and counted) and shortens titles longer than 4,096.
|
||||
- On Firefox, entries a file leaves loose at its top level go into the
|
||||
**Bookmarks Menu**, where Firefox's own import puts them. For an HTML file
|
||||
exported by Chrome itself, that means Chrome's Other and Mobile bookmarks;
|
||||
BookmarkMagic's own exports name every root and land where they came from.
|
||||
- CSV is a flattened view: empty folders and "which folder is the toolbar" are
|
||||
not preserved. Use HTML or JSON for a faithful backup.
|
||||
- Markdown is share-only — BookmarkMagic cannot read it back.
|
||||
|
||||
## Install
|
||||
|
||||
From the Chrome Web Store: [here](https://chromewebstore.google.com/detail/bookmarkmagic/eghnciphhegekmnofffpgbdfefckdhmg)
|
||||
| Browser | Where | Requires |
|
||||
|---|---|---|
|
||||
| Chrome, Brave, Vivaldi, Opera | [Chrome Web Store](https://chromewebstore.google.com/detail/bookmarkmagic/eghnciphhegekmnofffpgbdfefckdhmg) | Chrome 136 or later (April 2025), or a Chromium browser of the same vintage |
|
||||
| Microsoft Edge | [Edge Add-ons](https://microsoftedge.microsoft.com/addons/detail/nchfchjnlihbifggooggpmmacighmdjg) | Edge 136 or later |
|
||||
| Firefox (desktop) | Firefox Add-ons — **not listed yet**; the link will be here when it is | Firefox 140 or later. Firefox for Android has no bookmarks API for extensions |
|
||||
|
||||
Requires Chrome 136 or later (April 2025), or any Chromium browser of the same
|
||||
vintage — Edge, Brave, Vivaldi, Opera. On an older browser the store keeps the
|
||||
version you already have and simply stops updating it.
|
||||
On an older browser the store keeps the version you already have and simply
|
||||
stops updating it.
|
||||
|
||||
From source (Node.js 26):
|
||||
Each [GitHub Release](https://github.com/poli0981/bookmarkmagic/releases) carries
|
||||
the exact packages sent to the stores, with `SHA256SUMS.txt`. Firefox only
|
||||
installs add-ons Mozilla has signed, so its `-firefox.zip` there is for
|
||||
checking the store build, not for installing.
|
||||
|
||||
From source (Node.js 26) — [`BUILD.md`](BUILD.md) has the details:
|
||||
|
||||
```bash
|
||||
npm ci && npm run build
|
||||
npm ci && npm run build # Chromium: load .output/chrome-mv3/ at chrome://extensions (Developer mode)
|
||||
npm run build:firefox # Firefox: about:debugging → Load Temporary Add-on → .output/firefox-mv3/manifest.json
|
||||
```
|
||||
|
||||
Then load `.output/chrome-mv3/` at `chrome://extensions` with Developer mode on.
|
||||
|
||||
## Development
|
||||
|
||||
```bash
|
||||
@@ -106,8 +146,8 @@ npm run dev
|
||||
```
|
||||
|
||||
`npm run verify` is the gate everything else answers to — lint, type-check
|
||||
(svelte-check on the TypeScript 6 API, then `tsc` 7), knip, the grep gate and
|
||||
the test suite, in that order. It must be green before every commit;
|
||||
(svelte-check on the TypeScript 6 API, then `tsc` 7), knip, the grep gate, the
|
||||
licence gate and the test suite, in that order. It must be green before every commit;
|
||||
`npm run verify:full` adds coverage, the build and the built-manifest check,
|
||||
and must be green before anything release-bearing.
|
||||
|
||||
@@ -123,7 +163,9 @@ code and docs disagree, the docs win. Start with [`CLAUDE.md`](CLAUDE.md), then
|
||||
|
||||
Bug reports and translation fixes are welcome —
|
||||
[the issue forms](https://github.com/poli0981/bookmarkmagic/issues/new/choose)
|
||||
ask for what is needed, and none of them requires you to write code.
|
||||
ask for what is needed, and none of them requires you to write code. The
|
||||
project is in maintenance mode, so a request for a feature that is not on the
|
||||
roadmap is closed automatically ([`MAINTENANCE.md`](MAINTENANCE.md)).
|
||||
|
||||
If a bookmark file will not import, that is the most useful report there is,
|
||||
because the sample becomes a permanent test. Sanitize it first:
|
||||
@@ -148,6 +190,7 @@ a public issue.
|
||||
|---|---|
|
||||
| Security vulnerabilities (if you have no GitHub account) | security@poli0981.dev |
|
||||
| Privacy questions, removing a sample you sent | privacy@poli0981.dev |
|
||||
| An accessibility barrier (if you have no GitHub account) | accessibility@poli0981.dev |
|
||||
| The terms (EULA, disclaimer) | legal@poli0981.dev |
|
||||
| Licensing and permission questions | copyright@poli0981.dev |
|
||||
| Formal copyright (DMCA) notices | dmca@poli0981.dev |
|
||||
@@ -155,9 +198,10 @@ a public issue.
|
||||
| Contributing and code of conduct | code@poli0981.dev |
|
||||
| Sponsorship · collaboration · press | sponsor@ · collab@ · press@poli0981.dev |
|
||||
|
||||
Bugs and feature ideas are best as
|
||||
[issues](https://github.com/poli0981/bookmarkmagic/issues) — they help the next
|
||||
person too. The extension itself never shows or uses any of these addresses.
|
||||
Bugs are best as
|
||||
[issues](https://github.com/poli0981/bookmarkmagic/issues) and ideas as
|
||||
[Discussions](https://github.com/poli0981/bookmarkmagic/discussions/categories/ideas)
|
||||
— they help the next person too. The extension itself never shows or uses any of these addresses.
|
||||
|
||||
## Support development
|
||||
|
||||
@@ -180,5 +224,5 @@ questions: copyright@poli0981.dev.
|
||||
The BookmarkMagic name and icon identify this project. The GPL lets anyone fork
|
||||
the code; it does not let a fork present itself as this project.
|
||||
|
||||
Not affiliated with or endorsed by Google, Chrome, Mozilla, Firefox or any
|
||||
browser vendor. Browser names are trademarks of their respective owners.
|
||||
Not affiliated with or endorsed by Google, Chrome, Mozilla, Firefox,
|
||||
Microsoft, Edge or any browser vendor. Browser names are trademarks of their respective owners.
|
||||
+4
-4
@@ -4,13 +4,13 @@
|
||||
|
||||
| Version | Supported |
|
||||
|---|---|
|
||||
| The latest version published on the Chrome Web Store | ✅ |
|
||||
| The latest version published on the Chrome Web Store, Firefox Add-ons or Microsoft Edge Add-ons | ✅ |
|
||||
| Anything older | ❌ |
|
||||
|
||||
There is no back-porting, and there is nothing for you to do to stay current:
|
||||
Chrome auto-updates extensions once a new version passes store review. You can
|
||||
see which version you are running in the extension's **About** tab, or on
|
||||
`chrome://extensions`.
|
||||
your browser updates extensions once a new version passes store review. You
|
||||
can see which version you are running in the extension's **About** tab, on
|
||||
`chrome://extensions`, or on `about:addons` in Firefox.
|
||||
|
||||
## Reporting a vulnerability
|
||||
|
||||
|
||||
+1
-1
@@ -1,5 +1,5 @@
|
||||
{
|
||||
"$schema": "https://biomejs.dev/schemas/2.6.2/schema.json",
|
||||
"$schema": "https://biomejs.dev/schemas/2.6.6/schema.json",
|
||||
"vcs": { "enabled": true, "clientKind": "git", "useIgnoreFile": true },
|
||||
"files": {
|
||||
"ignoreUnknown": true,
|
||||
|
||||
Binary file not shown.
|
Before Width: | Height: | Size: 78 KiB After Width: | Height: | Size: 75 KiB |
+127
-8
@@ -1,7 +1,9 @@
|
||||
# 00 — Project Overview
|
||||
|
||||
> **Project:** BookmarkMagic
|
||||
> **Type:** Chrome/Chromium MV3 browser extension (open source, Chrome Web Store)
|
||||
> **Type:** MV3 browser extension for Chromium browsers and, since v1.3.0,
|
||||
> Firefox (open source; Chrome Web Store and, since 2026-11-19, Microsoft Edge
|
||||
> Add-ons — Firefox Add-ons pending its first review)
|
||||
> **Owner:** poli0981 (GitHub) / SkullMute
|
||||
> **Repo:** `poli0981/bookmarkmagic` ✔
|
||||
> **License:** GPL-3.0-or-later
|
||||
@@ -17,16 +19,42 @@
|
||||
> 5 users) on 2026-10-28. ⚠️ The exact approval date was never recorded — the
|
||||
> owner can read it from the dashboard. Installed users are on 1.0.1.
|
||||
>
|
||||
> **v1.1.0 is in preparation** on `release/1.1.0`: versioned, with its
|
||||
> CHANGELOG section dated 2026-10-29, but not yet tagged, released or
|
||||
> submitted. Until it clears review, installed users stay on 1.0.1. It raises
|
||||
> the floor to Chrome 136 (`08 §7`); permissions are unchanged.
|
||||
> **v1.1.0 is PUBLISHED.** Tagged and released 2026-10-29 (signed tag on
|
||||
> `9040f84`, checksum-verified zip); the listing showed version 1.1.0 on
|
||||
> 2026-11-06. It raised the floor to Chrome 136 (`08 §7`); permissions are
|
||||
> unchanged.
|
||||
>
|
||||
> **v1.2.0 is PUBLISHED.** Tagged and released 2026-11-06 (signed tag on
|
||||
> `e2f36bc`); the listing was observed showing **version 1.2.0** (`Updated:
|
||||
> November 7, 2026`, 5 languages) on 2026-11-10. Installed users are on 1.2.0.
|
||||
>
|
||||
> **v1.2.1 — accessibility — is RELEASED on GitHub, never on a store on its
|
||||
> own.** Tagged and released 2026-11-10 (signed tag on `d61318a`,
|
||||
> checksum-verified zip): an accessibility statement (`/ACCESSIBILITY.md`) and
|
||||
> the fixes an audit found (`06 §5`). 1.3.0 carries all of it and went to the
|
||||
> Chrome Web Store in its place (submitted 2026-11-18); until that clears
|
||||
> review, Chrome users stay on 1.2.0.
|
||||
>
|
||||
> **v1.3.0 — Firefox and Edge — is RELEASED, and LIVE on Edge Add-ons.**
|
||||
> Tagged and released 2026-11-18 (signed tag on `80c7190`, three
|
||||
> checksum-verified packages): a Firefox package (desktop, 140 or later), and
|
||||
> the Chrome package for Edge Add-ons as well, with 1.2.1 inside. The owner
|
||||
> submitted it to all three stores on 2026-11-18. **Edge Add-ons approved it
|
||||
> on 2026-11-19** — the first Edge version, live in five languages (§9 has the
|
||||
> listing). ⚠️ The Chrome Web Store update (in place of 1.2.1) and the first
|
||||
> Firefox Add-ons version are still in review (§10 items 20–21).
|
||||
>
|
||||
> The project is now in **maintenance**, not construction: every change from
|
||||
> here reaches installed users through a store review, so it needs a version
|
||||
> bump, a CHANGELOG entry and an update submission (`13 §1b`). Sequencing lives
|
||||
> in `/CLAUDE.md`; what is still open is in §10 below.
|
||||
> **Doc suite version:** 1.8 (2026-10-29 — specs reconciled with `release/1.1.0`)
|
||||
>
|
||||
> **Since 2026-11-18 that is a written policy: maintenance mode**
|
||||
> (`/MAINTENANCE.md`). Dependency and security updates, major platform
|
||||
> upgrades, bug/UI/UX/accessibility/translation fixes, and features only when
|
||||
> they are on `15`'s roadmap or genuinely needed; requests for anything else
|
||||
> are closed by `triage.yml` (`12 §2.6`).
|
||||
> **Doc suite version:** 1.13 (2026-11-18 — Firefox and Edge, v1.3.0)
|
||||
|
||||
---
|
||||
|
||||
@@ -109,6 +137,17 @@ 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
|
||||
not shipped; a Traditional Chinese browser on "Automatic" gets English.
|
||||
|
||||
## 7. Non-goals (v1.0)
|
||||
|
||||
- ❌ Cloud sync, accounts, or any server component.
|
||||
@@ -116,6 +155,8 @@ v1.0's scope):
|
||||
`ICON` attributes are tolerated on parse and dropped — documented limitation).
|
||||
- ❌ Dead-link checking (requires host permissions — deferred, see Roadmap).
|
||||
- ❌ Firefox/Safari *store* releases (WXT keeps the door open; see Roadmap).
|
||||
*Firefox and Edge became goals on 2026-11-18 (v1.3, `15`); Safari stays
|
||||
out.*
|
||||
- ❌ Editing browser-native root folders themselves (Bookmarks Bar / Other
|
||||
Bookmarks cannot be deleted/renamed — enforced by API anyway).
|
||||
|
||||
@@ -146,13 +187,16 @@ Derived identifiers (canonical across docs and code):
|
||||
|
||||
| Context | Value |
|
||||
|---|---|
|
||||
| Manifest / store / UI name | `BookmarkMagic` (identical in EN/VI/JA) |
|
||||
| Manifest / store / UI name | `BookmarkMagic` (identical in every locale) |
|
||||
| Repo slug | `poli0981/bookmarkmagic` ✔ |
|
||||
| Own JSON schema | "BM JSON v1", `"format": "bookmarkmagic"` |
|
||||
| Code prefix | `Bm*` (`BmParseError`, `BmAborted`) |
|
||||
| Safety-backup filename | `bookmarkmagic-backup-YYYYMMDD-HHmm.json` |
|
||||
| Chrome Web Store item id | `eghnciphhegekmnofffpgbdfefckdhmg` (also the value `CHROME_EXTENSION_ID` needs — `12 §3`) |
|
||||
| Store listing URL | `https://chromewebstore.google.com/detail/bookmarkmagic/eghnciphhegekmnofffpgbdfefckdhmg` |
|
||||
| Edge Add-ons item id ("CRX ID") | `nchfchjnlihbifggooggpmmacighmdjg` — the `runtime.id` of an install from Edge Add-ons, mapped in `links.ts` (`06 §3.5`) |
|
||||
| Edge Add-ons Product ID | `3bf2e086-99ee-4f8b-a8db-e13827f04ca1` (the value `EDGE_PRODUCT_ID` needs — `12 §3`) · Store ID `0RDCKC9LZ41P` |
|
||||
| Edge Add-ons listing URL | `https://microsoftedge.microsoft.com/addons/detail/nchfchjnlihbifggooggpmmacighmdjg` (live 2026-11-19) |
|
||||
|
||||
## 10. Manual action items (human-only) ⚠️
|
||||
|
||||
@@ -198,7 +242,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
|
||||
@@ -220,6 +267,78 @@ Derived identifiers (canonical across docs and code):
|
||||
open: the exact approval date, and `13 §1b` step 10 against the published
|
||||
build (install on a clean profile, re-run the upgrade check) — no result is
|
||||
recorded for either.
|
||||
12. ✔ **v1.1.0 cleared review** — the listing showed 1.1.0 ("Updated October
|
||||
29, 2026", 6 users, 3 languages) when checked on 2026-11-06. ⚠️ Still
|
||||
open, as for 1.0.1: `13 §1b` step 10 against the published build — no
|
||||
result is recorded. Also unverified outside the harness: the
|
||||
account-storage roots of a signed-in profile and the hidden empty Mobile
|
||||
root (`02 §4`), and the `MAX_WRITE_DEPTH` rationale against a real Chrome.
|
||||
|
||||
### v1.2.0 (added 2026-11-06)
|
||||
|
||||
13. ⚠️ **ZH-CN and RO native review passes.** Both locales ship best-effort
|
||||
(`07 §4`), written from Chrome's own terminology in each language but read
|
||||
by no native speaker. Each file's header carries `TODO(review-zh)` /
|
||||
`TODO(review-ro)`. The `translation` issue form lists both languages.
|
||||
14. ✔ **v1.2.0 to the store** — live, observed 2026-11-10 (version 1.2.0,
|
||||
`Updated: November 7, 2026`, 5 listing languages). ⚠️ Still unrecorded, as
|
||||
for 1.0.1 and 1.1.0: `13 §1b` step 10, the clean-profile install of the
|
||||
published build and the upgrade re-check against it.
|
||||
|
||||
### v1.2.1 (added 2026-11-10)
|
||||
|
||||
15. ⚠️ **v1.2.1 to the store.** The GitHub Release exists and is verified
|
||||
(`15`'s progress table). The usual `11 §5` pass plus the **1.2.0 →
|
||||
1.2.1 upgrade over an existing profile**, then the Release zip uploaded in
|
||||
the dashboard. No listing change: a patch (`13 §5`).
|
||||
16. ⚠️ **The accessibility checks no script can run** (`11 §5`): a Windows
|
||||
contrast theme over the tree, the tabs, the theme control and a running
|
||||
import; a screen-reader pass over Alt+↑/↓ (does the new position get
|
||||
spoken, once); 200 % zoom. The fixes were verified in a headless Chrome
|
||||
with `forced-colors` emulated, which is not the same as a real theme.
|
||||
17. ⚠️ **Other screen readers.** `ACCESSIBILITY.md` says Narrator with Chrome
|
||||
on Windows 11 was tested and NVDA, JAWS, VoiceOver and ChromeVox were not.
|
||||
Any pass with one of those moves it from the second list to the first.
|
||||
18. ⚠️ **Native review of the new strings** — the About link label and the
|
||||
spoken position — in JA, ZH-CN and RO, with the passes in items 9 and 13.
|
||||
|
||||
### v1.3.0 — maintenance mode, Firefox and Edge (added 2026-11-18)
|
||||
|
||||
19. ⚠️ **Pin the maintenance announcement** (Discussions #43) — the API cannot.
|
||||
20. ⚠️ **v1.3.0 to the Chrome Web Store** instead of 1.2.1, which never went
|
||||
up — **submitted 2026-11-18, in review**. The `11 §5` pass with the
|
||||
**1.2.0 → 1.3.0 upgrade over an existing profile**, then the Chrome
|
||||
package from the Release (`13 §1b`). The CWS
|
||||
listing text may keep its Chrome wording; it is the Chrome store.
|
||||
21. ⚠️ **The first Firefox Add-ons version, by hand** (`13 §8`) — **submitted
|
||||
2026-11-18, in review**. The `11 §5` Firefox section on a real Firefox
|
||||
140+, then the Developer Hub upload of
|
||||
the Firefox package **and** the sources archive, desktop only, with
|
||||
`BUILD.md` in the notes to reviewers. AMO's upload validator report is the
|
||||
first outside check of the package.
|
||||
22. ✔ **The first Edge Add-ons submission, by hand** (`13 §9`) — submitted
|
||||
2026-11-18, **approved and live 2026-11-19** (§9). Partner Center flagged
|
||||
the first description for naming another browser; the Edge copy now names
|
||||
none (PR #47, `08 §10`). ⚠️ Still open: the `11 §5` Edge items have no
|
||||
recorded result — above all a profile **signed in with sync on**
|
||||
(`08 §10`, unverified). An Edge user who meets `NO_WRITABLE_ROOTS` would be
|
||||
the first sign.
|
||||
23. ⚠️ **Store automation, when wanted** (`12 §3`): the three environments,
|
||||
each with a required reviewer, deployments limited to `v*` tags, and its
|
||||
secrets (Chrome: API v2 service
|
||||
account; AMO: JWT pair; Edge: API key + Client ID, renewed every 72 days),
|
||||
then the `*_AUTOPUBLISH` variables.
|
||||
24. ⚠️ **After the listings go live**: their URLs for the README and the
|
||||
About link (`06 §3.5` — Edge's needs its listing id), and the AMO/Edge
|
||||
badges. **Edge ✔ 2026-11-19**: README install table and badge, and the
|
||||
About link's mapping (ships with the next release — CHANGELOG
|
||||
`[Unreleased]`). AMO still to come: its About link is already the gecko-id
|
||||
URL, so only the README row and a badge remain.
|
||||
25. ⚠️ **Evidence for the Firefox fake** (`11 §4`): a sanitized `getTree()`
|
||||
dump from a real Firefox 140+ profile, committed as a fixture the fake is
|
||||
checked against; and a Firefox column in `11 §6`'s parse timing.
|
||||
26. ⚠️ **Native review** of the strings 1.3.0 added or changed (`07`) in JA,
|
||||
ZH-CN and RO, and of the store-listing blocks for AMO and Edge.
|
||||
|
||||
## 11. Reading order
|
||||
|
||||
|
||||
+17
-13
@@ -1,6 +1,6 @@
|
||||
# 01 — Tech Stack
|
||||
|
||||
> Versions verified against npm/official sources on **2026-10-28** (first pass
|
||||
> Versions verified against npm/official sources on **2026-11-18** (first pass
|
||||
> 2026-07-25).
|
||||
> Rule: latest stable or LTS only, with any deliberate exception stated inline.
|
||||
> Re-verify minor/patch at scaffold time (`npm outdated`), but do NOT jump
|
||||
@@ -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`. |
|
||||
|
||||
@@ -20,17 +21,17 @@
|
||||
|---|---|---|
|
||||
| Node.js | **26.x (Active LTS)** (was 24.x through v1.0.1) | Build runtime. Node 26 entered Active LTS on 2026-10-28 (maintenance from 2027-10-20, end of life 2029-04-30); Node 24 moved to maintenance on 2026-10-20. `.nvmrc`, `engines` and every CI job say 26 — CI reads `.nvmrc` where it can, and passes `'26'` to the ops reusable, which takes a string input. |
|
||||
| npm | bundled with Node 26 (v11.20+) | Package manager. Commit `package-lock.json`. `.npmrc` sets `min-release-age=7` (§6). |
|
||||
| **WXT** | **^0.21.4** (was ^0.20.27 through v1.0.0) | Extension framework: entrypoints, manifest generation, HMR, `wxt zip`, `wxt submit`. **0.x, so a minor is semver's breaking slot** — and 0.21 was: `wxt/testing` split into `wxt/testing/fake-browser` and `wxt/testing/vitest-plugin`, and `tabs.create` is now typed as returning `void`. Both are dev-only. Never take a WXT bump without diffing the **built** manifest before and after (`12 §2.3`); `tests/unit/manifest.test.ts` reads `wxt.config.ts` and is structurally incapable of noticing. |
|
||||
| **WXT** | **^0.21.5** (was ^0.20.27 through v1.0.0) | Extension framework: entrypoints, manifest generation, HMR, `wxt zip`, `wxt submit`. **0.x, so a minor is semver's breaking slot** — and 0.21 was: `wxt/testing` split into `wxt/testing/fake-browser` and `wxt/testing/vitest-plugin`, and `tabs.create` is now typed as returning `void`. Both are dev-only. Never take a WXT bump without diffing the **built** manifest before and after (`12 §2.3`); `tests/unit/manifest.test.ts` reads `wxt.config.ts` and is structurally incapable of noticing. |
|
||||
| **TypeScript** | **7.0 for `tsc`, 6.0 for the API** (strict) | Two packages under two names, Microsoft's documented side-by-side setup for toolchains that embed the compiler: `"@typescript/native": "npm:typescript@~7.0.2"` provides the `tsc` binary (the Go-native 7.0 compiler that type-checks every `.ts` file in `npm run check`), and `"typescript": "npm:@typescript/typescript6@~6.0.2"` keeps the TS 6.0 programmatic API under the `typescript` module name (it re-exports the real `typescript@6.0.x` and adds a `tsc6` binary). svelte-check (peer `typescript ^5 || ^6`) and Volar need that API — TS 7 has none until 7.1 — so `.svelte` files are checked by 6.0 and `.ts` files by both. `tsc --version` must say 7.x and `tsc6 --version` 6.x. Drop the alias when svelte-check declares TS 7 support. Both pinned `~` (patch-only). |
|
||||
| **Svelte** | **^5.57.2** | UI, runes mode only (`$state`, `$derived`, `$effect`, `$props`). The compiled runtime ships in the bundle (MIT — `legal/THIRD_PARTY_NOTICES.md`). |
|
||||
| **Svelte** | **^5.57.3** | UI, runes mode only (`$state`, `$derived`, `$effect`, `$props`). The compiled runtime ships in the bundle (MIT — `legal/THIRD_PARTY_NOTICES.md`). |
|
||||
| @sveltejs/vite-plugin-svelte | ^7.3.1 | Compiles `.svelte` and the runes in `.svelte.ts` stores for Vitest (`vitest.config.ts`). Its `deepmerge` dependency carries the one advisory with no fix (`09 §3.1`). |
|
||||
| @wxt-dev/module-svelte | ^2.0.5 | WXT ↔ Svelte integration. |
|
||||
| **Biome** | **2.6.2 (pinned exact)** | Lint + format (replaces ESLint + Prettier). Install with `npm i -D -E @biomejs/biome` per Biome guidance. 2.6 started formatting Markdown and YAML; both are excluded in `biome.json` so docs and workflows keep their hand layout (`10 §3`). |
|
||||
| svelte-check | ^4.7.7 | Type/template authority for `.svelte` files. Runs on the TS 6 API (see TypeScript above). |
|
||||
| **Biome** | **2.6.6 (pinned exact)** | Lint + format (replaces ESLint + Prettier). Install with `npm i -D -E @biomejs/biome` per Biome guidance. 2.6 started formatting Markdown and YAML; both are excluded in `biome.json` so docs and workflows keep their hand layout (`10 §3`). The `$schema` URL in `biome.json` names the same version and moves with the pin — Dependabot bumps the package and leaves the URL behind. |
|
||||
| svelte-check | ^4.7.8 | Type/template authority for `.svelte` files. Runs on the TS 6 API (see TypeScript above). |
|
||||
| **@types/node** | **^26** (matches the Node major) | Types for `node:fs`, `node:path`, `node:child_process` and `process`, which the test suite and `scripts/*.mjs` genuinely use. **Declared explicitly since 2026-08-03** — it used to arrive transitively, and WXT 0.21 stopped providing it. Types only: erased at build, so hard rule 2 (zero *runtime* dependencies) is untouched. |
|
||||
| jsdom | **^30.1** (was ^29 through v1.0.0) | Test DOM. Not interchangeable — `02 §3` picks jsdom over happy-dom because the Netscape walk depends on parse5's implied-end-tag behaviour. A major bump runs `tests/unit/dom-environment.test.ts` first; if that canary fails, pin rather than loosen the test. |
|
||||
| **Knip** | **^6** (6.42.1 as of 2026-10) | Dead code: unused files, exports, dependencies. Requires Node ≥ 20.19. v6 swapped the TypeScript backend for oxc-parser — confirm `compilers.svelte` is still the supported `.svelte` hook before scaffold (`10 §4`). |
|
||||
| **Vitest** | **^5.0.5** (was ^4 through v1.0.1) | Unit tests. 5.0 changed `clearMocks` to default `true`, requires `vi.mock` at top level and fails unawaited async assertions; the suite needed no changes. Requires Node ≥ 22.12. |
|
||||
| jsdom | **^31.0** (was ^30 through v1.2.1, ^29 through v1.0.0) | Test DOM. Not interchangeable — `02 §3` picks jsdom over happy-dom because the Netscape walk depends on parse5's implied-end-tag behaviour. A major bump runs `tests/unit/dom-environment.test.ts` first; if that canary fails, pin rather than loosen the test. |
|
||||
| **Knip** | **^6** (6.45.1 as of 2026-11-18) | Dead code: unused files, exports, dependencies. Requires Node ≥ 20.19. v6 swapped the TypeScript backend for oxc-parser — confirm `compilers.svelte` is still the supported `.svelte` hook before scaffold (`10 §4`). |
|
||||
| **Vitest** | **^5.1.0** (was ^4 through v1.0.1) | Unit tests. 5.0 changed `clearMocks` to default `true`, requires `vi.mock` at top level and fails unawaited async assertions; the suite needed no changes. Requires Node ≥ 22.12. |
|
||||
| @vitest/coverage-v8 | match Vitest | Coverage reporting (`text` + `lcov` for SonarCloud, `12 §2.5`). |
|
||||
|
||||
## 3. Explicitly rejected
|
||||
@@ -60,22 +61,25 @@
|
||||
"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 && tsc --noEmit && tsc -p tsconfig.scripts.json",
|
||||
"check": "svelte-check --tsconfig ./tsconfig.json --fail-on-warnings && tsc --noEmit && tsc -p tsconfig.scripts.json",
|
||||
// TS 6 API, the TS 7 tsc, then scripts/*.mjs via checkJs
|
||||
"lint": "biome check .",
|
||||
"lint:fix": "biome check --write .",
|
||||
"knip": "knip",
|
||||
"guard": "node scripts/guard.mjs", // the source gate, 08 §3
|
||||
"check:manifest": "node scripts/check-manifest.mjs", // the built-artifact gate, 08 §3
|
||||
"check:licenses": "node scripts/check-licenses.mjs", // every lockfile licence, 09 §3.2
|
||||
"icons": "node scripts/gen-icons.mjs", // regenerates the shipped icons (source of truth)
|
||||
"test": "vitest run",
|
||||
"test:watch": "vitest",
|
||||
"coverage": "vitest run --coverage",
|
||||
"verify": "npm run lint && npm run check && npm run knip && npm run guard && npm run test",
|
||||
"verify:full": "npm run verify && npm run coverage && npm run build && npm run check:manifest"
|
||||
"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 && npm run build:firefox && npm run check:manifest -- --browser firefox"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
+39
-7
@@ -58,10 +58,14 @@ bookmarkmagic/
|
||||
│ └── sanitize/ # its format modules: detect, mappers, spans, html, json, csv, leaks
|
||||
├── docs/ # this suite (00–15)
|
||||
├── legal/ # EULA.md, DISCLAIMER.md, PRIVACY.md, THIRD_PARTY_NOTICES.md
|
||||
├── README.md / CHANGELOG.md # what users read; CHANGELOG is linked from #about
|
||||
├── ACCESSIBILITY.md # the accessibility statement (06 §5), linked from #about
|
||||
├── CONTRIBUTING.md / SECURITY.md / CODE_OF_CONDUCT.md
|
||||
├── .github/ # issue forms, PR template, workflows (12), dependabot, FUNDING
|
||||
├── src/
|
||||
│ ├── public/
|
||||
│ │ ├── icon/ # 16/32/48/128 png
|
||||
│ │ ├── _locales/{en,vi,ja}/messages.json # manifest-level strings only
|
||||
│ │ ├── _locales/{en,vi,ja,zh_CN,ro}/messages.json # manifest-level strings only (07 §1)
|
||||
│ │ └── THIRD_PARTY_NOTICES.txt # MIT notices for what the build compiles in (14 §5)
|
||||
│ ├── entrypoints/
|
||||
│ │ ├── popup/ # index.html + App.svelte + main.ts
|
||||
@@ -99,6 +103,8 @@ bookmarkmagic/
|
||||
│ │ │ └── limits.ts # MAX_FILE_BYTES, MAX_NODES, MAX_DEPTH, LEGAL_VERSION
|
||||
│ │ ├── browser/
|
||||
│ │ │ ├── bookmarks.ts # getTree/create/move/update/remove wrappers
|
||||
│ │ │ ├── roots.ts # getRoots: which live folders are the roots (§4)
|
||||
│ │ │ ├── live-tree.ts # live → file model; separators, counts, move index (§4)
|
||||
│ │ │ ├── write-queue.ts # sequential tree writer + progress + abort
|
||||
│ │ │ ├── storage.ts # typed settings/legal accessors
|
||||
│ │ │ ├── download.ts # Blob → <a download>
|
||||
@@ -126,12 +132,13 @@ bookmarkmagic/
|
||||
│ │ │ ├── import-session.svelte.ts
|
||||
│ │ │ ├── edit-view.svelte.ts # #edit: what the tree shows (03 §3)
|
||||
│ │ │ ├── edit-commands.svelte.ts # #edit: single-item writes, extends the view
|
||||
│ │ │ └── edit-session.svelte.ts # #edit: duplicates + bulk commands, extends both
|
||||
│ │ │ ├── edit-session.svelte.ts # #edit: duplicates + bulk commands, extends both
|
||||
│ │ │ └── edit-live.ts # #edit: subscribes a session to the browser's events (03 §3)
|
||||
│ │ ├── i18n/ # runtime UI i18n (see 07_I18N.md)
|
||||
│ │ │ ├── index.svelte.ts
|
||||
│ │ │ ├── format.ts # pure Intl number/date helpers (07 §3)
|
||||
│ │ │ ├── resolve-locale.ts
|
||||
│ │ │ └── locales/{en,vi,ja}{,-notices,-import}.ts # split by namespace (07 §2)
|
||||
│ │ │ └── locales/{en,vi,ja,zh-CN,ro}{,-notices,-import}.ts # split by namespace (07 §2)
|
||||
│ │ └── components/ # Svelte components (see 06_UI.md); icons/Icon.svelte,
|
||||
│ │ # focus-heading.ts (the step-heading focus attachment)
|
||||
│ └── styles/
|
||||
@@ -169,7 +176,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[];
|
||||
}
|
||||
|
||||
@@ -215,7 +222,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
|
||||
@@ -224,7 +231,23 @@ 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`).
|
||||
|
||||
Chrome root mapping: `browser/bookmarks.ts` `getRoots()` resolves the three
|
||||
**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. The
|
||||
position fallback itself never takes the Menu either: it is left out of the
|
||||
candidates, so roots with unknown ids still map the bar, Other and Mobile
|
||||
(tested with hand-built roots in `bookmarks.test.ts` — neither fake reaches
|
||||
that path).
|
||||
**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/live-tree.ts` keep them out of every bookmark count.
|
||||
|
||||
Chrome root mapping: `browser/roots.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
|
||||
(`syncing: true`, Chrome 134+) are listed but never written to or emptied.
|
||||
@@ -235,6 +258,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
|
||||
@@ -313,7 +341,11 @@ the hash for a new tab, or via the broadcast for an open one.
|
||||
`NEWER_VERSION`, `EMPTY_TITLE`, and since v1.1.0 `INVALID_URL` (an address
|
||||
`chrome.bookmarks.create` would reject), `PLACE_QUERIES_SKIPPED` (Firefox smart
|
||||
bookmarks), `EXTRA_ROOTS_SKIPPED` (vendor roots in a browser JSON file) and
|
||||
`UNREADABLE_ENTRIES` (a `<DT>` with no readable `<A>` or `<H3>`).
|
||||
`UNREADABLE_ENTRIES` (a `<DT>` with no readable `<A>` or `<H3>`), and since
|
||||
v1.3.0 `SEPARATORS_SKIPPED` (separators an HTML file or a Firefox backup
|
||||
holds — no format keeps one) and `URL_TOO_LONG` (an address longer than the
|
||||
browser accepts, 65 536 characters in Firefox — added by the import from
|
||||
the browser layer's limit, not by a parser).
|
||||
- `browser/` adds `BmBackupError { code }` for the forced safety backup
|
||||
(`03 §1` step 6b) — `BACKUP_SERIALIZE_FAILED`, `BACKUP_EXCEEDS_LIMITS` (since
|
||||
v1.1.0: the backup would be refused by the import's own caps, so it is no
|
||||
|
||||
+49
-6
@@ -45,7 +45,15 @@
|
||||
|
||||
- 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.replaceSeparators`, shown only when there are any). The counts in
|
||||
that confirmation never include separators among the bookmarks, and they
|
||||
cover exactly what Replace deletes: the roots it empties, never a signed-in
|
||||
Chrome account's own roots (`syncing: true`, `02 §4`), which it leaves
|
||||
alone (fixed in v1.3.0 — they used to be counted).
|
||||
- **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 +63,18 @@
|
||||
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. It also means a **Chrome** HTML export's Other and Mobile
|
||||
contents, which Chrome writes loose (`04 §1.2`), land in the Menu in
|
||||
Firefox — as they do with Firefox's own import. BookmarkMagic's exports
|
||||
mark every root, so they are not affected. 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 +84,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,
|
||||
@@ -190,17 +216,34 @@ tree key was ignored.
|
||||
|---|---|
|
||||
| Search | input (debounced 150 ms) → core filter on title+URL → tree shows matches with ancestors expanded; a folder the user collapses during the search stays collapsed until the search text changes |
|
||||
| Rename | F2 or the row button → inline input, focused with its text selected; Enter or blur commits, Esc cancels (a blur after Esc does not commit), and after Enter or Esc focus returns to the tree → trimmed; blank or unchanged → nothing; else `bookmarks.update(id, { title })` |
|
||||
| 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 |
|
||||
| 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
|
||||
@@ -228,7 +271,7 @@ no longer silently stop the tree following the browser.
|
||||
lost from 200 ms to roughly nothing — not to zero.
|
||||
- Legal gate: on Manager mount read `legal.acceptedVersion`; if
|
||||
`< LEGAL_VERSION` render `<LegalGate>` overlay blocking **#import / #export /
|
||||
#edit** — **#settings and #about stay reachable**, so a VI/JA user can switch
|
||||
#edit** — **#settings and #about stay reachable**, so a non-English user can switch
|
||||
language (and theme) before reading the notice and the gate needs no language
|
||||
switcher of its own. Accept → write version + timestamp → unlock.
|
||||
This three-route set is normative; `14 §2` states the same list.
|
||||
|
||||
+29
-7
@@ -84,6 +84,19 @@ 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. The other way round, Chrome's own export writes Other's and Mobile's
|
||||
contents loose (§1.2), so in Firefox they land in the Bookmarks Menu, exactly
|
||||
as Firefox's own import places them; our exports mark both roots and land
|
||||
where they came from.
|
||||
|
||||
### 1.2 Parse tolerance (import)
|
||||
|
||||
@@ -116,7 +129,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 +163,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 +234,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 +329,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`).
|
||||
|
||||
+60
-6
@@ -335,11 +335,23 @@ 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`, through `moveIndexFor` in `live-tree.ts`)
|
||||
sends `api` to Chromium and `local` to Firefox and returns the index the
|
||||
browser reports; `moveTo` in `stores/edit-commands.svelte.ts` compares it with
|
||||
`local` and re-reads 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 +359,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):
|
||||
@@ -392,6 +406,46 @@ destination. Asserted in `move-target.test.ts` (both index spaces, cross-folder,
|
||||
into a bookmark refused, beside itself, beside a root) and, against the
|
||||
in-memory fake, in `edit-session.test.ts`.
|
||||
|
||||
**Keyboard reorder** (Alt+↑ / Alt+↓, since v1.2.1) adds no planner. It picks a
|
||||
target row and a zone, and `planDrop` does the rest:
|
||||
|
||||
```
|
||||
nudgeTarget(rows, id, direction): // rows: the visible rows, in order; direction: -1 | +1
|
||||
row = the row for id; none if absent
|
||||
siblings = rows with row.parentId, in order // the VISIBLE ones: under a search, only matches
|
||||
neighbour = siblings[index of row + direction]; none at either end
|
||||
return neighbour.id
|
||||
|
||||
nudge(id, direction):
|
||||
a nudge already in flight → nothing // a held key repeats faster than a move completes
|
||||
target = nudgeTarget(rows, id, direction); none → nothing
|
||||
plan = planDrop(roots, id, target, direction < 0 ? 'before' : 'after'); none → nothing
|
||||
moveTo(id, plan); refused → nothing
|
||||
row = the row for id, as it is now
|
||||
return { position: row.posInSet, total: row.setSize } // among the siblings ON SCREEN
|
||||
```
|
||||
|
||||
Visible siblings, not all of them, because that is what a drag does too: the
|
||||
user places the item relative to a row they can see. Under a search that has
|
||||
a consequence: the row passes its visible neighbour **and every hidden item
|
||||
between them**, so down-then-up restores what is on screen but not
|
||||
necessarily the hidden order. The place it reports is the visible one too —
|
||||
the same "n of m" the row's `aria-posinset`/`aria-setsize` give — so what is
|
||||
spoken and what the tree says cannot disagree. A permanent root has no
|
||||
`parentId` that `planDrop` accepts, so it never moves.
|
||||
|
||||
One at a time, because each plan is made from the optimistic tree: a second
|
||||
plan made before the first move has landed is made from a tree that is about
|
||||
to change. A residue is known and unfixed: the first move's live event can
|
||||
flush a frame after a second press's optimistic patch and roll the row back
|
||||
for that frame; the tree converges once the events drain (`15`, backlog).
|
||||
|
||||
Asserted in `tree-keyboard.test.ts` (ends of a folder, an open neighbour's
|
||||
children stepped over, a filtered list, a root's neighbour) and
|
||||
`edit-session.test.ts` (Chrome's index rule in both directions, a root, a
|
||||
managed node, hidden items under a search, one move at a time, while busy, a
|
||||
refusal).
|
||||
|
||||
## 11. Live-sync batching — `edit/live-sync.ts`
|
||||
|
||||
```
|
||||
|
||||
+135
-20
@@ -276,7 +276,8 @@ disabled while a bulk command runs.
|
||||
fixed-height scroller, mounted 500 rows at a time with a "Show more" row
|
||||
(`05 §9`); the roots start open. A row: disclosure chevron · glyph (folder,
|
||||
open folder, link — a lock for a policy-managed node) · title (an untitled
|
||||
bookmark shows its address, muted, in mono) · host · a child count on folders ·
|
||||
bookmark shows its address, muted, in mono) · host · a child count on folders
|
||||
(bookmarks and folders — a Firefox separator is not counted) ·
|
||||
⚠ on an address Open refuses (`09` T3) · action buttons, shown on hover and on
|
||||
the focused row: **Open** and **Copy link** (bookmarks), **Sort A→Z**
|
||||
(sortable folders), **Rename**, **Move to…**, **Delete** (editable nodes only —
|
||||
@@ -305,6 +306,13 @@ Search matches render bold in the accent colour.
|
||||
half. An illegal drop — onto itself, into its own subtree, beside a
|
||||
permanent root, into a managed folder — shows nothing and does nothing; a
|
||||
cancelled drag clears every highlight.
|
||||
- **Alt+↑ / Alt+↓** (since v1.2.1) is the keyboard's before/after: the focused
|
||||
row changes places with the sibling shown above or below it — under a search,
|
||||
the nearest one the search still shows. It is the same `planDrop` a drag
|
||||
resolves through (`05 §10`), so legality is one rule: nothing happens at
|
||||
either end of a folder, on a permanent root, on a policy-managed node or
|
||||
while a bulk command runs. Focus stays on the row, and the new position is
|
||||
spoken (§5).
|
||||
- **Move to…** (`MoveToDialog`, built on `Modal`): a filter box over every
|
||||
folder the item may move into, each as its full path, indented — the item
|
||||
itself, its subtree, its current parent and managed folders left out.
|
||||
@@ -329,12 +337,18 @@ Single column of **six** `<SettingRow>`s: Language · Theme
|
||||
(System/Light/Dark segmented) · Default export format · Default import mode ·
|
||||
CSV delimiter · Markdown layout.
|
||||
|
||||
- The Language select offers **four** options, not three: `Settings.locale` is
|
||||
`'auto' | 'en' | 'vi' | 'ja'` and `DEFAULT_SETTINGS.locale === 'auto'`, so
|
||||
- The Language select offers **six** options — one per shipped locale plus
|
||||
"Automatic": `Settings.locale` is `'auto' | Locale` (`en`, `vi`, `ja`,
|
||||
`zh-CN`, `ro` — `07 §2`) and `DEFAULT_SETTINGS.locale === 'auto'`, so
|
||||
"Automatic (follow the browser)" has to be selectable or the default is
|
||||
unreachable. The three language labels are **endonyms**, identical in all
|
||||
three dictionaries — a Japanese user hunting for Vietnamese looks for
|
||||
"Tiếng Việt".
|
||||
unreachable. The options are built from `LOCALES`, in that order. The
|
||||
language labels are **endonyms**, identical in every dictionary — a Japanese
|
||||
user hunting for Vietnamese looks for "Tiếng Việt", a Romanian one for
|
||||
"Română" — and `dictionaries.test.ts` enforces that they match.
|
||||
- Romanian runs roughly a third longer than English, and Chinese far shorter.
|
||||
Neither may truncate a control, wrap a tab label or push the popup past its
|
||||
340 px width — the visual sweep (`11 §5`) photographs every route in both,
|
||||
and that sweep, not a test, is where overflow is caught.
|
||||
- Markdown layout is the sixth row because `markdownStyle` is a persisted
|
||||
field; without it the only place to change it was a transient `#export`
|
||||
control that never wrote back.
|
||||
@@ -349,7 +363,8 @@ behind a `<ConfirmDialog>` (six preferences is enough to be worth a confirm).
|
||||
### 3.5 #about
|
||||
|
||||
`<AboutCard>`: logo, name, version (from manifest at runtime), tagline;
|
||||
links: **GitHub repo ↗** · Report an issue ↗ · Changelog ↗ · Chrome Web Store ↗;
|
||||
links: **GitHub repo ↗** · Report an issue ↗ · Changelog ↗ · Accessibility ↗ ·
|
||||
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
|
||||
@@ -372,14 +387,28 @@ releases page until Phase 5 wrote that file — an empty releases page beats a 4
|
||||
opened from a legal surface. `tests/unit/links.test.ts` now pins both the URL
|
||||
shape and the file's existence, so the fallback cannot silently return.)
|
||||
|
||||
"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.
|
||||
"Accessibility" (since v1.2.1) points at `ACCESSIBILITY.md` on `main` — the
|
||||
statement, the full key list and how to report a barrier. Someone who cannot
|
||||
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.
|
||||
|
||||
"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 a store's item id (`00 §9`) → that store's
|
||||
listing — the Chrome Web Store's, or Edge Add-ons' (mapped after the listing
|
||||
went live on 2026-11-19, so from the release after 1.3.0); anything else — an
|
||||
unpacked build → the README's install section, which lists every store. 1.3.0
|
||||
itself sends an Edge Add-ons install to that section, which links the Edge
|
||||
listing too. The label was "Chrome Web Store" until v1.3.0.
|
||||
|
||||
**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
|
||||
`legal/PRIVACY.md`, the rest in the legal files and the README's contact table;
|
||||
`contact@` is retired), and none of them is inside the extension. An address on
|
||||
`legal/PRIVACY.md`, `accessibility@` in `ACCESSIBILITY.md`, the rest in the
|
||||
legal files and the README's contact table; `contact@` is retired), and none of them is inside the extension. An address on
|
||||
an in-product surface invites users to mail their real bookmark file, and
|
||||
receiving unsanitized personal URLs is exactly what `09` and the privacy policy
|
||||
are written to avoid (`15` decision log, 2026-08-03). `tests/unit/links.test.ts`
|
||||
@@ -438,9 +467,15 @@ held failures at the head of the one queue instead, and every later toast —
|
||||
Home/End; type-ahead by first letter, wrapping. → on an empty folder does
|
||||
nothing, even after "Expand all" put it in the open set. Enter opens a
|
||||
bookmark or toggles a folder; F2 renames; Del asks to delete; the **menu key or
|
||||
Shift+F10** opens "Move to…"; **Ctrl/⌘+C** copies the focused bookmark's
|
||||
link. Ctrl/⌘+F focuses search from anywhere in the tab. Keys typed into the
|
||||
rename input belong to it.
|
||||
Shift+F10** opens "Move to…"; **Alt+↑ / Alt+↓** moves the row one place up
|
||||
or down among its siblings (§3.3); **Ctrl/⌘+C** copies the focused
|
||||
bookmark's link. Ctrl/⌘+F focuses search from anywhere in the tab. Keys
|
||||
typed into the rename input belong to it. `ACCESSIBILITY.md` carries the
|
||||
same list for users, and the About tab links to it — apart from "Ctrl F" on
|
||||
the search box, nothing in the UI shows these keys yet. Tabbing in with
|
||||
nothing focused focuses the first row; a **mouse** press does not (since
|
||||
v1.2.1): the press focuses the list too, and choosing the first row then
|
||||
scrolled a long tree to the top under the pointer.
|
||||
- **Focus never dangles.** A focused row that leaves the screen hands focus to
|
||||
its nearest visible folder (`03 §3`). After a delete, focus goes back where
|
||||
the delete was asked for — the tree, or in the duplicate panel the next
|
||||
@@ -452,6 +487,29 @@ held failures at the head of the one queue instead, and every later toast —
|
||||
change that removes the focused control (confirming the backup) hands focus
|
||||
to the step's heading again. The import's outcome is spoken by one
|
||||
always-present live region (`ImportAnnouncer`).
|
||||
Since v1.2.1 three more places that dropped focus on `<body>` are closed. A
|
||||
**route change** whose control went with the old route ("Open in Edit" on
|
||||
the import report) moves focus to `<main>` — only when focus was lost, and
|
||||
never on the first load. After **"Keep the first of each"** focus lands on
|
||||
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 an
|
||||
`aria-hidden` list item between the `treeitem`s — outside the accessibility
|
||||
tree, so the tree still owns only tree items, and with no `role`, which a
|
||||
hidden element does not need. 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
|
||||
count the siblings on screen, as the tree does. The attributes change too,
|
||||
but a screen reader does not re-read the active descendant for an attribute
|
||||
change, so without the region the move is silent. The region is emptied
|
||||
before each message: set to the text it already holds, it would say nothing.
|
||||
- **Dialogs** (`Modal`): the × is named "Dismiss" — it was named after the
|
||||
dialog, so a screen reader announced the cancel button as "Delete this
|
||||
item?" — and a confirmation's body is its `aria-describedby`, so the counts
|
||||
@@ -459,11 +517,20 @@ held failures at the head of the one queue instead, and every later toast —
|
||||
- **Row buttons are not tab stops** (`tabindex="-1"`; the disclosure is
|
||||
`aria-hidden`). They are mouse shortcuts, and each has a key above — Open
|
||||
(Enter), Copy link (Ctrl+C), Rename (F2), Move to… (menu key), Delete (Del);
|
||||
Sort A→Z is also on the toolbar.
|
||||
- Drag & drop has keyboard parity for **moving into a folder** ("Move to…").
|
||||
Placing an item at an exact position among its siblings — a before/after
|
||||
drop — has **no keyboard equivalent yet**; Sort A→Z is the only keyboard
|
||||
reorder.
|
||||
Sort A→Z is also on the toolbar. **A click on one, or on the chevron, hands
|
||||
focus back to the tree** (since v1.2.1, `focusOwningTree`): Chrome focuses a
|
||||
`tabindex="-1"` button on click, the tree's key handler ignores keys aimed at
|
||||
a row's own control, and so one click used to switch the arrow keys off
|
||||
until the next click on a row. It also means "Move to…" opened from the row
|
||||
button returns focus to the tree, not to a button on a row that has moved.
|
||||
With no row focused yet, the clicked control's row becomes the focused one,
|
||||
so the keys start from where the click was.
|
||||
- Drag & drop has keyboard parity: **into a folder** is "Move to…", and
|
||||
**before/after a sibling** is Alt+↑ / Alt+↓, one place at a time (since
|
||||
v1.2.1; through 1.2.0 Sort A→Z was the only keyboard reorder). What is still
|
||||
missing is a **pointer** route that is not a drag — a click-only way to
|
||||
place an item (WCAG 2.5.7); `ACCESSIBILITY.md` lists it as a known
|
||||
limitation.
|
||||
- **Read-only previews are lists, not trees.** The import preview and the
|
||||
export picker are nested `<ul>`s with disclosure buttons (`aria-expanded`,
|
||||
named "Expand folder: <title>") and, in the picker, checkboxes; plain Tab,
|
||||
@@ -491,6 +558,54 @@ held failures at the head of the one queue instead, and every later toast —
|
||||
in light and both dark variants (§1, enforced by `contrast.test.ts` at token
|
||||
level). Disabled controls say so with colour and the cursor, never opacity,
|
||||
which would drop text under the floor while it still has to be read.
|
||||
- **A ring drawn inside a filled control takes the fill's text colour.** The
|
||||
global ring is `--accent`, outside the control (`outline-offset: 2px`), where
|
||||
it sits on the page. The theme control insets it (`-2px`) to stay inside the
|
||||
group's border — and its selected segment is filled with `--accent`, so
|
||||
through 1.2.0 the ring was accent on accent: invisible, on the one segment
|
||||
roving focus ever lands on. An inset ring on an accent fill is `--accent-fg`
|
||||
(≥ 4.5:1 on `--accent`, already a tested pair), 4px in rather than 2, so
|
||||
the fill shows on both sides of it — at the very edge, a ring in the page's
|
||||
colour only made the segment look smaller. `styles/focus-ring.test.ts` fails
|
||||
on a component that insets a ring over an accent fill without the switch.
|
||||
- **Forced colours** (Windows contrast themes; since v1.2.1). The browser
|
||||
replaces every colour and removes `box-shadow` and background images, so
|
||||
state shown only by a fill or a shadow vanishes. Each such state gets a
|
||||
system-colour equivalent inside `@media (forced-colors: active)`: the tree's
|
||||
focused row and its drop lines, the selected theme segment, the current tab
|
||||
and status-bar entry, the selected import-mode and export-format cards, the
|
||||
progress fill, and the drop zone's edge (drawn with background gradients,
|
||||
which are images). **A border or an outline in `Highlight` wherever the
|
||||
state has a label**: Chrome paints a backplate in the page colour behind
|
||||
forced text, so a label on a `Highlight` fill became a box that hid it — the
|
||||
first cut of this did exactly that to the current tab. The one fill with a
|
||||
label on it, the selected theme segment, sets `forced-color-adjust: none`
|
||||
with `Highlight` / `HighlightText`, because its outline is already the focus
|
||||
ring's.
|
||||
`styles/forced-colors.test.ts` holds the list of components that must carry
|
||||
the block; like the contrast pair list it is hand-maintained, so a new
|
||||
filled state has to be added to it.
|
||||
- **Target size:** every pointer target is at least 24 × 24 CSS px (WCAG 2.2,
|
||||
2.5.8) — since v1.2.1 the row buttons (were 22), the three disclosure
|
||||
chevrons (16), the toast and dialog dismiss buttons, the popup's gear and
|
||||
"Show more" in the export picker and the import preview. The glyphs keep
|
||||
their size; the hit area grows. "Every target" means every button: native
|
||||
checkboxes and radios keep the browser's size inside a label that is the
|
||||
target, and links in running text are exempt by the criterion itself.
|
||||
- **A ring that would be clipped is drawn inside.** The tree's frame and the
|
||||
"Move to…" list clip their overflow, and the global ring sits 2px outside
|
||||
the control: on "Show earlier / Show more" and on the folder buttons it was
|
||||
cut off. Those use `outline-offset: -2px`.
|
||||
- **Placeholders use `--fg-muted`**, set once in `base.css`. The browser's
|
||||
default placeholder grey is not a token, so `contrast.test.ts` never saw it
|
||||
— about 4:1 on `--bg-sunken`.
|
||||
- **The selected theme segment keeps its label on hover.** `button:hover`
|
||||
outranks `.selected`, and `--fg` on the accent fill is under 3:1.
|
||||
- **The public statement is `ACCESSIBILITY.md`** at the repository root: the
|
||||
goal (WCAG 2.2 AA — a goal, not a conformance claim), what was tested and
|
||||
with what, the known limitations, and how to report a barrier. This section
|
||||
is the specification; the statement is what users are told, and a change
|
||||
here that makes the statement false has to change it too (`11 §5`).
|
||||
|
||||
## 6. Iconography
|
||||
|
||||
|
||||
+239
-72
@@ -1,7 +1,9 @@
|
||||
# 07 — Internationalization (EN / VI / JA)
|
||||
# 07 — Internationalization (EN / VI / JA / ZH-CN / RO)
|
||||
|
||||
Baseline matches the portfolio standard: **English (default), Vietnamese,
|
||||
Japanese**. Two mechanisms with a strict split:
|
||||
Japanese**. v1.2.0 adds **Simplified Chinese (`zh-CN`) and Romanian (`ro`)** —
|
||||
the two languages the CWS dashboard showed real installs and active users in
|
||||
after the first three. Two mechanisms with a strict split:
|
||||
|
||||
| Layer | Mechanism | Why |
|
||||
|---|---|---|
|
||||
@@ -11,9 +13,11 @@ Japanese**. Two mechanisms with a strict split:
|
||||
## 1. `_locales/` (manifest-level only)
|
||||
|
||||
```
|
||||
public/_locales/en/messages.json ← default_locale
|
||||
public/_locales/vi/messages.json
|
||||
public/_locales/ja/messages.json
|
||||
src/public/_locales/en/messages.json ← default_locale
|
||||
src/public/_locales/vi/messages.json
|
||||
src/public/_locales/ja/messages.json
|
||||
src/public/_locales/zh_CN/messages.json ← Chrome's directory name, underscore
|
||||
src/public/_locales/ro/messages.json
|
||||
```
|
||||
|
||||
```json
|
||||
@@ -25,13 +29,37 @@ public/_locales/ja/messages.json
|
||||
|
||||
`wxt.config.ts` manifest: `name: "__MSG_appName__"`,
|
||||
`description: "__MSG_appDesc__"`, `default_locale: "en"`.
|
||||
Keep `appName` identical in all three locales (brand name is not translated);
|
||||
`appDesc` is translated.
|
||||
Keep `appName` identical in every locale (brand name is not translated);
|
||||
`appDesc` is translated and stays ≤ 132 characters (the manifest limit, enforced
|
||||
by `manifest.test.ts`).
|
||||
|
||||
Directory names are **Chrome's**, not BCP 47: `zh_CN`, with an underscore. The
|
||||
runtime locale id is the BCP 47 tag `zh-CN` (§2). The two are mapped in `CHROME_LOCALE_DIRS` in `tests/helpers/locales.ts`; `manifest.test.ts`
|
||||
uses it to fail on a missing `messages.json` and on a `_locales/` directory no
|
||||
locale owns.
|
||||
|
||||
Chrome resolves a manifest string by trying the full UI locale, then its
|
||||
language, then `default_locale` — so a Traditional Chinese browser (`zh_TW`)
|
||||
falls back to **English**, never to `zh_CN`. §2's runtime rule deliberately
|
||||
matches it, so the name in `chrome://extensions` and the UI agree.
|
||||
|
||||
## 2. Runtime i18n — `src/lib/i18n/`
|
||||
|
||||
```ts
|
||||
// locales/en.ts (vi.ts, ja.ts mirror the exact same shape)
|
||||
// resolve-locale.ts — the single list of shipped locales
|
||||
export const LOCALES = ['en', 'vi', 'ja', 'zh-CN', 'ro'] as const;
|
||||
export type Locale = (typeof LOCALES)[number];
|
||||
```
|
||||
|
||||
`as const` is correct **here** — this is a list of ids, not a dictionary (the
|
||||
ban below is about dictionaries). Every table keyed by locale is a
|
||||
`Record<Locale, …>`, so a locale added to `LOCALES` and missing anywhere else is
|
||||
a compile error rather than a silent English fallback: `dicts` in
|
||||
`index.svelte.ts`, `TAGS` in `format.ts`. `storage.ts`'s allow-list is
|
||||
`['auto', ...LOCALES]` and the Settings choices are built from the same array.
|
||||
|
||||
```ts
|
||||
// locales/en.ts (every other locale mirrors the exact same shape)
|
||||
import { importTab } from './en-import';
|
||||
import { errors, warnings } from './en-notices';
|
||||
|
||||
@@ -45,11 +73,12 @@ const dict = {
|
||||
};
|
||||
|
||||
export default dict;
|
||||
export type Dict = typeof dict; // widened: string, NOT the literal 'Import'
|
||||
/** Widened (string, NOT the literal 'Import'); plural branches may add `few` (§5). */
|
||||
export type Dict = Localized<typeof dict>;
|
||||
```
|
||||
|
||||
```ts
|
||||
// locales/vi.ts (ja.ts identical in shape)
|
||||
// locales/vi.ts (ja.ts, zh-CN.ts, ro.ts identical in shape)
|
||||
import type { Dict } from './en';
|
||||
import { importTab } from './vi-import';
|
||||
import { errors, warnings } from './vi-notices';
|
||||
@@ -63,43 +92,73 @@ export const importTab = { /* … */ } satisfies Dict['import'];
|
||||
(`warnings` and `errors`) and `<lang>-import.ts` (the Import tab). `<lang>.ts`
|
||||
re-assembles them, so the runtime shape and every key path are unchanged — the
|
||||
split exists only to keep each file under the `10 §1` size limit as codes and
|
||||
Import strings are added. In vi/ja the parts are typed `satisfies
|
||||
Dict['warnings']`, `Dict['errors']` and `Dict['import']`, so a missing key fails
|
||||
`tsc` in the very file that lacks it. A new string goes in whichever file holds
|
||||
its branch.
|
||||
Import strings are added. In the non-English locales the parts are typed
|
||||
`satisfies Dict['warnings']`, `Dict['errors']` and `Dict['import']`, so a
|
||||
missing key fails `tsc` in the very file that lacks it. A new string goes in
|
||||
whichever file holds its branch.
|
||||
|
||||
```ts
|
||||
// index.svelte.ts
|
||||
import en from './locales/en'; import vi from './locales/vi'; import ja from './locales/ja';
|
||||
export type Locale = 'en' | 'vi' | 'ja';
|
||||
const dicts = { en, vi, ja };
|
||||
const dicts: Record<Locale, Dict> = { en, vi, ja, 'zh-CN': zhCN, ro };
|
||||
let locale = $state<Locale>('en'); // hydrated from settings store
|
||||
export function t(path: string, params?: Record<string, string | number>): string
|
||||
// resolves dotted path in dicts[locale], falls back to en, interpolates {tokens}
|
||||
export function setLocale(l: Locale) { locale = l; } // settings store persists
|
||||
```
|
||||
|
||||
- `en.ts` is the **schema source of truth**; `vi`/`ja` are typed
|
||||
- `en.ts` is the **schema source of truth**; every other locale is typed
|
||||
`satisfies Dict` → missing keys fail `tsc` (compile-time completeness check,
|
||||
no i18n framework needed).
|
||||
- ⚠️ **Do not write `as const` on `en.ts`.** It would make `typeof dict` a tree
|
||||
of *string literal* types, so `satisfies Dict` would demand
|
||||
`vi.common.import === 'Import'` — every correct translation becomes a compile
|
||||
error and the only way to make VI/JA build is to leave them in English.
|
||||
- ⚠️ **Do not write `as const` on `en.ts`** (or any dictionary). It would make
|
||||
`typeof dict` a tree of *string literal* types, so `satisfies Dict` would
|
||||
demand `vi.common.import === 'Import'` — every correct translation becomes a
|
||||
compile error and the only way to make a locale build is to leave it in
|
||||
English.
|
||||
- `Dict` is `Localized<typeof dict>`: `typeof dict` with every plural branch
|
||||
(`{ one, other }`) widened to `{ one, other, few? }`. That optional `few` is
|
||||
the only thing it adds — it lets Romanian carry its third form (§5) without
|
||||
every other locale writing a dead one. Whether a locale carries `few` is
|
||||
checked at runtime, not by the type.
|
||||
- `Dict` is exported from `locales/en.ts` (a leaf module), **not** from
|
||||
`index.svelte.ts`. That module imports vi/ja and holds runtime `$state`, so
|
||||
having vi/ja import a type back from it forms a cycle that is only harmless
|
||||
while the import stays type-only — fragile under `verbatimModuleSyntax`.
|
||||
`index.svelte.ts`. That module imports every locale and holds runtime
|
||||
`$state`, so having a locale import a type back from it forms a cycle that is
|
||||
only harmless while the import stays type-only — fragile under
|
||||
`verbatimModuleSyntax`.
|
||||
- Interpolation is `{token}` replacement only. **No string concatenation of
|
||||
sentence fragments** — full sentences per key, so VI/JA word order works.
|
||||
- Initial locale resolution: saved setting → else map
|
||||
`chrome.i18n.getUILanguage()` prefix (`vi*`→vi, `ja*`→ja) → else `en`.
|
||||
sentence fragments** — full sentences per key, so word order works in every
|
||||
language.
|
||||
- The document language follows the resolved locale: `<html lang>` is set to the
|
||||
locale id (`vi`, `zh-CN`, …). For `zh-CN` that is load-bearing — Chinese and
|
||||
Japanese share code points, and `lang` is what makes Chrome pick a Simplified
|
||||
Chinese font and glyph forms instead of Japanese ones.
|
||||
|
||||
**Initial locale resolution:** saved setting → else map
|
||||
`chrome.i18n.getUILanguage()` → else `en`. The mapping (`resolveLocale`):
|
||||
|
||||
| Browser UI language | Resolves to |
|
||||
|---|---|
|
||||
| `vi`, `vi-*` | `vi` |
|
||||
| `ja`, `ja-*` | `ja` |
|
||||
| `zh-Hant*` (any region) | **`en`** — matches Chrome's own manifest fallback (§1); the user can still pick 简体中文 by hand |
|
||||
| `zh-Hans*` (any region) | `zh-CN` |
|
||||
| `zh-TW`, `zh-HK`, `zh-MO` (no script subtag) | **`en`**, as above |
|
||||
| `zh`, `zh-CN`, `zh-SG` and every other `zh-*` region | `zh-CN` |
|
||||
| `ro`, `ro-*` (incl. `ro-MD`) | `ro` |
|
||||
| anything else | `en` |
|
||||
|
||||
The rows are checked top to bottom, so an explicit script wins over the region
|
||||
(`zh-Hans-TW` is Simplified). Only whole subtags match: `vic` or `jav` (Javanese)
|
||||
start with `vi`/`ja` but are not our locales. Extension and private-use subtags
|
||||
(`-u-…`, `-x-…`) are ignored. `-` and `_` both separate subtags.
|
||||
The `<option>` for each language carries its own `lang`, so the endonyms are
|
||||
voiced and drawn in their own language whatever the UI language is.
|
||||
|
||||
## 3. Formatting rules
|
||||
|
||||
- Dates in UI: `new Intl.DateTimeFormat(localeTag, { dateStyle:'medium', timeStyle:'short' })`
|
||||
with tags `en-US` / `vi-VN` / `ja-JP`.
|
||||
- Numbers (counts): `Intl.NumberFormat(localeTag)` — VI uses `.` thousands.
|
||||
with tags `en-US` / `vi-VN` / `ja-JP` / `zh-CN` / `ro-RO`.
|
||||
- Numbers (counts): `Intl.NumberFormat(localeTag)` — VI and RO use `.`
|
||||
thousands, EN, JA and ZH `,`.
|
||||
|
||||
Where these live: pure `localeTag` / `formatCount` / `formatDateTime` in
|
||||
`src/lib/i18n/format.ts` (formatters cached per tag — `StatsCard` alone formats
|
||||
@@ -114,7 +173,7 @@ comment at the site so the next reader does not "finish the job":
|
||||
|
||||
| Site | Why |
|
||||
|---|---|
|
||||
| `ProgressBar`'s `{n}%` | 0–100; no locale groups two digits, and it is the hottest render path in the app |
|
||||
| `ProgressBar`'s `{n}%` | 0–100; no shipped locale groups two digits, and it is the hottest render path in the app |
|
||||
| `import.folderName`'s date | this bullet list already pins it to the localized *word* + an **ISO** date; localizing it would rename folders written into the user's browser |
|
||||
| Export filenames and file contents | locale-independent so a file means the same thing whoever opens it |
|
||||
|
||||
@@ -123,64 +182,172 @@ stay raw.
|
||||
- File names & file contents stay locale-independent (ISO dates, English
|
||||
"Imported" folder prefix? **No** — the auto-folder title uses the localized
|
||||
word + ISO date, e.g. `Đã nhập 2026-07-03`, key `import.folderName`).
|
||||
- **Sort A→Z** collates with the UI locale (`Intl.Collator(getLocale())`), so a
|
||||
Chinese user's folders sort by pinyin and a Romanian user's put `ș` after `s`.
|
||||
|
||||
## 4. Translation workflow & tone
|
||||
|
||||
- New strings land in English first — in `en.ts`, `en-notices.ts` or
|
||||
`en-import.ts`, whichever holds the branch (PR fails type-check until vi/ja
|
||||
follow).
|
||||
`en-import.ts`, whichever holds the branch (PR fails type-check until every
|
||||
locale follows).
|
||||
- **Terminology follows the browser.** Where Chrome (or, for Firefox's root
|
||||
names, Firefox) already has a word in that language — bookmark, bookmarks
|
||||
bar, folder, import — use the browser's own word, so the extension and the
|
||||
browser around it never disagree.
|
||||
- VI: neutral–friendly register, "bạn"; keep established loanwords
|
||||
(bookmark, import/export may stay English in UI where natural — decide per
|
||||
string, be consistent; folder = "thư mục").
|
||||
- JA: です/ます form; katakana loanwords (ブックマーク, インポート,
|
||||
エクスポート, フォルダ).
|
||||
- No machine-translated commits without human review (owner reviews VI;
|
||||
JA reviewed best-effort — mark `// TODO(review-ja)` where unsure).
|
||||
- ZH-CN (Simplified only):
|
||||
- Chrome's zh-CN terms: 书签 · 书签栏 · 其他书签 · 移动设备书签 · 文件夹 ·
|
||||
导入 · 导出 · 编辑 · 设置 · 关于 · 重复 · 合并 · 替换 · 备份 · 主题.
|
||||
- Polite but sparing: 您 where a pronoun is needed. Most strings need none.
|
||||
- Full-width punctuation (,。:;?!“”()). The ellipsis is `…`, as in the
|
||||
English source.
|
||||
- One half-width space between Han characters and Latin text, numbers or a
|
||||
`{token}`: "导出 {n} 个书签", "HTML 文件". No space next to full-width
|
||||
punctuation.
|
||||
- Measure words with counts: 个书签, 个文件夹, 项 for mixed items.
|
||||
- RO:
|
||||
- Chrome's ro terms: marcaj / marcaje · Bara de marcaje · Alte marcaje ·
|
||||
Marcaje mobile · dosar / dosare · a importa / a exporta · setări · despre ·
|
||||
copie de rezervă · temă.
|
||||
- Polite plural address, as Chrome and Windows use: "Selectați", "Importați",
|
||||
"dumneavoastră" where a pronoun is needed.
|
||||
- **Comma-below `ș ț Ș Ț` (U+0219/021B/0218/021A), never cedilla `ş ţ`**. They
|
||||
are different letters to a search box and a sort. `dictionaries.test.ts`
|
||||
fails on a cedilla anywhere in the Romanian files.
|
||||
- Quotation marks „…”.
|
||||
- Counts take a third plural form (§5): "1 marcaj", "5 marcaje", "20 de
|
||||
marcaje".
|
||||
- **Review policy.** Commit no machine translation unless someone has reviewed
|
||||
it. The owner reviews VI. JA, ZH-CN and RO are **best-effort** until a native
|
||||
pass, and each file says so in its header: `TODO(review-ja)`,
|
||||
`TODO(review-zh)`, `TODO(review-ro)`, with the same marker on any single
|
||||
string that is especially uncertain. Native passes are open ⚠️ items
|
||||
(`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`,
|
||||
`import.replaceSeparators` and `import.target.menu`. The JA, ZH-CN and RO versions are best-effort and
|
||||
carry the usual `TODO(review-…)` marker.
|
||||
|
||||
## 5. Locale-sensitive edge cases
|
||||
|
||||
- Pluralization: plural keys are objects `{ one, other }` in **every** locale —
|
||||
a tiny helper selects by locale. VI/JA have one grammatical form, so they set
|
||||
`one` and `other` to the same string. They must still carry both keys, or the
|
||||
`satisfies Dict` shape check that §2 relies on for completeness fails.
|
||||
- **Pluralization.** A plural key is an object of CLDR plural forms. Every
|
||||
locale carries `{ one, other }`. **Romanian also carries `few`.** The rule is
|
||||
mechanical: a locale carries `few` exactly when
|
||||
`Intl.PluralRules(tag).resolvedOptions().pluralCategories` includes it.
|
||||
- VI, JA and ZH have one grammatical form, so they set `one` and `other` to
|
||||
the same string. They must still carry both keys, or the `satisfies Dict`
|
||||
shape check that §2 relies on for completeness fails.
|
||||
- EN has `one` (1) and `other`.
|
||||
- RO has `one` (1), `few` (0, 2–19, and any number ending in 01–19, such as
|
||||
101 or 119) and `other` (20–100, 120…). `other` is the form with "de":
|
||||
"{n} de marcaje".
|
||||
- A count-less noun label — the popup's eyebrows above a big number — is not
|
||||
a sentence. There the bare plural noun serves both `few` and `other`
|
||||
("marcaje").
|
||||
|
||||
Implemented as `selectPluralForm(count, tag)` in `i18n/format.ts` (backed by
|
||||
`Intl.PluralRules`, narrowed to the two forms — en yields `one`/`other`, vi
|
||||
and ja only ever `other`, so two forms cover every locale we ship) and
|
||||
`tPlural(path, count, params?)` in `index.svelte.ts`, which supplies `{n}`
|
||||
already grouped for the locale so callers pass a raw count. Two tests in
|
||||
`tests/unit/i18n/dictionaries.test.ts` enforce the shape: every plural key
|
||||
carries both forms in all three locales, and carries nothing else.
|
||||
Implemented as `selectPluralForm(count, tag)` in `i18n/format.ts`. It is
|
||||
backed by `Intl.PluralRules` and narrowed to `one`/`few`/`other`; `zero`,
|
||||
`two` and `many` fold into `other`, and no shipped locale produces them.
|
||||
`tPlural(path, count, params?)` in `index.svelte.ts` supplies `{n}` already
|
||||
grouped for the locale, so callers pass a raw count. It falls back from the
|
||||
selected form to `other`, then to English.
|
||||
|
||||
The plural keys are **every** `warnings.*` code — including the two that
|
||||
interpolate no count, because `ParseWarning` always carries one and a uniform
|
||||
shape lets `WarningList` call `tPlural` unconditionally instead of
|
||||
maintaining a list of which codes count things — then `import.warnings.title`
|
||||
and, since v1.1.0, eighteen more: `popup.bookmarks`/`folders`;
|
||||
`export.start`; `import.start`, `countBookmarks`/`countFolders`, `reused`,
|
||||
`cancelledSummary`, `partialCreated`/`partialCleared`;
|
||||
`edit.deleteFolderBody`, `keepFirst`/`keepFirstBody`, `sortBody`,
|
||||
`showMore`/`showEarlier` and `duplicateLinks`/`extraCopies` (the duplicate
|
||||
summary was one string with two counts, so it read "1 duplicated links · 1
|
||||
extra copies"). Anything else stays a plain string.
|
||||
`tests/unit/i18n/dictionaries.test.ts` enforces the shape:
|
||||
- every plural key carries exactly the forms its locale's rules need, and
|
||||
nothing else;
|
||||
- `few` is compared against English `other` for interpolation tokens;
|
||||
- **every shipped locale's `pluralCategories` ⊆ {one, few, other}**. A future
|
||||
locale that needs `two` or `many` (Arabic, Polish, Russian…) fails there
|
||||
first, before anyone ships a grammar the helper cannot select.
|
||||
|
||||
⚠️ **No non-plural key may be named `one` or `other`.** The second test reads
|
||||
any branch holding either key as a plural and fails it unless it has exactly
|
||||
two keys. That is why the Firefox root names are
|
||||
The plural keys are **every** `warnings.*` code. That includes the two that
|
||||
interpolate no count: `ParseWarning` always carries one, and a uniform shape
|
||||
lets `WarningList` call `tPlural` unconditionally instead of keeping a list
|
||||
of which codes count things. Beyond those come `import.warnings.title` and,
|
||||
since v1.1.0, eighteen more:
|
||||
- `popup.bookmarks`/`folders`;
|
||||
- `export.start`;
|
||||
- `import.start`, `countBookmarks`/`countFolders`, `reused`,
|
||||
`cancelledSummary`, `partialCreated`/`partialCleared`;
|
||||
- `edit.deleteFolderBody`, `keepFirst`/`keepFirstBody`, `sortBody`,
|
||||
`showMore`/`showEarlier` and `duplicateLinks`/`extraCopies`. The duplicate
|
||||
summary was one string with two counts, so it read "1 duplicated links · 1
|
||||
extra copies".
|
||||
|
||||
Anything else stays a plain string.
|
||||
|
||||
⚠️ **No non-plural key may be named `one`, `few` or `other`.** The test reads
|
||||
any branch holding one of those keys as a plural and fails it unless its keys
|
||||
are exactly the plural forms. That is why the Firefox root names are
|
||||
`import.rootTitle.{toolbar, unfiled, mobile}`: a third key named `other` made
|
||||
the branch a malformed "plural".
|
||||
|
||||
- **Every code needs a message, in all three locales.** A code with no key
|
||||
renders as its own dotted path (`warnings.INVALID_URL`) and no union type can
|
||||
see it, so `dictionaries.test.ts` walks three runtime lists:
|
||||
`PARSE_WARNING_CODES` (eleven since v1.1.0, each a plural under `warnings.*`),
|
||||
`BM_PARSE_ERROR_CODES`, and since v1.1.0 `BM_BACKUP_ERROR_CODES`
|
||||
(`browser/errors.ts`, now `BACKUP_EXCEEDS_LIMITS` included) — plain strings
|
||||
under `errors.*`. A new code goes into its list, or the test cannot see it.
|
||||
`BmEnvError`'s codes (`NO_WRITABLE_ROOTS`, `WRITE_LOCKED`) have no list yet:
|
||||
the key-path parity check keeps vi/ja in step with en, but nothing checks
|
||||
that en has them.
|
||||
- **Language labels are endonyms, identical in every dictionary.** A Japanese
|
||||
user hunting for Romanian looks for "Română", not "ルーマニア語".
|
||||
`dictionaries.test.ts` asserts `settings.lang` is the same in all of them.
|
||||
- **Every code needs a message, in every locale.** A code with no key renders
|
||||
as its own dotted path (`warnings.INVALID_URL`) and no union type can see it,
|
||||
so `dictionaries.test.ts` walks three runtime lists:
|
||||
- `PARSE_WARNING_CODES` (eleven since v1.1.0, each a plural under
|
||||
`warnings.*`);
|
||||
- `BM_PARSE_ERROR_CODES`;
|
||||
- since v1.1.0, `BM_BACKUP_ERROR_CODES` (`browser/errors.ts`, now including
|
||||
`BACKUP_EXCEEDS_LIMITS`).
|
||||
|
||||
The last two are plain strings under `errors.*`. A new code goes into its
|
||||
list, or the test cannot see it. `BmEnvError`'s codes are covered by
|
||||
`BM_ENV_ERROR_CODES`.
|
||||
- Legal Gate: the four legal documents are **English-only** (canonical), with
|
||||
a localized one-line note: "The legally binding documents are in English."
|
||||
- Store listing: EN required; VI + JA listings via CWS dashboard localized
|
||||
fields (copy lives in `13_RELEASE_PUBLISHING.md`).
|
||||
- Store listing: EN required; every other locale's listing goes into the CWS
|
||||
dashboard's localized fields (copy lives in `store/listing.*.md`, `13 §3`).
|
||||
|
||||
## 6. Adding a locale
|
||||
|
||||
Written while adding `zh-CN` and `ro`, so the next language is a checklist and
|
||||
not an investigation. Each step names what fails when it is skipped.
|
||||
|
||||
1. **Plural forms first.** Check
|
||||
`new Intl.PluralRules(tag).resolvedOptions().pluralCategories`. If it holds
|
||||
anything besides `one`, `few` and `other`, stop: `format.ts`, `Localized`
|
||||
and the dictionary tests need a new form before any translation can be
|
||||
correct. The guard test fails here anyway.
|
||||
2. `LOCALES` in `resolve-locale.ts`, plus a `resolveLocale` row and its tests.
|
||||
`tsc` then demands the `dicts` entry (`index.svelte.ts`) and the `TAGS`
|
||||
entry (`format.ts`).
|
||||
3. Three dictionary files modelled on `ja.ts` / `ja-notices.ts` /
|
||||
`ja-import.ts`, with a tone header and the `TODO(review-xx)` marker.
|
||||
4. The endonym in `settings.lang` of **every** dictionary (the endonym test
|
||||
fails otherwise).
|
||||
5. `src/public/_locales/<chrome dir>/messages.json`. Also add it to
|
||||
`CHROME_LOCALE_DIRS` (`tests/helpers/locales.ts`), to `REQUIRED_FILES`
|
||||
(`scripts/check-manifest.mjs`) and to that script's test fixture.
|
||||
6. `store/listing.<chrome dir>.md` plus its row in `store/README.md`.
|
||||
7. The language dropdown in `.github/ISSUE_TEMPLATE/translation.yml`, and the
|
||||
`LANGS` list in `scripts/screenshots.mjs`. Then run the visual sweep
|
||||
(`11 §5`) in both themes for overflow and glyphs.
|
||||
`tests/unit/i18n/touch-points.test.ts` fails on any of steps 5–7 left out,
|
||||
and on a `LANGUAGES` line in a listing or the README that does not name
|
||||
every language.
|
||||
8. This chapter's tone section, `06 §3.4`, `11 §5`, `README.md`, `CHANGELOG.md`.
|
||||
A new UI language is a **minor** release (`12 §4`).
|
||||
+100
-5
@@ -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
|
||||
@@ -198,9 +214,88 @@ any of them changes (`09 §4`).
|
||||
- [ ] Right-click → Options lands on `#settings` both on a fresh profile and
|
||||
with a Manager tab already open on another route (§1 uses an undocumented
|
||||
URL fragment; `02 §5`).
|
||||
- [ ] All three `_locales` load (chrome://extensions shows localized name
|
||||
when browser language switched).
|
||||
- [ ] All five `_locales` load (chrome://extensions shows the localized
|
||||
description when the browser language is switched — and a `zh_TW`
|
||||
browser shows English, `07 §1`).
|
||||
- [ ] Version bumped (semver) in `package.json` (WXT propagates to manifest).
|
||||
- [ ] 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.
|
||||
- **Options can open a second Manager tab.** Chrome reuses an open Manager
|
||||
for `options_ui` whatever its route, ignoring the `#settings` fragment
|
||||
(`02 §5`); Firefox matches the whole address, fragment included (its
|
||||
about:addons and `open_in_tab` code never pass `ignoreFragment`), so with a
|
||||
Manager open on `#edit` it opens another one on `#settings`. Cosmetic: both
|
||||
tabs work, and the write lock keeps them from writing at once (`03 §5`).
|
||||
- **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.
|
||||
- **The listing names no other browser.** Edge's developer policy (1.1.2)
|
||||
says an extension "must not reference other browsers", and Partner Center
|
||||
warns on any browser name in a description — on 2026-11-18 it flagged
|
||||
"Firefox" in the first Edge copy, which was the Chrome Web Store
|
||||
description with two bullets swapped and still listed seven browsers. The
|
||||
Edge copy in `store/listing.*.md` is now a complete description of its own:
|
||||
the profile `Bookmarks` file is the one "Edge and similar browsers keep",
|
||||
HTML export is the file "every major browser can import", and
|
||||
`tests/unit/store-listing.test.ts` fails on a name pasted back in. The same
|
||||
policy (1.5.2) asks that the privacy policy refer "primarily" to Edge;
|
||||
`legal/PRIVACY.md` names all three stores. That is a *should*, so it is left
|
||||
as it is unless review raises it.
|
||||
- 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.
|
||||
@@ -114,12 +114,19 @@ four of them sat under, and Vite 8 bundles with rolldown rather than esbuild.
|
||||
None of the six packages was in the lockfile — and a stale override is worse
|
||||
than none, because the day the package returns it silently pins it.
|
||||
|
||||
State after the v1.1.0 toolchain pass (Node 26, Vitest 5, Vite 8.3, WXT 0.21.4):
|
||||
State on 2026-11-18 (Node 26, Vitest 5.1, Vite 8.3, WXT 0.21.5):
|
||||
|
||||
| Check | Result |
|
||||
|---|---|
|
||||
| `npm audit --omit=dev` | **0** — nothing third-party is a runtime dependency (CI runs this, `12 §2.1`) |
|
||||
| `npm audit` (dev included) | 3 low, one root cause: **`deepmerge`** (GHSA-gcqx-w48m-w2h4, prototype poisoning in `mergeObject`), reached through `@sveltejs/vite-plugin-svelte`. **No fixed version exists.** It merges the build's own plugin options at dev/build time — never user data, never in the shipped extension — so it is accepted and recorded rather than overridden. Re-check when the plugin drops or bumps it. |
|
||||
| `npm audit` (dev included) | **14 high, one root cause: `picomatch`** — GHSA-fc5q-39xc-vjpf (CVE-2026-112366), a ReDoS through single-branch repeated extglobs. **Every version up to 4.0.7 is affected and no fixed version exists**, so there is nothing to upgrade or override to. It is the glob engine of the whole toolchain (WXT, Vite, Vitest, knip, svelte-check, unplugin, tinyglobby, fdir — the other 13 entries are those parents), and it matches patterns this repository writes into its own config files, at build and test time only: never user data, never in the shipped extension. Recorded rather than worked around. Dependabot opens a security PR the day a fixed release exists, and `MAINTENANCE.md` makes that PR urgent. |
|
||||
| Retired | The `deepmerge` advisory recorded here until v1.2.1 (GHSA-gcqx-w48m-w2h4, low, via `@sveltejs/vite-plugin-svelte`) was **withdrawn** by GitHub on 2026-11-16. `deepmerge` 4.3.1 is still in the tree; nothing else needs doing. |
|
||||
|
||||
The maintenance policy's rule for advisories (`MAINTENANCE.md`): a **high or
|
||||
critical** one is fixed as soon as a fixed version exists — through the
|
||||
Dependabot security PR, or a lockfile update when a parent's range already
|
||||
allows the fix. When no fix exists, the advisory goes in the table above with
|
||||
why it cannot reach a user, and the row stays until the fix lands.
|
||||
|
||||
How new advisories are kept out:
|
||||
|
||||
@@ -132,6 +139,33 @@ How new advisories are kept out:
|
||||
- Dependabot *security* PRs bypass `cooldown`; one for a version younger than
|
||||
a week may fail to resolve until it ages. That is the intended trade-off.
|
||||
|
||||
### 3.2 Licence gate — `npm run check:licenses`
|
||||
|
||||
Added 2026-11-18. `scripts/check-licenses.mjs` reads every entry of
|
||||
`package-lock.json` (lockfile v3 records each package's `license` field, and every
|
||||
entry carries one) and fails the run on any licence outside two lists:
|
||||
|
||||
| Packages | Accepted | Why |
|
||||
|---|---|---|
|
||||
| What the build compiles into the extension — `CREDITED_PACKAGES` in `scripts/credited-packages.mjs`, the same list the build gate and the notices test read (`14 §5`) | `MIT`, `ISC`, `BSD-2-Clause`, `BSD-3-Clause`, `Apache-2.0`, `0BSD`, `MIT-0` | This code travels inside a GPL-3.0-or-later extension; only permissive licences that combine with it cleanly |
|
||||
| Everything else — all of it build and test tooling, since there are no runtime dependencies | the above, plus `MPL-2.0`, `BlueOak-1.0.0`, `CC0-1.0`, `CC-BY-4.0`, `Python-2.0`, `Unlicense`, `Zlib` | Tools never ship. File-level copyleft (MPL-2.0 — `lightningcss`, under Vite) is fine for a tool; network copyleft, source-available terms and missing or custom licences are not |
|
||||
|
||||
SPDX expressions are evaluated (`OR` needs either side, `AND` both). An entry
|
||||
with no `license`, `UNLICENSED` or `SEE LICENSE IN …` fails. A new licence
|
||||
enters the tree through a reviewed change to the lists — or one `EXCEPTIONS`
|
||||
entry with its reason and a `15` decision-log row — never unnoticed inside a
|
||||
Dependabot bump. The gate trusts each package's own declaration, as any
|
||||
lockfile-based check must, and needs neither `node_modules` nor the network.
|
||||
It runs in `verify`, in CI's `quality` job and in the release build, over the
|
||||
root lockfile and, since v1.3.0, `tools/publish/package-lock.json` — the
|
||||
store-upload tool, which ships nothing, so it is held to the toolchain list
|
||||
(`12 §3`).
|
||||
|
||||
Considered and not used: `actions/dependency-review-action`. It sees only
|
||||
what a pull request changes, reads licences from ClearlyDefined rather than
|
||||
the lockfile, checks only runtime-scoped packages unless told otherwise, and
|
||||
cannot run locally — a second, weaker opinion beside this one.
|
||||
|
||||
## 4. Permissions posture
|
||||
|
||||
`bookmarks` + `storage`, nothing else (justifications in `08 §2`). Any PR
|
||||
@@ -146,8 +180,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.
|
||||
|
||||
@@ -50,7 +50,7 @@ rather than assign `undefined`. Build nodes with conditional spreads
|
||||
|
||||
```jsonc
|
||||
{
|
||||
"$schema": "https://biomejs.dev/schemas/2.6.2/schema.json",
|
||||
"$schema": "https://biomejs.dev/schemas/2.6.6/schema.json",
|
||||
"vcs": { "enabled": true, "clientKind": "git", "useIgnoreFile": true },
|
||||
// Svelte, CSS, Markdown and YAML are excluded on purpose — see the notes below.
|
||||
"files": {
|
||||
@@ -78,6 +78,15 @@ rather than assign `undefined`. Build nodes with conditional spreads
|
||||
(`switch-every-tab-hotkey`) excludes `.svelte` and `.css` instead, and we
|
||||
follow it rather than putting the build on an experimental flag.
|
||||
**`svelte-check` is the authority** for everything inside `.svelte`.
|
||||
Since v1.2.1 it runs with **`--fail-on-warnings`**: the Svelte compiler's
|
||||
accessibility warnings (`a11y_*` — a click handler with no key handler, a
|
||||
control with no label) are warnings, and through 1.2.0 a warning never
|
||||
failed anything. It is the only lint that reads the markup. A deliberate
|
||||
exception takes a `<!-- svelte-ignore a11y_… -->` with its reason in the
|
||||
same comment; there are two, on `Modal`'s backdrop click and on the tree's
|
||||
`<ul>`. (`TreeRow`'s row `<div>` avoids the same warning differently — an
|
||||
empty `onkeydown` and `role="presentation"` — because the keys are the
|
||||
tree's, not the row's.)
|
||||
- **Markdown and YAML are excluded since Biome 2.6**, which started formatting
|
||||
both. The docs and workflow files are laid out by hand (long explanatory
|
||||
comments, deliberate wrapping); letting a formatter own them would turn every
|
||||
|
||||
+168
-19
@@ -189,6 +189,28 @@ 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. Firefox has suites of its own rather than
|
||||
a second pass of the Chromium ones: `firefox-import.test.ts` (roots by GUID;
|
||||
Merge, New-folder and Replace — all four roots emptied, the backup restored
|
||||
twice; export), `edit-firefox.test.ts` (the edit model, keyboard positions,
|
||||
Sort A→Z around separators, drops and Alt+↑/↓ at Firefox's index, the re-read
|
||||
when the browser reports another landing place), `live-tree.test.ts`
|
||||
(separators, counts, the Menu marker, each browser's move index) and the pure
|
||||
`firefox-menu.test.ts`. The position fallback in `getRoots`, which neither
|
||||
fake reaches — both have known ids — is tested in `bookmarks.test.ts` with
|
||||
hand-built roots of unknown ids, including a Menu listed first. ⚠️ 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
|
||||
@@ -220,11 +242,57 @@ them is tested where it lives:
|
||||
from the real stylesheets, so a new component cannot opt out by forgetting.
|
||||
`motion.test.ts` first checks that it found more than 20 styled files to
|
||||
police.
|
||||
- **`styles/focus-ring.test.ts`** and **`styles/forced-colors.test.ts`**
|
||||
(v1.2.1) — the two `06 §5` rules 1.2.0 broke without a test noticing. The
|
||||
first fails on a component that insets a focus ring (`outline-offset` below
|
||||
zero) while filling a state with `--accent`, unless that ring is
|
||||
`--accent-fg`: the theme control's ring was accent on accent. The second
|
||||
holds the list of components that show state by a fill or a shadow and
|
||||
requires each to carry a `@media (forced-colors: active)` block naming a
|
||||
system colour. Both read the real `.svelte` files; the second's list is
|
||||
hand-maintained, like the contrast pairs.
|
||||
- **`edit/tree-keyboard.test.ts`**, **`edit/tree-keys.test.ts`** and
|
||||
**`stores/edit-session.test.ts`** — since v1.2.1 also Alt+↑/↓ (`05 §10`):
|
||||
`nudgeTarget` at both ends of a folder, stepping over an open neighbour's
|
||||
children, in a filtered list; the key reaching the command only with Alt
|
||||
alone; the move itself by Chrome's index rule, refused for a root, a managed
|
||||
node and while busy, one at a time, and returning the row's place among the
|
||||
siblings on screen — under a search too, where it passes hidden items.
|
||||
- **`stores/edit-live.test.ts`** (v1.2.1) — the wiring that used to sit
|
||||
untested in `EditTab`'s `onMount`, with `wxt/browser` mocked to seven
|
||||
hand-fired event emitters and a hand-fired frame: a frame's events land as
|
||||
one patch; a created node with no parent is ignored; nothing is patched
|
||||
during Chrome's own import, and its end re-reads once; a wholesale reorder
|
||||
re-reads; teardown detaches every listener and drops what was queued.
|
||||
SonarCloud's new-code gate is what asked for it — moving code out of a
|
||||
component makes it count.
|
||||
- **`components/focus-heading.test.ts`** — since v1.2.1 also
|
||||
`focusOwningTree`: a click on a row's control hands focus to the tree it
|
||||
sits in, and does nothing outside one.
|
||||
- **`links.test.ts`** — since v1.2.1 also `ACCESSIBILITY.md`: the file exists
|
||||
and the About link ends at it.
|
||||
- **`accessibility-statement.test.ts`** (v1.2.1) — the statement is a public
|
||||
promise nothing in the build reads, so its routes and its key table are
|
||||
pinned: the README links to it; the issue form exists and carries the
|
||||
`accessibility` label; the address is the same in the statement, the README
|
||||
and the issue chooser; every key `tree-keyboard.ts` switches on has a row;
|
||||
it states a goal and an untested list, and it is dated. It cannot tell
|
||||
whether a sentence is *true* — that is `§5`'s last item.
|
||||
- **`store-listing.test.ts`** (2026-11-18, after v1.3.0) — the Edge Add-ons
|
||||
copy in every `store/listing.*.md`: one complete description under the Edge
|
||||
heading, 250 to 5,000 characters (Partner Center's range), naming no browser
|
||||
but Edge (`08 §10`, `13 §9`). The same pattern has to find the browsers the
|
||||
Chrome Web Store copy lists, so it cannot pass by matching nothing.
|
||||
- **`tests/unit/scripts/`** — the repo's own gates, tested like code. New in
|
||||
v1.1.0: `guard.test.ts` (`08 §3`), `check-manifest.test.ts` (a correct build
|
||||
passes, one without the CSP fails) and `sanitize-formats.test.ts` (the
|
||||
browser JSON formats and the audit's HTML leaks, beside the older
|
||||
`sanitize-bookmarks.test.ts` — `09 §6`).
|
||||
`sanitize-bookmarks.test.ts` — `09 §6`). New in Phase 10:
|
||||
`check-licenses.test.ts` (SPDX expressions, the shipped list held stricter
|
||||
than the toolchain's, a missing or custom licence refused, the repository's
|
||||
own lockfile passing — `09 §3.2`) and `triage.test.ts` (every branch of the
|
||||
maintenance-mode decision, the feature form's dropdown wording, and no event
|
||||
text interpolated into the workflow's shell — `12 §2.6`).
|
||||
|
||||
## 5. Manual QA checklist (run before every store submission)
|
||||
|
||||
@@ -234,11 +302,12 @@ first — on `http://localhost:4318` with a fake `chrome`: neutral sample
|
||||
bookmarks, so no real profile ever appears, and in-memory storage. Every HTML
|
||||
page is served with the production CSP as a `<meta>`, so a violation shows in
|
||||
the console exactly as it would in the extension. Pages take
|
||||
`?theme=light|dark&lang=en|vi|ja&legal=0|1` and the route as the hash —
|
||||
`?theme=light|dark&lang=en|vi|ja|zh-CN|ro&legal=0|1` and the route as the hash —
|
||||
`manager.html?theme=dark&lang=vi#edit`; `legal=0` shows the gate. `--shoot`
|
||||
photographs every route × theme × language at 1280×800 with a local headless
|
||||
Chrome (`CHROME_PATH`, or the usual install paths), plus the store set
|
||||
(`13 §2`). Use it to sweep layout, translation overflow and both themes in
|
||||
photographs every route × theme × language at 1280×800 and the popup per theme
|
||||
× language at 360×420 with a local headless Chrome (`CHROME_PATH`, or the usual
|
||||
install paths), plus the README and store sets (`13 §2`). It does not shoot
|
||||
the gate (`legal=0`) — open that by hand in each language. Use it to sweep layout, translation overflow and both themes in
|
||||
minutes. It is **not** the pass below: each page has its own fake tree and
|
||||
storage, nothing written survives a reload, and the popup's tiles open nothing.
|
||||
|
||||
@@ -257,7 +326,8 @@ storage, nothing written survives a reload, and the popup's tiles open nothing.
|
||||
- [ ] **A Firefox JSON backup** (`bookmarks-YYYY-MM-DD.json`, or
|
||||
`tests/fixtures/firefox-bookmarks-2026-07-25.json`): format pill "Firefox
|
||||
backup"; in new-folder mode its roots arrive under localized names (check
|
||||
VI and JA too); `place:` smart bookmarks are skipped and counted.
|
||||
every non-English locale too); `place:` smart bookmarks are skipped and
|
||||
counted.
|
||||
- [ ] **Merge reuses folders:** import a file holding `Bookmarks bar/Dev/…`
|
||||
into a profile that already has `Dev` — no second `Dev`; the new items
|
||||
land at the end of the existing one, and the report says how many
|
||||
@@ -296,10 +366,49 @@ storage, nothing written survives a reload, and the popup's tiles open nothing.
|
||||
**and** Shift+F10 open **Move to…** with focus in its filter — type to
|
||||
narrow, Tab to a folder, Enter moves the item there; Esc closes it and
|
||||
focus returns to the tree. Ctrl+C copies the focused link. Every dialog
|
||||
opens with focus inside and returns it on close.
|
||||
- [ ] Language switch EN→VI→JA live-updates all tabs; dates/numbers
|
||||
localized; restart persists. Header switcher and the `#settings` row
|
||||
agree at all times (one state, two views).
|
||||
opens with focus inside and returns it on close. **Alt+↑ / Alt+↓** moves
|
||||
the focused row one place among its siblings and stops at either end;
|
||||
a permanent root does not move. After clicking a row button or a
|
||||
chevron with the mouse, the arrow keys still work.
|
||||
- [ ] **Focus is never lost:** Tab to the theme control — the ring is visible
|
||||
on the selected segment, in the header and in `#settings`, in both
|
||||
themes. After "Keep the first of each" and after a toolbar Sort A→Z,
|
||||
focus is on something visible. After "Open in Edit" from an import
|
||||
report it is on the page's main region, which shows no ring: the test is
|
||||
that the next Tab goes into the tab's content, not back to the header.
|
||||
- [ ] **Screen reader** (Narrator on Windows, or NVDA; VoiceOver on macOS):
|
||||
the tree announces each row's name, level and "n of m"; a dialog reads
|
||||
its title and body; the import's steps and outcome are spoken; Alt+↓
|
||||
speaks the row's new position, once. Record the reader and its version
|
||||
in `ACCESSIBILITY.md`'s "What has been tested".
|
||||
- [ ] **Contrast themes** (Windows: Settings → Accessibility → Contrast
|
||||
themes; or DevTools → Rendering → `forced-colors: active`): the tree's
|
||||
focused row, the drop line of a drag, the selected theme segment, the
|
||||
current tab, the selected import-mode and export-format cards and the
|
||||
progress bar's fill are all still distinguishable.
|
||||
- [ ] **Zoom and narrow windows:** at 200 % zoom and at a 400 px-wide window,
|
||||
every route still works without a horizontal scrollbar on the page, and
|
||||
no control is clipped or covered.
|
||||
- [ ] **`ACCESSIBILITY.md` is still true:** its key table matches `06 §5`, its
|
||||
known limitations still exist (and nothing new belongs there), and its
|
||||
"last reviewed" date is this release's.
|
||||
- [ ] Language switch EN→VI→JA→简体中文→Română live-updates all tabs;
|
||||
dates/numbers localized; restart persists. Header switcher and the
|
||||
`#settings` row agree at all times (one state, two views).
|
||||
- [ ] **Romanian plurals read right** at all three forms: import or select 1,
|
||||
then 2–19, then 20 or more items and read the counts — "1 marcaj",
|
||||
"5 marcaje", "20 de marcaje" — in the import stats, the Start button and
|
||||
the popup tiles.
|
||||
- [ ] **Chinese renders as Chinese**: with 简体中文 selected, `<html lang>` is
|
||||
`zh-CN` and characters such as 设置 / 导入 use Simplified Chinese glyphs,
|
||||
not Japanese ones. With the browser in Traditional Chinese (`zh-TW`)
|
||||
and the setting on Automatic, the UI is English, and so is the name in
|
||||
chrome://extensions (`07 §1`).
|
||||
- [ ] Romanian and Chinese in the popup, the tab bar, the status bar and
|
||||
every button: nothing truncated, wrapped mid-word or overlapping. The
|
||||
sweep photographs each route at 1280×800 and the popup at 360×420; this
|
||||
item covers what it cannot — narrower windows, open dialogs, the import
|
||||
preview, a running import and the Legal Gate.
|
||||
- [ ] Theme: system/light/dark. In **both** light and dark, read text on every
|
||||
surface — page, panels, inputs and the status bar, a selected row or
|
||||
card — and check the focus ring, control borders and disabled controls
|
||||
@@ -340,7 +449,7 @@ storage, nothing written survives a reload, and the popup's tiles open nothing.
|
||||
already open. The deep-link is refused by the same guard; confirm it
|
||||
behaves as `02 §5` describes rather than appearing to do nothing.
|
||||
- [ ] The import report states that imported bookmarks carry today's date — in
|
||||
EN, VI **and** JA.
|
||||
every locale.
|
||||
- [ ] chrome://extensions → no errors logged during the whole pass.
|
||||
- [ ] Edge (or Brave): smoke test install + import/export.
|
||||
|
||||
@@ -363,6 +472,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.
|
||||
@@ -373,15 +518,19 @@ failure mode that would hit every installed user at once.
|
||||
### Measured 2026-07-26 — Phase 5
|
||||
|
||||
A generated 100 000-node Netscape file (11.2 MB, 99 000 bookmarks in 1 000
|
||||
folders), timed **under jsdom 29**:
|
||||
folders), timed under jsdom — one column per jsdom major, never overwritten:
|
||||
|
||||
| Stage | Time |
|
||||
|---|---|
|
||||
| `detectFormat` | 0 ms |
|
||||
| `parseNetscapeHtml` | **2 869 ms** |
|
||||
| `buildUrlIndex` | 42 ms |
|
||||
| `diffAgainstBrowser` | 53 ms |
|
||||
| `serializeNetscapeHtml` | 72 ms |
|
||||
| Stage | jsdom 29 (2026-07-26) | jsdom 31 (2026-11-18) |
|
||||
|---|---|---|
|
||||
| `detectFormat` (now `sniffFormat`) | 0 ms | 0 ms |
|
||||
| `parseNetscapeHtml` | **2 869 ms** | **2 484 ms** (median of 3 runs, 2 416–2 733) |
|
||||
| `buildUrlIndex` | 42 ms | not re-run (pure JS) |
|
||||
| `diffAgainstBrowser` | 53 ms | not re-run (pure JS) |
|
||||
| `serializeNetscapeHtml` | 72 ms | not re-run (pure JS) |
|
||||
|
||||
The jsdom 31 column: Node 26.13, Windows 11, Intel i7-14700KF, the file from
|
||||
`gen-fixture.mjs --nodes 100000`. The jsdom 30 bump (2026-08-03) added no
|
||||
column, so there is no jsdom 30 figure.
|
||||
|
||||
⚠️ **This does not settle the 2 s budget either way.** Everything except the
|
||||
parse is pure JS and comfortably fast; the parse is dominated by `DOMParser`,
|
||||
|
||||
+159
-27
@@ -64,10 +64,14 @@ Three jobs. The two whose names branch protection requires (§5) are
|
||||
|
||||
- **`quality` — "Quality gates".** Local, because the ops reusable runs no
|
||||
quality gates at all (§1). In order: `lint`, `check` (svelte-check on the
|
||||
TS 6 API, then the TS 7 `tsc`), `knip`, `coverage` (`11 §1` thresholds),
|
||||
`guard` (`08 §3`), `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*
|
||||
TS 6 API — failing on warnings too since v1.2.1, which is what makes Svelte's
|
||||
`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`, 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
|
||||
@@ -114,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`; uploads both files as the artifact `release-<tag>` |
|
||||
| `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 the three files and `SHA256SUMS.txt` 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 by exact name against the `SHA256SUMS.txt` of the **published Release** (not the artifact's own copy), 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
|
||||
@@ -199,7 +204,7 @@ Added 2026-10-28, replacing SonarCloud's Automatic Analysis so the project gets
|
||||
- The price of that isolation: the scan job has no `node_modules`, so Sonar's
|
||||
type-aware rules resolve our own modules (through `.wxt/`) but not the
|
||||
dependencies' types.
|
||||
- The scan action is **pinned to a commit** (`v8.3.0`): it is the step that
|
||||
- The scan action is **pinned to a commit** (`v8.4.1`): it is the step that
|
||||
holds `SONAR_TOKEN`. Dependabot and fork PRs get no repository secrets, so the
|
||||
scan is skipped with a notice instead of failing.
|
||||
- Coverage: `vitest.config.ts` measures every `src/**/*.ts` module and reports
|
||||
@@ -218,23 +223,133 @@ Added 2026-10-28, replacing SonarCloud's Automatic Analysis so the project gets
|
||||
Snyk is connected only as a GitHub App (the `security/snyk (poli0981)` PR
|
||||
check); there is no `SNYK_TOKEN` and no Snyk step in any workflow.
|
||||
|
||||
## 3. Chrome Web Store publishing automation
|
||||
### 2.6 `triage.yml` — maintenance-mode triage
|
||||
|
||||
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**.
|
||||
Added 2026-11-18 with `/MAINTENANCE.md`. On `issues: [opened, labeled]` and
|
||||
`pull_request_target: [opened]` it runs `scripts/triage.mjs`, which reads the
|
||||
runner's event file and prints a decision, then carries it out with the `gh`
|
||||
CLI the runner ships — no third-party action ever holds its write token
|
||||
(`issues: write`, `pull-requests: write`, `contents: read`).
|
||||
|
||||
**Gating policy:**
|
||||
- **The decision is code with tests**, not shell: `decide()` is a pure
|
||||
function (`tests/unit/scripts/triage.test.ts`) — a feature-form issue
|
||||
answering "Something new" is labelled `maintenance-mode`, commented and
|
||||
closed *not planned*; the two in-policy answers get `needs-triage`; an
|
||||
`enhancement` label the owner adds by hand closes the issue the same way; an outside
|
||||
pull request titled `feat…` is closed. The owner's own issues, members,
|
||||
collaborators, bots and anything labelled `roadmap` are exempt. The test also
|
||||
pins the dropdown's wording against `feature_request.yml`, which is the only
|
||||
thing the decision parses.
|
||||
- ⚠️ **`pull_request_target` holds a write token for fork pull requests.** The
|
||||
checkout is the base branch — the event's default — and nothing from the
|
||||
pull request runs. Titles and bodies reach the script as the event file and
|
||||
are only compared with constants; the shell reads back an action from a fixed
|
||||
set, an integer, a label from a fixed list and a comment the script wrote, and
|
||||
validates the first two before using them.
|
||||
- **Idempotent.** The feature form fires `opened` and `labeled` for one new
|
||||
issue. `concurrency` runs them one at a time per number and the second
|
||||
re-reads the live labels and state before acting.
|
||||
- The labels must exist (`§5`); `gh … --add-label` fails on a missing one.
|
||||
- **Order: comment and close first, label last.** The label is what a re-run
|
||||
reads as "done", so it must not exist before the work it stands for.
|
||||
- **A hand label closes only when the owner adds it.** An `enhancement` issue
|
||||
with no answer to the form's question is the owner's one-touch close when
|
||||
the owner labelled it; from anyone else, or on `opened`, it goes to
|
||||
`needs-triage` instead of being closed on a guess.
|
||||
- `actions/checkout` and `actions/setup-node` are **pinned to commits here**,
|
||||
unlike the other workflows, because this one runs them with a write token
|
||||
on events anyone can trigger; and setup-node has no `cache:`.
|
||||
|
||||
### 2.7 `qodana.yml` — Qodana for JS
|
||||
|
||||
Added 2026-11-18. `qodana-js` (JetBrains' JavaScript/TypeScript linter,
|
||||
which needs the Ultimate licence `QODANA_TOKEN` carries) on push to `main`,
|
||||
pull requests, a weekly schedule and `workflow_dispatch`. Configuration is
|
||||
`qodana.yaml`: native mode (`withinDocker: false`), profile
|
||||
`qodana.recommended`, fixtures and generated output excluded.
|
||||
|
||||
- **Its own workflow, never required**, for the reason Sonar has one (§2.5).
|
||||
- **Two jobs.** `scan` has a read-only `GITHUB_TOKEN`, installs the dev
|
||||
dependencies (install scripts off) because `qodana-js` resolves types
|
||||
through `node_modules`, runs the action with PR comments and annotations
|
||||
off, and keeps the SARIF report as the `qodana-report` artifact.
|
||||
`publish` installs and runs nothing: it uploads that SARIF to code
|
||||
scanning (`category: qodana`), so the findings sit beside CodeQL's under
|
||||
Security and quality and on pull requests.
|
||||
- ⚠️ **The documented exception to §2.5.** Sonar's token never shares a
|
||||
runner with dependency code; Qodana's cannot avoid it, since the analysis
|
||||
needs the dependencies. The token only uploads reports to one Qodana
|
||||
Cloud project. If a dependency is ever found compromised, rotate it in
|
||||
qodana.cloud.
|
||||
- The action is **pinned to the commit of v2026.2.2**, not the vendor's
|
||||
moving `v2026.2` branch: it holds a token, and the newest tag was younger
|
||||
than the 7-day cooldown when it was added. Dependabot proposes updates.
|
||||
- `pr-mode: false`: the whole project every time. It is small, and a pull
|
||||
request that touches only docs would otherwise scan nothing.
|
||||
- Dependabot and fork pull requests have no secrets; the scan is skipped
|
||||
with a notice and `publish` does not run.
|
||||
- The report artifact is a zip inside the artifact, with absolute entry
|
||||
names; `publish` extracts the one entry `/qodana.sarif.json` by name. A
|
||||
glob for the file found nothing on the first run.
|
||||
- **First run (2026-11-18): 27 findings, none a defect.** Three regular
|
||||
expressions that could be simpler — fixed — and 24 that contradict a rule
|
||||
of this repository, switched off in `qodana.yaml` with the reason beside
|
||||
each: JSDoc completeness (doc comments here are prose, `10 §6`), bitwise
|
||||
operators in the PNG CRC-32 of `gen-icons.mjs`, and the deliberately
|
||||
doubled dark palette in `tokens.css`. A finding is fixed when it is a
|
||||
defect and switched off, with its reason, when it is a convention; it is
|
||||
never left standing to be ignored.
|
||||
|
||||
## 3. Store publishing automation (Chrome Web Store, Firefox Add-ons, Edge Add-ons)
|
||||
|
||||
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.
|
||||
|
||||
| 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, **and** restrict its deployment branches and tags to
|
||||
the tag pattern `v*`: an environment GitHub creates on first use has no
|
||||
rule at all, so any branch with a workflow that names it — a pushed branch,
|
||||
not only a release — could reach its secrets. The reviewer is the second
|
||||
lock, not the only one.
|
||||
- **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
|
||||
|
||||
@@ -244,9 +359,13 @@ release: bump package.json (semver) → CHANGELOG.md (Keep a Changelog) →
|
||||
git tag -s vX.Y.Z → push tag → release.yml
|
||||
```
|
||||
|
||||
- Patch = fixes/translations · Minor = features / any permission or
|
||||
privacy-tab change (per `09 §4`) · Major = breaking format/schema changes
|
||||
(BM JSON version bump).
|
||||
- Patch = fixes / translation fixes / **accessibility fixes** — including a
|
||||
keyboard or assistive-technology route to something the product could
|
||||
already do (v1.2.1's Alt+↑/↓ beside drag-to-reorder): it closes a barrier, it
|
||||
does not add a capability · Minor = features, **a new UI language**
|
||||
(it changes the listing and what the switcher offers — `07 §6`) / any
|
||||
permission or privacy-tab change (per `09 §4`) · Major = breaking
|
||||
format/schema changes (BM JSON version bump).
|
||||
|
||||
## 5. Repo settings checklist (one-time ⚠️)
|
||||
|
||||
@@ -276,20 +395,28 @@ 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,
|
||||
deployments limited to tags matching `v*`, 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, the `v*` tag rule and the 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).
|
||||
`DISCORD_PING_ROLE_ID` is optional and unset.
|
||||
- [x] `SONAR_TOKEN` — set 2026-10-28, used only by `sonarcloud.yml` (§2.5).
|
||||
- [x] `QODANA_TOKEN` — set by the owner 2026-11-18 (the Qodana Cloud project
|
||||
token, Ultimate), used only by `qodana.yml`'s `scan` job (§2.7).
|
||||
- [ ] ⚠️ SonarCloud **Automatic Analysis OFF** (SonarCloud → bookmarkmagic →
|
||||
Administration → Analysis Method). Required for §2.5; with it on, the CI
|
||||
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
|
||||
@@ -298,10 +425,15 @@ means "unknown", not "not done".
|
||||
posts. Unset means skipped; a reusable-workflow caller cannot use
|
||||
`continue-on-error` to absorb a failure (§2.3).
|
||||
- [x] Dependabot: npm weekly, grouped dev minor+patch, `github-actions` too —
|
||||
`.github/dependabot.yml`. Both ecosystems have a 7-day `cooldown`
|
||||
`.github/dependabot.yml` — and since v1.3.0 `tools/publish/` (the
|
||||
store-upload tool's own lockfile, §3) as a third ecosystem entry. Both ecosystems have a 7-day `cooldown`
|
||||
(matching `.npmrc` `min-release-age=7`, `09 §3.1`); WXT is excluded from
|
||||
the group so every WXT bump arrives alone and gets its built-manifest
|
||||
diff; majors of the TypeScript pair and `@types/node` are ignored.
|
||||
- [x] Labels the forms and `triage.yml` apply — `maintenance-mode`,
|
||||
`needs-triage`, `roadmap` (new with `MAINTENANCE.md`) and `parser`, `i18n`
|
||||
(named by the parser and translation forms since 2026-08-03, and missing
|
||||
until 2026-11-18: a form silently drops a label that does not exist).
|
||||
- [x] Issue templates: `.github/ISSUE_TEMPLATE/` — bug, parser report (requires
|
||||
a sanitized sample), translation, feature, plus a `config.yml` chooser.
|
||||
Landed 2026-08-03; `13 §6` had asserted they existed since before launch.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -49,6 +52,10 @@ privacy and distribution tabs are already filled; you are replacing the package.
|
||||
new `[X.Y.Z]` line must be added). Forgetting the link refs is the easy
|
||||
half to miss.
|
||||
|
||||
A third when the interface changed, or a new check was run:
|
||||
- `ACCESSIBILITY.md` — its "Last reviewed" line (date and version) and its
|
||||
"What has been tested" table, once `11 §5`'s last item has been done.
|
||||
|
||||
`wxt.config.ts` declares no `version` key — WXT derives it from
|
||||
`package.json` (`08 §5`). If it appears in your diff, something is wrong.
|
||||
3. PR → CI green → merge to `main`. **The bump must be on `main` before the
|
||||
@@ -58,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
|
||||
@@ -77,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)
|
||||
@@ -121,14 +143,15 @@ call (⚠️ `13 §1b`).
|
||||
|
||||
## 3. Store listing — EN (canonical)
|
||||
|
||||
**The listing copy lives in `store/listing.{en,vi,ja}.md`** — name, summary,
|
||||
**The listing copy lives in `store/listing.*.md`** — one file per locale
|
||||
(`en`, `vi`, `ja`, `zh_CN`, `ro`, named by Chrome's locale code) — name, summary,
|
||||
description, category and the privacy-policy URL, exactly as pasted into the
|
||||
dashboard. This section used to carry a second copy of the English text, and
|
||||
for v1.1.0 the two had already diverged (the store files gained the Chrome and
|
||||
Firefox imports, Merge reuse, the Replace confirmation and Sort A→Z; the copy
|
||||
here still described v1.0). A copy in two places is a copy that drifts.
|
||||
|
||||
When the description changes: edit all three `store/listing.*.md` in the same
|
||||
When the description changes: edit every `store/listing.*.md` in the same
|
||||
pull request as the feature, keep claims to what the CHANGELOG says shipped,
|
||||
and paste them into the dashboard as part of `§1b`. The summary must stay ≤132
|
||||
characters in every language.
|
||||
@@ -137,10 +160,20 @@ characters in every language.
|
||||
|
||||
**VI summary:** `Nhập, xuất & chỉnh sửa bookmark giữa các trình duyệt — offline, không tài khoản, không cloud. Dữ liệu không rời khỏi máy bạn.`
|
||||
**JA summary:** `ブラウザ間でブックマークをインポート・エクスポート・編集。オフライン、アカウント不要、クラウド不要。データは端末から出ません。`
|
||||
Full VI/JA descriptions: translate §3 keeping structure. The canonical copy
|
||||
lives in `store/listing.{en,vi,ja}.md` so listing text is version-controlled and
|
||||
reviewable — a listing edit made straight into the dashboard has no diff and no
|
||||
history.
|
||||
**ZH-CN summary:** `在浏览器之间导入、导出和编辑书签——离线运行,无需账户,无需云端。您的数据绝不会离开您的设备。`
|
||||
**RO summary:** `Import, export și editare de marcaje între browsere — offline, fără cont, fără cloud. Datele nu vă părăsesc dispozitivul.`
|
||||
Full descriptions: translate `store/listing.en.md` keeping its structure. The
|
||||
canonical copy lives in `store/listing.*.md` so listing text is
|
||||
version-controlled and reviewable — a listing edit made straight into the
|
||||
dashboard has no diff and no history.
|
||||
|
||||
**Adding a listing language** (v1.2.0 did two): in the dashboard, Store listing
|
||||
→ the language selector → add the language, then paste name, summary and
|
||||
description from its file. The "Languages" line in the public listing is not
|
||||
typed by anyone — CWS derives it from the package's `_locales/`, so it changes
|
||||
only when the new package is live. The `LANGUAGES` paragraph inside every
|
||||
description *is* typed, so a new locale means re-pasting the description of
|
||||
every existing language too.
|
||||
|
||||
⚠️ Those files were written from §3 **after** the listing went live, so they are
|
||||
a reconstruction, not a transcript. Owner: diff them against what the dashboard
|
||||
@@ -167,9 +200,18 @@ actually shows and correct the files, not the dashboard.
|
||||
requires a sanitized sample (`scripts/sanitize-bookmarks.mjs`) plus explicit
|
||||
consent to commit it as a GPL-3.0 fixture, because that is what turns a report
|
||||
into a regression test (`11 §2`, `15 §v1.0.x`).
|
||||
- Accessibility reports — their own form (`accessibility.yml`, label
|
||||
`accessibility`) and `accessibility@poli0981.dev` for people without a
|
||||
GitHub account. `ACCESSIBILITY.md` promises an acknowledgement within about
|
||||
a week and a patch for a blocking barrier (`15`, release trigger); a report
|
||||
that is not fixed at once goes into its Known limitations.
|
||||
- Discord servers (`#support` in the OSS server) — pin an FAQ post.
|
||||
⚠️ The invite URL is not recorded anywhere in the repo.
|
||||
- Review flow for feature requests: label → roadmap doc PR → milestone.
|
||||
- Feature requests, in maintenance mode (`/MAINTENANCE.md`): `triage.yml`
|
||||
closes a request for something new and labels the two in-policy answers
|
||||
`needs-triage` (`12 §2.6`). Read every `needs-triage` issue and every closed
|
||||
one; one that fits goes into `15` by pull request and gets the `roadmap`
|
||||
label, which the automation leaves alone. Ideas live in Discussions › Ideas.
|
||||
|
||||
The three recurring questions are already answered in prose and make the FAQ
|
||||
seed: favicons cannot be imported; imported bookmarks carry today's date (the
|
||||
@@ -191,6 +233,9 @@ to read carefully.
|
||||
already seen, so a rejected 1.0.1 comes back as 1.0.2 — not as a re-upload.
|
||||
3. Never delete or move the tag of a rejected version. It is a real, published
|
||||
GitHub Release and moving it invalidates its checksum. Leave it and move on.
|
||||
The one exception is a tag whose run failed **before** any Release existed —
|
||||
nothing was published, so fix the workflow on `main` and re-point the tag,
|
||||
as `v1.1.0` was (`15` decision log, 2026-10-29).
|
||||
4. Note the rejection and its resolution in `15`'s decision log — it is the only
|
||||
memory the project has of what the reviewers actually object to.
|
||||
|
||||
@@ -215,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
|
||||
@@ -228,3 +282,71 @@ 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.
|
||||
Checked 2026-11-18: the sources archive, unpacked into an empty folder,
|
||||
`npm ci --ignore-scripts`, `wxt prepare`, `npm run build:firefox`, rebuilt
|
||||
every one of the package's 19 files byte for byte.
|
||||
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 **Microsoft Edge Add-ons**
|
||||
section: a complete description of its own, pasted whole, that names no
|
||||
browser but Edge (Edge's policy 1.1.2 — Partner Center warns on any other
|
||||
browser's name, `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`). The About link
|
||||
matches the **CRX ID** (the `runtime.id` an install reports), not the
|
||||
Product ID.
|
||||
Done for 1.3.0: submitted 2026-11-18, live 2026-11-19 — ids and listing
|
||||
in `00 §9`.
|
||||
|
||||
**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.
|
||||
+15
-3
@@ -15,7 +15,7 @@ the user accepts, once, with links to canonical documents on GitHub.
|
||||
`<LegalGate>` overlay.
|
||||
- **Blocks:** `#import`, `#export`, `#edit`. **`#settings` and `#about` stay
|
||||
reachable** — `#about` so users can read the linked documents before
|
||||
accepting, `#settings` so a VI/JA user can switch language and theme first
|
||||
accepting, `#settings` so a non-English user can switch language and theme first
|
||||
(which is why `<LegalGate>` needs no language switcher of its own). Popup is
|
||||
never blocked (it only launches the Manager). Same list in `03 §4` and the
|
||||
`11 §5` QA checklist.
|
||||
@@ -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`
|
||||
|
||||
@@ -117,7 +127,9 @@ same value in `package.json#license` (`01 §5`).
|
||||
MIT-licensed pieces into the package: the Svelte runtime, `clsx` (which the
|
||||
Svelte runtime imports) and WXT's one-line `browser` shim (`wxt` +
|
||||
`@wxt-dev/browser`). `wxt.config.ts` fails the build when any other package
|
||||
would ship (`CREDITED_PACKAGES`). Through v1.0.x the About tab said "None"
|
||||
would ship (`CREDITED_PACKAGES` — since 2026-11-18 in
|
||||
`scripts/credited-packages.mjs`, the one list the build gate, the notices
|
||||
test and the licence gate of `09 §3.2` all read). Through v1.0.x the About tab said "None"
|
||||
and THIRD_PARTY_NOTICES said "no third-party code" — both wrong, corrected in
|
||||
v1.1.0. The notices ship as `THIRD_PARTY_NOTICES.txt` (from `src/public/`),
|
||||
which `check:manifest` requires in every build; `legal/THIRD_PARTY_NOTICES.md`
|
||||
|
||||
+152
-24
@@ -1,5 +1,10 @@
|
||||
# 15 — Roadmap
|
||||
|
||||
> **Maintenance mode since 2026-11-18.** What the project still takes, and how
|
||||
> requests outside that are handled, is [`/MAINTENANCE.md`](../MAINTENANCE.md) —
|
||||
> the policy, not restated here. Every feature that can still land is on this
|
||||
> page; anything not on it needs a decision-log row first.
|
||||
|
||||
## v1.0 — MVP (store launch) — ✔ SHIPPED
|
||||
|
||||
Everything in `00_PROJECT_OVERVIEW.md §6`. Definition of done was
|
||||
@@ -25,7 +30,22 @@ Build-phase breakdown lives in `CLAUDE.md` (single source for sequencing).
|
||||
| **v1.0.1 released** | ✔ 2026-08-03 | signed tag on `4654086`, GitHub Release with a `sha256sum -c`-verified zip; shipped manifest `1.0.1`, permissions unchanged. `announce` skipped (no `DISCORD_ANNOUNCE`), store publish skipped (no `CWS_AUTOPUBLISH`) |
|
||||
| **v1.0.1 submitted** | ✔ 2026-08-03 | uploaded to the CWS dashboard by hand (`13 §1b` step 6) |
|
||||
| **v1.0.1 published** | ✔ observed 2026-10-28 | listing shows version 1.0.1 (`Updated: August 3, 2026`), 5 users. ⚠️ Exact approval date not recorded; `13 §1b` step 10 (clean-profile install of the published build + upgrade re-check) has no recorded result |
|
||||
| 7 — v1.1.0 | in review 2026-10-29 | PR-A toolchain/CI/Sonar merged as #26; PR-B (import redesign, Chrome/Firefox formats, Merge reuse, Edit store + Sort A→Z + reorder, technical UI, diagnostics, docs/legal) on `release/1.1.0` |
|
||||
| 7 — v1.1.0 | ✔ 2026-10-29 | PR-A toolchain/CI/Sonar (#26); PR-B import redesign, Chrome/Firefox formats, Merge reuse, Edit store + Sort A→Z + reorder, technical UI, diagnostics, docs/legal (#27); the second review's fixes, which missed the #27 merge (#28); the release workflow's artifact fix (#29) |
|
||||
| **v1.1.0 released** | ✔ 2026-10-29 | signed tag on `9040f84`, GitHub Release with a `sha256sum -c`-verified zip (`104f020c…2dd6c94`, 94 091 bytes). Its manifest differs from 1.0.1's only in `version`, `minimum_chrome_version` (120 → 136) and the new CSP; permissions unchanged. The first tag run failed before publishing anything (`12 §2.3`); fixed in #29 and the tag moved while no Release existed. `announce` and store publish skipped (variables unset) |
|
||||
| **v1.1.0 submitted** | ✔ by 2026-11-06 | uploaded to the CWS dashboard by hand (`13 §1b` step 6) |
|
||||
| **v1.1.0 published** | ✔ observed 2026-11-06 | owner reported the review passed; the listing shows version 1.1.0 (`Updated: October 29, 2026`), 6 users, "3 languages". ⚠️ As for 1.0.1, `13 §1b` step 10 (clean-profile install of the published build + upgrade re-check) has no recorded result |
|
||||
| 8 — v1.2.0 languages | ✔ 2026-11-06 | Simplified Chinese (`zh-CN`) and Romanian (`ro`): one `LOCALES` list, a third plural form for Romanian, manifest `_locales`, store listings, intake form (`07`). One PR (#33); a code review and a native-style translation review before the bump, every finding fixed — the worst a Romanian CSV note saying the bookmarks-bar folder itself is lost on export |
|
||||
| **v1.2.0 released** | ✔ 2026-11-06 | signed tag on `e2f36bc`, GitHub Release with a `sha256sum -c`-verified zip (`0b4a268c…f8617b`, 105 284 bytes). Its manifest differs from 1.1.0's only in `version`; the package gains `_locales/zh_CN` and `_locales/ro`. `announce` and store publish skipped (variables unset) |
|
||||
| **v1.2.0 submitted** | ✔ by 2026-11-07 | uploaded to the CWS dashboard by hand, with the 简体中文 and Română listing languages (`13 §1b` step 6, `13 §4`) |
|
||||
| **v1.2.0 published** | ✔ observed 2026-11-10 | the listing shows version 1.2.0 (`Updated: November 7, 2026`), 3 users, "5 languages" — English, Tiếng Việt, română, 中文(中国), 日本語. ⚠️ As for 1.0.1 and 1.1.0, `13 §1b` step 10 (clean-profile install of the published build + upgrade re-check) has no recorded result |
|
||||
| 9 — v1.2.1 accessibility | ✔ 2026-11-10 | `ACCESSIBILITY.md` and its intake (issue form, PR checklist, `accessibility@`); the defects an audit of `src/` found that a keyboard-and-Narrator pass had not — an invisible focus ring on the theme control, no forced-colours support, drag-only reordering (Alt+↑/↓), focus dropped on `<body>` in three places, targets under 24 px; dependency sync after Dependabot #31/#32/#35/#36 (`06 §5`) |
|
||||
| **v1.2.1 released** | ✔ 2026-11-10 | PR #37, merged at the head that was reviewed. Signed tag on `d61318a`, GitHub Release with a `sha256sum -c`-verified zip (`4975b5df…ca13254`, 106 290 bytes). Its manifest differs from 1.2.0's only in `version`, and the file inventory is the same. SonarCloud's new-code gate failed the first push at 73.6 % — the live-sync wiring moved out of `EditTab` had no test — and passed once it had one. `announce` and store publish skipped (variables unset) |
|
||||
| **v1.2.1 submitted** | skipped — 1.3.0 went up in its place on 2026-11-18 | owner: the `11 §5` pass incl. the **1.2.0 → 1.2.1 upgrade over an existing profile**, a Windows contrast theme and a screen-reader pass over Alt+↑/↓, then the zip upload (`13 §1b`). 1.3.0 contains all of 1.2.1, so uploading 1.3.0 instead is the shorter path (`00 §10` item 20) |
|
||||
| 10 — maintenance mode, Firefox + Edge | ✔ 2026-11-18 | PR #42: Dependabot #39–#41 and their hand sync, the unfixable `picomatch` advisory recorded, a lockfile licence gate, `MAINTENANCE.md` with a feature form that classifies and `triage.yml` that closes out-of-policy requests, Qodana (`qodana-js`) beside SonarCloud — 27 first-run findings, none a defect. PR #44: Firefox and Edge Add-ons — Firefox's roots by GUID and the Bookmarks Menu as a fourth root, separators recognised by type, each browser's move index, Firefox's address limit, a second (Firefox) package with its own manifest gate, three store jobs in their own environments (CWS API v2), `BUILD.md` (the sources archive rebuilt the package byte for byte) |
|
||||
| **v1.3.0 released** | ✔ 2026-11-18 | PR #44, merged at the head that was reviewed (`42c78ec`; `main`'s tree identical). Signed tag on `80c7190`, GitHub Release with three packages and `SHA256SUMS.txt`, each `sha256sum -c`-verified after download — chrome `89c01451…fb921561` (107 946 bytes), firefox `45db6de9…8c09ef71` (108 100 bytes), sources `76799878…5fd6a4a4` (413 081 bytes). The Chrome manifest differs from 1.2.1's in `version` alone; the Firefox one adds `browser_specific_settings.gecko` and has no `minimum_chrome_version`. The store jobs and `announce` skipped (variables unset) |
|
||||
| **v1.3.0 submitted** | ✔ 2026-11-18 | by the owner, to all three stores: the Chrome Web Store (in place of 1.2.1), the first Firefox Add-ons version and the first Edge Add-ons submission. Partner Center flagged the first Edge description for naming another browser — the Edge copy now names none (PR #47). ⚠️ The `11 §5` passes (`00 §10` items 20–22) have no recorded result |
|
||||
| **v1.3.0 on Edge Add-ons** | ✔ live 2026-11-19 | approved on the first submission: listing `microsoftedge.microsoft.com/addons/detail/nchfchjnlihbifggooggpmmacighmdjg`, category Productivity, public, five languages. Policy 1.5.2 (a privacy policy that refers "primarily" to Edge, `08 §10`) did not block it. README install row and badge, and the About link's mapping for the next release, followed the same day (`00 §10` item 24) |
|
||||
| **v1.3.0 on the Chrome Web Store / Firefox Add-ons** | ⚠️ in review | — |
|
||||
|
||||
**Verified on real browsers 2026-07-25:** Chrome and Brave, unpacked build.
|
||||
Until that point every phase had been tested only against a hand-rolled
|
||||
@@ -101,8 +121,9 @@ There is exactly one path, and every step has an owner in the repo:
|
||||
5. `11 §2`'s inventory and `CHANGELOG.md [Unreleased]` are updated.
|
||||
|
||||
Translation fixes use `.github/ISSUE_TEMPLATE/translation.yml` and follow
|
||||
`07 §4`; the JA native review pass (`ja.ts`'s `TODO(review-ja)`) is the
|
||||
outstanding one, and it is user-facing now.
|
||||
`07 §4`. The native review passes are the outstanding ones, and all of them are
|
||||
user-facing: JA (`TODO(review-ja)`) since launch, and ZH-CN and RO
|
||||
(`TODO(review-zh)`, `TODO(review-ro)`) since v1.2.0.
|
||||
|
||||
### Release trigger
|
||||
|
||||
@@ -110,12 +131,16 @@ Cut a patch when **any** of these is true, rather than on a schedule:
|
||||
|
||||
- a parser-tolerance fix exists (a user is currently unable to import a file);
|
||||
- a data-integrity or dead-end defect is fixed;
|
||||
- an accessibility barrier is fixed — something a keyboard, screen-reader or
|
||||
contrast-theme user could not do or could not perceive (`ACCESSIBILITY.md`
|
||||
promises exactly this);
|
||||
- a batch of translation fixes has accumulated;
|
||||
- a dependency fix is needed for a real advisory.
|
||||
|
||||
Listing copy tweaks alone do **not** need a patch — the store listing is edited
|
||||
independently of the package (`13 §5`), though the copy should still go through
|
||||
`store/listing.{en,vi,ja}.md` first so it is reviewable.
|
||||
`store/listing.*.md` first so it is reviewable. A **new** UI language is not a
|
||||
patch: it is a minor (`12 §4`).
|
||||
|
||||
## v1.1 — quality of life
|
||||
|
||||
@@ -124,7 +149,7 @@ independently of the package (`13 §5`), though the copy should still go through
|
||||
| Automated CWS publishing | Flip `CWS_AUTOPUBLISH=true`; `wxt submit` in release workflow (`12 §3`). |
|
||||
| ✔ Import Chrome's internal `Bookmarks` JSON file | **Shipped in v1.1.0** (`04 §2a`). |
|
||||
| ✔ Import Firefox `.json` backup | **Shipped in v1.1.0** (`04 §2b`). The compressed automatic backups (`.jsonlz4`) are a separate item: a ~80-line pure-TS LZ4 block decoder, no dependency. |
|
||||
| "Export all formats as .zip" | First runtime dep decision: `fflate` (gated, `01 §4`; About/THIRD_PARTY updates per `14 §5`). |
|
||||
| "Export all formats as .zip" | First runtime dep decision: `fflate` (gated, `01 §4`; About/THIRD_PARTY updates per `14 §5`). **Not planned in maintenance mode** (2026-11-18): it would end "zero runtime dependencies" for a convenience. |
|
||||
| Aggressive-dedupe toggle | Optional `www.`/`utm_*` stripping in normalize (off by default). |
|
||||
| ✔ Sort folder A→Z action | **Shipped in v1.1.0** — a row action and a toolbar button, planned first and confirmed with a count (`03 §3`). |
|
||||
|
||||
@@ -138,12 +163,14 @@ independently of the package (`13 §5`), though the copy should still go through
|
||||
block decoder, no dependency. Also: capture a real Chrome HTML + `Bookmarks`
|
||||
pair to sit beside the hand-built `chrome-156-*` fixtures, and the JA native
|
||||
review.
|
||||
3. **v1.2 — the aggressive-dedupe toggle** (deferred this round), a
|
||||
3. **v1.4 — the aggressive-dedupe toggle** (deferred this round), a
|
||||
session-scoped import undo, Biome linting of `.svelte` files, and true
|
||||
virtualization of the edit tree if 500-row chunks prove too coarse.
|
||||
4. **v1.2+ — automated CWS publishing** once the owner creates the `CHROME_*`
|
||||
secrets; Edge Add-ons and Firefox AMO listings through WXT's multi-target
|
||||
build (each a separate go/no-go).
|
||||
virtualization of the edit tree if 500-row chunks prove too coarse. These
|
||||
were the v1.2 plan until 2026-11-06, when real installs in Chinese and
|
||||
Romanian made two languages the next minor instead (see below), and the
|
||||
v1.3 plan until 2026-11-18, when Firefox and Edge took that number.
|
||||
4. **v1.3 — Firefox (AMO) and Edge Add-ons, and automated publishing to all
|
||||
three stores** — **GO 2026-11-18** (decision log; the section below).
|
||||
|
||||
### Backlog carried from the v1.1.0 audit
|
||||
|
||||
@@ -151,23 +178,97 @@ Items found by the 2026-10-28 audit and not closed in v1.1.0, with their IDs:
|
||||
cL6 non-UTF-8 charsets in HTML imports; cL9 an extension allowlist on drop
|
||||
(content sniffing is the gate, so not planned); cL13 a newline inside a title
|
||||
for Chrome's line-based importer; sA8.1 Biome does not lint `.svelte`. From
|
||||
the post-implementation review: a keyboard way to place an item before or after
|
||||
a sibling (drag has it; "Move to…" only appends); true virtualization of the
|
||||
the post-implementation review: ~~a keyboard way to place an item before or
|
||||
after a sibling~~ (✔ v1.2.1, Alt+↑/↓); true virtualization of the
|
||||
edit tree (a 500-row window around the focus shipped — `05 §9`); a
|
||||
`require-trusted-types-for 'script'` CSP, which would make Chrome itself
|
||||
enforce the raw-HTML ban (the Svelte runtime already creates the policy;
|
||||
untested in extension pages); an input on the ops repo's reusable workflow to
|
||||
skip install scripts in the `Build + package` job (`12 §2`); whether a
|
||||
screen reader reads a focused row's button labels with its name (unconfirmed
|
||||
without one).
|
||||
screen reader reads a focused row's button labels with its name (the owner's
|
||||
Narrator pass on 1.2.0 found nothing blocking, 2026-11; the verbosity itself
|
||||
was not measured, and NVDA, JAWS and VoiceOver remain untested).
|
||||
|
||||
## v1.2 — resilience
|
||||
### Accessibility backlog (from the 2026-11-10 audit, not closed in v1.2.1)
|
||||
|
||||
- **Scheduled local snapshots**: periodic JSON backup. ⚠️ Requires `alarms`
|
||||
permission + a background service worker + `downloads` (or OPFS storage)
|
||||
→ permission-story change ⇒ minor version, docs 08/09 update, privacy tab
|
||||
re-review. Decide deliberately; OPFS-based silent snapshots may avoid
|
||||
`downloads`.
|
||||
`ACCESSIBILITY.md` lists the user-facing ones as known limitations; this is
|
||||
where they are scheduled. None blocks a task; each is a patch when it lands
|
||||
(`12 §4`).
|
||||
|
||||
- **Spoken results for the other edit commands.** Only Alt+↑/↓ announces what
|
||||
it did. A move, a sort, a rename, "keep first" and a new folder are silent
|
||||
on success, and so is a search (no result count, and "Nothing matches" is
|
||||
not a live region).
|
||||
- **Row semantics.** A folder and a bookmark differ only by an `aria-hidden`
|
||||
icon (an empty folder has no `aria-expanded`, so it sounds like a
|
||||
bookmark); the policy-managed lock and the child count are an icon and a
|
||||
bare number.
|
||||
- **A pointer route to reorder that is not a drag** (WCAG 2.5.7): drag and
|
||||
Alt+↑/↓ exist; a click-only one does not.
|
||||
- **The tree's keys are shown nowhere in the UI.** `ACCESSIBILITY.md` lists
|
||||
them and About links to it; an in-product key list would need a dialog.
|
||||
- **`role="toolbar"` without arrow keys** on the edit toolbar — the mismatch
|
||||
the previews' `role="tree"` was removed for.
|
||||
- **Hover-only hints** (`title` on elements that cannot take focus): the
|
||||
status bar's notes, the import target note, the busy reason on a disabled
|
||||
tab.
|
||||
- **Headings and a skip link.** Only the legal gate has an `<h1>`, `#edit` has
|
||||
no headings, and the header's five tab stops cannot be skipped. Landmarks
|
||||
exist.
|
||||
- **Settings descriptions** are not tied to their controls
|
||||
(`aria-describedby`), nor is the "dedupe is off under Replace" note.
|
||||
- **Info toasts leave after four seconds** with no pause on hover or focus.
|
||||
- **Font sizes are in px**, so Chrome's font-size setting does not scale the
|
||||
UI (zoom does).
|
||||
- **Ctrl/⌘+F always goes to the search box** on `#edit`, even with a dialog
|
||||
open.
|
||||
- **No automated check of the rendered markup** — no axe pass, no role
|
||||
queries; the harness photographs but does not inspect. (A process gap, so
|
||||
not in the statement.) The forced-colours and focus-ring tests are
|
||||
file-level text checks: they cannot see specificity, which is how three of
|
||||
the 1.2.1 review's findings got past them.
|
||||
- **Disabled without a visual cue.** The section tabs during a write, and a
|
||||
row's buttons during a bulk command, change only the cursor.
|
||||
- **Keys that cannot act are silent** — Alt+↑ at the top of a folder, Delete on
|
||||
a root. And on a Mac laptop the delete key is Backspace, which the tree
|
||||
does not handle; on ChromeOS Alt+↑/↓ may arrive as Page Up/Down.
|
||||
- **Truncated titles** have no way to be read in full in the tree.
|
||||
- **A held Alt+↑/↓ can flicker.** Moves run one at a time, but the live event
|
||||
of one can flush a frame after the next press's optimistic patch and roll
|
||||
the row back for that frame (`05 §10`). It converges; the fix is to drain
|
||||
the batcher before planning.
|
||||
|
||||
## v1.2 — languages (planned 2026-11-06)
|
||||
|
||||
The CWS dashboard showed installs and active users in Chinese and Romanian
|
||||
browsers, which the three shipped languages did not cover. v1.2.0 adds:
|
||||
|
||||
| Locale | Notes |
|
||||
|---|---|
|
||||
| **简体中文 (`zh-CN`)** | Simplified only. A Traditional Chinese browser (`zh-TW`/`HK`/`MO`) on "Automatic" gets English, matching Chrome's own manifest fallback (`07 §1–2`). A `zh-TW` dictionary is a separate, later decision; the `zh-CN` id leaves room for it. |
|
||||
| **Română (`ro`)** | The first locale with **three** plural forms (`07 §5`), so the plural machinery grows a `few` form first. Comma-below `ș ț` enforced by a test. |
|
||||
|
||||
Both are best-effort translations awaiting a native pass (`07 §4`, `00 §10`).
|
||||
The other candidates (Traditional Chinese, Russian, Polish, Arabic…) wait for
|
||||
the same dashboard evidence. Russian, Polish and Arabic also need plural forms
|
||||
beyond `few`; the guard test in `dictionaries.test.ts` fails first if one is
|
||||
attempted.
|
||||
|
||||
## v1.3 — Firefox and Edge (GO 2026-11-18)
|
||||
|
||||
The last "reach" item, taken out of the v2.0 table below on the owner's
|
||||
decision the day maintenance mode began (decision log). The roadmap's own
|
||||
wording was right: it is not "the same zip" for Firefox — the bookmark roots,
|
||||
separators and the move index all differ — so it is a minor, built docs-first.
|
||||
Edge takes the Chromium package unchanged. Scope and status live in the
|
||||
decision log and `CLAUDE.md` Phase 10.
|
||||
|
||||
## v1.4 — resilience (was v1.3 until 2026-11-18, v1.2 until 2026-11-06)
|
||||
|
||||
- ~~**Scheduled local snapshots**~~ — **not planned in maintenance mode**
|
||||
(2026-11-18). It needs the `alarms` permission and a background service
|
||||
worker, and `/MAINTENANCE.md` puts anything that needs a new permission out
|
||||
of scope, as `CLAUDE.md` hard rule 1 always did.
|
||||
- Import "undo" (session-scoped): remember created ids → one-click revert.
|
||||
- Virtualized tree rendering if >100k real-world demand appears.
|
||||
|
||||
@@ -175,11 +276,11 @@ without one).
|
||||
|
||||
| Candidate | Consideration |
|
||||
|---|---|
|
||||
| Firefox Add-ons (AMO) release | WXT multi-target already builds it (`wxt -b firefox`); needs AMO listing, `browser_specific_settings.gecko.id`, separate signing flow. |
|
||||
| Edge Add-ons store | Same zip usually passes; Partner Center account needed. |
|
||||
| ~~Firefox Add-ons (AMO) release~~ | **GO 2026-11-18 → v1.3** (above). |
|
||||
| ~~Edge Add-ons store~~ | **GO 2026-11-18 → v1.3** (above). |
|
||||
| Dead-link checker | Needs `host_permissions: <all_urls>` → destroys the minimal-permission story. If ever done: **separate companion extension**, not this one. |
|
||||
| Duplicate auto-merge assistant | Merge metadata (keep oldest addDate) + folder-aware suggestions. |
|
||||
| Bookmarklet/notes fields | Only if a lossless place exists in Chrome's model (likely not — avoid schema lies). |
|
||||
| Duplicate auto-merge assistant | Merge metadata (keep oldest addDate) + folder-aware suggestions. **Not planned in maintenance mode.** |
|
||||
| Bookmarklet/notes fields | Only if a lossless place exists in Chrome's model (likely not — avoid schema lies). **Not planned in maintenance mode.** |
|
||||
|
||||
## Explicit "never" list (re-affirm before any pivot)
|
||||
|
||||
@@ -188,6 +289,9 @@ without one).
|
||||
- Analytics/telemetry of any kind.
|
||||
- Ads, sponsored bookmarks, affiliate link rewriting.
|
||||
- Collecting or transmitting bookmark content.
|
||||
- Any permission beyond `bookmarks` and `storage` (`CLAUDE.md` hard rule 1),
|
||||
which is what keeps the dead-link checker a separate extension and the
|
||||
scheduled snapshots off the roadmap.
|
||||
|
||||
## Decision log
|
||||
|
||||
@@ -296,3 +400,27 @@ without one).
|
||||
| 2026-10-29 | **The extension-page CSP gains `default-src 'none'`** — reversing the earlier "deliberately no default-src". Every directive the pages use is listed, so it changes nothing for them, and it closes what was left open (manifests, prefetch). WebRTC, which no CSP directive Chrome enforces governs, stays covered by the bundle and source scans | 08 §3 |
|
||||
| 2026-10-29 | **Diagnostics allowlist enforced by types**: every `DiagEvent` string field is a union of fixed values, error names pass through an allowlist (`'other'` otherwise), and `@ts-expect-error` tests keep a title from compiling | 09 §7 |
|
||||
| 2026-10-29 | **SonarCloud runs in two jobs**: coverage with no secret, then a scan that installs nothing and gets the lcov report as an artifact — a job's secrets are readable by every step on its runner | 12 §2.5 |
|
||||
| 2026-10-29 | **The first `v1.1.0` tag run failed before publishing, and the tag was moved.** `upload-artifact` skips hidden paths, so the build job's `.output/*` matched nothing. Fixed in #29; since no Release or asset existed yet, `v1.1.0` was re-pointed at the fixed `main` (`9040f84`) rather than burning a version. `13 §7`'s rule — never move the tag of a published Release — is unchanged | 12 §2.3, 13 §7 |
|
||||
| 2026-11-06 | **v1.1.0 is live; v1.2.0 is two languages, not the dedupe toggle.** The dashboard showed real installs in Chinese and Romanian browsers. A new UI language is a **minor** release — it changes what the switcher offers and what the listing says — while translation *fixes* stay patches (`12 §4`). The old v1.2 items move to v1.3 unchanged | 12 §4, 15 |
|
||||
| 2026-11-06 | **Simplified Chinese only, and a Traditional Chinese browser on "Automatic" gets English.** Chrome's manifest fallback goes `zh_TW → zh → en`, never to `zh_CN`, so mapping Traditional to Simplified in the UI would make the extension's name and its UI disagree. A user can still pick 简体中文 by hand | 07 §1–2 |
|
||||
| 2026-11-06 | **The locale id is `zh-CN`, not `zh`.** It is a persisted setting value: a bare `zh` would have to be migrated the day a `zh-TW` dictionary exists. The id doubles as the `<html lang>` value, which is what makes Chrome draw Simplified glyphs rather than Japanese ones | 07 §2 |
|
||||
| 2026-11-06 | **One `LOCALES` list.** Every table keyed by locale is a `Record<Locale, …>` and every allow-list spreads `LOCALES`, so a new locale missing anywhere is a compile error. Before, adding a language meant finding six hand-written `['en', 'vi', 'ja']` lists, and missing one degraded silently to English | 07 §2, §6 |
|
||||
| 2026-11-06 | **A third plural form, only where a locale needs it.** `Dict` widens each plural branch to `{ one, other, few? }`. Whether a locale carries `few` is decided by its own `Intl.PluralRules` categories and enforced at runtime, so en/vi/ja/zh write no dead `few`. A guard fails on any shipped locale needing `two`/`many`/`zero` before a grammar the helper cannot select can ship | 07 §5 |
|
||||
| 2026-11-06 | **Romanian uses comma-below `ș ț`, enforced by a test.** The cedilla forms `ş ţ` look alike and are different letters to search and sort — the classic Romanian localization defect | 07 §4 |
|
||||
| 2026-11-06 | **ZH-CN and RO ship best-effort, like JA.** Written from Chrome's own terminology in each language and marked `TODO(review-zh)` / `TODO(review-ro)`; the translation form lists both. Waiting for native reviewers would have left users who already installed the extension on English indefinitely | 07 §4, 00 §10 |
|
||||
| 2026-11-10 | **v1.2.0 is live; v1.2.1 is accessibility.** The owner's keyboard-only and Narrator pass over 1.2.0 found nothing, and an audit of `src/` then found five things such a pass cannot see or did not reach: a focus ring drawn in the colour of the fill under it, no forced-colours support, reordering that only a drag could do, focus dropped on `<body>` in three places, and targets under 24 px. A pass by one person with one screen reader is evidence, not a verdict — which is also why the statement says what was tested and what was not | 06 §5, 11 §5 |
|
||||
| 2026-11-10 | **An accessibility statement, at the repository root.** `ACCESSIBILITY.md`, beside `SECURITY.md` and `CONTRIBUTING.md`, linked from the README and from About. It states **WCAG 2.2 AA as the goal, not as a conformance claim**: nobody has audited the product, and a claim would be the kind of sentence `14` exists to keep out of the project. Known limitations are listed in it rather than left in this backlog, because a user deciding whether the product will work for them reads that file, not this one | 06 §5, 15 |
|
||||
| 2026-11-10 | **`accessibility@poli0981.dev` for barrier reports**, the eleventh per-purpose alias (created and tested by the owner). It appears in `ACCESSIBILITY.md`, the README's contact table and the issue chooser — never in `src/`, by the 2026-08-03 rule, which the About link respects by pointing at the file instead. Reports have their own issue form and an `accessibility` label, because a barrier report needs the assistive technology and its version, which the bug form does not ask for | 06 §3.5, 13 §6 |
|
||||
| 2026-11-10 | **Svelte's accessibility warnings fail the build.** `svelte-check --fail-on-warnings`: the `a11y_*` checks are compiler warnings, a warning never failed anything, and Biome does not read `.svelte` — so nothing linted the markup. The suite was at zero warnings, which is the only cheap moment to turn it on | 10 §3, 12 §2 |
|
||||
| 2026-11-10 | **The review of 1.2.1 found what the tests could not, again.** Twelve code findings and seventeen in the docs — among them a tree that jumped to the top on the first click of a row button (the fix for one focus defect causing another), three forced-colours rules that lost to more specific ones, and an accessibility statement that promised more than the code did: "every clickable target is 24 px", "nothing times out", "focus is always a 2-pixel ring". The statement was rewritten to what the source supports, and its untested list grew. A statement written by the author of the code needs the same adversarial read as the code | 11 §5 |
|
||||
| 2026-11-10 | **Alt+↑ / Alt+↓ reorders, and it is a patch.** It reuses `planDrop` and `moveTo`, so a keyboard move and a drag cannot disagree about what is legal, and there is no second write path to test. One place at a time, among the siblings on screen, like a drag. It ships in a patch because it closes a barrier to something the product already did rather than adding a capability; `12 §4` now says so. Rejected: "Move up / Move down" row buttons (two more on a row that already hides up to five), and a position field in "Move to…" (a new dialog flow for the same result) — though a click-only route is still owed (WCAG 2.5.7, backlog) | 05 §10, 12 §4 |
|
||||
| 2026-11-10 | **Focus after a route change goes to `<main>`, not to the tree.** "Open in Edit" removes the button that was clicked. Focusing the tree when `#edit` mounts would also have fired on every first load, highlighting a row nobody chose and changing every screenshot; a route change with focus lost is the narrower condition and covers every tab | 06 §5 |
|
||||
| 2026-11-10 | **Dependabot's bumps are not the whole bump.** #31 and #36 moved Biome twice and left `biome.json`'s `$schema` behind both times, and left `vitest`'s declared range a minor behind the coverage plugin's, which must match it (the lockfile had both at 5.1.0); `01 §2` drifted with them. The sync is a human step after each Dependabot merge, and WXT still gets the built-manifest diff — 0.21.5 produced a manifest byte-identical to the 1.2.0 release asset | 01 §2, §6 |
|
||||
| 2026-11-18 | **Maintenance mode, as a written policy.** The project had been "in maintenance" since launch in the loose sense; the owner made it explicit: dependency updates on a schedule, high/critical advisories fixed as soon as a fix exists, major platform upgrades, bug/UI/UX/accessibility/translation fixes, and features only when on this roadmap or genuinely needed. **`/MAINTENANCE.md` is the policy and this file does not restate it** — the lesson of `12 §2`: a copy in two places drifts. The roadmap below stays valid; it is now the whole list of features that can still land | `MAINTENANCE.md` |
|
||||
| 2026-11-18 | **Out-of-policy requests are closed by a workflow, not by hand.** The feature form asks one required question (on the roadmap / needed for a fix / something new); `scripts/triage.mjs` decides, as a pure and unit-tested function, and `triage.yml` acts with `gh` only — labelled `maintenance-mode` and closed *not planned*, or labelled `needs-triage`. `pull_request_target` checks out the base branch only and never interpolates a title or body into a shell line. Outside `feat…` pull requests are closed the same way; the owner, members, collaborators, bots and anything labelled `roadmap` are exempt. Rejected: removing the feature form (requests would arrive through the bug form, where nothing can detect them) and closing every request unread (the two in-policy answers deserve a human) | `12 §2.6`, `MAINTENANCE.md` |
|
||||
| 2026-11-18 | **A high advisory with no fix is recorded, not worked around.** `npm audit` reports 14 high findings, all `picomatch` GHSA-fc5q-39xc-vjpf, every version affected, nothing to upgrade to. It is the toolchain's glob engine, matching patterns this repository writes, and never ships. The `deepmerge` row left: GitHub withdrew that advisory on 2026-11-16 | `09 §3.1` |
|
||||
| 2026-11-18 | **A licence gate over the whole lockfile** (`scripts/check-licenses.mjs`): shipped packages must be permissive and GPL-3.0-compatible, tooling may also be MPL-2.0 and a few other non-copyleft licences; anything else fails until a person adds it on purpose. One shared `CREDITED_PACKAGES` list (`scripts/credited-packages.mjs`) now feeds the build gate, the notices test and this gate. `dependency-review-action` was considered and not used: PR-only, ClearlyDefined rather than the lockfile, runtime scope by default, not runnable locally. `legal/THIRD_PARTY_NOTICES.md` had called the tooling all MIT/Apache-2.0/ISC; corrected, **not a `LEGAL_VERSION` bump** — it describes tooling that never ships | `09 §3.2`, `14 §3.1` |
|
||||
| 2026-11-18 | **Dependabot #39–#41 merged and synced by hand**, as the 2026-11-10 row requires: `biome.json`'s `$schema` to 2.6.6, `01 §2`, the scan action's pin in `12 §2.5`, and for the jsdom 31 major a new column in `11 §6` (2 484 ms median) beside the jsdom 29 figure | `01 §2`, `11 §6` |
|
||||
| 2026-11-18 | **GO for Firefox (AMO) and Microsoft Edge Add-ons, as v1.3.** The owner's decision, recorded here before any code because the maintenance announcement names it. Settled with the owner: gecko id `bookmarkmagic@poli0981.dev` — permanent after the first AMO upload, an id and not a mailbox, shown nowhere in the UI; desktop only, because Firefox for Android has no `bookmarks` API; MV3 everywhere (WXT defaults Firefox to MV2); and Firefox separators shown, protected and warned about rather than written into any file format. An audit found why it is a minor and not a CI change: Firefox's roots are GUIDs with a fourth (Bookmarks Menu) root, so `getRoots`' position fallback maps the Menu to the toolbar; separators come back as `data:` bookmarks; and a same-folder `move` counts its index after removal | `00 §7`, `15 §v1.3` |
|
||||
| 2026-11-18 | **Qodana beside SonarCloud**, at the owner's request (Ultimate licence, `QODANA_TOKEN`). Its own, never-required workflow, in two jobs: `scan` installs the dev dependencies — `qodana-js` needs them — with a read-only `GITHUB_TOKEN`; `publish` installs nothing and uploads the SARIF to code scanning, instead of the PR comments and annotations the vendor's snippet asks `contents: write` for. Sharing a runner with dependency code is a recorded exception to the Sonar rule, accepted because the token can only upload reports | `12 §2.7` |
|
||||
| 2026-11-18 | **The roadmap pruned to what maintenance mode allows.** Scheduled snapshots need `alarms` and are off the roadmap; the permission rule joins the never list, where the feature form had already put it. The `fflate` zip export (a runtime dependency), the duplicate auto-merge assistant and bookmarklet notes are not planned. The old v1.3 "resilience" becomes v1.4 | `15` |
|
||||
+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
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# Third-Party Notices — BookmarkMagic
|
||||
|
||||
Last updated: 2026-10-29
|
||||
Last updated: 2026-11-18
|
||||
|
||||
**No runtime dependencies are installed** — `package.json` has an empty
|
||||
`dependencies` list (`docs/01 §4`). A few small MIT-licensed pieces are,
|
||||
@@ -14,14 +14,18 @@ notices travel with it in `THIRD_PARTY_NOTICES.txt` at the root of the package:
|
||||
| [wxt](https://github.com/wxt-dev/wxt) + [@wxt-dev/browser](https://github.com/wxt-dev/wxt) | The one-line `browser` export: `globalThis.browser` when it exists, else `globalThis.chrome` | MIT |
|
||||
|
||||
The build enforces this list: `wxt.config.ts` fails the build when code from any
|
||||
other npm package would ship (`CREDITED_PACKAGES`), and
|
||||
`tests/unit/third-party.test.ts` checks that this file and the shipped `.txt`
|
||||
name every package on it. None of these contains network code; the
|
||||
other npm package would ship (`CREDITED_PACKAGES`, kept in
|
||||
`scripts/credited-packages.mjs`), `tests/unit/third-party.test.ts` checks that
|
||||
this file and the shipped `.txt` name every package on it, and
|
||||
`npm run check:licenses` holds each of them to a permissive licence. None of these contains network code; the
|
||||
extension's Content-Security-Policy forbids it anyway (`docs/08 §3`).
|
||||
|
||||
Build-time tooling (WXT's CLI, Vite, TypeScript, Biome, Knip, Vitest,
|
||||
svelte-check) is not distributed with the extension and is not listed here.
|
||||
All of it is MIT/Apache-2.0/ISC licensed and compatible with GPL-3.0-or-later.
|
||||
svelte-check and what they depend on) is not distributed with the extension and
|
||||
is not listed here. Its licences are checked on every build by
|
||||
`npm run check:licenses`: permissive (MIT, Apache-2.0, ISC, BSD, 0BSD, MIT-0,
|
||||
BlueOak, CC0) or, for one CSS tool under Vite (`lightningcss`), the
|
||||
file-level copyleft MPL-2.0 — none of which reaches the extension.
|
||||
|
||||
Licensing questions: **copyright@poli0981.dev**.
|
||||
|
||||
|
||||
Generated
+305
-472
File diff suppressed because it is too large.
Load diff
+16
-13
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"name": "bookmarkmagic",
|
||||
"private": true,
|
||||
"version": "1.1.0",
|
||||
"version": "1.3.0",
|
||||
"type": "module",
|
||||
"description": "Import, export & edit bookmarks between browsers — offline, no account, no cloud.",
|
||||
"license": "GPL-3.0-or-later",
|
||||
@@ -22,33 +22,36 @@
|
||||
"dev": "wxt",
|
||||
"dev:firefox": "wxt -b firefox",
|
||||
"build": "wxt build",
|
||||
"build:firefox": "wxt build -b firefox",
|
||||
"zip": "wxt zip",
|
||||
"check": "svelte-check --tsconfig ./tsconfig.json && tsc --noEmit && tsc -p tsconfig.scripts.json",
|
||||
"zip:firefox": "wxt zip -b firefox",
|
||||
"check": "svelte-check --tsconfig ./tsconfig.json --fail-on-warnings && tsc --noEmit && tsc -p tsconfig.scripts.json",
|
||||
"lint": "biome check .",
|
||||
"lint:fix": "biome check --write .",
|
||||
"knip": "knip",
|
||||
"guard": "node scripts/guard.mjs",
|
||||
"check:manifest": "node scripts/check-manifest.mjs",
|
||||
"check:licenses": "node scripts/check-licenses.mjs",
|
||||
"icons": "node scripts/gen-icons.mjs",
|
||||
"test": "vitest run",
|
||||
"test:watch": "vitest",
|
||||
"coverage": "vitest run --coverage",
|
||||
"verify": "npm run lint && npm run check && npm run knip && npm run guard && npm run test",
|
||||
"verify:full": "npm run verify && npm run coverage && npm run build && npm run check:manifest"
|
||||
"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 && npm run build:firefox && npm run check:manifest -- --browser firefox"
|
||||
},
|
||||
"devDependencies": {
|
||||
"@biomejs/biome": "2.6.2",
|
||||
"@biomejs/biome": "2.6.6",
|
||||
"@sveltejs/vite-plugin-svelte": "^7.3.1",
|
||||
"@types/node": "^26.6.5",
|
||||
"@types/node": "^26.6.6",
|
||||
"@typescript/native": "npm:typescript@~7.0.2",
|
||||
"@vitest/coverage-v8": "^5.0.5",
|
||||
"@vitest/coverage-v8": "^5.1.0",
|
||||
"@wxt-dev/module-svelte": "^2.0.5",
|
||||
"jsdom": "^30.1.3",
|
||||
"knip": "^6.42.1",
|
||||
"svelte": "^5.57.2",
|
||||
"svelte-check": "^4.7.7",
|
||||
"jsdom": "^31.0.0",
|
||||
"knip": "^6.45.1",
|
||||
"svelte": "^5.57.3",
|
||||
"svelte-check": "^4.7.8",
|
||||
"typescript": "npm:@typescript/typescript6@~6.0.2",
|
||||
"vitest": "^5.0.5",
|
||||
"wxt": "^0.21.4"
|
||||
"vitest": "^5.1.0",
|
||||
"wxt": "^0.21.5"
|
||||
}
|
||||
}
|
||||
+49
@@ -0,0 +1,49 @@
|
||||
# Qodana — docs/12 §2.7. Read by .github/workflows/qodana.yml.
|
||||
#
|
||||
# qodana-js is JetBrains' JavaScript/TypeScript linter; it needs the Ultimate
|
||||
# licence that QODANA_TOKEN carries. Native mode (no Docker image): the
|
||||
# workflow installs node_modules on the runner first, with install scripts
|
||||
# off, and the analysis reads them from there.
|
||||
version: "1.0"
|
||||
linter: qodana-js
|
||||
withinDocker: false
|
||||
|
||||
profile:
|
||||
name: qodana.recommended
|
||||
|
||||
# What is not code, or not ours: byte-exact browser samples (malformed on
|
||||
# purpose), build and coverage output, screenshots, store copy, prose.
|
||||
exclude:
|
||||
- name: All
|
||||
paths:
|
||||
- tests/fixtures
|
||||
- .output
|
||||
- .wxt
|
||||
- coverage
|
||||
- capture
|
||||
- store
|
||||
- docs
|
||||
- legal
|
||||
# Inspections switched off after the first run (2026-11-18), each because it
|
||||
# contradicts a rule of this repository rather than finding a defect:
|
||||
#
|
||||
# Doc comments here are prose (docs/10 §6). `@param` tags appear only where a
|
||||
# `// @ts-check` script needs a type, so "every parameter described" is not
|
||||
# the convention — 22 of the first run's 27 findings.
|
||||
- name: JSCommentMatchesSignature
|
||||
# A CRC-32 table for PNG chunks is bitwise by definition.
|
||||
- name: JSBitwiseOperatorUsage
|
||||
paths:
|
||||
- scripts/gen-icons.mjs
|
||||
# The dark palette is declared twice on purpose: once under the
|
||||
# prefers-color-scheme query, once for the explicit theme switch (docs/06 §1).
|
||||
- name: DuplicatedCode
|
||||
paths:
|
||||
- src/styles/tokens.css
|
||||
|
||||
# Clean since 2026-11-18 (docs/12 §2.7): any new finding turns this workflow
|
||||
# red, so it is fixed or switched off here with its reason — never left
|
||||
# standing to be ignored. Not a required check.
|
||||
failureConditions:
|
||||
severityThresholds:
|
||||
any: 0
|
||||
@@ -0,0 +1,17 @@
|
||||
/**
|
||||
* Types for scripts/check-licenses.mjs, so its tests can call it directly.
|
||||
* The script itself is plain JavaScript checked with `// @ts-check`.
|
||||
*/
|
||||
export const SHIPPED_LICENSES: readonly string[];
|
||||
export const TOOLCHAIN_LICENSES: readonly string[];
|
||||
export const EXCEPTIONS: Readonly<Record<string, string>>;
|
||||
export function satisfies(expression: string, allowed: readonly string[]): boolean;
|
||||
export function packageNameOf(key: string): string;
|
||||
export function checkLockfile(
|
||||
lock: unknown,
|
||||
options?: { shipsCode?: boolean },
|
||||
): {
|
||||
problems: string[];
|
||||
checked: number;
|
||||
counts: Map<string, number>;
|
||||
};
|
||||
@@ -0,0 +1,248 @@
|
||||
// @ts-check
|
||||
/**
|
||||
* Licence gate — docs/09 §3.2, docs/12 §2.1.
|
||||
*
|
||||
* Reads `package-lock.json` (lockfile v3), where npm records each installed
|
||||
* package's `license` field, and checks every entry against one of two lists:
|
||||
*
|
||||
* - SHIPPED — the packages the build compiles into the extension
|
||||
* (`CREDITED_PACKAGES`, scripts/credited-packages.mjs). Their code travels
|
||||
* inside a GPL-3.0-or-later extension, so only permissive licences that
|
||||
* combine with it cleanly are accepted.
|
||||
* - TOOLCHAIN — everything else. The extension has no runtime dependencies,
|
||||
* so all of these are build and test tools that never ship. Permissive
|
||||
* licences and weak, file-level copyleft (MPL-2.0) are fine; network
|
||||
* copyleft (AGPL), source-available terms (SSPL, BUSL, Commons Clause),
|
||||
* a missing or custom licence (`UNLICENSED`, `SEE LICENSE IN …`) are not.
|
||||
*
|
||||
* Anything outside the lists fails the run until a person looks at it — the
|
||||
* point is that a new licence enters the tree through a reviewed change to
|
||||
* this file, never unnoticed through a Dependabot bump. `EXCEPTIONS` is that
|
||||
* reviewed change for one package, with its reason.
|
||||
*
|
||||
* The `license` value is self-declared by each package and copied verbatim by
|
||||
* npm; this gate trusts it, as every lockfile-based checker must. It needs no
|
||||
* `node_modules` and no network, so it runs before anything is installed.
|
||||
*
|
||||
* Usage: node scripts/check-licenses.mjs — reads <repo>/package-lock.json and
|
||||
* <repo>/tools/publish/package-lock.json (the store-upload tool, docs/12 §3),
|
||||
* resolved from this file. Its tests call `checkLockfile(lock)` directly.
|
||||
*/
|
||||
import { readFileSync } from 'node:fs';
|
||||
import { resolve } from 'node:path';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
import { CREDITED_PACKAGES } from './credited-packages.mjs';
|
||||
|
||||
/** Permissive licences that may ship inside a GPL-3.0-or-later extension. */
|
||||
export const SHIPPED_LICENSES = Object.freeze([
|
||||
'0BSD',
|
||||
'Apache-2.0',
|
||||
'BSD-2-Clause',
|
||||
'BSD-3-Clause',
|
||||
'ISC',
|
||||
'MIT',
|
||||
'MIT-0',
|
||||
]);
|
||||
|
||||
/** Licences accepted for build and test tooling, which never ships. */
|
||||
export const TOOLCHAIN_LICENSES = Object.freeze([
|
||||
...SHIPPED_LICENSES,
|
||||
'BlueOak-1.0.0',
|
||||
'CC-BY-4.0',
|
||||
'CC0-1.0',
|
||||
'MPL-2.0',
|
||||
'Python-2.0',
|
||||
'Unlicense',
|
||||
'Zlib',
|
||||
]);
|
||||
|
||||
/**
|
||||
* Packages accepted despite the lists above: `name → reason`. Empty on
|
||||
* purpose; an entry is a decision, recorded in docs/15's decision log.
|
||||
* @type {Readonly<Record<string, string>>}
|
||||
*/
|
||||
export const EXCEPTIONS = Object.freeze({});
|
||||
|
||||
/**
|
||||
* Whether an SPDX licence expression is satisfied by the allowed identifiers.
|
||||
* `A OR B` needs either side, `A AND B` both; parentheses group; `A WITH X`
|
||||
* (a licence exception) is judged by `A`. Anything unparseable is refused.
|
||||
*
|
||||
* @param {string} expression
|
||||
* @param {readonly string[]} allowed
|
||||
* @returns {boolean}
|
||||
*/
|
||||
export function satisfies(expression, allowed) {
|
||||
const tokens = expression.match(/\(|\)|[^\s()]+/g) ?? [];
|
||||
let at = 0;
|
||||
|
||||
/** @returns {boolean} */
|
||||
const parseOr = () => {
|
||||
let ok = parseAnd();
|
||||
while (tokens[at] === 'OR') {
|
||||
at++;
|
||||
const right = parseAnd();
|
||||
ok = ok || right;
|
||||
}
|
||||
return ok;
|
||||
};
|
||||
/** @returns {boolean} */
|
||||
const parseAnd = () => {
|
||||
let ok = parseTerm();
|
||||
while (tokens[at] === 'AND') {
|
||||
at++;
|
||||
const right = parseTerm();
|
||||
ok = ok && right;
|
||||
}
|
||||
return ok;
|
||||
};
|
||||
/** @returns {boolean} */
|
||||
const parseTerm = () => {
|
||||
const token = tokens[at++];
|
||||
if (token === '(') {
|
||||
const ok = parseOr();
|
||||
if (tokens[at++] !== ')') throw new SyntaxError('unbalanced parentheses');
|
||||
return ok;
|
||||
}
|
||||
if (token === undefined || token === ')' || token === 'AND' || token === 'OR') {
|
||||
throw new SyntaxError('expected a licence identifier');
|
||||
}
|
||||
if (tokens[at] === 'WITH') at += 2;
|
||||
return allowed.includes(token);
|
||||
};
|
||||
|
||||
try {
|
||||
const ok = parseOr();
|
||||
return at === tokens.length && tokens.length > 0 && ok;
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* The package name a lockfile key installs: the part after the last
|
||||
* `node_modules/`, scope included.
|
||||
* @param {string} key
|
||||
*/
|
||||
export function packageNameOf(key) {
|
||||
const at = key.lastIndexOf('node_modules/');
|
||||
return at === -1 ? key : key.slice(at + 'node_modules/'.length);
|
||||
}
|
||||
|
||||
/**
|
||||
* Lockfile text is our own committed file, but it is still file content: keep
|
||||
* what reaches the log to the characters package names and SPDX ids use.
|
||||
* @param {unknown} value
|
||||
*/
|
||||
function printable(value) {
|
||||
return String(value)
|
||||
.replaceAll(/[^\w@/.+() -]/g, '?')
|
||||
.slice(0, 120);
|
||||
}
|
||||
|
||||
/**
|
||||
* Check every installed package of a v2/v3 lockfile.
|
||||
*
|
||||
* @param {unknown} lock - the parsed `package-lock.json`
|
||||
* @param {{ shipsCode?: boolean }} [options] - `shipsCode: false` for a lockfile
|
||||
* that builds nothing into the extension (tools/publish), where the credited
|
||||
* packages are not expected
|
||||
* @returns {{ problems: string[], checked: number, counts: Map<string, number> }}
|
||||
*/
|
||||
export function checkLockfile(lock, options = {}) {
|
||||
const shipsCode = options.shipsCode ?? true;
|
||||
/** @type {string[]} */
|
||||
const problems = [];
|
||||
/** @type {Map<string, number>} */
|
||||
const counts = new Map();
|
||||
const packages =
|
||||
typeof lock === 'object' && lock !== null && 'packages' in lock ? lock.packages : undefined;
|
||||
if (typeof packages !== 'object' || packages === null) {
|
||||
return { problems: ['no "packages" map — lockfile v2 or v3 expected'], checked: 0, counts };
|
||||
}
|
||||
|
||||
const shippedSeen = new Set();
|
||||
let checked = 0;
|
||||
for (const [key, raw] of Object.entries(packages)) {
|
||||
// The root project (key "") and workspace links carry no install of their own.
|
||||
if (key === '' || !key.includes('node_modules/')) continue;
|
||||
if (typeof raw === 'object' && raw !== null && 'link' in raw && raw.link === true) continue;
|
||||
checked++;
|
||||
const name = packageNameOf(key);
|
||||
const license =
|
||||
typeof raw === 'object' && raw !== null && 'license' in raw ? raw.license : undefined;
|
||||
const label = typeof license === 'string' ? license : '(none)';
|
||||
counts.set(label, (counts.get(label) ?? 0) + 1);
|
||||
|
||||
const shipped = CREDITED_PACKAGES.includes(name);
|
||||
if (shipped) shippedSeen.add(name);
|
||||
if (Object.hasOwn(EXCEPTIONS, name)) continue;
|
||||
const allowed = shipped ? SHIPPED_LICENSES : TOOLCHAIN_LICENSES;
|
||||
if (typeof license !== 'string' || !satisfies(license, allowed)) {
|
||||
problems.push(
|
||||
`${printable(key)}: licence "${printable(label)}" is not accepted for ` +
|
||||
(shipped ? 'code that ships in the extension' : 'build tooling'),
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
for (const name of shipsCode ? CREDITED_PACKAGES : []) {
|
||||
if (!shippedSeen.has(name)) {
|
||||
problems.push(`${printable(name)}: credited as shipping, but not in the lockfile`);
|
||||
}
|
||||
}
|
||||
return { problems, checked, counts };
|
||||
}
|
||||
|
||||
/** The lockfiles this repository installs from, and whether each builds the extension. */
|
||||
const LOCKFILES = [
|
||||
{ path: 'package-lock.json', shipsCode: true },
|
||||
{ path: 'tools/publish/package-lock.json', shipsCode: false },
|
||||
];
|
||||
|
||||
/** @returns {number} exit code */
|
||||
function main() {
|
||||
const repo = resolve(fileURLToPath(import.meta.url), '..', '..');
|
||||
/** @type {string[]} */
|
||||
const problems = [];
|
||||
let checked = 0;
|
||||
/** @type {Map<string, number>} */
|
||||
const counts = new Map();
|
||||
for (const { path, shipsCode } of LOCKFILES) {
|
||||
/** @type {unknown} */
|
||||
let lock;
|
||||
try {
|
||||
lock = JSON.parse(readFileSync(resolve(repo, path), 'utf8'));
|
||||
} catch (cause) {
|
||||
console.error(`::error::check-licenses: cannot read ${path} (${String(cause)})`);
|
||||
return 1;
|
||||
}
|
||||
const result = checkLockfile(lock, { shipsCode });
|
||||
for (const problem of result.problems) problems.push(`${path}: ${problem}`);
|
||||
checked += result.checked;
|
||||
for (const [license, n] of result.counts) counts.set(license, (counts.get(license) ?? 0) + n);
|
||||
}
|
||||
if (problems.length > 0) {
|
||||
for (const problem of problems) console.error(`::error::check-licenses: ${problem}`);
|
||||
console.error(
|
||||
'\nSee docs/09 §3.2: add the licence to a list, or an EXCEPTIONS entry, on purpose.',
|
||||
);
|
||||
return 1;
|
||||
}
|
||||
const summary = [...counts]
|
||||
.sort((a, b) => b[1] - a[1])
|
||||
.map(([license, n]) => `${printable(license)} ${n}`)
|
||||
.join(', ');
|
||||
console.warn(`check-licenses: clean — ${checked} packages (${summary}).`);
|
||||
return 0;
|
||||
}
|
||||
|
||||
// Run only as the entry point (same guard as check-manifest.mjs).
|
||||
const isEntry =
|
||||
import.meta.url.startsWith('file:') &&
|
||||
process.argv[1] !== undefined &&
|
||||
resolve(process.argv[1]) === fileURLToPath(import.meta.url);
|
||||
if (isEntry) {
|
||||
// exitCode, not exit(): exit() can cut off piped stderr before CI reads it.
|
||||
process.exitCode = main();
|
||||
}
|
||||
@@ -2,4 +2,8 @@
|
||||
* Types for scripts/check-manifest.mjs, so its tests can call it directly.
|
||||
* The script itself is plain JavaScript checked with `// @ts-check`.
|
||||
*/
|
||||
export function checkExtension(outDir: string): { problems: string[]; readError?: string };
|
||||
export const TARGETS: Record<string, { dir: string; keys: string[]; label: string }>;
|
||||
export function checkExtension(
|
||||
outDir: string,
|
||||
target?: string,
|
||||
): { problems: string[]; readError?: string };
|
||||
+91
-19
@@ -18,10 +18,12 @@
|
||||
* 3. the bundle: none of the network identifiers `npm run guard` bans in the
|
||||
* source, anywhere in the shipped JavaScript.
|
||||
*
|
||||
* Usage: node scripts/check-manifest.mjs — checks <repo>/.output/chrome-mv3,
|
||||
* resolved from this file, not the cwd. It takes no arguments on purpose: a
|
||||
* path from the command line flowed straight into file reads (SonarCloud
|
||||
* S8707). Its tests call `checkExtension(dir)` directly instead.
|
||||
* Usage: node scripts/check-manifest.mjs [--browser chrome|firefox] — checks
|
||||
* <repo>/.output/chrome-mv3 (the default) or <repo>/.output/firefox-mv3 (since
|
||||
* v1.3.0, docs/08 §9), resolved from this file, not the cwd. It takes no path:
|
||||
* one from the command line flowed straight into file reads (SonarCloud
|
||||
* S8707), so `--browser` only picks an entry of a fixed table. Its tests call
|
||||
* `checkExtension(dir, target)` directly instead.
|
||||
*/
|
||||
import { existsSync, readdirSync, readFileSync } from 'node:fs';
|
||||
import { join, relative, resolve } from 'node:path';
|
||||
@@ -54,7 +56,10 @@ const EXPECTED_CSP =
|
||||
*
|
||||
* Adding a key here is a deliberate act. Check docs/08 §1 first.
|
||||
*/
|
||||
const EXPECTED_KEYS = [
|
||||
/** @param {string} a @param {string} b */
|
||||
const byName = (a, b) => a.localeCompare(b, 'en');
|
||||
|
||||
const COMMON_KEYS = [
|
||||
'action',
|
||||
'content_security_policy',
|
||||
'default_locale',
|
||||
@@ -62,13 +67,57 @@ const EXPECTED_KEYS = [
|
||||
'homepage_url',
|
||||
'icons',
|
||||
'manifest_version',
|
||||
'minimum_chrome_version',
|
||||
'name',
|
||||
'options_ui',
|
||||
'permissions',
|
||||
'version',
|
||||
];
|
||||
|
||||
/**
|
||||
* Firefox's block, exactly (docs/08 §9). The id is permanent once on AMO; the
|
||||
* floor is the first Firefox that accepts `data_collection_permissions`.
|
||||
*/
|
||||
const FIREFOX_SETTINGS = {
|
||||
gecko: {
|
||||
id: 'bookmarkmagic@poli0981.dev',
|
||||
strict_min_version: '140.0',
|
||||
data_collection_permissions: { required: ['none'] },
|
||||
},
|
||||
};
|
||||
|
||||
/**
|
||||
* The two packages (docs/08 §1): where each is built, its exact key set, and
|
||||
* how its floor reads in the log. Edge Add-ons takes the Chrome package.
|
||||
*
|
||||
* @type {Record<string, { dir: string, keys: string[], label: string }>}
|
||||
*/
|
||||
export const TARGETS = {
|
||||
chrome: {
|
||||
dir: 'chrome-mv3',
|
||||
keys: [...COMMON_KEYS, 'minimum_chrome_version'].sort(byName),
|
||||
label: `Chrome ≥${CHROME_FLOOR}`,
|
||||
},
|
||||
firefox: {
|
||||
dir: 'firefox-mv3',
|
||||
keys: [...COMMON_KEYS, 'browser_specific_settings'].sort(byName),
|
||||
label: 'Firefox ≥140, gecko id pinned',
|
||||
},
|
||||
};
|
||||
|
||||
/**
|
||||
* A value's JSON with object keys sorted, so key order never decides equality.
|
||||
* @param {unknown} value
|
||||
* @returns {string}
|
||||
*/
|
||||
function canonical(value) {
|
||||
if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
|
||||
if (value !== null && typeof value === 'object') {
|
||||
const entries = Object.entries(value).sort(([a], [b]) => byName(a, b));
|
||||
return `{${entries.map(([k, v]) => `${JSON.stringify(k)}:${canonical(v)}`).join(',')}}`;
|
||||
}
|
||||
return JSON.stringify(value) ?? 'undefined';
|
||||
}
|
||||
|
||||
/** Keys that would widen the extension's reach. None may be present. */
|
||||
const FORBIDDEN_KEYS = [
|
||||
'host_permissions',
|
||||
@@ -92,6 +141,8 @@ const REQUIRED_FILES = [
|
||||
'_locales/en/messages.json',
|
||||
'_locales/vi/messages.json',
|
||||
'_locales/ja/messages.json',
|
||||
'_locales/zh_CN/messages.json',
|
||||
'_locales/ro/messages.json',
|
||||
];
|
||||
|
||||
/**
|
||||
@@ -108,9 +159,6 @@ const NETWORK_IN_BUNDLE =
|
||||
/** `src`/`href` values in a built page. Vite writes them double-quoted. */
|
||||
const PAGE_REFS = /\b(?:src|href)="([^"]*)"/g;
|
||||
|
||||
/** @param {string} a @param {string} b */
|
||||
const byName = (a, b) => a.localeCompare(b, 'en');
|
||||
|
||||
/** @param {string} dir @returns {string[]} */
|
||||
function listFiles(dir) {
|
||||
return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
|
||||
@@ -131,8 +179,13 @@ function readManifest(outDir) {
|
||||
}
|
||||
}
|
||||
|
||||
/** @param {Record<string, unknown>} manifest @param {string[]} problems */
|
||||
function checkManifest(manifest, problems) {
|
||||
/**
|
||||
* @param {Record<string, unknown>} manifest
|
||||
* @param {string[]} problems
|
||||
* @param {string} target - a key of TARGETS
|
||||
*/
|
||||
function checkManifest(manifest, problems, target) {
|
||||
const expectedKeys = TARGETS[target]?.keys ?? [];
|
||||
if (manifest.manifest_version !== 3) {
|
||||
problems.push(`manifest_version is ${manifest.manifest_version}, expected 3`);
|
||||
}
|
||||
@@ -150,14 +203,20 @@ function checkManifest(manifest, problems) {
|
||||
}
|
||||
|
||||
const actualKeys = Object.keys(manifest);
|
||||
const unexpected = actualKeys.filter((key) => !EXPECTED_KEYS.includes(key)).sort(byName);
|
||||
const missing = EXPECTED_KEYS.filter((key) => !actualKeys.includes(key));
|
||||
const unexpected = actualKeys.filter((key) => !expectedKeys.includes(key)).sort(byName);
|
||||
const missing = expectedKeys.filter((key) => !actualKeys.includes(key));
|
||||
if (unexpected.length > 0) {
|
||||
problems.push(`unexpected top-level key(s): ${unexpected.join(', ')} — see docs/08 §1`);
|
||||
}
|
||||
if (missing.length > 0) problems.push(`missing expected top-level key(s): ${missing.join(', ')}`);
|
||||
|
||||
if (manifest.minimum_chrome_version !== CHROME_FLOOR) {
|
||||
if (target === 'firefox') {
|
||||
if (canonical(manifest.browser_specific_settings) !== canonical(FIREFOX_SETTINGS)) {
|
||||
problems.push(
|
||||
`browser_specific_settings is ${JSON.stringify(manifest.browser_specific_settings)}, expected exactly ${JSON.stringify(FIREFOX_SETTINGS)} (docs/08 §9)`,
|
||||
);
|
||||
}
|
||||
} else if (manifest.minimum_chrome_version !== CHROME_FLOOR) {
|
||||
problems.push(
|
||||
`minimum_chrome_version is ${JSON.stringify(manifest.minimum_chrome_version)}, expected "${CHROME_FLOOR}" (docs/01 §1)`,
|
||||
);
|
||||
@@ -233,15 +292,19 @@ function checkBundle(outDir, problems) {
|
||||
* Check one built extension directory.
|
||||
*
|
||||
* @param {string} outDir
|
||||
* @param {string} [target] - a key of TARGETS; `chrome` when omitted
|
||||
* @returns {{ problems: string[], readError?: string }} no problems and no read
|
||||
* error means the build is clean
|
||||
*/
|
||||
export function checkExtension(outDir) {
|
||||
export function checkExtension(outDir, target = 'chrome') {
|
||||
if (!Object.hasOwn(TARGETS, target)) {
|
||||
return { problems: [], readError: `unknown target "${target}"` };
|
||||
}
|
||||
const manifest = readManifest(outDir);
|
||||
if (typeof manifest === 'string') return { problems: [], readError: manifest };
|
||||
/** @type {string[]} */
|
||||
const problems = [];
|
||||
checkManifest(manifest, problems);
|
||||
checkManifest(manifest, problems, target);
|
||||
checkInventory(outDir, manifest, problems);
|
||||
checkBundle(outDir, problems);
|
||||
return { problems };
|
||||
@@ -249,10 +312,19 @@ export function checkExtension(outDir) {
|
||||
|
||||
/** @returns {number} the exit code */
|
||||
function main() {
|
||||
const flag = process.argv.indexOf('--browser');
|
||||
const target = flag === -1 ? 'chrome' : (process.argv[flag + 1] ?? '');
|
||||
const profile = Object.hasOwn(TARGETS, target) ? TARGETS[target] : undefined;
|
||||
if (profile === undefined) {
|
||||
console.error(`check-manifest: --browser must be one of ${Object.keys(TARGETS).join(', ')}`);
|
||||
return 1;
|
||||
}
|
||||
const repo = resolve(fileURLToPath(new URL('..', import.meta.url)));
|
||||
const { problems, readError } = checkExtension(join(repo, '.output', 'chrome-mv3'));
|
||||
// The directory comes from the table, never from the command line.
|
||||
const { problems, readError } = checkExtension(join(repo, '.output', profile.dir), target);
|
||||
if (readError !== undefined) {
|
||||
console.error(`check-manifest: ${readError} — run \`npm run build\` first.`);
|
||||
const build = target === 'chrome' ? 'npm run build' : `npm run build:${target}`;
|
||||
console.error(`check-manifest: ${readError} — run \`${build}\` first.`);
|
||||
return 1;
|
||||
}
|
||||
if (problems.length > 0) {
|
||||
@@ -266,7 +338,7 @@ function main() {
|
||||
// Constants only: the manifest has just passed every check, so its values ARE
|
||||
// these — and nothing read from a file is echoed into the log.
|
||||
console.warn(
|
||||
`check-manifest: clean — MV3, permissions exactly ${ALLOWED_PERMISSIONS.join(' + ')}, Chrome ≥${CHROME_FLOOR}, CSP pinned, inventory complete, no network API in the bundle.`,
|
||||
`check-manifest: clean (${target}) — MV3, permissions exactly ${ALLOWED_PERMISSIONS.join(' + ')}, ${profile.label}, CSP pinned, inventory complete, no network API in the bundle.`,
|
||||
);
|
||||
return 0;
|
||||
}
|
||||
|
||||
@@ -0,0 +1,5 @@
|
||||
/**
|
||||
* Types for scripts/credited-packages.mjs, so `wxt.config.ts` and the tests can
|
||||
* import the list. The script itself is plain JavaScript checked with `// @ts-check`.
|
||||
*/
|
||||
export const CREDITED_PACKAGES: readonly string[];
|
||||
@@ -0,0 +1,17 @@
|
||||
// @ts-check
|
||||
/**
|
||||
* The npm packages whose code the build compiles into the extension — docs/14 §5.
|
||||
*
|
||||
* One list behind three gates, so none of them can drift from the others:
|
||||
* - `wxt.config.ts` fails the build when code from any other package ships;
|
||||
* - `tests/unit/third-party.test.ts` requires both notices files to credit
|
||||
* every package named here;
|
||||
* - `scripts/check-licenses.mjs` holds each of them to the licences that may
|
||||
* travel inside a GPL-3.0-or-later extension.
|
||||
*
|
||||
* Through v1.0.x the notices said "none" while three of these shipped. Adding
|
||||
* a name here is the first step of shipping a new package, never the last:
|
||||
* its licence text goes into `legal/THIRD_PARTY_NOTICES.md` and
|
||||
* `src/public/THIRD_PARTY_NOTICES.txt` in the same pull request.
|
||||
*/
|
||||
export const CREDITED_PACKAGES = Object.freeze(['svelte', 'clsx', '@wxt-dev/browser', 'wxt']);
|
||||
@@ -107,7 +107,7 @@ export function makeTitleMapper() {
|
||||
const SCRIPTS = [
|
||||
[/[一-鿿-ヿ]/, '文字'],
|
||||
[/[-ࣿ]/, 'شيء'],
|
||||
[/[\p{Extended_Pictographic}]/u, '🌸'],
|
||||
[/\p{Extended_Pictographic}/u, '🌸'],
|
||||
];
|
||||
|
||||
return (raw) => {
|
||||
|
||||
+58
-61
@@ -13,13 +13,14 @@
|
||||
* npm run build && node scripts/screenshots.mjs # serve on :4318
|
||||
* node scripts/screenshots.mjs --shoot # also capture PNGs
|
||||
*
|
||||
* Page URLs take `?theme=light|dark&lang=en|vi|ja&legal=0|1`, and the route as
|
||||
* the hash: http://localhost:4318/manager.html?theme=dark&lang=vi#edit
|
||||
* Page URLs take `?theme=light|dark&lang=en|vi|ja|zh-CN|ro&legal=0|1`, and the
|
||||
* route as the hash: http://localhost:4318/manager.html?theme=dark&lang=vi#edit
|
||||
*
|
||||
* `--shoot` drives a locally installed Chrome (CHROME_PATH, or the usual
|
||||
* install paths) headless, on a throwaway profile — never the user's own:
|
||||
* every route × theme × language at 1280×800 into `.output/qa-screens/` (for
|
||||
* review, git-ignored), the README set into `capture/`, and the store set into
|
||||
* every route × theme × language at 1280×800, plus the popup per theme ×
|
||||
* language at 360×420, into `.output/qa-screens/` (for review, git-ignored),
|
||||
* the README set into `capture/`, and the store set into
|
||||
* `store/screenshots/`. Dev tool only: nothing here ships, the server listens
|
||||
* on 127.0.0.1 alone, and it never touches the network beyond it.
|
||||
*/
|
||||
@@ -80,6 +81,11 @@ function shim() {
|
||||
] },
|
||||
{ id: '3', title: 'Mobile bookmarks', children: [b('Read later', 'https://later.example.com/')] },
|
||||
] }];
|
||||
// Chrome gives every node but the root a parentId, and the product relies on
|
||||
// it: without one, nothing can be placed beside a sibling (drag, Alt+↑/↓) and
|
||||
// the toolbar's Sort has no folder to act on.
|
||||
const adopt = (nodes, parentId) => { for (const n of nodes) { if (parentId !== undefined) n.parentId = parentId; if (n.children) adopt(n.children, n.id); } };
|
||||
adopt(tree);
|
||||
const byId = (id, nodes = tree) => { for (const n of nodes) { if (n.id === id) return n; const hit = n.children && byId(id, n.children); if (hit) return hit; } };
|
||||
const parentOf = (id, nodes = tree) => { for (const n of nodes) { if (n.children?.some((c) => c.id === id)) return n; const hit = n.children && parentOf(id, n.children); if (hit) return hit; } };
|
||||
const clone = (v) => structuredClone(v);
|
||||
@@ -88,7 +94,7 @@ function shim() {
|
||||
getTree: async () => clone(tree),
|
||||
create: async ({ parentId, title, url, index }) => { const p = byId(parentId); const n = url ? { id: String(next++), parentId, title, url, dateAdded: Date.now() } : { id: String(next++), parentId, title, dateAdded: Date.now(), children: [] }; const at = index ?? p.children.length; p.children.splice(at, 0, n); events.onCreated.fire(n.id, clone({ ...n, index: at })); return clone(n); },
|
||||
update: async (id, changes) => { Object.assign(byId(id), changes); events.onChanged.fire(id, changes); },
|
||||
move: async (id, { parentId, index }) => { const from = parentOf(id); const n = byId(id); const old = from.children.indexOf(n); from.children.splice(old, 1); const to = byId(parentId ?? from.id); let at = index ?? to.children.length; if (to === from && at > old) at--; to.children.splice(at, 0, n); events.onMoved.fire(id, { parentId: to.id, index: at, oldParentId: from.id, oldIndex: old }); },
|
||||
move: async (id, { parentId, index }) => { const from = parentOf(id); const n = byId(id); const old = from.children.indexOf(n); from.children.splice(old, 1); const to = byId(parentId ?? from.id); let at = index ?? to.children.length; if (to === from && at > old) at--; to.children.splice(at, 0, n); n.parentId = to.id; events.onMoved.fire(id, { parentId: to.id, index: at, oldParentId: from.id, oldIndex: old }); },
|
||||
remove: async (id) => { const p = parentOf(id); p.children = p.children.filter((c) => c.id !== id); events.onRemoved.fire(id, {}); },
|
||||
};
|
||||
bookmarks.removeTree = bookmarks.remove;
|
||||
@@ -214,21 +220,51 @@ function findChrome() {
|
||||
* @param {string} file @param {string} size
|
||||
*/
|
||||
async function shoot(chrome, profile, url, file, size) {
|
||||
await run(
|
||||
chrome,
|
||||
[
|
||||
'--headless=new',
|
||||
`--user-data-dir=${profile}`,
|
||||
'--no-first-run',
|
||||
'--disable-gpu',
|
||||
'--hide-scrollbars',
|
||||
`--window-size=${size}`,
|
||||
'--virtual-time-budget=4000',
|
||||
`--screenshot=${file}`,
|
||||
url,
|
||||
],
|
||||
{ timeout: 60_000 },
|
||||
);
|
||||
const flags = ['--headless=new', '--no-first-run', '--disable-gpu', '--hide-scrollbars'];
|
||||
const page = [`--window-size=${size}`, '--virtual-time-budget=4000', `--screenshot=${file}`];
|
||||
await run(chrome, [...flags, `--user-data-dir=${profile}`, ...page, url], { timeout: 60_000 });
|
||||
}
|
||||
|
||||
/** `LOCALES` (resolve-locale.ts), which .mjs cannot import — touch-points.test.ts pins it. */
|
||||
const LANGS = ['en', 'vi', 'ja', 'zh-CN', 'ro'];
|
||||
|
||||
/**
|
||||
* Every screenshot `--shoot` takes, as [url, file, window size] (docs/11 §5):
|
||||
* the QA sweep — each route × theme × locale, plus the popup, the narrowest
|
||||
* surface (340 px) and where a long translation overflows first — then the
|
||||
* README set and the store set, both English.
|
||||
*
|
||||
* @param {{ qa: string, capture: string, store: string }} dirs
|
||||
* @returns {[url: string, file: string, size: string][]}
|
||||
*/
|
||||
function shotList({ qa, capture, store }) {
|
||||
const origin = `http://${HOST}:${PORT}`;
|
||||
const page = (/** @type {string} */ query, /** @type {string} */ route) =>
|
||||
`${origin}/manager.html?${query}#${route}`;
|
||||
const routes = ['import', 'export', 'edit', 'settings', 'about'];
|
||||
/** @type {[string, string, string][]} */
|
||||
const jobs = [];
|
||||
for (const lang of LANGS) {
|
||||
for (const theme of ['light', 'dark']) {
|
||||
const query = `theme=${theme}&lang=${lang}`;
|
||||
for (const route of routes) {
|
||||
jobs.push([page(query, route), join(qa, `${route}-${theme}-${lang}.png`), '1280,800']);
|
||||
}
|
||||
jobs.push([
|
||||
`${origin}/popup.html?${query}`,
|
||||
join(qa, `popup-${theme}-${lang}.png`),
|
||||
'360,420',
|
||||
]);
|
||||
}
|
||||
}
|
||||
for (const route of routes) {
|
||||
jobs.push([page('theme=light&lang=en', route), join(capture, `${route}.png`), '1280,800']);
|
||||
}
|
||||
for (const route of ['edit', 'export', 'import']) {
|
||||
jobs.push([page('theme=dark&lang=en', route), join(store, `${route}.png`), '1280,800']);
|
||||
}
|
||||
jobs.push([`${origin}/popup.html?theme=light&lang=en`, join(capture, 'popup.png'), '360,420']);
|
||||
return jobs;
|
||||
}
|
||||
|
||||
if (!existsSync(join(OUT, 'manifest.json'))) {
|
||||
@@ -248,49 +284,10 @@ if (!existsSync(join(OUT, 'manifest.json'))) {
|
||||
const store = join(ROOT, 'store', 'screenshots');
|
||||
for (const dir of [qa, capture, store]) mkdirSync(dir, { recursive: true });
|
||||
const profile = mkdtempSync(join(tmpdir(), 'bookmarkmagic-harness-'));
|
||||
const page = (/** @type {string} */ query, /** @type {string} */ route) =>
|
||||
`http://${HOST}:${PORT}/manager.html?${query}#${route}`;
|
||||
const ROUTES = ['import', 'export', 'edit', 'settings', 'about'];
|
||||
try {
|
||||
for (const lang of ['en', 'vi', 'ja']) {
|
||||
for (const theme of ['light', 'dark']) {
|
||||
for (const route of ROUTES) {
|
||||
const file = join(qa, `${route}-${theme}-${lang}.png`);
|
||||
await shoot(
|
||||
chrome,
|
||||
profile,
|
||||
page(`theme=${theme}&lang=${lang}`, route),
|
||||
file,
|
||||
'1280,800',
|
||||
);
|
||||
}
|
||||
}
|
||||
for (const [url, file, size] of shotList({ qa, capture, store })) {
|
||||
await shoot(chrome, profile, url, file, size);
|
||||
}
|
||||
for (const route of ROUTES) {
|
||||
await shoot(
|
||||
chrome,
|
||||
profile,
|
||||
page('theme=light&lang=en', route),
|
||||
join(capture, `${route}.png`),
|
||||
'1280,800',
|
||||
);
|
||||
}
|
||||
for (const route of ['edit', 'export', 'import']) {
|
||||
await shoot(
|
||||
chrome,
|
||||
profile,
|
||||
page('theme=dark&lang=en', route),
|
||||
join(store, `${route}.png`),
|
||||
'1280,800',
|
||||
);
|
||||
}
|
||||
await shoot(
|
||||
chrome,
|
||||
profile,
|
||||
`http://${HOST}:${PORT}/popup.html?theme=light&lang=en`,
|
||||
join(capture, 'popup.png'),
|
||||
'360,420',
|
||||
);
|
||||
} finally {
|
||||
rmSync(profile, { recursive: true, force: true });
|
||||
server.close();
|
||||
|
||||
@@ -0,0 +1,22 @@
|
||||
/**
|
||||
* Types for scripts/triage.mjs, so its tests can call it directly.
|
||||
* The script itself is plain JavaScript checked with `// @ts-check`.
|
||||
*/
|
||||
export interface Decision {
|
||||
action: 'close' | 'label' | 'none';
|
||||
reason: string;
|
||||
kind?: 'issue' | 'pr';
|
||||
number?: number;
|
||||
label?: string;
|
||||
comment?: string;
|
||||
}
|
||||
|
||||
export const POLICY_URL: string;
|
||||
export const IDEAS_URL: string;
|
||||
export const KIND_QUESTION: string;
|
||||
export const KIND: Readonly<{ roadmap: string; needed: string; fresh: string }>;
|
||||
export const LABEL: Readonly<{ feature: string; closed: string; triage: string; exempt: string }>;
|
||||
export const ISSUE_COMMENT: string;
|
||||
export const PR_COMMENT: string;
|
||||
export function kindOf(body: unknown): string | undefined;
|
||||
export function decide(eventName: string | undefined, payload: unknown): Decision;
|
||||
@@ -0,0 +1,261 @@
|
||||
// @ts-check
|
||||
/**
|
||||
* Maintenance-mode triage — MAINTENANCE.md, docs/12 §2.6.
|
||||
*
|
||||
* Decides what `.github/workflows/triage.yml` does with a new issue or pull
|
||||
* request; the workflow then carries the decision out with `gh`. The decision
|
||||
* is a pure function of the event payload, so every branch is unit-tested
|
||||
* (tests/unit/scripts/triage.test.ts) instead of living in shell `if`s.
|
||||
*
|
||||
* - An issue labelled `enhancement` (the feature form applies it) whose
|
||||
* "kind of change" answer is "something new" — or that has no answer at
|
||||
* all, i.e. the maintainer labelled it by hand — is labelled
|
||||
* `maintenance-mode`, gets a comment and is closed as not planned.
|
||||
* - The other two answers (on the roadmap; needed for a fix) keep it open,
|
||||
* labelled `needs-triage`, for the maintainer to read.
|
||||
* - A pull request from outside the project titled `feat…` (Conventional
|
||||
* Commits) is labelled and closed the same way.
|
||||
* - Exempt: the owner's own issues, project members and collaborators, bots
|
||||
* (Dependabot), anything labelled `roadmap`, anything already triaged.
|
||||
*
|
||||
* Nothing here runs code from the event: titles and bodies are only compared
|
||||
* with constants, and the workflow passes the payload by file, never through
|
||||
* shell interpolation.
|
||||
*
|
||||
* Usage (in CI): node scripts/triage.mjs — reads GITHUB_EVENT_NAME and
|
||||
* GITHUB_EVENT_PATH from the environment the runner sets, prints a JSON
|
||||
* decision on stdout. It takes no arguments.
|
||||
*/
|
||||
import { readFileSync } from 'node:fs';
|
||||
import { resolve } from 'node:path';
|
||||
import { fileURLToPath } from 'node:url';
|
||||
|
||||
const REPO = 'https://github.com/poli0981/bookmarkmagic';
|
||||
export const POLICY_URL = `${REPO}/blob/main/MAINTENANCE.md`;
|
||||
export const IDEAS_URL = `${REPO}/discussions/categories/ideas`;
|
||||
|
||||
/** The feature form's dropdown, word for word (`.github/ISSUE_TEMPLATE/feature_request.yml`). */
|
||||
export const KIND_QUESTION = 'Which kind of change is this?';
|
||||
export const KIND = Object.freeze({
|
||||
roadmap: 'Something already on the roadmap (docs/15)',
|
||||
needed: 'Needed to fix a bug, a UI/UX defect or an accessibility barrier',
|
||||
fresh: 'Something new — not on the roadmap',
|
||||
});
|
||||
|
||||
export const LABEL = Object.freeze({
|
||||
feature: 'enhancement',
|
||||
closed: 'maintenance-mode',
|
||||
triage: 'needs-triage',
|
||||
exempt: 'roadmap',
|
||||
});
|
||||
|
||||
/** Associations that mean "part of the project", per GitHub's author_association. */
|
||||
const INSIDERS = new Set(['OWNER', 'MEMBER', 'COLLABORATOR']);
|
||||
|
||||
const BOT_NOTE = '<sub>Posted automatically by the triage workflow.</sub>';
|
||||
|
||||
export const ISSUE_COMMENT = [
|
||||
'Thank you for the suggestion.',
|
||||
'',
|
||||
`BookmarkMagic is in **maintenance mode** ([MAINTENANCE.md](${POLICY_URL})): it takes bug, UI/UX and accessibility fixes, translation fixes, dependency and security updates, and features that are already on the roadmap. This request is for something new, so it has been labelled \`${LABEL.closed}\` and closed.`,
|
||||
'',
|
||||
'It has not been deleted, and it will be read. If it is on the roadmap, or it is needed to fix a defect or remove a barrier, it will be reopened. Ideas are welcome in [Discussions › Ideas](' +
|
||||
`${IDEAS_URL}).`,
|
||||
'',
|
||||
BOT_NOTE,
|
||||
].join('\n');
|
||||
|
||||
export const PR_COMMENT = [
|
||||
'Thank you for the pull request.',
|
||||
'',
|
||||
`BookmarkMagic is in **maintenance mode** ([MAINTENANCE.md](${POLICY_URL})). A pull request that adds a feature — its title starts with \`feat\` — is closed automatically unless the feature is already on the roadmap, so this one has been labelled \`${LABEL.closed}\` and closed.`,
|
||||
'',
|
||||
'Please open a feature request first; if it is accepted (label `roadmap`), this pull request will be reopened. If it is a fix rather than a feature, say so in a comment — a `fix:` title is what the maintainer expects.',
|
||||
'',
|
||||
BOT_NOTE,
|
||||
].join('\n');
|
||||
|
||||
/**
|
||||
* @typedef {{
|
||||
* action: 'close' | 'label' | 'none',
|
||||
* reason: string,
|
||||
* kind?: 'issue' | 'pr',
|
||||
* number?: number,
|
||||
* label?: string,
|
||||
* comment?: string,
|
||||
* }} Decision
|
||||
*/
|
||||
|
||||
/**
|
||||
* The answer to the feature form's dropdown, or undefined when the body has
|
||||
* none (an issue from another form, labelled by hand). Issue forms render each
|
||||
* field as `### <label>` followed by the answer.
|
||||
* @param {unknown} body
|
||||
* @returns {string | undefined}
|
||||
*/
|
||||
export function kindOf(body) {
|
||||
if (typeof body !== 'string') return undefined;
|
||||
const lines = body.split(/\r?\n/);
|
||||
const at = lines.findIndex((line) => line.trim() === `### ${KIND_QUESTION}`);
|
||||
if (at === -1) return undefined;
|
||||
for (const line of lines.slice(at + 1)) {
|
||||
const text = line.trim();
|
||||
if (text.startsWith('### ')) return undefined;
|
||||
if (text !== '') return text;
|
||||
}
|
||||
return undefined;
|
||||
}
|
||||
|
||||
/** @param {unknown} value @returns {Record<string, unknown>} */
|
||||
function record(value) {
|
||||
return typeof value === 'object' && value !== null
|
||||
? /** @type {Record<string, unknown>} */ (value)
|
||||
: {};
|
||||
}
|
||||
|
||||
/** @param {unknown} labels @returns {string[]} */
|
||||
function labelNames(labels) {
|
||||
if (!Array.isArray(labels)) return [];
|
||||
return labels.map((label) => record(label).name).filter((name) => typeof name === 'string');
|
||||
}
|
||||
|
||||
/** @param {unknown} value @returns {number | undefined} */
|
||||
function positiveInt(value) {
|
||||
return typeof value === 'number' && Number.isInteger(value) && value > 0 ? value : undefined;
|
||||
}
|
||||
|
||||
/**
|
||||
* Whether this event is the repository owner adding a label by hand.
|
||||
* @param {Record<string, unknown>} payload
|
||||
*/
|
||||
function addedByOwner(payload) {
|
||||
const sender = record(payload.sender).login;
|
||||
const owner = record(record(payload.repository).owner).login;
|
||||
return (
|
||||
payload.action === 'labeled' && typeof sender === 'string' && sender !== '' && sender === owner
|
||||
);
|
||||
}
|
||||
|
||||
/**
|
||||
* @param {Record<string, unknown>} payload
|
||||
* @returns {Decision}
|
||||
*/
|
||||
function decideIssue(payload) {
|
||||
const issue = record(payload.issue);
|
||||
const number = positiveInt(issue.number);
|
||||
if (number === undefined) return { action: 'none', reason: 'no issue number' };
|
||||
if (payload.action !== 'opened' && payload.action !== 'labeled') {
|
||||
return { action: 'none', reason: `issue action ${String(payload.action)}` };
|
||||
}
|
||||
if (payload.action === 'labeled' && record(payload.label).name !== LABEL.feature) {
|
||||
return { action: 'none', reason: 'a different label was added' };
|
||||
}
|
||||
if (issue.state !== 'open') return { action: 'none', reason: 'issue is not open' };
|
||||
const labels = labelNames(issue.labels);
|
||||
if (!labels.includes(LABEL.feature)) return { action: 'none', reason: 'not a feature request' };
|
||||
for (const done of [LABEL.exempt, LABEL.closed, LABEL.triage]) {
|
||||
if (labels.includes(done)) return { action: 'none', reason: `already labelled ${done}` };
|
||||
}
|
||||
if (issue.author_association === 'OWNER')
|
||||
return { action: 'none', reason: "the owner's own issue" };
|
||||
|
||||
const kind = kindOf(issue.body);
|
||||
const forTriage = /** @type {Decision} */ ({
|
||||
action: 'label',
|
||||
reason: 'in policy — for the maintainer',
|
||||
kind: 'issue',
|
||||
number,
|
||||
label: LABEL.triage,
|
||||
});
|
||||
if (kind === KIND.roadmap || kind === KIND.needed) return forTriage;
|
||||
// No answer at all means the form was not used. Closing on that is the
|
||||
// owner's one-touch close, so it needs the owner's own `enhancement` label;
|
||||
// anything else (an edited body, an answer the form never offered) goes to
|
||||
// a human rather than being closed on a guess.
|
||||
if (kind !== KIND.fresh && !addedByOwner(payload)) {
|
||||
return { ...forTriage, reason: 'no answer to the form, not labelled by the owner' };
|
||||
}
|
||||
return {
|
||||
action: 'close',
|
||||
reason:
|
||||
kind === KIND.fresh ? 'a new feature outside the roadmap' : 'labelled enhancement by hand',
|
||||
kind: 'issue',
|
||||
number,
|
||||
label: LABEL.closed,
|
||||
comment: ISSUE_COMMENT,
|
||||
};
|
||||
}
|
||||
|
||||
/** Conventional Commits `feat`, with an optional scope and breaking-change mark. */
|
||||
const FEAT_TITLE = /^feat(\([^)]*\))?!?:/i;
|
||||
|
||||
/**
|
||||
* @param {Record<string, unknown>} payload
|
||||
* @returns {Decision}
|
||||
*/
|
||||
function decidePullRequest(payload) {
|
||||
const pr = record(payload.pull_request);
|
||||
const number = positiveInt(pr.number);
|
||||
if (number === undefined) return { action: 'none', reason: 'no pull request number' };
|
||||
if (payload.action !== 'opened')
|
||||
return { action: 'none', reason: `pull request action ${String(payload.action)}` };
|
||||
if (pr.state !== 'open') return { action: 'none', reason: 'pull request is not open' };
|
||||
if (record(pr.user).type === 'Bot') return { action: 'none', reason: 'opened by a bot' };
|
||||
if (INSIDERS.has(String(pr.author_association)))
|
||||
return { action: 'none', reason: 'opened from inside the project' };
|
||||
if (labelNames(pr.labels).includes(LABEL.exempt))
|
||||
return { action: 'none', reason: 'labelled roadmap' };
|
||||
if (typeof pr.title !== 'string' || !FEAT_TITLE.test(pr.title.trim())) {
|
||||
return { action: 'none', reason: 'not a feature pull request' };
|
||||
}
|
||||
return {
|
||||
action: 'close',
|
||||
reason: 'a feature pull request from outside the project',
|
||||
kind: 'pr',
|
||||
number,
|
||||
label: LABEL.closed,
|
||||
comment: PR_COMMENT,
|
||||
};
|
||||
}
|
||||
|
||||
/**
|
||||
* What to do with one event.
|
||||
* @param {string | undefined} eventName — GITHUB_EVENT_NAME
|
||||
* @param {unknown} payload — the parsed GITHUB_EVENT_PATH file
|
||||
* @returns {Decision}
|
||||
*/
|
||||
export function decide(eventName, payload) {
|
||||
const event = record(payload);
|
||||
if (eventName === 'issues') return decideIssue(event);
|
||||
if (eventName === 'pull_request_target') return decidePullRequest(event);
|
||||
return { action: 'none', reason: `event ${String(eventName)} is not triaged` };
|
||||
}
|
||||
|
||||
/** @returns {number} exit code */
|
||||
function main() {
|
||||
const eventPath = process.env.GITHUB_EVENT_PATH;
|
||||
if (eventPath === undefined || eventPath === '') {
|
||||
console.error('triage: GITHUB_EVENT_PATH is not set — this runs inside GitHub Actions only');
|
||||
return 1;
|
||||
}
|
||||
/** @type {unknown} */
|
||||
let payload;
|
||||
try {
|
||||
payload = JSON.parse(readFileSync(eventPath, 'utf8'));
|
||||
} catch (cause) {
|
||||
console.error(`triage: cannot read the event payload (${String(cause)})`);
|
||||
return 1;
|
||||
}
|
||||
process.stdout.write(`${JSON.stringify(decide(process.env.GITHUB_EVENT_NAME, payload))}\n`);
|
||||
return 0;
|
||||
}
|
||||
|
||||
// Run only as the entry point (same guard as check-manifest.mjs).
|
||||
const isEntry =
|
||||
import.meta.url.startsWith('file:') &&
|
||||
process.argv[1] !== undefined &&
|
||||
resolve(process.argv[1]) === fileURLToPath(import.meta.url);
|
||||
if (isEntry) {
|
||||
// exitCode, not exit(): exit() can cut off piped output before CI reads it.
|
||||
process.exitCode = main();
|
||||
}
|
||||
@@ -1,5 +1,5 @@
|
||||
<script lang="ts">
|
||||
import { onMount } from 'svelte';
|
||||
import { onMount, tick } from 'svelte';
|
||||
import AboutTab from '@/lib/components/AboutTab.svelte';
|
||||
import EditTab from '@/lib/components/EditTab.svelte';
|
||||
import ExportTab from '@/lib/components/ExportTab.svelte';
|
||||
@@ -11,6 +11,7 @@
|
||||
import TabBar from '@/lib/components/TabBar.svelte';
|
||||
import ThemeToggle from '@/lib/components/ThemeToggle.svelte';
|
||||
import Toast from '@/lib/components/Toast.svelte';
|
||||
import { focusIfLost } from '@/lib/components/focus-heading';
|
||||
import Icon from '@/lib/components/icons/Icon.svelte';
|
||||
import { t } from '@/lib/i18n/index.svelte';
|
||||
import { isWriting } from '@/lib/stores/import-session.svelte';
|
||||
@@ -52,6 +53,20 @@
|
||||
document.title = `${t(ROUTE_KEYS[getRoute()])} · ${t('common.appName')}`;
|
||||
});
|
||||
|
||||
// A route change can take the focused control with it — "Open in Edit" on
|
||||
// the import report unmounts the button that was clicked — and focus then
|
||||
// falls to <body>, back at the top of the page. It goes to <main> instead.
|
||||
// Only when it was lost — the tab and status-bar buttons keep theirs — and
|
||||
// never while the page is loading: `startRouting` reads the hash on mount,
|
||||
// which is a route change to this effect and not to the user, and a fresh
|
||||
// load must not move focus by itself.
|
||||
let routeSettled = false;
|
||||
$effect(() => {
|
||||
void getRoute();
|
||||
if (!routeSettled) return;
|
||||
void tick().then(() => focusIfLost(mainEl));
|
||||
});
|
||||
|
||||
onMount(() => {
|
||||
// The tab bar and the footer already refuse to navigate mid-write. This
|
||||
// closes the third door: browser Back, which fires `hashchange` directly
|
||||
@@ -61,6 +76,10 @@
|
||||
isBlocked: isWriting,
|
||||
onBlocked: () => pushToast(t('common.busy'), 'info'),
|
||||
});
|
||||
// After the route the hash named has rendered (see the effect above).
|
||||
void tick().then(() => {
|
||||
routeSettled = true;
|
||||
});
|
||||
|
||||
// Leaving mid-write would kill the queue with the tab (docs/03 §5).
|
||||
const onBeforeUnload = (event: BeforeUnloadEvent): void => {
|
||||
|
||||
@@ -2,6 +2,7 @@
|
||||
import { onMount } from 'svelte';
|
||||
import { getAppVersion } from '@/lib/browser/app-info';
|
||||
import { getRootChildren } from '@/lib/browser/bookmarks';
|
||||
import { countLive } from '@/lib/browser/live-tree';
|
||||
import { type ManagerRoute, openManager } from '@/lib/browser/open-manager';
|
||||
import Icon, { type IconName } from '@/lib/components/icons/Icon.svelte';
|
||||
import { num, t, tPlural } from '@/lib/i18n/index.svelte';
|
||||
@@ -27,21 +28,10 @@
|
||||
*/
|
||||
async function countTree(): Promise<void> {
|
||||
try {
|
||||
let bookmarks = 0;
|
||||
let folders = 0;
|
||||
const stack: { url?: string; children?: unknown[] }[] = [];
|
||||
for (const root of await getRootChildren()) {
|
||||
// A loop, not push(...spread): Other Bookmarks can hold 100k children.
|
||||
for (const child of root.children ?? []) stack.push(child);
|
||||
}
|
||||
while (stack.length > 0) {
|
||||
const node = stack.pop();
|
||||
if (node === undefined) break;
|
||||
if (node.url === undefined) folders++;
|
||||
else bookmarks++;
|
||||
// SAFETY: children of a LiveNode are LiveNodes, which have this shape.
|
||||
for (const child of (node.children ?? []) as typeof stack) stack.push(child);
|
||||
}
|
||||
// Inside the roots, separators (Firefox) apart: a separator's url is
|
||||
// "data:", and counting by url called every one a bookmark.
|
||||
const inside = (await getRootChildren()).flatMap((root) => root.children ?? []);
|
||||
const { bookmarks, folders } = countLive(inside);
|
||||
counts = { bookmarks, folders };
|
||||
} catch {
|
||||
counts = undefined;
|
||||
@@ -227,7 +217,7 @@
|
||||
|
||||
.settings {
|
||||
display: inline-flex;
|
||||
padding: 3px;
|
||||
padding: 4px;
|
||||
border: 1px solid transparent;
|
||||
border-radius: var(--radius-sm);
|
||||
background: none;
|
||||
|
||||
@@ -25,6 +25,15 @@ export function getAppVersion(): string {
|
||||
}
|
||||
}
|
||||
|
||||
/** This install's extension id, or `''` when it cannot be read. Never throws. */
|
||||
export function getExtensionId(): string {
|
||||
try {
|
||||
return browser.runtime.id;
|
||||
} catch {
|
||||
return '';
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* The `generator` string written into exported and backup BM JSON.
|
||||
*
|
||||
|
||||
+36
-187
@@ -3,60 +3,20 @@
|
||||
*
|
||||
* Purpose: the single audited surface where the extension talks to the
|
||||
* bookmarks API. Components never call `chrome.*` directly.
|
||||
* Inputs / guarantees: raw rejections are mapped to `BmBrowserError`; the live
|
||||
* tree is converted into the pure `BookmarkNode` file model here, including
|
||||
* the millisecond→second conversion (`chrome.bookmarks` reports `dateAdded`
|
||||
* in ms; `BookmarkNode.addDate` is seconds — docs/05 §4).
|
||||
* Inputs / guarantees: raw rejections are mapped to `BmBrowserError`. The
|
||||
* pure half — the node shape, separators, counts and the conversion into the
|
||||
* `BookmarkNode` file model — is `live-tree.ts`; which folders are the roots
|
||||
* is `roots.ts`. Firefox's API differs from Chromium's in ways this file
|
||||
* absorbs (docs/02 §4): its move index (below) and its missing events.
|
||||
*/
|
||||
import { browser } from 'wxt/browser';
|
||||
import type { BookmarkNode } from '../core/model';
|
||||
import { millisToSeconds } from '../core/timestamps';
|
||||
import { BmAborted, BmBrowserError, BmEnvError, BmPartialWrite } from './errors';
|
||||
import { BmAborted, BmBrowserError, BmPartialWrite } from './errors';
|
||||
import { type LiveNode, type MoveDestination, type MoveIndexRule, moveIndexFor } from './live-tree';
|
||||
|
||||
/** The live-tree node. Unlike `BookmarkNode` it carries browser identity. */
|
||||
export interface LiveNode {
|
||||
id: string;
|
||||
parentId?: string;
|
||||
index?: number;
|
||||
title: string;
|
||||
url?: string;
|
||||
dateAdded?: number;
|
||||
dateGroupModified?: number;
|
||||
/** Set by Chrome on policy-managed nodes; such nodes reject writes. */
|
||||
unmodifiable?: string;
|
||||
/**
|
||||
* Chrome 134+: which permanent folder a root is ('bookmarks-bar', 'other',
|
||||
* 'mobile', 'managed'), and whether it is in the signed-in account's storage
|
||||
* rather than this device's. Both exist from the 136 floor up.
|
||||
*/
|
||||
folderType?: string;
|
||||
syncing?: boolean;
|
||||
children?: LiveNode[];
|
||||
}
|
||||
|
||||
export interface BookmarkRoots {
|
||||
/** Bookmarks Bar. */
|
||||
toolbarId: string;
|
||||
/** Other Bookmarks. */
|
||||
otherId: string;
|
||||
/** Mobile Bookmarks, when the profile has one. */
|
||||
mobileId: string | undefined;
|
||||
/** The same three roots as nodes, children included — Merge matches inside them. */
|
||||
toolbar: LiveNode;
|
||||
other: LiveNode;
|
||||
mobile: LiveNode | undefined;
|
||||
/** Writable top-level folders, in tree order, excluding managed ones. */
|
||||
writable: LiveNode[];
|
||||
/**
|
||||
* The roots Replace backs up and empties: exactly the destinations above.
|
||||
* Never an account-storage root this import does not write back into —
|
||||
* deleting one would sync the deletion to every device, and the restore
|
||||
* would land its bookmarks in local storage.
|
||||
*/
|
||||
replaceable: LiveNode[];
|
||||
/** Every top-level folder, managed ones included — what "already in this browser" means. */
|
||||
all: LiveNode[];
|
||||
}
|
||||
// The node shape and the move-index rule live with the pure helpers
|
||||
// (live-tree.ts); re-exported so the adapter stays the one import for code
|
||||
// that talks to the browser.
|
||||
export type { LiveNode, MoveDestination } from './live-tree';
|
||||
|
||||
async function guard<T>(operation: string, run: () => Promise<T>): Promise<T> {
|
||||
try {
|
||||
@@ -72,139 +32,6 @@ export async function getRootChildren(): Promise<LiveNode[]> {
|
||||
return (tree[0]?.children ?? []) as LiveNode[];
|
||||
}
|
||||
|
||||
const FOLDER_IDS = { 'bookmarks-bar': '1', other: '2', mobile: '3' } as const;
|
||||
|
||||
/**
|
||||
* Desktop Chrome leaves an EMPTY Mobile root out of `getTree()`, so a restore
|
||||
* into a fresh profile found no Mobile root and nested those bookmarks under
|
||||
* Other. The node still exists, and accepts writes; ask for it by id.
|
||||
*/
|
||||
async function hiddenMobileRoot(): Promise<LiveNode | undefined> {
|
||||
try {
|
||||
const [node] = (await browser.bookmarks.get(FOLDER_IDS.mobile)) as LiveNode[];
|
||||
const usable =
|
||||
node !== undefined &&
|
||||
node.url === undefined &&
|
||||
node.unmodifiable === undefined &&
|
||||
node.syncing !== true &&
|
||||
(node.folderType === undefined || node.folderType === 'mobile');
|
||||
return usable ? { ...node, children: node.children ?? [] } : undefined;
|
||||
} catch {
|
||||
return undefined;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Resolve the destination roots.
|
||||
*
|
||||
* By `folderType` first — Chrome 134+ can list a signed-in account's own bar,
|
||||
* Other and Mobile beside this device's, and the old by-id-then-by-position
|
||||
* rule mixed the two sets up. This device's roots are the destinations;
|
||||
* account roots are never written to or emptied. The ids "1"/"2"/"3" and then
|
||||
* position remain as fallbacks for a browser without `folderType`. Nodes
|
||||
* carrying `unmodifiable` (the enterprise "Managed bookmarks" folder) are
|
||||
* excluded everywhere — writing to or removing them rejects.
|
||||
*/
|
||||
export async function getRoots(): Promise<BookmarkRoots> {
|
||||
const children = await getRootChildren();
|
||||
const writable = children.filter((node) => node.unmodifiable === undefined);
|
||||
const local = writable.filter((node) => node.syncing !== true);
|
||||
const typed = local.some((node) => node.folderType !== undefined);
|
||||
|
||||
const pick = (type: keyof typeof FOLDER_IDS): LiveNode | undefined =>
|
||||
local.find((node) => node.folderType === type) ??
|
||||
local.find((node) => node.id === FOLDER_IDS[type]);
|
||||
const toolbar = pick('bookmarks-bar') ?? (typed ? undefined : local[0]);
|
||||
const other = pick('other') ?? (typed ? undefined : local.find((n) => n !== toolbar));
|
||||
const mobile =
|
||||
pick('mobile') ??
|
||||
(typed ? undefined : local.find((n) => n !== toolbar && n !== other)) ??
|
||||
(await hiddenMobileRoot());
|
||||
|
||||
if (toolbar === undefined || other === undefined) {
|
||||
// Not a BmBrowserError: nothing refused anything. Every root this profile
|
||||
// has is policy-managed, so there is nowhere an extension may write, and
|
||||
// "the browser refused a bookmark operation" would be actively misleading.
|
||||
throw new BmEnvError('NO_WRITABLE_ROOTS', `${children.length} root(s), none writable`);
|
||||
}
|
||||
|
||||
return {
|
||||
toolbarId: toolbar.id,
|
||||
otherId: other.id,
|
||||
mobileId: mobile?.id,
|
||||
toolbar,
|
||||
other,
|
||||
mobile,
|
||||
writable,
|
||||
replaceable: mobile === undefined ? [toolbar, other] : [toolbar, other, mobile],
|
||||
all: children,
|
||||
};
|
||||
}
|
||||
|
||||
export interface ToNodesOptions {
|
||||
/**
|
||||
* Id of the Bookmarks Bar. The matching node is marked `toolbar: true`.
|
||||
*
|
||||
* Without this the marker is lost, and re-importing the file (including the
|
||||
* Replace safety backup) lands the entire toolbar under Other Bookmarks —
|
||||
* `03 §1` routes purely on that flag.
|
||||
*/
|
||||
toolbarId?: string;
|
||||
/**
|
||||
* Ids of Other and Mobile Bookmarks, marked `root: 'other'`/`'mobile'` for
|
||||
* the same reason: without them a restore nested both one level too deep.
|
||||
*/
|
||||
otherId?: string;
|
||||
mobileId?: string;
|
||||
}
|
||||
|
||||
/** The marker ids for a whole-tree conversion — what an export or backup passes. */
|
||||
export function rootMarkersOf(roots: BookmarkRoots): ToNodesOptions {
|
||||
return {
|
||||
toolbarId: roots.toolbarId,
|
||||
otherId: roots.otherId,
|
||||
...(roots.mobileId !== undefined && { mobileId: roots.mobileId }),
|
||||
};
|
||||
}
|
||||
|
||||
function markerOf(id: string, options: ToNodesOptions): Pick<BookmarkNode, 'toolbar' | 'root'> {
|
||||
if (id === options.toolbarId) return { toolbar: true };
|
||||
if (id === options.otherId) return { root: 'other' };
|
||||
if (id === options.mobileId) return { root: 'mobile' };
|
||||
return {};
|
||||
}
|
||||
|
||||
/** Convert the live tree into the pure file model (ms → s, ids dropped). */
|
||||
export function toBookmarkNodes(
|
||||
nodes: readonly LiveNode[],
|
||||
options: ToNodesOptions = {},
|
||||
): BookmarkNode[] {
|
||||
return nodes.map((node) => {
|
||||
const addDate = millisToSeconds(node.dateAdded);
|
||||
const isFolderNode = node.url === undefined;
|
||||
// dateGroupModified is a FOLDER field — Chrome does not set it on
|
||||
// bookmarks, and our HTML serializer only emits LAST_MODIFIED on <H3>.
|
||||
const lastModified = isFolderNode ? millisToSeconds(node.dateGroupModified) : undefined;
|
||||
return {
|
||||
title: node.title,
|
||||
...(node.url !== undefined && { url: node.url }),
|
||||
...(addDate !== undefined && { addDate }),
|
||||
...(lastModified !== undefined && { lastModified }),
|
||||
...(isFolderNode && markerOf(node.id, options)),
|
||||
...(isFolderNode && { children: toBookmarkNodes(node.children ?? [], options) }),
|
||||
};
|
||||
});
|
||||
}
|
||||
|
||||
/** Flatten a live tree, parents before children. Used by dedupe and #edit. */
|
||||
export function flattenLive(nodes: readonly LiveNode[], into: LiveNode[] = []): LiveNode[] {
|
||||
for (const node of nodes) {
|
||||
into.push(node);
|
||||
if (node.children !== undefined) flattenLive(node.children, into);
|
||||
}
|
||||
return into;
|
||||
}
|
||||
|
||||
/** The current children of one folder — what a bulk command re-plans from. */
|
||||
export async function getChildren(id: string): Promise<LiveNode[]> {
|
||||
return (await guard('bookmarks.getChildren', () =>
|
||||
@@ -226,11 +53,33 @@ export async function update(id: string, changes: { title?: string; url?: string
|
||||
await guard('bookmarks.update', () => browser.bookmarks.update(id, changes));
|
||||
}
|
||||
|
||||
const MOVE_INDEX_RULE: MoveIndexRule = import.meta.env.FIREFOX ? 'firefox' : 'chromium';
|
||||
|
||||
/**
|
||||
* The longest address this browser accepts in a bookmark, or `undefined` for
|
||||
* none. Firefox refuses anything over 65 536 characters (Places'
|
||||
* `MAX_URL_LENGTH`) — mid-write, so the import drops such addresses up front
|
||||
* (docs/04 §1.2); Chromium has no limit an import can reach.
|
||||
*/
|
||||
export const MAX_URL_LENGTH: number | undefined = import.meta.env.FIREFOX ? 65_536 : undefined;
|
||||
|
||||
/**
|
||||
* Move a node. Resolves to the index the browser says the node now has, which
|
||||
* the caller compares with `position.local` — a disagreement means the tree on
|
||||
* screen no longer matches the browser's, and it is re-read (docs/03 §3).
|
||||
*/
|
||||
export async function move(
|
||||
id: string,
|
||||
destination: { parentId?: string; index?: number },
|
||||
): Promise<void> {
|
||||
await guard('bookmarks.move', () => browser.bookmarks.move(id, destination));
|
||||
destination: MoveDestination,
|
||||
rule: MoveIndexRule = MOVE_INDEX_RULE,
|
||||
): Promise<number | undefined> {
|
||||
const { parentId, position } = destination;
|
||||
const details = {
|
||||
...(parentId !== undefined && { parentId }),
|
||||
...(position !== undefined && { index: moveIndexFor(position, rule) }),
|
||||
};
|
||||
const moved = await guard('bookmarks.move', () => browser.bookmarks.move(id, details));
|
||||
return (moved as { index?: number } | undefined)?.index;
|
||||
}
|
||||
|
||||
/** Remove a single bookmark. Folders need `removeTree`. */
|
||||
|
||||
@@ -102,14 +102,28 @@ export interface DiagnosticsContext {
|
||||
theme: string;
|
||||
}
|
||||
|
||||
/**
|
||||
* The browser and its major version from the user agent: "Firefox 160",
|
||||
* "Edge 142", "Chrome 142", or "unknown". Edge's agent also says Chrome, so it
|
||||
* is read first. Since v1.3.0 — until then the report carried `chromeMajor`,
|
||||
* which said "unknown" on Firefox.
|
||||
*/
|
||||
export function browserOf(userAgent: string): string {
|
||||
for (const [name, pattern] of [
|
||||
['Firefox', /Firefox\/(\d+)/],
|
||||
['Edge', /Edg\/(\d+)/],
|
||||
['Chrome', /Chrome\/(\d+)/],
|
||||
] as const) {
|
||||
const major = pattern.exec(userAgent)?.[1];
|
||||
if (major !== undefined) return `${name} ${major}`;
|
||||
}
|
||||
return 'unknown';
|
||||
}
|
||||
|
||||
/** The report the About tab copies: context first, then the events, oldest first. */
|
||||
export function snapshot(context: DiagnosticsContext): string {
|
||||
const chrome = /Chrome\/(\d+)/.exec(globalThis.navigator?.userAgent ?? '')?.[1] ?? 'unknown';
|
||||
return JSON.stringify(
|
||||
{ app: 'BookmarkMagic', ...context, chromeMajor: chrome, events: entries },
|
||||
null,
|
||||
2,
|
||||
);
|
||||
const browser = browserOf(globalThis.navigator?.userAgent ?? '');
|
||||
return JSON.stringify({ app: 'BookmarkMagic', ...context, browser, events: entries }, null, 2);
|
||||
}
|
||||
|
||||
/** Test teardown — module state outlives a single `it()`. */
|
||||
|
||||
@@ -0,0 +1,173 @@
|
||||
/**
|
||||
* The live bookmark tree as the browser reports it — docs/02 §4.
|
||||
*
|
||||
* Purpose: the pure half of the bookmarks adapter — the node shape, Firefox's
|
||||
* separators, the counts, and the conversion into the file model. No
|
||||
* browser call lives here, so every line is tested directly.
|
||||
* Guarantees: separators are recognised by `type` alone. Firefox gives them
|
||||
* `url: "data:"`, so every "has a url, so it is a bookmark" test in the code
|
||||
* would otherwise count, export, dedupe and open them as bookmarks.
|
||||
*/
|
||||
import type { BookmarkNode } from '../core/model';
|
||||
import { millisToSeconds } from '../core/timestamps';
|
||||
|
||||
/** The live-tree node. Unlike `BookmarkNode` it carries browser identity. */
|
||||
export interface LiveNode {
|
||||
id: string;
|
||||
parentId?: string;
|
||||
index?: number;
|
||||
title: string;
|
||||
url?: string;
|
||||
dateAdded?: number;
|
||||
dateGroupModified?: number;
|
||||
/** Set by Chrome on policy-managed nodes; such nodes reject writes. */
|
||||
unmodifiable?: string;
|
||||
/**
|
||||
* Chrome 134+: which permanent folder a root is ('bookmarks-bar', 'other',
|
||||
* 'mobile', 'managed'), and whether it is in the signed-in account's storage
|
||||
* rather than this device's. Both exist from the 136 floor up; Firefox has
|
||||
* neither.
|
||||
*/
|
||||
folderType?: string;
|
||||
syncing?: boolean;
|
||||
/** Firefox: 'bookmark', 'folder' or 'separator'. Chromium does not send it. */
|
||||
type?: string;
|
||||
children?: LiveNode[];
|
||||
}
|
||||
|
||||
/** A Firefox separator. By `type`, never by url: a separator's url is "data:". */
|
||||
export function isSeparator(node: { type?: string }): boolean {
|
||||
return node.type === 'separator';
|
||||
}
|
||||
|
||||
/**
|
||||
* The forest without its separators — for everything that reads bookmarks as
|
||||
* bookmarks (the dedupe index, Merge's folder matching). Untouched branches
|
||||
* are returned as they are.
|
||||
*/
|
||||
export function withoutSeparators(nodes: readonly LiveNode[]): LiveNode[] {
|
||||
const out: LiveNode[] = [];
|
||||
for (const node of nodes) {
|
||||
if (isSeparator(node)) continue;
|
||||
out.push(
|
||||
node.children === undefined ? node : { ...node, children: withoutSeparators(node.children) },
|
||||
);
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
export interface LiveCounts {
|
||||
bookmarks: number;
|
||||
folders: number;
|
||||
/** Firefox only; always 0 in a Chromium browser. */
|
||||
separators: number;
|
||||
}
|
||||
|
||||
/**
|
||||
* Count what a forest holds, separators apart. Iterative: Other Bookmarks can
|
||||
* hold 100k children, and the live tree has no depth cap.
|
||||
*/
|
||||
export function countLive(nodes: readonly LiveNode[]): LiveCounts {
|
||||
const counts: LiveCounts = { bookmarks: 0, folders: 0, separators: 0 };
|
||||
const stack: LiveNode[] = [];
|
||||
for (const node of nodes) stack.push(node);
|
||||
while (stack.length > 0) {
|
||||
const node = stack.pop();
|
||||
if (node === undefined) break;
|
||||
if (isSeparator(node)) counts.separators++;
|
||||
else if (node.url === undefined) counts.folders++;
|
||||
else counts.bookmarks++;
|
||||
for (const child of node.children ?? []) stack.push(child);
|
||||
}
|
||||
return counts;
|
||||
}
|
||||
|
||||
export interface ToNodesOptions {
|
||||
/**
|
||||
* Id of the Bookmarks Bar. The matching node is marked `toolbar: true`.
|
||||
*
|
||||
* Without this the marker is lost, and re-importing the file (including the
|
||||
* Replace safety backup) lands the entire toolbar under Other Bookmarks —
|
||||
* `03 §1` routes purely on that flag.
|
||||
*/
|
||||
toolbarId?: string;
|
||||
/**
|
||||
* Ids of Other and Mobile Bookmarks, and of Firefox's Bookmarks Menu,
|
||||
* marked `root: 'other'`/`'mobile'`/`'menu'` for the same reason: without
|
||||
* them a restore nested each one level too deep.
|
||||
*/
|
||||
otherId?: string;
|
||||
mobileId?: string;
|
||||
menuId?: string;
|
||||
}
|
||||
|
||||
function markerOf(id: string, options: ToNodesOptions): Pick<BookmarkNode, 'toolbar' | 'root'> {
|
||||
if (id === options.toolbarId) return { toolbar: true };
|
||||
if (id === options.otherId) return { root: 'other' };
|
||||
if (id === options.mobileId) return { root: 'mobile' };
|
||||
if (id === options.menuId) return { root: 'menu' };
|
||||
return {};
|
||||
}
|
||||
|
||||
/**
|
||||
* Convert the live tree into the pure file model (ms → s, ids dropped).
|
||||
* Separators are left out: no format BookmarkMagic writes can hold one
|
||||
* (docs/04).
|
||||
*/
|
||||
export function toBookmarkNodes(
|
||||
nodes: readonly LiveNode[],
|
||||
options: ToNodesOptions = {},
|
||||
): BookmarkNode[] {
|
||||
const out: BookmarkNode[] = [];
|
||||
for (const node of nodes) {
|
||||
if (isSeparator(node)) continue;
|
||||
const addDate = millisToSeconds(node.dateAdded);
|
||||
const isFolderNode = node.url === undefined;
|
||||
// dateGroupModified is a FOLDER field — Chrome does not set it on
|
||||
// bookmarks, and our HTML serializer only emits LAST_MODIFIED on <H3>.
|
||||
const lastModified = isFolderNode ? millisToSeconds(node.dateGroupModified) : undefined;
|
||||
out.push({
|
||||
title: node.title,
|
||||
...(node.url !== undefined && { url: node.url }),
|
||||
...(addDate !== undefined && { addDate }),
|
||||
...(lastModified !== undefined && { lastModified }),
|
||||
...(isFolderNode && markerOf(node.id, options)),
|
||||
...(isFolderNode && { children: toBookmarkNodes(node.children ?? [], options) }),
|
||||
});
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
/**
|
||||
* How a browser counts `bookmarks.move`'s index for a move inside one folder
|
||||
* (docs/05 §10). Chromium counts as if the node were still in place; Firefox
|
||||
* counts after removing it, because Places stores the final position. Moving
|
||||
* `a` after `c` in `[a, b, c]` is index 3 in Chrome and 2 in Firefox — and
|
||||
* sending Chrome's number to Firefox made every rightward drag land one place
|
||||
* too far and Alt+↓ move two places.
|
||||
*/
|
||||
export type MoveIndexRule = 'chromium' | 'firefox';
|
||||
|
||||
/** Where a node goes: a folder, and optionally a place in it counted both ways (`planDrop`). */
|
||||
export interface MoveDestination {
|
||||
parentId?: string;
|
||||
/** `api` counted before the node's removal (Chromium's rule), `local` after it. */
|
||||
position?: { api: number; local: number };
|
||||
}
|
||||
|
||||
/** The index to send under a browser's rule. */
|
||||
export function moveIndexFor(
|
||||
position: { api: number; local: number },
|
||||
rule: MoveIndexRule,
|
||||
): number {
|
||||
return rule === 'firefox' ? position.local : position.api;
|
||||
}
|
||||
|
||||
/** Flatten a live tree, parents before children. Used by dedupe and #edit. */
|
||||
export function flattenLive(nodes: readonly LiveNode[], into: LiveNode[] = []): LiveNode[] {
|
||||
for (const node of nodes) {
|
||||
into.push(node);
|
||||
if (node.children !== undefined) flattenLive(node.children, into);
|
||||
}
|
||||
return into;
|
||||
}
|
||||
@@ -0,0 +1,139 @@
|
||||
/**
|
||||
* Which live folders are the browser's permanent roots — docs/02 §4.
|
||||
*
|
||||
* Purpose: find the import's destinations — the bar, Other, Mobile, and on
|
||||
* Firefox the Bookmarks Menu — in whatever browser this runs in.
|
||||
* Guarantees: this device's roots only (a signed-in Chrome account's own roots
|
||||
* are listed but never written to or emptied); policy-managed roots never;
|
||||
* and on Firefox the Menu is never mistaken for the bar.
|
||||
*/
|
||||
import { browser } from 'wxt/browser';
|
||||
import { getRootChildren } from './bookmarks';
|
||||
import { BmEnvError } from './errors';
|
||||
import type { LiveNode, ToNodesOptions } from './live-tree';
|
||||
|
||||
export interface BookmarkRoots {
|
||||
/** Bookmarks Bar. */
|
||||
toolbarId: string;
|
||||
/** Other Bookmarks. */
|
||||
otherId: string;
|
||||
/** Mobile Bookmarks, when the profile has one. */
|
||||
mobileId: string | undefined;
|
||||
/** Firefox's Bookmarks Menu. No Chromium browser has one. */
|
||||
menuId: string | undefined;
|
||||
/** The same roots as nodes, children included — Merge matches inside them. */
|
||||
toolbar: LiveNode;
|
||||
other: LiveNode;
|
||||
mobile: LiveNode | undefined;
|
||||
menu: LiveNode | undefined;
|
||||
/** Writable top-level folders, in tree order, excluding managed ones. */
|
||||
writable: LiveNode[];
|
||||
/**
|
||||
* The roots Replace backs up and empties: exactly the destinations above.
|
||||
* Never an account-storage root this import does not write back into —
|
||||
* deleting one would sync the deletion to every device, and the restore
|
||||
* would land its bookmarks in local storage.
|
||||
*/
|
||||
replaceable: LiveNode[];
|
||||
/** Every top-level folder, managed ones included — what "already in this browser" means. */
|
||||
all: LiveNode[];
|
||||
}
|
||||
|
||||
/** Chromium's stable ids for the three permanent folders. */
|
||||
const CHROMIUM_IDS = { 'bookmarks-bar': '1', other: '2', mobile: '3' } as const;
|
||||
|
||||
/** Firefox's permanent folders — Places GUIDs, the same in every profile. */
|
||||
const FIREFOX_IDS = {
|
||||
'bookmarks-bar': 'toolbar_____',
|
||||
other: 'unfiled_____',
|
||||
mobile: 'mobile______',
|
||||
} as const;
|
||||
const FIREFOX_MENU_ID = 'menu________';
|
||||
|
||||
/**
|
||||
* Desktop Chrome leaves an EMPTY Mobile root out of `getTree()`, so a restore
|
||||
* into a fresh profile found no Mobile root and nested those bookmarks under
|
||||
* Other. The node still exists, and accepts writes; ask for it by id. (Firefox
|
||||
* always lists its Mobile root, and rejects the id "3" — caught here.)
|
||||
*/
|
||||
async function hiddenMobileRoot(): Promise<LiveNode | undefined> {
|
||||
try {
|
||||
const [node] = (await browser.bookmarks.get(CHROMIUM_IDS.mobile)) as LiveNode[];
|
||||
const usable =
|
||||
node !== undefined &&
|
||||
node.url === undefined &&
|
||||
node.unmodifiable === undefined &&
|
||||
node.syncing !== true &&
|
||||
(node.folderType === undefined || node.folderType === 'mobile');
|
||||
return usable ? { ...node, children: node.children ?? [] } : undefined;
|
||||
} catch {
|
||||
return undefined;
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Resolve the destination roots.
|
||||
*
|
||||
* By `folderType` first — Chrome 134+ can list a signed-in account's own bar,
|
||||
* Other and Mobile beside this device's, and the old by-id-then-by-position
|
||||
* rule mixed the two sets up. Then the stable Chromium ids, then Firefox's
|
||||
* GUIDs, and position last. The Bookmarks Menu is never a candidate for a
|
||||
* position: Firefox lists it first, and until v1.3.0 the position fallback
|
||||
* took it for the bar — Replace would have emptied the Menu and the toolbar
|
||||
* and restored the bar's bookmarks into the Menu. Nodes carrying
|
||||
* `unmodifiable` (the enterprise "Managed bookmarks" folder) are excluded
|
||||
* everywhere — writing to or removing them rejects.
|
||||
*/
|
||||
export async function getRoots(): Promise<BookmarkRoots> {
|
||||
const children = await getRootChildren();
|
||||
const writable = children.filter((node) => node.unmodifiable === undefined);
|
||||
const local = writable.filter((node) => node.syncing !== true);
|
||||
const typed = local.some((node) => node.folderType !== undefined);
|
||||
const menu = local.find((node) => node.id === FIREFOX_MENU_ID);
|
||||
const positional = local.filter((node) => node !== menu);
|
||||
|
||||
const pick = (type: keyof typeof CHROMIUM_IDS): LiveNode | undefined =>
|
||||
local.find((node) => node.folderType === type) ??
|
||||
local.find((node) => node.id === CHROMIUM_IDS[type]) ??
|
||||
local.find((node) => node.id === FIREFOX_IDS[type]);
|
||||
const toolbar = pick('bookmarks-bar') ?? (typed ? undefined : positional[0]);
|
||||
const other = pick('other') ?? (typed ? undefined : positional.find((n) => n !== toolbar));
|
||||
const mobile =
|
||||
pick('mobile') ??
|
||||
(typed ? undefined : positional.find((n) => n !== toolbar && n !== other)) ??
|
||||
(await hiddenMobileRoot());
|
||||
|
||||
if (toolbar === undefined || other === undefined) {
|
||||
// Not a BmBrowserError: nothing refused anything. Every root this profile
|
||||
// has is policy-managed, so there is nowhere an extension may write, and
|
||||
// "the browser refused a bookmark operation" would be actively misleading.
|
||||
throw new BmEnvError('NO_WRITABLE_ROOTS', `${children.length} root(s), none writable`);
|
||||
}
|
||||
|
||||
const replaceable = [toolbar, other];
|
||||
if (mobile !== undefined) replaceable.push(mobile);
|
||||
if (menu !== undefined) replaceable.push(menu);
|
||||
return {
|
||||
toolbarId: toolbar.id,
|
||||
otherId: other.id,
|
||||
mobileId: mobile?.id,
|
||||
menuId: menu?.id,
|
||||
toolbar,
|
||||
other,
|
||||
mobile,
|
||||
menu,
|
||||
writable,
|
||||
replaceable,
|
||||
all: children,
|
||||
};
|
||||
}
|
||||
|
||||
/** The marker ids for a whole-tree conversion — what an export or backup passes. */
|
||||
export function rootMarkersOf(roots: BookmarkRoots): ToNodesOptions {
|
||||
return {
|
||||
toolbarId: roots.toolbarId,
|
||||
otherId: roots.otherId,
|
||||
...(roots.mobileId !== undefined && { mobileId: roots.mobileId }),
|
||||
...(roots.menuId !== undefined && { menuId: roots.menuId }),
|
||||
};
|
||||
}
|
||||
@@ -10,7 +10,7 @@
|
||||
import { browser } from 'wxt/browser';
|
||||
import type { CsvDelimiter } from '../core/csv-dialect';
|
||||
import type { MarkdownStyle } from '../core/serialize/markdown';
|
||||
import type { Locale } from '../i18n/resolve-locale';
|
||||
import { LOCALES, type Locale } from '../i18n/resolve-locale';
|
||||
import { record } from './diagnostics';
|
||||
|
||||
export type ThemePreference = 'system' | 'light' | 'dark';
|
||||
@@ -55,7 +55,7 @@ function coerceSettings(raw: unknown): Settings {
|
||||
allowed.includes(raw[key] as Settings[K]) ? (raw[key] as Settings[K]) : DEFAULT_SETTINGS[key];
|
||||
|
||||
return {
|
||||
locale: pick('locale', ['auto', 'en', 'vi', 'ja']),
|
||||
locale: pick('locale', ['auto', ...LOCALES]),
|
||||
theme: pick('theme', ['system', 'light', 'dark']),
|
||||
defaultExportFormat: pick('defaultExportFormat', [
|
||||
'netscape-html',
|
||||
|
||||
@@ -1,7 +1,15 @@
|
||||
<script lang="ts">
|
||||
import { getAppVersion } from '../browser/app-info';
|
||||
import { getAppVersion, getExtensionId } from '../browser/app-info';
|
||||
import { dateTime, t } from '../i18n/index.svelte';
|
||||
import { CHANGELOG_URL, DONATE_LINKS, ISSUES_URL, LEGAL_URLS, REPO_URL, STORE_URL } from '../links';
|
||||
import {
|
||||
ACCESSIBILITY_URL,
|
||||
CHANGELOG_URL,
|
||||
DONATE_LINKS,
|
||||
ISSUES_URL,
|
||||
LEGAL_URLS,
|
||||
REPO_URL,
|
||||
storeUrlFor,
|
||||
} from '../links';
|
||||
import { copyToClipboard } from '../browser/clipboard';
|
||||
import { snapshot } from '../browser/diagnostics';
|
||||
import { getAcceptance } from '../stores/legal.svelte';
|
||||
@@ -11,6 +19,9 @@
|
||||
import Icon from './icons/Icon.svelte';
|
||||
|
||||
const version = getAppVersion();
|
||||
// The listing this copy came from (docs/06 §3.5): AMO for the Firefox build,
|
||||
// the Chrome Web Store for its own id, the install page for anything else.
|
||||
const storeUrl = storeUrlFor({ firefox: import.meta.env.FIREFOX, extensionId: getExtensionId() });
|
||||
const acceptance = $derived(getAcceptance());
|
||||
// undefined when acceptedAt is missing or unparseable — storage coerces a
|
||||
// missing timestamp to '', and formatting that would throw inside the render.
|
||||
@@ -47,7 +58,12 @@
|
||||
{t('about.changelog')}<Icon name="external" size={12} />
|
||||
</a>
|
||||
</li>
|
||||
<li><a href={STORE_URL} target="_blank" rel="noopener noreferrer">{t('about.store')}<Icon name="external" size={12} /></a></li>
|
||||
<li>
|
||||
<a href={ACCESSIBILITY_URL} target="_blank" rel="noopener noreferrer">
|
||||
{t('about.accessibility')}<Icon name="external" size={12} />
|
||||
</a>
|
||||
</li>
|
||||
<li><a href={storeUrl} target="_blank" rel="noopener noreferrer">{t('about.store')}<Icon name="external" size={12} /></a></li>
|
||||
</ul>
|
||||
|
||||
<h2 class="eyebrow">{t('about.thirdParty')}</h2>
|
||||
|
||||
@@ -0,0 +1,62 @@
|
||||
<script lang="ts">
|
||||
/**
|
||||
* The chevron that opens a folder — docs/06 §5. One component for the #edit
|
||||
* tree, the import preview and the export picker, so the three cannot drift.
|
||||
*
|
||||
* With a `label` it is a real disclosure button: `aria-expanded`, a name,
|
||||
* a tab stop. Without one it is the #edit tree's mouse shortcut — the tree
|
||||
* itself carries `aria-expanded` and the arrow keys, so the button is hidden
|
||||
* from assistive technology and is not a tab stop. With no `expanded` at all
|
||||
* the row has nothing to open, and an empty slot keeps the columns aligned.
|
||||
*
|
||||
* The glyph is 16 px; the target is 24 (WCAG 2.5.8), grown by a pseudo-element
|
||||
* so the row's layout does not change.
|
||||
*/
|
||||
import Icon from './icons/Icon.svelte';
|
||||
|
||||
interface Props {
|
||||
expanded?: boolean | undefined;
|
||||
label?: string | undefined;
|
||||
onclick?: (event: MouseEvent) => void;
|
||||
}
|
||||
|
||||
let { expanded, label, onclick }: Props = $props();
|
||||
</script>
|
||||
|
||||
{#if expanded === undefined}
|
||||
<span class="disclosure" aria-hidden="true"></span>
|
||||
{:else if label === undefined}
|
||||
<button class="disclosure" tabindex="-1" aria-hidden="true" {onclick}>
|
||||
<Icon name="chevron" size={12} turned={expanded} />
|
||||
</button>
|
||||
{:else}
|
||||
<button class="disclosure" aria-expanded={expanded} aria-label={label} {onclick}>
|
||||
<Icon name="chevron" size={12} turned={expanded} />
|
||||
</button>
|
||||
{/if}
|
||||
|
||||
<style>
|
||||
.disclosure {
|
||||
position: relative;
|
||||
display: inline-flex;
|
||||
align-items: center;
|
||||
justify-content: center;
|
||||
width: 16px;
|
||||
height: 16px;
|
||||
flex: none;
|
||||
background: none;
|
||||
border: none;
|
||||
color: var(--fg-muted);
|
||||
padding: 0;
|
||||
}
|
||||
|
||||
button {
|
||||
cursor: pointer;
|
||||
}
|
||||
|
||||
button::after {
|
||||
content: '';
|
||||
position: absolute;
|
||||
inset: -4px;
|
||||
}
|
||||
</style>
|
||||
@@ -91,6 +91,18 @@
|
||||
background-color: var(--accent-subtle);
|
||||
}
|
||||
|
||||
/* The dashed edge is four background gradients, and a contrast theme removes
|
||||
background images: the zone lost its boundary altogether (docs/06 §5). */
|
||||
@media (forced-colors: active) {
|
||||
.zone {
|
||||
border: 2px dashed ButtonText;
|
||||
}
|
||||
|
||||
.dragging {
|
||||
border-color: Highlight;
|
||||
}
|
||||
}
|
||||
|
||||
.glyph {
|
||||
display: inline-flex;
|
||||
padding: var(--sp-3);
|
||||
|
||||
@@ -0,0 +1,79 @@
|
||||
<script lang="ts">
|
||||
/**
|
||||
* The #edit tab's dialogs — docs/06 §3.3: "Move to…" and the three
|
||||
* confirmations (delete, keep the first of each, Sort A→Z). Markup only:
|
||||
* what each one asks comes from the session, and what happens after a
|
||||
* confirmation — the command, and where focus goes once it is done
|
||||
* (docs/06 §5) — is the tab's, passed in.
|
||||
*/
|
||||
import { countDescendants, displayTitle } from '../edit/edit-node';
|
||||
import { moveTargets } from '../edit/move-target';
|
||||
import { t, tPlural } from '../i18n/index.svelte';
|
||||
import type { EditSession } from '../stores/edit-session.svelte';
|
||||
import ConfirmDialog from './ConfirmDialog.svelte';
|
||||
import MoveToDialog from './MoveToDialog.svelte';
|
||||
|
||||
interface Props {
|
||||
session: EditSession;
|
||||
ondelete: () => void;
|
||||
onkeepFirst: () => void;
|
||||
onsort: () => void;
|
||||
}
|
||||
|
||||
let { session, ondelete, onkeepFirst, onsort }: Props = $props();
|
||||
|
||||
// Only while the dialog is open: it walks every folder in the tree.
|
||||
const targets = $derived(
|
||||
session.movingNode === undefined ? [] : moveTargets(session.roots, session.movingNode),
|
||||
);
|
||||
const descendantCount = $derived(countDescendants(session.pendingDelete));
|
||||
const pendingTitle = $derived(displayTitle(session.pendingDelete, t('edit.untitled')));
|
||||
</script>
|
||||
|
||||
<MoveToDialog
|
||||
node={session.movingNode}
|
||||
{targets}
|
||||
onpick={(parentId) => {
|
||||
const id = session.movingNode?.id;
|
||||
session.movingNode = undefined;
|
||||
if (id !== undefined) void session.moveTo(id, { parentId });
|
||||
}}
|
||||
oncancel={() => (session.movingNode = undefined)}
|
||||
/>
|
||||
|
||||
<ConfirmDialog
|
||||
open={session.pendingDelete !== undefined}
|
||||
danger
|
||||
title={t('edit.deleteTitle')}
|
||||
body={descendantCount > 0
|
||||
? tPlural('edit.deleteFolderBody', descendantCount, { title: pendingTitle })
|
||||
: t('edit.deleteBody', { title: pendingTitle })}
|
||||
confirmLabel={t('edit.delete')}
|
||||
cancelLabel={t('common.cancel')}
|
||||
onconfirm={ondelete}
|
||||
oncancel={() => (session.pendingDelete = undefined)}
|
||||
/>
|
||||
|
||||
<ConfirmDialog
|
||||
open={session.pendingKeepFirst}
|
||||
danger
|
||||
title={t('edit.keepFirstTitle')}
|
||||
body={tPlural(
|
||||
'edit.keepFirstBody',
|
||||
session.duplicateGroups.reduce((n, g) => n + g.nodes.length - 1, 0),
|
||||
)}
|
||||
confirmLabel={t('edit.delete')}
|
||||
cancelLabel={t('common.cancel')}
|
||||
onconfirm={onkeepFirst}
|
||||
oncancel={() => (session.pendingKeepFirst = false)}
|
||||
/>
|
||||
|
||||
<ConfirmDialog
|
||||
open={session.pendingSort !== undefined}
|
||||
title={t('edit.sortTitle', { title: displayTitle(session.pendingSort?.folder, t('edit.untitled')) })}
|
||||
body={tPlural('edit.sortBody', session.pendingSort?.moves.length ?? 0)}
|
||||
confirmLabel={t('edit.sort')}
|
||||
cancelLabel={t('common.cancel')}
|
||||
onconfirm={onsort}
|
||||
oncancel={() => (session.pendingSort = undefined)}
|
||||
/>
|
||||
@@ -2,65 +2,39 @@
|
||||
/**
|
||||
* The #edit tab — docs/03 §3, docs/06 §3.3. Markup and wiring only: state
|
||||
* and commands live in `stores/edit-session.svelte.ts`, live events in
|
||||
* `edit/live-sync.ts`.
|
||||
* `edit/live-sync.ts` (wired by `stores/edit-live.ts`), the dialogs' markup
|
||||
* in `EditDialogs.svelte`.
|
||||
*/
|
||||
import { onMount, tick, untrack } from 'svelte';
|
||||
import { subscribe } from '../browser/bookmarks';
|
||||
import { copyToClipboard } from '../browser/clipboard';
|
||||
import { openBookmarkUrl } from '../browser/open-url';
|
||||
import { countDescendants, displayTitle, toEditNode } from '../edit/edit-node';
|
||||
import { createBatcher } from '../edit/live-sync';
|
||||
import { moveTargets } from '../edit/move-target';
|
||||
import { displayTitle } from '../edit/edit-node';
|
||||
import { type EditNode, findNode } from '../edit/patch-tree';
|
||||
import { onTreeKey } from '../edit/tree-keys';
|
||||
import { getLocale, num, t, tPlural } from '../i18n/index.svelte';
|
||||
import { getLocale, num, t } from '../i18n/index.svelte';
|
||||
import { connectLive } from '../stores/edit-live';
|
||||
import { EditSession } from '../stores/edit-session.svelte';
|
||||
import { pushToast } from '../stores/toast.svelte';
|
||||
import ConfirmDialog from './ConfirmDialog.svelte';
|
||||
import DuplicatePanel from './DuplicatePanel.svelte';
|
||||
import EditDialogs from './EditDialogs.svelte';
|
||||
import EditToolbar from './EditToolbar.svelte';
|
||||
import ErrorCallout from './ErrorCallout.svelte';
|
||||
import { focusIfLost } from './focus-heading';
|
||||
import MoveToDialog from './MoveToDialog.svelte';
|
||||
import TreeList from './TreeList.svelte';
|
||||
|
||||
const session = new EditSession(undefined, getLocale);
|
||||
let searchInput = $state<HTMLInputElement | undefined>();
|
||||
let treeEl = $state<HTMLElement | undefined>();
|
||||
let panelEl = $state<HTMLElement | undefined>();
|
||||
/** What Alt+↑/↓ just did, for the live region below (docs/06 §5). */
|
||||
let announcement = $state('');
|
||||
|
||||
onMount(() => {
|
||||
void session.load();
|
||||
// One patch per frame, and a single re-read for bursts — an import in
|
||||
// another tab sends an event per node (docs/03 §3 "Live sync").
|
||||
const batcher = createBatcher({
|
||||
onFlush: session.applyLiveEvents,
|
||||
onBurst: () => void session.load(),
|
||||
});
|
||||
let importing = false;
|
||||
// Listeners attach on enter and detach on leave: a tab left subscribed
|
||||
// during an import would take one event per created node.
|
||||
const unsubscribe = subscribe({
|
||||
onCreated: (_id, node) => {
|
||||
if (importing || node.parentId === undefined) return;
|
||||
batcher.push({ kind: 'created', parentId: node.parentId, index: node.index, node: toEditNode(node) });
|
||||
},
|
||||
onRemoved: (id) => batcher.push({ kind: 'removed', id }),
|
||||
onChanged: (id, changes) => batcher.push({ kind: 'changed', id, changes }),
|
||||
onMoved: (id, info) => batcher.push({ kind: 'moved', id, ...info }),
|
||||
onChildrenReordered: () => batcher.resync(),
|
||||
onImportBegan: () => {
|
||||
importing = true;
|
||||
},
|
||||
onImportEnded: () => {
|
||||
importing = false;
|
||||
batcher.resync();
|
||||
},
|
||||
});
|
||||
const disconnect = connectLive(session);
|
||||
globalThis.addEventListener('keydown', onWindowKeydown);
|
||||
return () => {
|
||||
unsubscribe();
|
||||
batcher.dispose();
|
||||
disconnect();
|
||||
session.dispose();
|
||||
globalThis.removeEventListener('keydown', onWindowKeydown);
|
||||
};
|
||||
@@ -82,12 +56,6 @@
|
||||
if (node === undefined) return undefined;
|
||||
return node.url === undefined ? node : findNode(session.roots, node.parentId ?? '');
|
||||
});
|
||||
// Only while the dialog is open: it walks every folder in the tree.
|
||||
const targets = $derived(
|
||||
session.movingNode === undefined ? [] : moveTargets(session.roots, session.movingNode),
|
||||
);
|
||||
const descendantCount = $derived(countDescendants(session.pendingDelete));
|
||||
const pendingTitle = $derived(displayTitle(session.pendingDelete, t('edit.untitled')));
|
||||
|
||||
const partialNote = $derived.by(() => {
|
||||
const partial = session.actionError?.partial;
|
||||
@@ -114,8 +82,32 @@
|
||||
pushToast(t(copied ? 'edit.copied' : 'edit.copyFailed'), copied ? 'success' : 'danger');
|
||||
}
|
||||
|
||||
/**
|
||||
* Alt+↑ / Alt+↓. The row's `aria-posinset` changes, but a screen reader does
|
||||
* not re-read the active descendant for that — so the new place is spoken.
|
||||
*/
|
||||
async function nudge(id: string, direction: -1 | 1): Promise<void> {
|
||||
const placed = await session.nudge(id, direction);
|
||||
if (placed === undefined) return;
|
||||
// Emptied first: a region set to the text it already holds says nothing,
|
||||
// and two rows of one name can land on one position.
|
||||
announcement = '';
|
||||
await tick();
|
||||
announcement = t('edit.movedPosition', {
|
||||
title: displayTitle(findNode(session.roots, id), t('edit.untitled')),
|
||||
position: num(placed.position),
|
||||
total: num(placed.total),
|
||||
});
|
||||
await tick();
|
||||
treeEl?.querySelector(`[data-node-id="${CSS.escape(id)}"]`)?.scrollIntoView({ block: 'nearest' });
|
||||
}
|
||||
|
||||
function onKeydown(event: KeyboardEvent): void {
|
||||
onTreeKey(event, session, { open: (node) => void open(node), copy: (node) => void copy(node) });
|
||||
onTreeKey(event, session, {
|
||||
open: (node) => void open(node),
|
||||
copy: (node) => void copy(node),
|
||||
nudge: (id, direction) => void nudge(id, direction),
|
||||
});
|
||||
}
|
||||
|
||||
/** ⌘/Ctrl-F focuses the search box, whatever the case of the F (docs/06 §3.3). */
|
||||
@@ -143,6 +135,18 @@
|
||||
);
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* A bulk command disables the button that started it for as long as it runs
|
||||
* (Sort A→Z), or removes it with what it deleted (keep-first), and the
|
||||
* closing dialog cannot return focus to either. Once the command is over,
|
||||
* a focus that fell to `<body>` is put somewhere deliberate.
|
||||
*/
|
||||
async function afterBulk(run: Promise<void>, target: () => HTMLElement | null | undefined): Promise<void> {
|
||||
await run;
|
||||
await tick();
|
||||
focusIfLost(target());
|
||||
}
|
||||
</script>
|
||||
|
||||
{#if session.loadError !== undefined}
|
||||
@@ -194,52 +198,19 @@
|
||||
</div>
|
||||
{/if}
|
||||
|
||||
<MoveToDialog
|
||||
node={session.movingNode}
|
||||
{targets}
|
||||
onpick={(parentId) => {
|
||||
const id = session.movingNode?.id;
|
||||
session.movingNode = undefined;
|
||||
if (id !== undefined) void session.moveTo(id, { parentId });
|
||||
}}
|
||||
oncancel={() => (session.movingNode = undefined)}
|
||||
/>
|
||||
<!-- Always in the page, and only its text changes: a region inserted already
|
||||
filled is not reliably announced (the same rule as ImportAnnouncer). -->
|
||||
<p class="sr-only" role="status" aria-live="polite">{announcement}</p>
|
||||
|
||||
<ConfirmDialog
|
||||
open={session.pendingDelete !== undefined}
|
||||
danger
|
||||
title={t('edit.deleteTitle')}
|
||||
body={descendantCount > 0
|
||||
? tPlural('edit.deleteFolderBody', descendantCount, { title: pendingTitle })
|
||||
: t('edit.deleteBody', { title: pendingTitle })}
|
||||
confirmLabel={t('edit.delete')}
|
||||
cancelLabel={t('common.cancel')}
|
||||
onconfirm={() => void confirmDelete()}
|
||||
oncancel={() => (session.pendingDelete = undefined)}
|
||||
/>
|
||||
|
||||
<ConfirmDialog
|
||||
open={session.pendingKeepFirst}
|
||||
danger
|
||||
title={t('edit.keepFirstTitle')}
|
||||
body={tPlural(
|
||||
'edit.keepFirstBody',
|
||||
session.duplicateGroups.reduce((n, g) => n + g.nodes.length - 1, 0),
|
||||
)}
|
||||
confirmLabel={t('edit.delete')}
|
||||
cancelLabel={t('common.cancel')}
|
||||
onconfirm={() => void session.keepFirst()}
|
||||
oncancel={() => (session.pendingKeepFirst = false)}
|
||||
/>
|
||||
|
||||
<ConfirmDialog
|
||||
open={session.pendingSort !== undefined}
|
||||
title={t('edit.sortTitle', { title: displayTitle(session.pendingSort?.folder, t('edit.untitled')) })}
|
||||
body={tPlural('edit.sortBody', session.pendingSort?.moves.length ?? 0)}
|
||||
confirmLabel={t('edit.sort')}
|
||||
cancelLabel={t('common.cancel')}
|
||||
onconfirm={() => void session.confirmSort()}
|
||||
oncancel={() => (session.pendingSort = undefined)}
|
||||
<EditDialogs
|
||||
{session}
|
||||
ondelete={() => void confirmDelete()}
|
||||
onkeepFirst={() =>
|
||||
void afterBulk(
|
||||
session.keepFirst(),
|
||||
() => panelEl?.querySelector<HTMLElement>('[data-panel-close]') ?? treeEl,
|
||||
)}
|
||||
onsort={() => void afterBulk(session.confirmSort(), () => treeEl)}
|
||||
/>
|
||||
|
||||
<style>
|
||||
|
||||
@@ -44,7 +44,7 @@
|
||||
markdownStyle = settings.markdownStyle;
|
||||
} catch (err) {
|
||||
// Was `err.detail` alone — a raw English Chrome string as the entire
|
||||
// screen, in all three languages (docs/02 §7).
|
||||
// screen, in every language (docs/02 §7).
|
||||
loadError = describeError(err);
|
||||
} finally {
|
||||
loading = false;
|
||||
|
||||
@@ -1,7 +1,9 @@
|
||||
<script lang="ts">
|
||||
import type { LiveNode } from '../browser/bookmarks';
|
||||
import { isSeparator } from '../browser/live-tree';
|
||||
import type { CheckState } from '../core/select';
|
||||
import { num, t, tPlural } from '../i18n/index.svelte';
|
||||
import Disclosure from './Disclosure.svelte';
|
||||
import Icon from './icons/Icon.svelte';
|
||||
import Self from './FolderPickNode.svelte';
|
||||
|
||||
@@ -23,7 +25,10 @@
|
||||
|
||||
/** Only folders are pickable — a bookmark travels with its parent. */
|
||||
const folders = $derived((node.children ?? []).filter((child) => child.url === undefined));
|
||||
const bookmarks = $derived((node.children ?? []).filter((child) => child.url !== undefined).length);
|
||||
// A Firefox separator has a url ("data:") but is not a bookmark (docs/02 §4).
|
||||
const bookmarks = $derived(
|
||||
(node.children ?? []).filter((child) => child.url !== undefined && !isSeparator(child)).length,
|
||||
);
|
||||
const shown = $derived(folders.length > limit ? folders.slice(0, limit) : folders);
|
||||
|
||||
let input: HTMLInputElement | undefined = $state();
|
||||
@@ -40,18 +45,13 @@
|
||||
keyboard interface, and a tree role promised arrow keys it never had (uM5). -->
|
||||
<li>
|
||||
<div class="row" style:--depth={depth - 1}>
|
||||
{#if folders.length > 0}
|
||||
<button
|
||||
class="disclosure"
|
||||
aria-expanded={expanded}
|
||||
aria-label={`${expanded ? t('import.collapse') : t('import.expand')}: ${node.title}`}
|
||||
onclick={() => {
|
||||
expanded = !expanded;
|
||||
}}><Icon name="chevron" size={12} turned={expanded} /></button
|
||||
>
|
||||
{:else}
|
||||
<span class="disclosure" aria-hidden="true"></span>
|
||||
{/if}
|
||||
<Disclosure
|
||||
expanded={folders.length > 0 ? expanded : undefined}
|
||||
label={`${expanded ? t('import.collapse') : t('import.expand')}: ${node.title}`}
|
||||
onclick={() => {
|
||||
expanded = !expanded;
|
||||
}}
|
||||
/>
|
||||
|
||||
<label>
|
||||
<input
|
||||
@@ -113,20 +113,6 @@
|
||||
min-width: 0;
|
||||
}
|
||||
|
||||
.disclosure {
|
||||
display: inline-flex;
|
||||
align-items: center;
|
||||
justify-content: center;
|
||||
width: 16px;
|
||||
height: 16px;
|
||||
flex: none;
|
||||
background: none;
|
||||
border: none;
|
||||
color: var(--fg-muted);
|
||||
cursor: pointer;
|
||||
padding: 0;
|
||||
}
|
||||
|
||||
.glyph {
|
||||
display: inline-flex;
|
||||
color: var(--accent);
|
||||
@@ -156,6 +142,7 @@
|
||||
border-radius: var(--radius-sm);
|
||||
color: var(--accent);
|
||||
cursor: pointer;
|
||||
padding: 1px var(--sp-2);
|
||||
/* 24 px tall: an 18 px line, 2 px of padding, the border (WCAG 2.5.8). */
|
||||
padding: 2px var(--sp-2);
|
||||
}
|
||||
</style>
|
||||
@@ -65,6 +65,14 @@
|
||||
box-shadow: inset 3px 0 0 var(--accent);
|
||||
}
|
||||
|
||||
/* The radio still says which is chosen; the card around it should too. */
|
||||
@media (forced-colors: active) {
|
||||
.selected {
|
||||
outline: 2px solid Highlight;
|
||||
outline-offset: -2px;
|
||||
}
|
||||
}
|
||||
|
||||
input {
|
||||
margin-top: 3px;
|
||||
}
|
||||
|
||||
@@ -111,6 +111,14 @@
|
||||
box-shadow: inset 3px 0 0 var(--danger);
|
||||
}
|
||||
|
||||
/* The radio still says which is chosen; the card around it should too. */
|
||||
@media (forced-colors: active) {
|
||||
.mode.selected {
|
||||
outline: 2px solid Highlight;
|
||||
outline-offset: -2px;
|
||||
}
|
||||
}
|
||||
|
||||
.mode input {
|
||||
margin-top: 3px;
|
||||
}
|
||||
|
||||
@@ -191,11 +191,19 @@
|
||||
open={confirmingReplace}
|
||||
danger
|
||||
title={t('import.replaceConfirmTitle')}
|
||||
body={t('import.replaceConfirmBody', {
|
||||
current: counts(prepared?.current.bookmarks ?? 0, prepared?.current.folders ?? 0),
|
||||
incoming: counts(forecast?.stats.bookmarkCount ?? 0, forecast?.stats.folderCount ?? 0),
|
||||
name: session.filename,
|
||||
})}
|
||||
body={[
|
||||
t('import.replaceConfirmBody', {
|
||||
current: counts(prepared?.current.bookmarks ?? 0, prepared?.current.folders ?? 0),
|
||||
incoming: counts(forecast?.stats.bookmarkCount ?? 0, forecast?.stats.folderCount ?? 0),
|
||||
name: session.filename,
|
||||
}),
|
||||
// Firefox only: separators go with the rest, and nothing brings them back.
|
||||
(prepared?.current.separators ?? 0) > 0
|
||||
? tPlural('import.replaceSeparators', prepared?.current.separators ?? 0)
|
||||
: '',
|
||||
]
|
||||
.filter((sentence) => sentence !== '')
|
||||
.join(' ')}
|
||||
confirmLabel={t('import.replaceConfirm')}
|
||||
cancelLabel={t('common.cancel')}
|
||||
onconfirm={() => void start(session.filename)}
|
||||
|
||||
@@ -34,7 +34,12 @@
|
||||
onchange={(event) => select(event.currentTarget.value)}
|
||||
>
|
||||
{#each LOCALE_CHOICES as choice (choice.value)}
|
||||
<option value={choice.value}>{t(choice.labelKey)}</option>
|
||||
<!-- Each endonym in its own language: a screen reader voices "简体中文"
|
||||
as Chinese and Chrome draws it with Chinese glyphs, whatever the UI
|
||||
language is (docs/07 §2). "Automatic" is in the UI language. -->
|
||||
<option value={choice.value} lang={choice.value === 'auto' ? undefined : choice.value}>
|
||||
{t(choice.labelKey)}
|
||||
</option>
|
||||
{/each}
|
||||
</select>
|
||||
</label>
|
||||
|
||||
@@ -49,7 +49,7 @@
|
||||
}
|
||||
// The localized recovery sentence is the message; the raw browser error
|
||||
// is the separate technical detail (docs/02 §7). Showing `detail` in its
|
||||
// place made legal.saveFailed dead in all three locales — at the one
|
||||
// place made legal.saveFailed dead in every locale — at the one
|
||||
// moment a first-run user most needs an actionable instruction.
|
||||
saveFailed = true;
|
||||
saveDetail = outcome.detail;
|
||||
|
||||
@@ -85,7 +85,9 @@
|
||||
}
|
||||
</script>
|
||||
|
||||
<!-- svelte-ignore a11y_click_events_have_key_events, a11y_no_noninteractive_element_interactions -->
|
||||
<!-- svelte-ignore a11y_click_events_have_key_events, a11y_no_noninteractive_element_interactions —
|
||||
the click is the backdrop's (it lands on the dialog element), a pointer
|
||||
shortcut for what Esc and the Dismiss button already do from the keyboard. -->
|
||||
<dialog
|
||||
bind:this={dialog}
|
||||
class:danger
|
||||
@@ -170,7 +172,8 @@
|
||||
border-radius: var(--radius-sm);
|
||||
color: var(--fg-muted);
|
||||
cursor: pointer;
|
||||
padding: 2px;
|
||||
/* 24 × 24 px with its 16 px glyph (WCAG 2.5.8). */
|
||||
padding: 4px;
|
||||
}
|
||||
|
||||
.dismiss:hover {
|
||||
|
||||
@@ -107,6 +107,11 @@
|
||||
background: var(--accent-subtle);
|
||||
}
|
||||
|
||||
/* Inset: the list scrolls, so it clips the global ring drawn outside. */
|
||||
button:focus-visible {
|
||||
outline-offset: -2px;
|
||||
}
|
||||
|
||||
.label {
|
||||
overflow: hidden;
|
||||
text-overflow: ellipsis;
|
||||
|
||||
@@ -10,8 +10,8 @@
|
||||
const percent = $derived(total === 0 ? 0 : Math.round((done / total) * 100));
|
||||
// Announce every 10% rather than on every tick — docs/06 §5.
|
||||
const announced = $derived(Math.floor(percent / 10) * 10);
|
||||
// Not run through Intl (unlike counts elsewhere): this is 0–100, and none of
|
||||
// en-US/vi-VN/ja-JP groups a two-digit number — so it would cost a formatter
|
||||
// Not run through Intl (unlike counts elsewhere): this is 0–100, and no
|
||||
// shipped locale groups a two-digit number — so it would cost a formatter
|
||||
// lookup on the hottest render path in the app and change nothing.
|
||||
</script>
|
||||
|
||||
@@ -58,6 +58,14 @@
|
||||
background-size: 17px 17px;
|
||||
}
|
||||
|
||||
/* A contrast theme removes the fill's colour and stripes: without a system
|
||||
colour the bar is an empty box at every percentage (docs/06 §5). */
|
||||
@media (forced-colors: active) {
|
||||
.fill {
|
||||
background-color: Highlight;
|
||||
}
|
||||
}
|
||||
|
||||
.status {
|
||||
margin: 0;
|
||||
font-family: var(--font-mono);
|
||||
|
||||
@@ -5,10 +5,16 @@
|
||||
* writing ones are disabled while a bulk command runs: a second sort started
|
||||
* from a row used to fail with two false messages and re-enable the toolbar
|
||||
* mid-sort (v1.1.0 review).
|
||||
*
|
||||
* A click hands focus back to the tree: Chrome focuses a `tabindex="-1"`
|
||||
* button when it is clicked, and the tree ignores keys aimed at a row's own
|
||||
* control, so the arrow keys went dead until the next click on a row. Each
|
||||
* button is 24 × 24 px — the 14 px glyph, 4 px of padding, a 1 px border.
|
||||
*/
|
||||
import type { EditNode } from '../edit/patch-tree';
|
||||
import { t } from '../i18n/index.svelte';
|
||||
import type { EditSession } from '../stores/edit-session.svelte';
|
||||
import { focusOwningTree } from './focus-heading';
|
||||
import Icon from './icons/Icon.svelte';
|
||||
|
||||
interface Props {
|
||||
@@ -22,10 +28,18 @@
|
||||
|
||||
let { node, session, editable, onopen, oncopy, onsort }: Props = $props();
|
||||
|
||||
/** A row button must not also focus or activate the row under it. */
|
||||
/**
|
||||
* A row button must not also focus or activate the row under it. Focus moves
|
||||
* to the tree BEFORE the action runs, so a dialog the action opens remembers
|
||||
* the tree — not this button — as where to return.
|
||||
*/
|
||||
function act(run: () => void): (event: MouseEvent) => void {
|
||||
return (event) => {
|
||||
event.stopPropagation();
|
||||
// With no row focused yet, this one is: the tree would otherwise start
|
||||
// its arrow keys from the top, a screenful away from the click.
|
||||
session.focusedId ??= node.id;
|
||||
focusOwningTree(event.currentTarget);
|
||||
run();
|
||||
};
|
||||
}
|
||||
@@ -69,7 +83,7 @@
|
||||
button {
|
||||
display: inline-flex;
|
||||
align-items: center;
|
||||
padding: 3px;
|
||||
padding: 4px;
|
||||
background: none;
|
||||
border: 1px solid transparent;
|
||||
border-radius: var(--radius-sm);
|
||||
|
||||
@@ -37,7 +37,7 @@
|
||||
// The LOCALIZED sentence is the message; the raw browser error is the
|
||||
// separate technical detail docs/02 §7 asks for. Putting `detail` first
|
||||
// made every translation of settings.saveFailed dead code and showed a
|
||||
// VI/JA user an untranslated Chrome string.
|
||||
// non-English user an untranslated Chrome string.
|
||||
pushToast(t('settings.saveFailed'), 'danger');
|
||||
saveDetail = outcome.detail;
|
||||
});
|
||||
|
||||
@@ -113,4 +113,17 @@
|
||||
footer button:disabled {
|
||||
cursor: not-allowed;
|
||||
}
|
||||
|
||||
/* The current section was a colour and a fill, both of which a contrast
|
||||
theme replaces (docs/06 §5). A border, not an outline — the focus ring is
|
||||
the outline — and not a fill, which Chrome's text backplate would cover. */
|
||||
@media (forced-colors: active) {
|
||||
/* `nav .cell`, to outrank the `:last-child` rule that removes About's
|
||||
right edge; the padding gives back what the border takes, so the bar
|
||||
does not change height between routes. */
|
||||
footer nav .cell[aria-current='page'] {
|
||||
border: 2px solid Highlight;
|
||||
padding: 2px 6px;
|
||||
}
|
||||
}
|
||||
</style>
|
||||
@@ -117,6 +117,16 @@
|
||||
visibility: hidden;
|
||||
}
|
||||
|
||||
/* A contrast theme leaves the pill a hairline box in the page's own colours.
|
||||
A heavier border in the highlight colour marks the current section
|
||||
(docs/06 §5) — a border, not a fill: Chrome paints a backplate behind
|
||||
forced text, so a label on a filled pill became a box of the page colour. */
|
||||
@media (forced-colors: active) {
|
||||
.indicator {
|
||||
border: 2px solid Highlight;
|
||||
}
|
||||
}
|
||||
|
||||
@media (max-width: 560px) {
|
||||
nav {
|
||||
--tab-width: 2.75rem;
|
||||
|
||||
@@ -130,6 +130,39 @@
|
||||
color: var(--accent-fg);
|
||||
}
|
||||
|
||||
/* `button:hover` above is the more specific rule, and --fg on the accent
|
||||
fill is under 3:1: hovering the chosen segment dimmed its own label. */
|
||||
.selected:hover {
|
||||
color: var(--accent-fg);
|
||||
}
|
||||
|
||||
/* The inset ring sits ON the selected segment's fill — and roving focus only
|
||||
ever lands on the selected segment. In --accent it was accent on accent:
|
||||
no visible focus at all (docs/06 §5). Drawn 2px further in, so the fill
|
||||
shows on both sides of it: at the very edge, a ring in the page's own
|
||||
colour only made the segment look 2px smaller. */
|
||||
.selected:focus-visible {
|
||||
outline-color: var(--accent-fg);
|
||||
outline-offset: -4px;
|
||||
}
|
||||
|
||||
/* Contrast themes replace the fill, so the choice is said in system colours.
|
||||
`forced-color-adjust: none` because the label sits on that fill: Chrome
|
||||
paints a backplate in the page colour behind forced text, which left
|
||||
"Light" as a black box on the highlight. */
|
||||
@media (forced-colors: active) {
|
||||
.selected,
|
||||
.selected:hover {
|
||||
forced-color-adjust: none;
|
||||
background: Highlight;
|
||||
color: HighlightText;
|
||||
}
|
||||
|
||||
.selected:focus-visible {
|
||||
outline-color: HighlightText;
|
||||
}
|
||||
}
|
||||
|
||||
.compact button {
|
||||
padding: 5px 7px;
|
||||
}
|
||||
|
||||
@@ -108,10 +108,11 @@
|
||||
color: var(--danger);
|
||||
}
|
||||
|
||||
/* 24 × 24 px with its 14 px glyph (WCAG 2.5.8). */
|
||||
button {
|
||||
display: inline-flex;
|
||||
flex-shrink: 0;
|
||||
padding: 2px;
|
||||
padding: 5px;
|
||||
border: none;
|
||||
border-radius: var(--radius-sm);
|
||||
background: none;
|
||||
|
||||
@@ -76,9 +76,16 @@
|
||||
win = next(follow(win, focusIndex, rows.length), rows.length);
|
||||
}
|
||||
|
||||
/** Tabbing in with nothing focused focuses the first row, so arrows work at once (uL6). */
|
||||
/**
|
||||
* Tabbing in with nothing focused focuses the first row, so arrows work at
|
||||
* once (uL6). Only for a focus that came from the keyboard: a mouse press on
|
||||
* a row in a scrolled tree focuses this list too, and picking the first row
|
||||
* then scrolled the tree to the top under the pointer — the click that
|
||||
* followed landed on whatever row had moved there.
|
||||
*/
|
||||
function onFocus(): void {
|
||||
if (session.focusedId === undefined) session.focusedId = rows[0]?.node.id;
|
||||
if (session.focusedId !== undefined || element?.matches(':focus-visible') !== true) return;
|
||||
session.focusedId = rows[0]?.node.id;
|
||||
}
|
||||
</script>
|
||||
|
||||
@@ -88,7 +95,9 @@
|
||||
{tPlural('edit.showEarlier', Math.min(range.from, WINDOW))}
|
||||
</button>
|
||||
{/if}
|
||||
<!-- svelte-ignore a11y_no_noninteractive_element_interactions -->
|
||||
<!-- svelte-ignore a11y_no_noninteractive_element_interactions — the tree
|
||||
pattern: the focusable `role="tree"` list IS the widget that takes the
|
||||
keys, with the active row named by aria-activedescendant. -->
|
||||
<ul
|
||||
bind:this={element}
|
||||
class="tree"
|
||||
@@ -101,18 +110,27 @@
|
||||
onfocus={onFocus}
|
||||
>
|
||||
{#each shown as row (row.node.id)}
|
||||
<li
|
||||
id="node-{row.node.id}"
|
||||
data-node-id={row.node.id}
|
||||
role="treeitem"
|
||||
aria-level={row.depth}
|
||||
aria-setsize={row.setSize}
|
||||
aria-posinset={row.posInSet}
|
||||
aria-expanded={row.expandable ? row.expanded : undefined}
|
||||
aria-selected={session.focusedId === row.node.id}
|
||||
>
|
||||
<TreeRow {row} {session} {onopen} {oncopy} {onsort} />
|
||||
</li>
|
||||
{#if row.node.separator === true}
|
||||
<!-- A Firefox separator (docs/06 §5): a line, and aria-hidden, so it is
|
||||
outside the accessibility tree and the tree still owns only
|
||||
treeitems. It takes no focus and no drop. -->
|
||||
<li class="separator" aria-hidden="true" style:--depth={row.depth - 1}>
|
||||
<span class="rule"></span>
|
||||
</li>
|
||||
{:else}
|
||||
<li
|
||||
id="node-{row.node.id}"
|
||||
data-node-id={row.node.id}
|
||||
role="treeitem"
|
||||
aria-level={row.depth}
|
||||
aria-setsize={row.setSize}
|
||||
aria-posinset={row.posInSet}
|
||||
aria-expanded={row.expandable ? row.expanded : undefined}
|
||||
aria-selected={session.focusedId === row.node.id}
|
||||
>
|
||||
<TreeRow {row} {session} {onopen} {oncopy} {onsort} />
|
||||
</li>
|
||||
{/if}
|
||||
{/each}
|
||||
</ul>
|
||||
|
||||
@@ -147,6 +165,21 @@
|
||||
overflow: auto;
|
||||
}
|
||||
|
||||
/* Indented like a row: 18px per level, plus the row's own inset and a
|
||||
disclosure-sized gap, so the line starts where its siblings' titles do. */
|
||||
.separator {
|
||||
display: flex;
|
||||
align-items: center;
|
||||
height: 12px;
|
||||
padding-left: calc(var(--depth) * 18px + var(--sp-1) + 18px);
|
||||
padding-right: var(--sp-2);
|
||||
}
|
||||
|
||||
.separator .rule {
|
||||
flex: 1;
|
||||
border-top: 1px solid var(--border-strong);
|
||||
}
|
||||
|
||||
.tree:focus-visible {
|
||||
outline: 2px solid var(--accent);
|
||||
outline-offset: -2px;
|
||||
@@ -177,4 +210,10 @@
|
||||
.more:hover {
|
||||
background: var(--accent-subtle);
|
||||
}
|
||||
|
||||
/* Inset: `.frame` clips its overflow, and the global ring sits 2px outside
|
||||
the button — on these two it was cut off on every side. */
|
||||
.more:focus-visible {
|
||||
outline-offset: -2px;
|
||||
}
|
||||
</style>
|
||||
@@ -2,6 +2,7 @@
|
||||
import type { NodeStatus } from '../core/diff';
|
||||
import { type BookmarkNode, isFolder } from '../core/model';
|
||||
import { num, t, tPlural } from '../i18n/index.svelte';
|
||||
import Disclosure from './Disclosure.svelte';
|
||||
import Icon from './icons/Icon.svelte';
|
||||
import Self from './TreePreviewNode.svelte';
|
||||
|
||||
@@ -35,26 +36,23 @@
|
||||
? 'unfiled'
|
||||
: node.root === 'mobile'
|
||||
? 'mobile'
|
||||
: undefined,
|
||||
: // Only Firefox has a Bookmarks Menu to unwrap into; elsewhere a
|
||||
// menu folder stays a folder, so it gets no pill (docs/03 §1).
|
||||
node.root === 'menu' && import.meta.env.FIREFOX
|
||||
? 'menu'
|
||||
: undefined,
|
||||
);
|
||||
</script>
|
||||
|
||||
<li>
|
||||
<div class="row" style:--depth={depth - 1}>
|
||||
{#if folder && children.length > 0}
|
||||
<button
|
||||
class="disclosure"
|
||||
aria-expanded={expanded}
|
||||
aria-label={`${expanded ? t('import.collapse') : t('import.expand')}: ${node.title}`}
|
||||
onclick={() => {
|
||||
expanded = !expanded;
|
||||
}}
|
||||
>
|
||||
<Icon name="chevron" size={12} turned={expanded} />
|
||||
</button>
|
||||
{:else}
|
||||
<span class="disclosure" aria-hidden="true"></span>
|
||||
{/if}
|
||||
<Disclosure
|
||||
expanded={folder && children.length > 0 ? expanded : undefined}
|
||||
label={`${expanded ? t('import.collapse') : t('import.expand')}: ${node.title}`}
|
||||
onclick={() => {
|
||||
expanded = !expanded;
|
||||
}}
|
||||
/>
|
||||
<span class="glyph" class:folder aria-hidden="true">
|
||||
<Icon name={folder ? (expanded && children.length > 0 ? 'folder-open' : 'folder') : 'link'} size={14} />
|
||||
</span>
|
||||
@@ -111,20 +109,6 @@
|
||||
background: var(--bg-raised);
|
||||
}
|
||||
|
||||
.disclosure {
|
||||
display: inline-flex;
|
||||
align-items: center;
|
||||
justify-content: center;
|
||||
width: 16px;
|
||||
height: 16px;
|
||||
flex: none;
|
||||
background: none;
|
||||
border: none;
|
||||
color: var(--fg-muted);
|
||||
cursor: pointer;
|
||||
padding: 0;
|
||||
}
|
||||
|
||||
.glyph {
|
||||
display: inline-flex;
|
||||
color: var(--fg-muted);
|
||||
@@ -183,6 +167,7 @@
|
||||
border-radius: var(--radius-sm);
|
||||
color: var(--accent);
|
||||
cursor: pointer;
|
||||
padding: 1px var(--sp-2);
|
||||
/* 24 px tall: an 18 px line, 2 px of padding, the border (WCAG 2.5.8). */
|
||||
padding: 2px var(--sp-2);
|
||||
}
|
||||
</style>
|
||||
@@ -6,6 +6,8 @@
|
||||
import type { VisibleRow } from '../edit/tree-keyboard';
|
||||
import { t } from '../i18n/index.svelte';
|
||||
import type { EditSession } from '../stores/edit-session.svelte';
|
||||
import Disclosure from './Disclosure.svelte';
|
||||
import { focusOwningTree } from './focus-heading';
|
||||
import Icon from './icons/Icon.svelte';
|
||||
import RenameInput from './RenameInput.svelte';
|
||||
import RowActions from './RowActions.svelte';
|
||||
@@ -26,6 +28,8 @@
|
||||
const focused = $derived(session.focusedId === node.id);
|
||||
const renaming = $derived(session.renamingId === node.id && editable);
|
||||
const domain = $derived(hostOf(node.url));
|
||||
// Bookmarks and folders only: a Firefox separator is not an item (docs/03 §3).
|
||||
const itemCount = $derived((node.children ?? []).filter((c) => c.separator !== true).length);
|
||||
const blocked = $derived(!isFolder && isBlockedUrl(node.url));
|
||||
|
||||
/** Which part of this row a drag is over, when the drop there is legal. */
|
||||
@@ -89,22 +93,17 @@
|
||||
if (at !== undefined) void session.drop(node.id, at);
|
||||
}}
|
||||
>
|
||||
{#if row.expandable}
|
||||
<button
|
||||
class="disclosure"
|
||||
tabindex="-1"
|
||||
aria-hidden="true"
|
||||
onclick={(event) => {
|
||||
// The row under it must not also take the click.
|
||||
event.stopPropagation();
|
||||
session.toggle(node.id);
|
||||
}}
|
||||
>
|
||||
<Icon name="chevron" size={12} turned={row.expanded} />
|
||||
</button>
|
||||
{:else}
|
||||
<span class="disclosure" aria-hidden="true"></span>
|
||||
{/if}
|
||||
<Disclosure
|
||||
expanded={row.expandable ? row.expanded : undefined}
|
||||
onclick={(event) => {
|
||||
// The row under it must not also take the click — and the tree, not
|
||||
// this button, keeps the keyboard (docs/06 §5).
|
||||
event.stopPropagation();
|
||||
session.toggle(node.id);
|
||||
session.focusedId ??= node.id;
|
||||
focusOwningTree(event.currentTarget);
|
||||
}}
|
||||
/>
|
||||
|
||||
<span class="glyph" class:folder={isFolder}>
|
||||
{#if node.unmodifiable !== undefined}
|
||||
@@ -121,7 +120,7 @@
|
||||
{:else}
|
||||
<span class="title" class:untitled={node.title === ''}>{node.title === '' ? (node.url ?? '') : node.title}</span>
|
||||
{#if domain !== ''}<span class="domain">{domain}</span>{/if}
|
||||
{#if isFolder}<span class="count">{node.children?.length ?? 0}</span>{/if}
|
||||
{#if isFolder}<span class="count">{itemCount}</span>{/if}
|
||||
{#if blocked}
|
||||
<!-- docs/09 T3: a javascript:/data: bookmark must not look like an
|
||||
ordinary link that merely does nothing when clicked. -->
|
||||
@@ -189,25 +188,45 @@
|
||||
box-shadow: inset 0 -2px 0 var(--accent);
|
||||
}
|
||||
|
||||
/* Contrast themes drop every fill and shadow above, which is all that marked
|
||||
the focused row and a drop's place (docs/06 §5). */
|
||||
@media (forced-colors: active) {
|
||||
.focused {
|
||||
outline: 2px solid Highlight;
|
||||
outline-offset: -2px;
|
||||
}
|
||||
|
||||
/* After `.focused`: a drop INTO the focused folder must still show. */
|
||||
.drop-into {
|
||||
outline: 2px dashed Highlight;
|
||||
outline-offset: -2px;
|
||||
}
|
||||
|
||||
/* A line laid over the row's edge: a real border would change the row's
|
||||
height mid-drag and move the very zones the drop is measured against. */
|
||||
.drop-before::after,
|
||||
.drop-after::after {
|
||||
content: '';
|
||||
position: absolute;
|
||||
inset-inline: 0;
|
||||
border-top: 2px solid Highlight;
|
||||
pointer-events: none;
|
||||
}
|
||||
|
||||
.drop-before::after {
|
||||
top: 0;
|
||||
}
|
||||
|
||||
.drop-after::after {
|
||||
bottom: 0;
|
||||
}
|
||||
}
|
||||
|
||||
.matched .title {
|
||||
color: var(--accent);
|
||||
font-weight: 600;
|
||||
}
|
||||
|
||||
.disclosure {
|
||||
display: inline-flex;
|
||||
align-items: center;
|
||||
justify-content: center;
|
||||
width: 16px;
|
||||
height: 16px;
|
||||
flex: none;
|
||||
background: none;
|
||||
border: none;
|
||||
color: var(--fg-muted);
|
||||
cursor: pointer;
|
||||
padding: 0;
|
||||
}
|
||||
|
||||
.glyph {
|
||||
display: inline-flex;
|
||||
color: var(--fg-muted);
|
||||
|
||||
@@ -35,3 +35,18 @@ export function focusLost(): boolean {
|
||||
export function focusIfLost(target: HTMLElement | null | undefined): void {
|
||||
if (target !== null && target !== undefined && focusLost()) target.focus();
|
||||
}
|
||||
|
||||
/**
|
||||
* Hand focus to the tree a row control sits in — docs/06 §5.
|
||||
*
|
||||
* The #edit tree's row buttons and chevron are mouse shortcuts, not tab stops
|
||||
* (`tabindex="-1"`), but Chrome still focuses one when it is clicked. The
|
||||
* tree's key handler ignores keys aimed at a row's own control, so a single
|
||||
* click used to switch the arrow keys off until the next click on a row; and
|
||||
* "Move to…" opened from the button returned focus to a button on a row that
|
||||
* had since moved. Called from the click, before any dialog opens, so the
|
||||
* dialog remembers the tree as the place to return to.
|
||||
*/
|
||||
export function focusOwningTree(from: EventTarget | null): void {
|
||||
if (from instanceof Element) from.closest<HTMLElement>('[role="tree"]')?.focus();
|
||||
}
|
||||
@@ -8,6 +8,8 @@
|
||||
* censor; they are never rendered as links).
|
||||
*/
|
||||
|
||||
import { type BookmarkNode, computeStats, isFolder, type ParseResult } from './model';
|
||||
|
||||
export type HrefVerdict = 'ok' | 'missing' | 'invalid' | 'place-query';
|
||||
|
||||
/**
|
||||
@@ -31,3 +33,42 @@ export function classifyHref(raw: string | null | undefined): HrefVerdict {
|
||||
if (/^place:/i.test(trimmed)) return 'place-query';
|
||||
return 'ok';
|
||||
}
|
||||
|
||||
/** Bookmarks under `nodes` whose address is longer than `max`, removed. */
|
||||
function withoutLongUrls(
|
||||
nodes: readonly BookmarkNode[],
|
||||
max: number,
|
||||
dropped: { count: number },
|
||||
): BookmarkNode[] {
|
||||
const out: BookmarkNode[] = [];
|
||||
for (const node of nodes) {
|
||||
if (!isFolder(node)) {
|
||||
if ((node.url ?? '').length > max) dropped.count++;
|
||||
else out.push(node);
|
||||
continue;
|
||||
}
|
||||
out.push({ ...node, children: withoutLongUrls(node.children ?? [], max, dropped) });
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
/**
|
||||
* Drop the bookmarks a browser would refuse for their length — docs/04 §1.2.
|
||||
*
|
||||
* Firefox refuses an address longer than 65 536 characters, and refuses it in
|
||||
* the middle of a write, possibly after a Replace has cleared the tree. The
|
||||
* browser layer passes its limit; Chromium has none and passes `undefined`,
|
||||
* which returns the result untouched. Applied once after parsing, so every
|
||||
* format meets one rule, and before the preview, so its counts include it.
|
||||
*/
|
||||
export function capUrlLength(result: ParseResult, max: number | undefined): ParseResult {
|
||||
if (max === undefined) return result;
|
||||
const dropped = { count: 0 };
|
||||
const roots = withoutLongUrls(result.roots, max, dropped);
|
||||
if (dropped.count === 0) return result;
|
||||
return {
|
||||
roots,
|
||||
stats: computeStats(roots),
|
||||
warnings: [...result.warnings, { code: 'URL_TOO_LONG', count: dropped.count }],
|
||||
};
|
||||
}
|
||||
@@ -11,8 +11,11 @@
|
||||
* OMITTING absent keys, never by assigning `undefined`.
|
||||
*/
|
||||
|
||||
/** A top-level folder that stands for a browser root other than the bar (docs/04 §1.1, §2). */
|
||||
export type RootMarker = 'other' | 'mobile';
|
||||
/**
|
||||
* A top-level folder that stands for a browser root other than the bar
|
||||
* (docs/04 §1.1, §2). `menu` is Firefox's Bookmarks Menu (since v1.3.0).
|
||||
*/
|
||||
export type RootMarker = 'other' | 'mobile' | 'menu';
|
||||
|
||||
export interface BookmarkNode {
|
||||
title: string;
|
||||
@@ -56,6 +59,8 @@ export const PARSE_WARNING_CODES = [
|
||||
'PLACE_QUERIES_SKIPPED',
|
||||
'EXTRA_ROOTS_SKIPPED',
|
||||
'UNREADABLE_ENTRIES',
|
||||
'SEPARATORS_SKIPPED',
|
||||
'URL_TOO_LONG',
|
||||
] as const;
|
||||
|
||||
export type ParseWarningCode = (typeof PARSE_WARNING_CODES)[number];
|
||||
|
||||
@@ -47,7 +47,9 @@ function readDate(value: unknown, warnings: WarningBag): number | undefined {
|
||||
|
||||
function readRootMarker(raw: Record<string, unknown>): RootMarker | undefined {
|
||||
if (raw.toolbar === true) return undefined; // the toolbar wins
|
||||
return raw.root === 'other' || raw.root === 'mobile' ? raw.root : undefined;
|
||||
return raw.root === 'other' || raw.root === 'mobile' || raw.root === 'menu'
|
||||
? raw.root
|
||||
: undefined;
|
||||
}
|
||||
|
||||
function readNode(
|
||||
|
||||
@@ -9,18 +9,12 @@
|
||||
* by shape), plus display titles for the roots Firefox names only by key.
|
||||
* Guarantees: emits the same tree Firefox's own HTML export describes for the
|
||||
* same profile (docs/04 §2b parity rule), with the Mobile root added.
|
||||
* Separators are skipped silently, as `<HR>` is; `place:` smart bookmarks
|
||||
* Separators are skipped and counted, as `<HR>` is; `place:` smart bookmarks
|
||||
* are skipped and counted; the tags root is dropped, because it is a view
|
||||
* over bookmarks the other roots already hold.
|
||||
*/
|
||||
import { classifyHref } from '../href';
|
||||
import {
|
||||
BmParseError,
|
||||
type BookmarkNode,
|
||||
computeStats,
|
||||
type ParseResult,
|
||||
type RootMarker,
|
||||
} from '../model';
|
||||
import { BmParseError, type BookmarkNode, computeStats, type ParseResult } from '../model';
|
||||
import { microsToSeconds } from '../timestamps';
|
||||
import { bookmarkTitle, isRecord, NodeBudget, type RootTitles, WarningBag } from './shared';
|
||||
|
||||
@@ -141,6 +135,8 @@ function readNode(raw: unknown, depth: number, ctx: ReadContext): BookmarkNode |
|
||||
case 'bookmark':
|
||||
return readBookmark(raw, ctx);
|
||||
case 'separator':
|
||||
// No format BookmarkMagic writes holds one; counted, as <HR> is (docs/04 §2b).
|
||||
ctx.warnings.add('SEPARATORS_SKIPPED');
|
||||
return null;
|
||||
case 'unknown':
|
||||
ctx.warnings.add('UNREADABLE_ENTRIES');
|
||||
@@ -162,7 +158,7 @@ function countBookmarks(root: unknown): number {
|
||||
}
|
||||
|
||||
/** A Map, not an object literal: `root: "toString"` must not find a prototype method. */
|
||||
const ROOT_KEYS = new Map<unknown, 'toolbar' | RootMarker>([
|
||||
const ROOT_KEYS = new Map<unknown, 'toolbar' | 'other' | 'mobile'>([
|
||||
['toolbarFolder', 'toolbar'],
|
||||
['unfiledBookmarksFolder', 'other'],
|
||||
['mobileFolder', 'mobile'],
|
||||
@@ -180,7 +176,7 @@ function readPlacesRoot(
|
||||
ctx: ReadContext,
|
||||
): BookmarkNode[] {
|
||||
const menu: BookmarkNode[] = [];
|
||||
const special: Partial<Record<'toolbar' | RootMarker, BookmarkNode>> = {};
|
||||
const special: Partial<Record<'toolbar' | 'other' | 'mobile', BookmarkNode>> = {};
|
||||
|
||||
for (const child of children) {
|
||||
if (!isRecord(child)) {
|
||||
|
||||
@@ -128,9 +128,9 @@ function walkDl(dl: Element, depth: number, ctx: WalkContext): BookmarkNode[] {
|
||||
const out: BookmarkNode[] = [];
|
||||
for (const child of entryElements(dl)) {
|
||||
const tag = tagOf(child);
|
||||
// <HR> separators (Firefox) are skipped silently — docs/04 §1.2. The HTML
|
||||
// parser usually nests them inside the preceding <DT>; either way they
|
||||
// are never read as an entry.
|
||||
// <HR> separators (Firefox) are never read as an entry — docs/04 §1.2.
|
||||
// The HTML parser usually nests them inside the preceding <DT>, so they
|
||||
// are counted once for the whole document instead (SEPARATORS_SKIPPED).
|
||||
if (tag === 'dd') ctx.warnings.add('DESCRIPTIONS_DROPPED');
|
||||
if (tag !== 'dt') continue;
|
||||
// Checked per entry, not per list: an EMPTY list one level past the cap is
|
||||
@@ -287,6 +287,9 @@ export function parseNetscapeHtml(text: string): ParseResult {
|
||||
}
|
||||
|
||||
const ctx: WalkContext = { warnings: new WarningBag(), budget: new NodeBudget() };
|
||||
// The file model has no separator (docs/04 §1.2): count what is left out.
|
||||
const separators = doc.getElementsByTagName('hr').length;
|
||||
if (separators > 0) ctx.warnings.add('SEPARATORS_SKIPPED', separators);
|
||||
let roots = body === null || !hasEntries ? [] : collectRoots(body, ctx);
|
||||
if (roots.length === 0 && hasEntries) roots = outermostLists(doc, ctx);
|
||||
|
||||
|
||||
@@ -26,6 +26,8 @@ export interface PlanDestinations {
|
||||
other: LiveFolderLike;
|
||||
/** Absent when the profile has none; Mobile-marked folders then land under Other. */
|
||||
mobile?: LiveFolderLike;
|
||||
/** Firefox's Bookmarks Menu; absent in every Chromium browser (docs/03 §1). */
|
||||
menu?: LiveFolderLike;
|
||||
}
|
||||
|
||||
export interface BuildPlanOptions {
|
||||
@@ -70,8 +72,12 @@ function planSplit(
|
||||
destinations: PlanDestinations,
|
||||
mode: 'merge' | 'replace',
|
||||
): { segments: PlanSegment[]; reusedFolders: number } {
|
||||
const routed = routeTopLevel(nodes, { hasMobileRoot: destinations.mobile !== undefined });
|
||||
const routed = routeTopLevel(nodes, {
|
||||
hasMobileRoot: destinations.mobile !== undefined,
|
||||
hasMenuRoot: destinations.menu !== undefined,
|
||||
});
|
||||
const targets: [BookmarkNode[], LiveFolderLike | undefined][] = [
|
||||
[routed.menu, destinations.menu],
|
||||
[routed.toolbar, destinations.toolbar],
|
||||
[routed.other, destinations.other],
|
||||
[routed.mobile, destinations.mobile],
|
||||
|
||||
+18
-5
@@ -2,7 +2,8 @@
|
||||
* Top-level routing — docs/03 §1 step 7, docs/02 §4.
|
||||
*
|
||||
* Purpose: decide which browser root each top-level node of a file lands in.
|
||||
* Inputs: the (deduped) top-level nodes; whether the profile has a Mobile root.
|
||||
* Inputs: the (deduped) top-level nodes; whether the profile has a Mobile root,
|
||||
* and whether it has a Bookmarks Menu (Firefox).
|
||||
* Guarantees: pure. Markers are read on TOP-LEVEL nodes only — deeper they are
|
||||
* carried as data. A marked folder IS that root, so it is unwrapped: its
|
||||
* children go into the root and the folder itself is never written, which is
|
||||
@@ -14,6 +15,8 @@ export interface RoutedNodes {
|
||||
toolbar: BookmarkNode[];
|
||||
other: BookmarkNode[];
|
||||
mobile: BookmarkNode[];
|
||||
/** Firefox's Bookmarks Menu; always empty without one. */
|
||||
menu: BookmarkNode[];
|
||||
/** Marked folders that were unwrapped rather than written. */
|
||||
unwrapped: number;
|
||||
}
|
||||
@@ -30,13 +33,17 @@ function append(target: BookmarkNode[], list: readonly BookmarkNode[] | undefine
|
||||
* - `root: 'other'` folder → its children into Other, in its place in the order;
|
||||
* - `root: 'mobile'` folder → its children into Mobile; a profile with no
|
||||
* Mobile root keeps it as an ordinary folder under Other instead;
|
||||
* - everything else → Other.
|
||||
* - `root: 'menu'` folder → its children into the Bookmarks Menu; a browser
|
||||
* with none (every Chromium one) keeps it as an ordinary folder under Other;
|
||||
* - everything else → the Bookmarks Menu where there is one — what Firefox's
|
||||
* own import does with the loose entries its own export writes — else Other.
|
||||
*/
|
||||
export function routeTopLevel(
|
||||
nodes: readonly BookmarkNode[],
|
||||
options: { hasMobileRoot: boolean },
|
||||
options: { hasMobileRoot: boolean; hasMenuRoot?: boolean },
|
||||
): RoutedNodes {
|
||||
const routed: RoutedNodes = { toolbar: [], other: [], mobile: [], unwrapped: 0 };
|
||||
const routed: RoutedNodes = { toolbar: [], other: [], mobile: [], menu: [], unwrapped: 0 };
|
||||
const loose = options.hasMenuRoot === true ? routed.menu : routed.other;
|
||||
for (const node of nodes) {
|
||||
if (node.toolbar === true) {
|
||||
if (isFolder(node)) {
|
||||
@@ -51,8 +58,14 @@ export function routeTopLevel(
|
||||
} else if (isFolder(node) && node.root === 'mobile' && options.hasMobileRoot) {
|
||||
append(routed.mobile, node.children);
|
||||
routed.unwrapped++;
|
||||
} else {
|
||||
} else if (isFolder(node) && node.root === 'menu' && options.hasMenuRoot === true) {
|
||||
append(routed.menu, node.children);
|
||||
routed.unwrapped++;
|
||||
} else if (isFolder(node) && (node.root === 'menu' || node.root === 'mobile')) {
|
||||
// A root this browser does not have stays a folder, under Other.
|
||||
routed.other.push(node);
|
||||
} else {
|
||||
loose.push(node);
|
||||
}
|
||||
}
|
||||
return routed;
|
||||
|
||||
@@ -13,6 +13,8 @@ export interface SearchableNode {
|
||||
id: string;
|
||||
title: string;
|
||||
url?: string;
|
||||
/** A Firefox separator: shown, never a match — its url is "data:" (docs/03 §3). */
|
||||
separator?: true;
|
||||
children?: SearchableNode[];
|
||||
}
|
||||
|
||||
@@ -50,7 +52,7 @@ export function searchTree(roots: readonly SearchableNode[], query: string): Sea
|
||||
const walk = (nodes: readonly SearchableNode[], ancestors: readonly string[]): boolean => {
|
||||
let anyHere = false;
|
||||
for (const node of nodes) {
|
||||
const self = matches(node, needle);
|
||||
const self = node.separator !== true && matches(node, needle);
|
||||
const trail = [...ancestors, node.id];
|
||||
const below = walk(node.children ?? [], trail);
|
||||
|
||||
|
||||
@@ -78,10 +78,23 @@ function writeNode(node: BookmarkNode, depth: number, out: string[]): void {
|
||||
);
|
||||
}
|
||||
|
||||
/** Serialize a tree to Netscape bookmark HTML (UTF-8, LF line endings). */
|
||||
/**
|
||||
* Serialize a tree to Netscape bookmark HTML (UTF-8, LF line endings).
|
||||
*
|
||||
* Firefox's Bookmarks Menu has no attribute in this format: Firefox writes the
|
||||
* menu's entries as the file's top level and reads loose top-level entries
|
||||
* back into the menu. A top-level `root: 'menu'` folder is therefore
|
||||
* unwrapped here, its children written in its place (docs/04 §1.1).
|
||||
*/
|
||||
export function serializeNetscapeHtml(roots: readonly BookmarkNode[]): string {
|
||||
const out: string[] = ['<DL><p>'];
|
||||
for (const node of roots) writeNode(node, 1, out);
|
||||
for (const node of roots) {
|
||||
if (node.root === 'menu' && node.toolbar !== true && !isBookmark(node)) {
|
||||
for (const child of node.children ?? []) writeNode(child, 1, out);
|
||||
} else {
|
||||
writeNode(node, 1, out);
|
||||
}
|
||||
}
|
||||
out.push('</DL><p>');
|
||||
return `${HEADER}${out.join('\n')}\n`;
|
||||
}
|
||||
@@ -6,7 +6,7 @@
|
||||
* Inputs: `EditNode` trees, plus `LiveNode`s straight from the bookmarks API.
|
||||
* Guarantees: pure — no `chrome.*`, no Svelte, no mutation of the input.
|
||||
*/
|
||||
import type { LiveNode } from '../browser/bookmarks';
|
||||
import { isSeparator, type LiveNode } from '../browser/live-tree';
|
||||
import type { EditNode } from './patch-tree';
|
||||
|
||||
/**
|
||||
@@ -17,13 +17,18 @@ import type { EditNode } from './patch-tree';
|
||||
* folders, which is what makes `url === undefined` a reliable folder test.
|
||||
*/
|
||||
export function toEditNode(node: LiveNode): EditNode {
|
||||
const separator = isSeparator(node);
|
||||
// A separator keeps a url — Firefox sends "data:" — so that no "no url ⇒
|
||||
// folder" test anywhere mistakes it for an empty folder.
|
||||
const url = separator ? (node.url ?? 'data:') : node.url;
|
||||
return {
|
||||
id: node.id,
|
||||
...(node.parentId !== undefined && { parentId: node.parentId }),
|
||||
title: node.title,
|
||||
...(node.url !== undefined && { url: node.url }),
|
||||
...(node.url === undefined && { children: (node.children ?? []).map(toEditNode) }),
|
||||
...(url !== undefined && { url }),
|
||||
...(url === undefined && { children: (node.children ?? []).map(toEditNode) }),
|
||||
...(node.unmodifiable !== undefined && { unmodifiable: node.unmodifiable }),
|
||||
...(separator && { separator: true as const }),
|
||||
};
|
||||
}
|
||||
|
||||
@@ -45,6 +50,8 @@ export function flattenTree(nodes: readonly EditNode[], into: EditNode[] = []):
|
||||
*/
|
||||
export function isEditable(roots: readonly EditNode[], node: EditNode): boolean {
|
||||
if (node.unmodifiable !== undefined) return false;
|
||||
// Separators are shown and left alone: none of the row commands applies.
|
||||
if (node.separator === true) return false;
|
||||
return !roots.some((root) => root.id === node.id);
|
||||
}
|
||||
|
||||
@@ -87,10 +94,13 @@ export function hostOf(url: string | undefined): string {
|
||||
return new URL(url).host;
|
||||
}
|
||||
|
||||
/** How many nodes sit inside `node`. Drives the delete confirmation's count. */
|
||||
/**
|
||||
* How many bookmarks and folders sit inside `node` — the delete confirmation's
|
||||
* count. Separators (Firefox) go too, but are not "items" to anyone reading it.
|
||||
*/
|
||||
export function countDescendants(node: EditNode | undefined): number {
|
||||
if (node === undefined) return 0;
|
||||
return flattenTree(node.children ?? []).length;
|
||||
return flattenTree(node.children ?? []).filter((child) => child.separator !== true).length;
|
||||
}
|
||||
|
||||
/** Ids to delete so one copy of each duplicated link survives. */
|
||||
|
||||
@@ -19,6 +19,11 @@ export interface EditNode {
|
||||
url?: string;
|
||||
dateAdded?: number;
|
||||
unmodifiable?: string;
|
||||
/**
|
||||
* A Firefox separator (docs/03 §3): a row of its own that no command touches.
|
||||
* It keeps its `url` ("data:"), so every "no url ⇒ folder" test stays right.
|
||||
*/
|
||||
separator?: true;
|
||||
children?: EditNode[];
|
||||
}
|
||||
|
||||
|
||||
+31
-5
@@ -22,11 +22,9 @@ function sortKey(node: EditNode): string {
|
||||
return node.title.trim() === '' && node.url !== undefined ? node.url : node.title;
|
||||
}
|
||||
|
||||
/** The children in sorted order, without moving anything. */
|
||||
export function sortedOrder(children: readonly EditNode[], locale: string): EditNode[] {
|
||||
const collator = new Intl.Collator(locale, { numeric: true, sensitivity: 'base' });
|
||||
return children
|
||||
.map((node, position) => ({ node, position }))
|
||||
/** One run of children between separators, sorted: folders first, then by name. */
|
||||
function sortRun(run: readonly { node: EditNode; position: number }[], collator: Intl.Collator) {
|
||||
return [...run]
|
||||
.sort((a, b) => {
|
||||
const aFolder = a.node.url === undefined;
|
||||
const bFolder = b.node.url === undefined;
|
||||
@@ -36,6 +34,34 @@ export function sortedOrder(children: readonly EditNode[], locale: string): Edit
|
||||
.map(({ node }) => node);
|
||||
}
|
||||
|
||||
/**
|
||||
* The children in sorted order, without moving anything.
|
||||
*
|
||||
* Firefox's separators split a folder into runs the user made on purpose, so
|
||||
* each run is sorted on its own and every separator keeps its place (docs/05
|
||||
* §10). Chromium has no separators: one run, as before.
|
||||
*/
|
||||
export function sortedOrder(children: readonly EditNode[], locale: string): EditNode[] {
|
||||
const collator = new Intl.Collator(locale, { numeric: true, sensitivity: 'base' });
|
||||
const out: EditNode[] = [];
|
||||
// A loop, not push(...spread): a folder can hold 100k children.
|
||||
const flush = (items: readonly { node: EditNode; position: number }[]): void => {
|
||||
for (const node of sortRun(items, collator)) out.push(node);
|
||||
};
|
||||
let run: { node: EditNode; position: number }[] = [];
|
||||
for (const [position, node] of children.entries()) {
|
||||
if (node.separator === true) {
|
||||
flush(run);
|
||||
out.push(node);
|
||||
run = [];
|
||||
} else {
|
||||
run.push({ node, position });
|
||||
}
|
||||
}
|
||||
flush(run);
|
||||
return out;
|
||||
}
|
||||
|
||||
/**
|
||||
* The moves, left to right: each fills the next position with the child that
|
||||
* belongs there. Every move takes a child from further right, so moving it to
|
||||
|
||||
Loaded 100 of 178 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user