ACCESSIBILITY.md at the repository root, after opensource.guide's accessibility practices and the accessibility-toolkit template: WCAG 2.2 AA as a goal and not a conformance claim, supported environments, the tree's full key table (shown nowhere in the UI), what was tested and with what (keyboard only and Narrator with Chrome on Windows 11), what was not, the known limitations, and how a report is handled by a one-person project. Intake: an "accessibility" issue form and label, accessibility@poli0981.dev in the issue chooser and the README's contact table, an interface section in CONTRIBUTING.md and in the PR checklist. tests/unit/accessibility-statement.test.ts pins the routes and the key table, since nothing in the build reads the file. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
9.5 KiB
Contributing to BookmarkMagic
Bug reports, parser samples and translation fixes are all genuinely useful, and none of them requires you to write code. If you only want to report something, open an issue and stop reading here — the forms ask for what is needed.
Security problems go through SECURITY.md, never a public issue.
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 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 permanent test and the bug can then never come back.
Sanitize the file first. From a clone of this repository:
node scripts/sanitize-bookmarks.mjs your-bookmarks.html
It needs nothing installed — plain Node. It writes
your-bookmarks.sanitized.html next to the original, and prints what it found.
It reads the usual bookmarks.html export, a BookmarkMagic JSON file, Chrome's
profile Bookmarks file (also Edge, Brave and Vivaldi), a Firefox
bookmarks-YYYY-MM-DD.json backup, and our CSV. It refuses anything else rather
than guess, and it refuses to write if its own output still looks personal.
What it destroys: every hostname, path, query value and fragment; every
bookmark and folder title and description; Firefox keywords and tags; favicon
data; local file: paths; in JSON, every string except structural fields
(types, ids, timestamps), including Chrome's meta_info and sync blob.
What it keeps, because this is where the bug lives: the byte order mark, the
doctype, the <META> line, comments, line endings, indentation, tag and
attribute case, quoting style, attribute order, the tree's shape and depth,
every timestamp exactly as written, whether a URL had a port, how deep its path
was, whether it ended in a slash, how many query parameters it had, whether
there was a fragment, any percent-escapes, and any HTML entities in a title.
Distinct hosts stay distinct, so duplicate-detection bugs survive too.
That combination is the point: the sanitized file still reproduces the problem,
without telling us where you browse. A test in tests/unit/scripts/ asserts
exactly that against every fixture in the repo.
Please do not send a real bookmarks file — an export is a browsing history.
Anything you attach to a GitHub issue is public and permanent; see
legal/PRIVACY.md for what happens to anything you email.
Suggesting a translation fix
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, 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
count. A build gate enforces it.
Setting up to write code
Node 26 or newer (see .nvmrc).
npm ci
npx wxt prepare
npm run verify
wxt prepare is not optional: tsconfig.json extends ./.wxt/tsconfig.json,
which does not exist until it has run.
Using a git worktree? It needs its own
npm ciandnpx wxt prepare. With an emptynode_modules/the packages resolve upward from the parent checkout and almost everything appears to work — but knip then reports every devDependency as unused andverifyfails in a way that looks like your change broke something.
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
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
release tag enforce.
The rules that are not negotiable
These are what the extension promises in its store listing and privacy policy, so they are not style preferences:
- Zero runtime dependencies. Not "few". A new one needs discussion first.
- Exactly two permissions,
bookmarksandstorage. Changing that list is a minor-version event that also requires re-certifying the store's privacy answers. - No network access of any kind — no
fetch,XMLHttpRequest,WebSocket,EventSourceorsendBeacon.npm run guardfails the build on any of them. - No
eval,{@html}orinnerHTML. File content reaches the DOM as text. src/lib/core/is pure: it imports nothing frombrowser/,stores/, Svelte orchrome.*.- Files stay under 300 lines (hard limit 500), functions under 50 (hard 80).
- Every user-visible string is an i18n key present in every locale (en, vi,
ja, zh-CN, ro —
LOCALESinsrc/lib/i18n/resolve-locale.ts).
CLAUDE.md is the entry point and 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 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.tshas 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-colorsequivalent; anything that moves sits behindprefers-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 lostrole="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:
- Commit the sanitized sample to
tests/fixtures/(orweird/, ormalformed/). Note that.gitattributessetstests/fixtures/** -text, so line-ending normalization cannot rewrite the CRLF or BOM bytes the bug may depend on — do not "fix" that. - Add the regression test to
tests/unit/core/fixtures.test.ts, the only parser regression suite. A browser export goes in itsBROWSER_EXPORTSarray, which drives a shared set of assertions; anything else gets its own case. There is no shared fixture-loading helper — that file has its own loader. - Fix the parser in
src/lib/core/parse/. The test and the fix land in the same pull request; a fixture with no test is just a file. - Write the quirk down in the parser source and in
docs/04 §1.2. The format chapter is where the next person looks to understand why the code is shaped oddly. - Update
docs/11 §2's inventory andCHANGELOG.md's[Unreleased].
If the fix changes what a format is able to preserve, that is a specification
change: update docs/04 first, then tests/helpers/tree.ts's project() — it
models each format's documented lossiness, and widening it without the doc turns
a real regression into a passing test.
Translations, in code
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 every other locale in English.
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, plusfewin 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
Conventional Commits (fix(import): …, feat(edit): …, docs: …,
chore(deps): …). Small commits, one concern each; tests land with or before
the implementation. The PR template lists the rest.