Initial Commit

openspec/archive/2026-05-19-extend-react-ui-runtime-theme-mutation/tasks.md

@@ -0,0 +1,77 @@
+# Tasks — extend-react-ui-runtime-theme-mutation
+
+## 1. Foundation
+
+- [ ] Add `INVALID_EXTENSION_TOKEN_NAME` to `REACT_UI_CODES` registry; update the registry doc-comment.
+- [ ] Update `src/errors/error-codes.test.ts` to pin the new code.
+
+## 2. Layer stack (module-level)
+
+- [ ] Create `src/theme/layer-stack/layer-stack.types.ts` with `MutationLayer`, `LayerOrigin`, `LayerStackListener`.
+- [ ] Create `src/theme/layer-stack/layer-stack.ts` exporting `pushLayer`, `removeLayer`, `updateLayer`, `getMergedResolved`, `subscribe`. Tracks the `Set<string>` of every CSS-var name ever touched; on every change re-applies merged state to the bound root element and removes any tracked name not present in the merged set.
+- [ ] Co-locate `.md` (≥200 words; basic + advanced examples).
+- [ ] `layer-stack.test.ts` — runner-agnostic, covers push/pop/update/merge order; tracked-name cleanup on removeLayer.
+- [ ] `layer-stack/index.ts` — explicit named re-exports only.
+
+## 3. Provider integration
+
+- [ ] Modify `theme-provider.tsx` to push a `MutationLayer` for the active plugin on mount and update it on `setTheme(...)` / theme change. Unmount removes the layer. Maintain `providerId` (uuid). Reduced-motion + font-stack writes also go through the layer (so they participate in the unmount cleanup).
+- [ ] Extend `ThemeContextValue` with a `mutators` field carrying `{ providerId, push, update, remove }` private hooks for `useThemeMutator` consumption. Keep all existing fields and types unchanged.
+- [ ] Extended `theme-provider.test.tsx` tests:
+  - [ ] "applying the active plugin writes all 19 chassis tokens"
+  - [ ] "switching themes re-applies merged result with mutators still on top"
+  - [ ] "unmounting the provider clears all 19 chassis tokens"
+
+## 4. `useThemeMutator`
+
+- [ ] `src/theme/use-theme-mutator/use-theme-mutator.types.ts` — `ThemeMutatorHandle`.
+- [ ] `src/theme/use-theme-mutator/use-theme-mutator.ts` — implementation. `useRef` + `useEffect` lifecycle. Validates extension keys; throws `ReactUiError(REACT_UI.INVALID_EXTENSION_TOKEN_NAME)`. Calls `clear` on unmount.
+- [ ] Co-located `.md` (basic = static prop; advanced = runtime fetch + apply).
+- [ ] `.test.tsx` — at least:
+  - [ ] "setChassisOverrides writes Partial<ThemeTokenSet> on document.documentElement"
+  - [ ] "setExtensionTokens writes arbitrary -- properties on document.documentElement"
+  - [ ] "extension token without -- prefix throws INVALID_EXTENSION_TOKEN_NAME"
+  - [ ] "clear() removes all of this mutator's contributions"
+  - [ ] "unmount removes all of this mutator's contributions"
+  - [ ] "nested mutators stack innermost-wins per key"
+  - [ ] "nested mutator unmount restores outer mutator's value"
+  - [ ] "extension tokens are namespace-orthogonal to chassis tokens"
+  - [ ] "setExtensionTokens replaces previous extension tokens (removed keys are cleared)"
+  - [ ] "throws REACT_UI.NO_PROVIDER outside a ThemeProvider"
+- [ ] `index.ts` — explicit named re-exports.
+
+## 5. `useResolvedThemeTokens`
+
+- [ ] `src/theme/use-resolved-theme-tokens/use-resolved-theme-tokens.ts` — subscribes to layer-stack notifier via `useSyncExternalStore`.
+- [ ] Co-located `.md`.
+- [ ] `.test.tsx`:
+  - [ ] "returns the active plugin's tokens when no mutators present"
+  - [ ] "reflects mutator overrides in chassis"
+  - [ ] "reflects mutator extension tokens"
+  - [ ] "throws REACT_UI.NO_PROVIDER outside a ThemeProvider"
+- [ ] `index.ts`.
+
+## 6. Subpath exports + barrel
+
+- [ ] Add `./theme/use-theme-mutator` and `./theme/use-resolved-theme-tokens` to `package.json` exports.
+- [ ] Re-export new hooks + types from `src/theme/index.ts` (explicit named).
+- [ ] Re-export from `src/index.ts` (top-level barrel) if precedent is set for `useTheme` / `useThemeTokens`.
+
+## 7. Story
+
+- [ ] `theme-provider.stories.tsx` — add a story showing live runtime token-override input (text fields → calls `setExtensionTokens`).
+
+## 8. Spec reconciliation + gates
+
+- [ ] Verify every `### Requirement` in `specs/react-ui/spec.md` has a matching `**Verified by:**` `it(...)` title that exists in the codebase.
+- [ ] `bun run check` (biome).
+- [ ] `bunx turbo lint typecheck test --filter=@suaveplan/react-ui --force`.
+- [ ] `bunx turbo test:coverage --filter=@suaveplan/react-ui` — no regression on per-metric coverage.
+- [ ] `bun scripts/openspec-conformance.ts @suaveplan/react-ui` — 0 errors.
+- [ ] `bunx turbo build --filter=@suaveplan/react-ui --force`.
+- [ ] `bun scripts/lint/check-test-runner-imports.ts` — 0 violations.
+
+## 9. Archival
+
+- [ ] Fold `specs/react-ui/spec.md` delta into canonical `openspec/specs/react-ui/spec.md` (capability is being instantiated for the first time alongside this change; if a prior unarchived change already established the canonical file, merge instead of overwrite).
+- [ ] Move `openspec/changes/extend-react-ui-runtime-theme-mutation/` → `openspec/archive/2026-05-19-extend-react-ui-runtime-theme-mutation/`.