Track v1.0.0 readiness

[arshad-shah]

Tracking issue for the path from 0.3.x to 1.0.0. v1 is a stability contract: the public API surface in this issue is what we commit to keeping backwards-compatible under semver, and the rough edges below should be smoothed before we make that promise.

Current state

• Released: 0.3.1 (see CHANGELOG.md).
• Pending changesets in .changeset/: 33 (~20 of which are fix-*). Density implies the surface is still settling.
• ## [Unreleased] in CHANGELOG.md covers significant new behavior (HMR v3 + React Fast Refresh, content-script HMR scaffolding, Plasmo-parity packages) that hasn't shipped yet.

Public API surface to stabilize for v1

Subpath exports from package.json:

• extforge (core builder + config)
• extforge/logger
• extforge/plugins
• extforge/testing, extforge/testing/vitest
• extforge/storage, extforge/storage/react
• extforge/messaging
• extforge/csui
• extforge/env

CLI surface (extforge <cmd>):

• init, dev, build, validate, doctor, upgrade, package, icons

Configuration: extforge.config.{ts,js,mjs,cjs,json} schema (loaded via the first-party loadExtForgeConfig).

Pre-v1 checklist

Must-have (blocks v1)

• Ship the 0.4.0 release: land the 33 pending changesets and clear the ## [Unreleased] section.
• Soak period: one minor release cycle with no new fix-* changesets against core areas (HMR, builder, manifest, csui, storage, messaging).
• API freeze audit: review every subpath export's public surface, document what's stable vs. internal. Add @internal JSDoc tags where appropriate.
• Config schema lock-in: confirm extforge.config field names are final. Anything still in flux gets renamed or marked experimental before v1.
• CLI flag freeze: review every flag in src/cli/index.ts and finalize names. Document deprecations if any rename is needed.
• HMR protocol v3: documented and stable. v2 fallback path tested and documented.
• Plasmo-parity packages (storage, messaging, csui, env) have full README/docs coverage and at least one example each in examples/.
• Node engine policy: confirm >=20.0.0 (or bump to >=22) and document the LTS support window.
• Cross-browser e2e: all four targets (Chrome, Firefox, Safari, Edge) green in CI.
• Supply chain: pnpm audit --prod stays at 0 vulns; OIDC provenance verified.
• Docs site parity with package surface; every exported symbol has a docs page or reference entry.

Nice-to-have

• Migration guide 0.x → 1.0 with breaking change list and codemod notes (extforge upgrade could ship at least one codemod).
• Performance baseline: cold-build and dev-server-start benchmarks committed alongside CI, so post-v1 regressions are catchable.
• Bundle size budget for the published package — current dist/ size noted in CI.

Out of scope for v1

• Nested CLI subcommands beyond one level (parser deliberately doesn't support this — src/cli/parser.ts:12).
• Babel-based RFR fallback (SWC + esbuild only).

Versioning policy after v1

• Major: breaking changes to any documented subpath export, CLI command/flag, or config schema field.
• Minor: new exports, new CLI commands, new optional config fields, new browser targets.
• Patch: bug fixes, internal refactors, doc updates.

Open questions

• Do we mark the extforge/testing subpaths as experimental at v1 (so we can iterate on the test helpers without a major bump), or freeze them with the rest?
• HMR runtime globals (globalThis.__EXTFORGE_HMR__, globalThis.__EXTFORGE_HMR_QUIET__) — public contract or internal?
• Is extforge/plugins a stable plugin API surface, or experimental until v2?