suaveplan/openspec/changes/enterprise-browser-test-vite/tasks.md

Tasks: enterprise-browser-test-vite

Change ID: enterprise-browser-test-vite Package: @suaveplan/test-vite Target path: browser/dev/test-vite Prerequisite packages on Verdaccio: none (no workspace runtime deps)

---

0. Pre-flight (non-negotiable)

• 0.1 Confirm clean working tree (git status reports nothing) and no in-flight worktrees with uncommitted work (git worktree list then git status in each)
• 0.2 If any worktrees exist under .claude/worktrees/, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (git worktree remove) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
• 0.3 Confirm the package set in MANIFEST.md matches find packages -maxdepth 3 -name package.json count. Drift here means a prior change archived without regenerating the manifest.

1. Scaffold

• Create directory tree per proposal.md.
• package.json v0.0.0, "sideEffects": false.
  • dependencies: @suaveplan/logger workspace:^, tslib catalog:build
  • peerDependencies: vite, vitest
  • devDependencies: vitest catalog:testing, @vitest/coverage-istanbul catalog:testing, vite catalog:build, @suaveplan/testing workspace:^
  • Subpath exports: ".", "./config/vite-library", "./config/vite-app", "./config/vitest", "./config/vitest-browser", "./setup/browser", "./utils/tree-shake", "./utils/bundle-size", "./matchers", "./ports"
• tsconfig.json, vitest.config.ts (pool: forks).
• Delete export const test = "hi" placeholder from src/index.ts.

---

2. Types (src/types/types.ts)

• ViteLibraryOptions, ViteAppOptions, VitestOptions, VitestBrowserOptions, BrowserEnvOptions, SetupResult, TreeShakeResult, BundleSizeResult.
• All option types validated by Zod with sensible defaults.
• Write types.md.

---

3. Scope split documentation

• Document formal scope split in this change's OpenSpec entry: test-vite = Vite/Vitest build config factories; @suaveplan/testing = polyfills + test utilities + fixtures. No overlap.

---

4. createViteLibraryConfig (src/config/vite-library/)

• vite-library.ts — preserveModules: true, vite-plugin-dts, external @suaveplan/* peers, ESM-first output, configurable entry.
• Options validated by Zod.
• Write vite-library.test.ts (options validation, externals list, DTS flag). Write vite-library.md.

---

5. createViteAppConfig (src/config/vite-app/)

• vite-app.ts — React/Vue plugin switch, env-var type declarations, hashing strategy.
• Write vite-app.test.ts. Write vite-app.md.

---

6. createVitestConfig (src/config/vitest/)

• vitest.ts — defaults: pool: 'forks', setupFiles: ['@suaveplan/testing/polyfills'], Istanbul provider, reporters tuned for CI.
• Accepts environment, coverage, pool overrides.
• Write vitest.test.ts (default pool is forks, Istanbul provider selected, polyfills in setupFiles). Write vitest.md.

---

7. createVitestBrowserConfig (src/config/vitest-browser/)

• vitest-browser.ts — Playwright provider; fileParallelism: false; configurable browser (chromium/firefox/webkit); headless toggle.
• Write vitest-browser.test.ts. Write vitest-browser.md.

---

8. setupBrowserEnvironment (src/setup/browser/)

• browser.ts — happy-dom / jsdom helper with switches: mockLocalStorage, mockServiceWorker, mockMatchMedia, mockResizeObserver.
• Implementations use typed adapters — no vi.stubGlobal.
• Write browser.test.ts (each mock flag). Write browser.md.

---

9. Tree-shake validator (src/utils/tree-shake/)

• tree-shake.ts — verifyTreeShake(entry, expectedSymbols) builds with Rollup, asserts only listed symbols in output chunk.
• Write tree-shake.test.ts (synthetic package — verify dead code eliminated). Write tree-shake.md.

---

10. Bundle-size snapshot (src/utils/bundle-size/)

• bundle-size.ts — snapshotBundleSize(entry, budgetBytes) writes .size.snap; fails when budget exceeded.
• Write bundle-size.test.ts. Write bundle-size.md.

---

11. Custom matchers (src/matchers/)

• matchers.ts — typed expect.extend: toBeAccessible (axe-core), toMatchDataURL, toHaveValidCSSVars.
• Write matchers.test.ts (each matcher pass + fail case). Write matchers.md.

---

12. Port helpers (src/ports/)

• ports.ts — allocatePort(label) / releasePort(label) backed by a file lock; deterministic port assignment; getPortMap() for diagnostics.
• Write ports.test.ts (allocate, release, conflict avoidance). Write ports.md.

---

13. Proof-of-concept consumer migration

• Migrate one browser consumer (e.g., @suaveplan/react-tour) off its handwritten vite.config.ts + vitest.config.ts onto the new factories.
• Document the migration as an example in README.md.

---

14. Integration test (tests/integration.test.ts)

• Build a synthetic library package end-to-end using createViteLibraryConfig; assert ESM output, DTS files, externals.
• Run createVitestConfig in a child process; assert pool: forks and Istanbul provider.
• verifyTreeShake on a test module; assert dead export eliminated.

---

15. Docs + verify

• Write .md per module (≥200 words, API reference, options table, example).
• Write README.md with scope-split table, subpath table, migration example.
• bunx turbo lint typecheck test --filter=@suaveplan/test-vite — green.
• bunx turbo test:coverage — 100% (currently near-zero).
• No @ts-expect-error in src/ or tests. No placeholder exports.
• At least one consumer package migrated to new factories.
• bun scripts/publish.ts --package @suaveplan/test-vite.
• Archive to openspec/archive/2026-04-24-enterprise-browser-test-vite/.