v1: freeze the API surface, move to Biome, update every dependency

[arshad-shah]

Summary

Closes the remaining pre-v1 gates from #35 and brings the whole dependency tree to latest, so 1.0.0 can ship off a clean build. Adds a major changeset — there are no breaking changes from 0.6.x; what v1 adds is the promise that the documented surface stays put.

Type of change

• New feature (non-breaking)
• Performance / refactor (no behaviour change)
• Documentation only
• Test or tooling only

Linked issues

Closes #35. Supersedes #44, and the dependabot PRs #49, #50, #51, #52, #53, #54, #62, #63, #64, #69, #70, #71, #72, #73, #74, #75, #76.

Contains the commit from #67 — merge that one first and this fast-forwards over it cleanly.

Implementation notes

API freeze

New API stability page assigns every export, command, flag, config field and runtime global to a tier: Stable, Experimental, or Internal. If it isn't listed there, it's internal. Symbols exported only because the CLI needs them across module boundaries (createBuildContext, classifyChange, generateHMRClientCode, writeManifest, PluginRunner) now carry @internal tags that say what to use instead.

The issue's three open questions, answered:

• extforge/testing ships experimental. The Chrome fakes mirror a surface MV3 keeps extending, so freezing them means either an incomplete mock forever or a major release every time Chrome adds an API. They're also the lowest-blast-radius thing to change — a fake that shifts breaks a test suite, not a shipped extension.
• HMR globals split. __EXTFORGE_HMR_QUIET__ is a documented user opt-out, so it's stable. __EXTFORGE_HMR__ is the binding target the dev-mode transform emits against and moves with the wire protocol, so it's internal.
• extforge/plugins is stable. It already carries an apiVersion: 1 discriminator, so an incompatible future plugin API can ship as apiVersion: 2 alongside rather than breaking existing plugins.

Node policy is written down too: >=22.12, supported through Active and Maintenance LTS, and dropping an EOL major is a minor release — holding the floor down until the next major would mean shipping against an unpatched runtime.

ESLint + Prettier → Biome

One tool for both linting and formatting. Every ESLint suppression is ported to its Biome equivalent with the original rationale intact; the no-console whitelist survives as per-file overrides in biome.json. Rule levels are deliberately kept in line with the old config (noExplicitAny warns; noNonNullAssertion and noConfusingVoidType are off, because the codebase uses both idioms on purpose), so the result is 0 errors and the same 59 any warnings as before rather than a new wall of noise.

Biome's stricter preset did surface real things, fixed here rather than silenced:

• Storage's private useChrome() → hasChromeStorage(). It is not a React hook; only its name made useHookAtTopLevel think so.
• getLogger() and the SWC refresh-plugin getters no longer memoize via assignment-in-expression.
• forEach callbacks in tests no longer return a value.
• An unused import and loop binding in tests/manifest.test.ts, and a void-returning return in the config reference generator.
• The "we deliberately exclude defaultValue from deps" note in storage/react.ts becomes a real suppression — ESLint never had the react-hooks plugin installed, so that rule was never actually enforced.

Dependencies

Every npm dependency across the root package, docs-site, tests-e2e and the examples is on its latest release, plus all SHA-pinned actions (checkout v7, setup-node v6.4, codeql v4.36.2, pnpm/action-setup).

Two judgment calls worth a look:

• TypeScript stays on 6.0.3. TS 7 typechecks the project cleanly, but breaks the .d.ts bundle: tsup's rollup-plugin-dts binds to the TypeScript compiler API, which the Go-based TS 7 doesn't expose. typescript-eslint also caps at <6.1.0, though Biome makes that moot.
• Peer dependency ranges are untouched. They're compatibility floors for consumers, not versions to keep current — raising react >=18.0.0 to ^19 would drop React 18 users for no reason.

Astro 6 → 7 needed a Starlight migration: 0.39 removed the { label, autogenerate } sidebar shorthand, so those entries are nested under items now. Astro/Starlight also pull vulnerable postcss, nanoid, js-yaml and svgo transitively, which would fail the pnpm audit --prod gate — new pnpm.overrides pin them to patched versions, following the pattern already used for esbuild and devalue.

Cross-browser gate

pnpm check:cross-browser builds all three examples for Chrome, Firefox, Edge and Safari and asserts each emitted manifest is well-formed and carries that browser's shape (Firefox gets background.scripts + browser_specific_settings; the others get service_worker and no addon id). All 12 combinations pass, and it runs as its own CI job.

This is a build gate, not a behavioural one. Live-browser e2e is still Chromium-only — see below.

Changelog

Removed the stale [Unreleased] section. Everything in it (HMR v3, SWC + React Fast Refresh, content-script HMR scaffolding, centralized logging) shipped in 0.3.0 and 0.4.0, so it was advertising released work as pending.

Testing

• pnpm typecheck && pnpm lint && pnpm test && pnpm build passes locally — 519 tests, 57 files
• pnpm audit --prod reports 0 vulnerabilities
• pnpm docs:build passes on Astro 7 / Starlight 0.41 — 50 pages
• pnpm check:cross-browser passes — 3 examples × 4 targets
• E2E not verified locally. Playwright 1.62 needs a browser build this sandbox can't fetch (cdn.playwright.dev is blocked by the environment's network policy). CI installs it, so the e2e job will be the first real signal. The jump is 1.59.1 → 1.62.1, so the risk is low, but it is unverified.

Documentation

• Added reference/stability.mdx and guides/migration-v1.mdx, both wired into the sidebar
• pnpm docs:gen re-run as part of docs:build
• Added @internal TSDoc to the newly-classified internal surface
• Added a major changeset

Breaking change notes

None. No config field was renamed, no export removed, no CLI flag changed between 0.6.x and 1.0.0. The migration guide leads with exactly that, then covers what does bite people skipping releases: the Node 22.12 floor and the logger's number formatting, both from 0.6.0.

The one contributor-facing change is pnpm lint now running Biome instead of ESLint. CONTRIBUTING.md is updated.

Checklist

• No new runtime dependencies in src/core/ — @biomejs/biome is a devDependency
• Followed the rules in CONTRIBUTING.md

Still open after this

Two gates from #35 aren't closed by code, flagged rather than quietly dropped:

• Soak period — "one minor cycle with no new fix-* changesets against core". A process gate; 0.6.0 shipped with zero pending changesets, so the clock is running, but it's your call whether it's served.
• Cross-browser e2e — this PR covers builds for all four targets. Real browser automation is Chromium-only. Firefox is tractable via Playwright and would be the natural next step; Safari needs a macOS runner plus web-extension conversion, and Edge is Chromium anyway.

Both nice-to-haves (performance baseline, bundle size budget) are also still open.

---

Generated by Claude Code

[cloudflare-workers-and-pages]

Deploying extforge with    Cloudflare Pages

Latest commit:	a4e4c6f
Status:	✅  Deploy successful!
Preview URL:	https://f9e90b1f.extforge.pages.dev
Branch Preview URL:	https://claude-issue-35-v1-readiness.extforge.pages.dev

View logs