Open-source development

Repository structure

• src/entrypoints/newtab: Chrome new-tab entry point.
• src/entrypoints/background.ts: MV3 background job recovery and processing.
• src/app, src/domain, src/services: UI, domain rules, storage, and network services.
• worker/: Cloudflare Worker for Google OAuth, sessions, and end-to-end encrypted backups.
• website/: the public site, five-language content, legal pages, and this documentation center.
• tests/ and website/tests/: extension and website automation.

Development setup

Node.js 22 or newer is required. Prepare all three workspaces:

npm ci
npm --prefix worker ci
npm --prefix website ci

Common commands

Repository maintainers run npm run release:local after real project changes. It increments the patch version, performs the complete gate, and atomically updates the local loadable package. External contributors do not bump versions or commit build output for a PR.

# Extension visual preview
npm run dev

# Full extension checks and MV3 build
npm run check

# Worker typecheck, tests, and dry run
npm run check:worker

# Website development, lint, and rendered tests
npm --prefix website run dev
npm --prefix website run lint
npm --prefix website test

Contribution principles

• One PR addresses one clear problem and states user impact, failure modes, and evidence.
• Network features request minimum permissions; data-handling changes update code, the site privacy policy, and relevant docs together.
• Never commit keys, OAuth secrets, tokens, cookies, private bookmarks, or real user data.
• Do not introduce remote executable code; provider output is untrusted data and must be parsed and validated.
• Record author, source, license, and redistribution basis for new assets.

Documentation rules

• Current code and tests are the source of truth for user behavior; planned work is never presented as shipped.
• Changes to privacy, permissions, backup formats, provider fields, or retention update the relevant docs in the same PR.
• Command examples must work from a clean checkout and never reference maintainer-only paths or credentials.
• Long-form user help belongs here; architecture, release checklists, and maintainer procedures stay under repository docs/.

License and security

Source code is licensed under Apache License 2.0. Dependencies, fonts, icons, and backgrounds retain their own licenses; Apache-2.0 does not automatically grant rights to the project name, icon, or other marks.

Report security vulnerabilities privately before public disclosure. Normal bugs, feature proposals, and documentation fixes can follow the contribution guide.