@vantageos/mosaic 0.2.2 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,145 @@
+# Changelog
+
+All notable changes to `@vantageos/mosaic` are documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+---
+
+## [Unreleased]
+
+### Added
+- **D-PR1 — Pre-publish dry-run evidence for v0.3.0 GA.** New doc `docs/D-PR1-PRE-PUBLISH-DRY-RUN-V0.3.0.md` (bilingual EN+FR) capturing the hard-evidence pre-publish gate run in a fresh sandbox worktree off `origin/main` @ `7ae5450`: sandbox build-pass (RULE #19, `SANDBOX_BUILD_PASS_ID=7ae5450`, build exit 0), Gate 1 build-parity (exit 0), `npm pack --dry-run` (150 files / 511.8 kB / unpacked 3.0 MB / version 0.3.0 / sha `31caed2f`, CHANGELOG + README + package.json + registry.yaml + full `dist/` surface present — **no real publish**), corrected vendored cross-runtime subpath coverage gate (`--ga-mode`, exit 0, 0 missing), and the full gate set re-run green (tsc, biome, vitest 854, playwright-axe 29, size-limit, registry-drift, storybook-test 103, Gate 2 peer-resolution, Gate 3 coherence 10). Documents the **D-T1 blocker**: the canonical B-PR1 skill / B-PR2 publish hook carry a category-prefixed layout defect (`./forms/react`) vs Mosaic's runtime-prefixed layout (`./react/forms`) and **false-block** the real publish — must be fixed before `tag v0.3.0` (Sigma task `k176e5rpz`); plus `ETA_APPROVED_TASK_ID` must be set after Eta approval. Mission `k57b6d1b` · task `k177e1wr`. No source/build/gate code changed — docs-only.
+- **CI Gate 4 — Cross-runtime subpath coverage (B-PR3).** New fail-fast CI gate asserting that **every bare component category** in `packages/mosaic/package.json` `exports` (`./forms`, `./progress`, `./display`, `./artifacts`, `./confirmation`, `./media`, `./input`) also exports a **non-empty** `dist` artifact under **both** `./react/<cat>` and `./preact/<cat>`. This is the gate that would have caught the original v0.3.0 GA blocker (foundation components present as bare exports but missing/empty under `/react` + `/preact`).
+  - New vendored script `packages/mosaic/scripts/cross-runtime-subpath-coverage-check.py` — vendored from the canonical B-PR1 skill `mosaic-cross-runtime-subpath-coverage-check` (VantageRegistry; PR #20). Stdlib-only, with an optional PyYAML registry cross-check that degrades gracefully when PyYAML is absent (no Python dependency added to CI). Carries one documented deviation: a `RUNTIME_PREFIXED` toggle adapting the canonical category-prefixed layout (`./forms/react`) to this repo's runtime-prefixed layout (`./react/forms`).
+  - New job `cross-runtime-subpath-coverage` (`needs: build-parity-cross-runtime`) builds tokens + mosaic so `dist/` exists, then runs `python3 .../cross-runtime-subpath-coverage-check.py --package-root packages/mosaic --ga-mode` (exit 1 fails CI with a `component × runtime` diagnostic). CI-side equivalent of the B-PR2 npm-publish hook.
+  - New doc `docs/CROSS-RUNTIME-GATE.md` (bilingual EN+FR). Additive change — no existing gate (Gate 1 build-parity, Gate 2 peerDeps smoke, Gate 3 coherence, `ci` job) weakened or replaced. Mission `k57b6d1b` · task `k176pzsszyy4v3f505khwg33gx88j36n`.
+- Wave 3 components TBD (DatePicker, Avatar, FilterChip, Pagination — demand-driven T21+).
+
+### Fixed
+- CI Gate 2 (PeerDeps optionality smoke) now runs GREEN (unblocks v0.3.0 GA publish gate). Two layered bugs, both packaging-scope:
+  - **Build (tsup):** the preact runtime bundles that re-export the shared React implementation (`preact/progress`, `preact/input`, `preact/confirmation`, `preact/forms`) shipped `import … from "react/jsx-runtime"` and `import … from "react"`. `esbuildOptions.alias` (`react → preact/compat`) never fired because tsup auto-externalises peerDeps (`react`, `react/jsx-runtime`) *before* alias resolution, so the alias was a no-op for those specifiers. A react-only consumer (which has react) could therefore resolve `@vantageos/mosaic/preact/*` even with preact absent — optionality broken in both directions. Fix: replaced the alias with an esbuild `onResolve` plugin (`mosaic-react-to-preact`) that deterministically rewrites the whole react family (`react`, `react-dom`, `react-dom/client`, `react/jsx-runtime`, `react/jsx-dev-runtime`) to their preact equivalents and marks them external; paired with `noExternal: [/^react…/]` on the preact pass so tsup's own external plugin returns undefined for the react family and lets the rewrite run. Added `preact/jsx-runtime` to `PREACT_EXTERNAL`. Preact bundles now import only preact specifiers; react bundles unchanged.
+  - **Smoke fixture (run-smoke.sh):** the fixtures installed mosaic via `npm install file:../../../packages/mosaic`, which npm symlinks into the monorepo source tree; Node then resolved the bundle's runtime imports by climbing out of the fixture into the monorepo root `node_modules` (where both react and preact are hoisted devDeps), producing a false PASS. Rewrote the driver to model a real npm consumer faithfully: `pnpm pack` both packages (rewriting the `workspace:*` tokens dep to a concrete version) and install the tarballs into an isolated `mktemp -d` consumer outside the repo tree, with `--legacy-peer-deps` so npm does not auto-install the *transitive* peer react pulled by `@tanstack/react-virtual` into a preact-only consumer. Fixture assertions (`index.mjs`) untouched. Smoke now PASSES: react-only resolves `react/*` and fails `preact/*`; preact-only resolves `preact/*` and fails `react/*`.
+- CI `biome check --error-on-warnings` now exits 0 on `main` (unblocks v0.3.0 GA publish gate): suppressed 6 `noNonNullAssertion` lint errors in VirtualList tests (React + Preact) with justified `biome-ignore` comments matching repo convention, plus format/organizeImports auto-fixes across 7 files.
+- `forms/Select.tsx` (React + Preact) biome a11y gate: replaced the blanket `biome.json` per-file rule override with scoped, justified `biome-ignore` comments on exactly the 6 flagged ARIA roles per runtime (`useSemanticElements` on the `combobox`/`listbox`/`option` roles, `noNoninteractiveElementToInteractiveRole` on `ul`→`listbox` + `li`→`option`, `useFocusableInteractive` on the `li`). These are biome heuristic false-positives on the WAI-ARIA APG combobox + listbox pattern (options managed via `aria-activedescendant`, intentionally not in the tab order). Comments mirror the existing `noAutofocus` APG-pattern suppression; no JSX/logic changed. Added `tests/a11y/Select.spec.ts` (axe-core) proving 0 violations on the pattern.
+- CI `playwright-axe` step now runs GREEN (unblocks v0.3.0 GA `npm-publish` gate, which is `needs: ci`). Root cause from real CI logs: the runner ships no browsers, so every a11y spec died at `browserType.launch` ("Executable doesn't exist"). Fixes: (1) added a `playwright install --with-deps chromium` step before `playwright-axe` in `.github/workflows/ci.yml`; (2) normalized the stale `/storybook/?story=` spec URLs (StatusBadge, MarkdownRenderer, ConfirmDialog, TokenDisplayOnceModal, ProgressBar) to the working `/iframe.html?id=` convention used by `Select.spec.ts`, corrected three wrong story-id slugs (`media-statusbadge--error-state`, `artifacts-markdownrenderer--error-state`, `progress-progressbar--default`), and scoped axe to `#storybook-root` so the Storybook iframe shell's page-level best-practice rules no longer mask component results; (3) `TableView.spec.ts` now waits via `getByRole("table")` (matches the native `<table>` implicit role; the CSS `[role="table"]` selector never matched) and scopes axe to `#storybook-root`.
+- `display/TableView.tsx`: fixed a real axe violation (`scrollable-region-focusable`, WCAG 2.1.1 / 2.1.3, serious) — the virtualized scroll viewport is scrollable but was not keyboard-operable. Added `tabIndex={0}` + `role="region"` + `aria-label` (justified `biome-ignore` comments matching repo convention). Full `tests/a11y/` suite now passes 29/29 with axe 0 violations under `CI=true` against the Playwright `webServer`.
+
+---
+
+## [0.3.0] — GA — 2026-06-13
+
+### Added
+- All Wave 1 + Wave 2 components promoted from `0.3.0-alpha.1` with no breaking API changes.
+- `forms` category becomes stable (7th top-level taxonomy bucket).
+
+---
+
+## [0.3.0-alpha.1] — 2026-06-11
+
+### Added
+- **`RadioGroup`** (Wave 2 T17) — WCAG-AA mutually exclusive single-choice form primitive. Cross-runtime: `@vantageos/mosaic/react/forms` + `@vantageos/mosaic/preact/forms`. Roving tabindex (WAI-ARIA §3.10), Arrow/Home/End keyboard navigation, `aria-orientation`, group-level and per-option disabled.
+- **`Select`** (Wave 2 T13) — single-select dropdown implementing the ARIA combobox+listbox pattern (APG 2024). Optional in-popup search. ArrowUp/Down/Home/End/Enter/Escape/type-ahead keyboard navigation. Shared pure logic (`Select.logic.ts`) referenced by both runtimes.
+- **`MultiSelect`** (Wave 2 T15) — multi-value dropdown with removable chips. `aria-multiselectable`, per-chip `aria-label="Remove {label}"`, `maxItems` gate, searchable filter, Backspace removes last chip.
+- **`Textarea`** (Wave 2 T12) — multi-line text input with optional `autoResize` (grow-to-fit) and `maxLength` clamping enforced at the `onChange` boundary before RHF receives the value.
+- **`Input`** (Wave 2 T11) — first field primitive of the `forms` category. Five HTML input types (`text | email | password | number | url`). `aria-invalid` + `aria-describedby` wired automatically.
+- **`Checkbox`** (Wave 2 T14) — boolean checkbox with `indeterminate` state (DOM `.indeterminate = true` + `aria-checked="mixed"`), optional `description` wired to `aria-describedby`.
+- **`FieldArray`** (Wave 2 T16) — render-prop wrapper around RHF `useFieldArray`. Keys rows by stable `field.id` (not array index). Provides `append / remove / move / swap / insert / prepend / replace / update`. WCAG-AA `role="list"` + `role="listitem"` container.
+- **`ConfirmModal`** alias (Wave 1 T9-v2) — thin re-export of `ConfirmDialog` on `@vantageos/mosaic/react/confirmation` and `@vantageos/mosaic/preact/confirmation`. Referential identity invariant (`ConfirmModal === ConfirmDialog`) enforced by tests.
+- **`VirtualList<T>`** (Wave 1 T2) — generic virtualized list using `@tanstack/react-virtual` v3. API: `items`, `itemHeight`, `estimateSize`, `renderItem`, `onRowClick`, `overscan`, `className`, `locale`. WCAG-AA when `onRowClick` present (`role="button"`, `tabIndex={0}`, Enter/Space handlers). Bilingual empty state (EN/FR).
+- **`forms` category** (Wave 2 T10 scaffold) — 7th top-level taxonomy bucket. Five scaffold primitives: `useMosaicForm`, `FormProvider`, `FormField`, `ErrorDisplay`, `SubmitButton`. Default validation mode `"onBlur"`. Subpaths: `@vantageos/mosaic/react/forms`, `@vantageos/mosaic/preact/forms`, `@vantageos/mosaic/forms` (back-compat root).
+- `react-hook-form ^7.54.0` and `@hookform/resolvers ^3.10.0` added as optional peer dependencies.
+- `./forms`, `./react/forms`, `./preact/forms` subpath exports added.
+
+### Fixed
+- Cascade-merge build break (hotfix 2026-06-11): restored JSDoc openers, deduped barrel re-exports, dropped phantom `Badge` refs, added missing `Skeleton` i18n strings.
+
+### Wave 1 additions (also shipping in 0.3.0-alpha.1 codebase)
+- **`Tabs`** (T5) — cross-runtime React 19 + Preact 10, WCAG-AA.
+- **`Alert`** (T8) — persistent inline banner (React 19 + Preact 10).
+- **`Toast`** (T3) — ephemeral notification (confirmation category, Chi+Hermes convergence).
+- **`Skeleton`** (T6) — loading placeholder (React 19 + Preact 10).
+- **`EmptyState`** (T7) — empty list / zero-data state (display category, Hermes+Chi convergence).
+- Three new CI gate jobs wired into `ci.yml` per Standard v1.2 §20.
+
+---
+
+## [0.2.2] — 2026-06-11
+
+### Fixed
+- **Critical — §18.5 type surface contract**: `tsup.config.ts` react pass changed from `clean: true` to `clean: false`. The three sibling tsup configs (react / preact / tokens re-export) ran their DTS phases in parallel; the react DTS pass finished last and previously wiped `dist/preact/*.d.ts` and `dist/tokens.d.ts` written by the sibling passes. All DTS files now persist on disk.
+- Added `prebuild` script (`node -e "fs.rmSync('dist',{recursive:true,force:true})"`) to guarantee a clean `dist` before tsup runs, replacing the racy in-pass `clean: true`.
+
+---
+
+## [0.2.1] — 2026-06-11 (YANKED — superseded by 0.2.2)
+
+### Added
+- `TableView.onRowClick(row, index)` and `StreamingTableView.onRowClick` — when provided, rows render with `role="button"`, `tabIndex={0}`, and Enter/Space keyboard handlers. Fixes 5-BU ABSOLUTE blocker (Phi + Chi + Theta + Hermes + Demeter).
+
+### Notes
+- 100% back-compat with v0.2.0: when `onRowClick` is undefined, row rendering is byte-identical to v0.2.0.
+
+---
+
+## [0.2.0] — 2026-06-02
+
+### Added
+- **Cross-runtime subpaths** — `@vantageos/mosaic/react/<cat>` (React 19) and `@vantageos/mosaic/preact/<cat>` (Preact 10) for all 6 categories (`progress`, `input`, `display`, `artifacts`, `confirmation`, `media`). Path A architecture (single package, multi-runtime subpaths) replaces forked maintenance.
+- **`@vantageos/mosaic/tokens` subpath** — convenience re-export of `@vantageos/mosaic-tokens`.
+- **tsup three sibling configs** — react pass (legacy v0.1.2 entries + new `react/<cat>`), preact pass (`preact/<cat>` ESM-only with esbuild `alias` mapping `react` → `preact/compat`), tokens re-export shim.
+- **`preact ^10.25.0`** added to peerDependencies. All peer deps (`react`, `react-dom`, `preact`, `react-i18next`, `@mcp-ui/client`, `rxjs`) marked optional via `peerDependenciesMeta`.
+- **`@vantageos/mosaic-tokens`** (new sibling package) — 58 framework-free design tokens across 6 categories: 15 colors (OKLCH × 3 shades × 5 statuses), 8 spacing values, 14 typography vars, 6 shadows, 7 radii, 8 motion. Three surfaces: CSS custom properties, typed JS exports, Tailwind v4 plugin.
+
+### Changed
+- Standard §18 "Cross-Runtime Support (v0.2.0 amendment)" published to `mosaic-architecture-standard-v1.md` documenting the A1 architecture, exports surface table, peerDependenciesMeta model, bundle targets, new CI gates, compatibility commitments, and per-BU migration guide.
+
+---
+
+## [0.1.2] — 2026-06-02
+
+### Added
+- Per-component subpath exports: `@vantageos/mosaic/progress`, `/input`, `/display`, `/artifacts`, `/confirmation`, `/media`, `/server`.
+- `TableView` static rows array overload — accepts `rows: Row[]` for already-fetched data. Streaming variant renamed to `StreamingTableView` with `rows$: Observable`.
+
+### Fixed
+- Removed `recharts` from dependencies (unused in v0.1.0 — will re-add as optional peer when Chart component lands).
+- Moved `rxjs` from dependencies → optional peerDependencies.
+
+### Migration from 0.1.1
+- Root imports (`import { Foo } from '@vantageos/mosaic'`) still work — root export preserved.
+- For optimal tree-shaking, switch to subpath: `import { ProgressBar } from '@vantageos/mosaic/progress'`.
+- Streaming usage: rename `<TableView rows$={obs}>` to `<StreamingTableView rows$={obs}>` and ensure `rxjs` is in your project deps.
+
+---
+
+## [0.1.1] — 2026-06-02
+
+### Added
+- `no-hardcode-strings.test.ts` — vitest AST scan enforcing zero raw JSX text children with alphabetic content (Eta axis 6 CONDITION fix path).
+- Whitelist mechanisms: same-line `// allow-hardcode-i18n: <reason>` comment and file-level `// allow-hardcode-i18n-file: <reason>` comment.
+- Auto-exempt: `.test.tsx`, `.spec.tsx`, `.stories.tsx` files.
+
+---
+
+## [0.1.0] — 2026-05-28
+
+### Added
+- Initial release — 6 consumer-driven MCP UI components: `MarkdownRenderer`, `TokenDisplayOnceModal`, `TableView`, `ConfirmDialog`, `StatusBadge`, `ProgressBar`.
+- Monorepo scaffold: pnpm + turbo + 4 pattern infrastructure + CI gate.
+- Zod runtime validation on all component props.
+- `registry.yaml` with component catalogue.
+- i18n consumer-driven model (zero hardcoded JSX text).
+
+---
+
+[Unreleased]: https://github.com/elpiarthera/vantageos-mosaic/compare/v0.3.0...HEAD
+[0.3.0]: https://github.com/elpiarthera/vantageos-mosaic/compare/v0.2.2...v0.3.0
+[0.3.0-alpha.1]: https://github.com/elpiarthera/vantageos-mosaic/compare/v0.2.2...v0.3.0-alpha.1
+[0.2.2]: https://github.com/elpiarthera/vantageos-mosaic/compare/v0.2.1...v0.2.2
+[0.2.1]: https://github.com/elpiarthera/vantageos-mosaic/compare/v0.2.0...v0.2.1
+[0.2.0]: https://github.com/elpiarthera/vantageos-mosaic/compare/v0.1.2...v0.2.0
+[0.1.2]: https://github.com/elpiarthera/vantageos-mosaic/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/elpiarthera/vantageos-mosaic/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/elpiarthera/vantageos-mosaic/releases/tag/v0.1.0

package/README.md

@@ -14,6 +14,18 @@ npm install @vantageos/mosaic@^0.2.0 @vantageos/mosaic-tokens@^0.2.0 preact
 
 All runtime peers are marked optional via `peerDependenciesMeta` — install only what your runtime needs.
 
+## Build
+
+```sh
+pnpm --filter @vantageos/mosaic build
+```
+
+The `build` script prefixes `NODE_OPTIONS=--max-old-space-size=8192` automatically — no manual env export required.
+
+**Why 8 GB heap?** tsup runs multiple parallel DTS (declaration emit) configs for cross-runtime outputs (React 19, Preact 10, server, tokens). Each TypeScript compiler worker holds the full type graph in memory. The combined peak exceeds Node's default 2 GB V8 limit, causing OOM crashes (`FATAL ERROR: Reached heap limit Allocation failed`). 8 GB gives adequate headroom on a standard CI runner (ubuntu-latest provides 16 GB RAM).
+
+This constraint is codified locally via the `build` script (the `NODE_OPTIONS` prefix above), so it applies anywhere the script runs — including CI. Wiring it as an explicit job-level `env: NODE_OPTIONS` in `.github/workflows/ci.yml` for the build-bearing jobs (`build-parity-cross-runtime`, `peer-resolution-smoke`, `npm-publish`) is planned but not yet present.
+
 ## Surface
 
 | Subpath | Runtime | Use case |
@@ -52,6 +64,143 @@ export function MyComponent({ progress, label }: { progress: number; label: stri
 }
 ```
 
+## Forms (v0.3.0-alpha.1)
+
+`@vantageos/mosaic/{react,preact}/forms` — composite form primitives wrapping `react-hook-form` + `@hookform/resolvers/zod`. Default validation mode is `onBlur` (Chi co-validated, Day 102 DM). Cross-runtime: same imports, React 19 path or Preact 10 path.
+
+### Install peers
+
+```sh
+npm install react-hook-form@^7.54.0 @hookform/resolvers@^3.10.0
+```
+
+Both peers are declared optional in `peerDependenciesMeta` — only install them if you use the forms surface.
+
+### Quick start
+
+```tsx
+import { z } from "zod";
+import {
+  useMosaicForm,
+  FormProvider,
+  FormField,
+  ErrorDisplay,
+  SubmitButton,
+} from "@vantageos/mosaic/react/forms";
+
+const schema = z.object({
+  email: z.string().email("Invalid email"),
+  age: z.number().min(18, "Must be 18+"),
+});
+
+export function SignupForm({ onSubmit }: { onSubmit: (data: z.infer<typeof schema>) => void }) {
+  const form = useMosaicForm({
+    schema,
+    defaultValues: { email: "", age: 0 },
+    // mode defaults to "onBlur" — Mosaic doctrine
+  });
+
+  return (
+    <FormProvider form={form}>
+      <form onSubmit={form.handleSubmit(onSubmit)}>
+        <FormField name="email">
+          {({ field, fieldState }) => (
+            <label>
+              Email
+              <input {...field} value={(field.value as string) ?? ""} />
+              <ErrorDisplay error={fieldState.error} />
+            </label>
+          )}
+        </FormField>
+        <SubmitButton label="Sign up" />
+      </form>
+    </FormProvider>
+  );
+}
+```
+
+### Surface
+
+| Export | Purpose |
+|---|---|
+| `useMosaicForm({ schema, defaultValues, mode? })` | Wrapper around `useForm` + `zodResolver`. Returns RHF's `UseFormReturn` extended with `mosaicSchema` + `mosaicMode`. |
+| `<FormProvider form={...}>` | Wraps RHF's `FormProvider` AND a Mosaic-specific context. Use `useMosaicFormContext()` inside descendants. |
+| `<FormField name="...">{({ field, fieldState, formState }) => ...}</FormField>` | Render-prop wrapper around RHF's `Controller`. |
+| `<ErrorDisplay error={...} messageMap={...} />` | Single-field error formatter. Renders nothing when no error. Priority: `error.message` → `messageMap[type]` → generic fallback. |
+| `<SubmitButton label="..." loadingLabel="..." />` | Bound to the surrounding `FormProvider`. Disabled while invalid OR submitting. |
+| `<Input name="..." type="text\|email\|password\|number\|url" label="..." placeholder? disabled? autoComplete? />` | Single-field `<input>` bound to the surrounding `FormProvider`. `label` is required (consumer-driven i18n). Emits `aria-invalid` + `aria-describedby` on validation error. |
+
+Field primitives (Textarea, Select, Checkbox, MultiSelect, RadioGroup, FieldArray) land in T12-T20 — see `docs/v0.3.0-plan.md` §7.
+| `<Textarea name="..." rows? maxLength? autoResize? placeholder? disabled? label?  />` | Multi-line text input field primitive. `rows` default 3, `maxLength` enforced via shared logic gate, optional `autoResize` grows to content. `aria-invalid` + `aria-describedby` on error. |
+
+Remaining field primitives (Input shipped T11, Select, Checkbox, MultiSelect, RadioGroup, FieldArray) land in T13-T20 — see `docs/v0.3.0-plan.md` §7.
+| `useFieldArray({ name, control? })` | Thin wrapper around RHF's `useFieldArray`. Returns `{ fields, append, remove, move, swap }` + the rest of RHF's native return for advanced cases. Reads `control` from `FormProvider` when omitted. |
+| `<FieldArray name="...">{({ field, index }, { append, remove, move, swap, fields }) => ...}</FieldArray>` | Render-prop wrapper around `useFieldArray`. Emits `role="list"` shell + `role="listitem"` per row, keyed by RHF's stable `field.id` (NOT array index). Powers PromptForm Add Variable, Hermes variable mappings, Demeter filter chips. |
+
+| `<Checkbox name="..." label="..." indeterminate? description? disabled? />` | Boolean checkbox primitive. `indeterminate=true` → `aria-checked="mixed"` + DOM `.indeterminate=true` via ref. `description` wired via `aria-describedby`. `aria-invalid` + `aria-describedby` on error. |
+| `<RadioGroup name="..." label="..." options={[...]} orientation? disabled? />` | WCAG-AA radiogroup. Roving tabIndex, Arrow key selection sync, Home/End, Space/Enter. |
+
+Remaining field primitives (Input, Textarea, Select, MultiSelect) land in T11-T15 + T18-T20 — see `docs/v0.3.0-plan.md` §7.
+
+### RadioGroup
+
+Mutually exclusive single-choice field. Keyboard navigation follows WAI-ARIA radiogroup pattern (§3.10): Arrow keys move focus AND select simultaneously (roving tabindex). Disabled options are skipped during navigation.
+
+```tsx
+import { z } from "zod";
+import {
+  useMosaicForm,
+  FormProvider,
+  RadioGroup,
+} from "@vantageos/mosaic/react/forms";
+
+const schema = z.object({
+  plan: z.string().min(1, "Please select a plan"),
+});
+
+export function PlanSelector() {
+  const form = useMosaicForm({
+    schema,
+    defaultValues: { plan: "" },
+  });
+
+  return (
+    <FormProvider form={form}>
+      <form onSubmit={form.handleSubmit(console.log)}>
+        <RadioGroup
+          name="plan"
+          label="Select a plan"
+          options={[
+            { value: "free", label: "Free", description: "Up to 3 projects" },
+            { value: "pro", label: "Pro", description: "Unlimited projects" },
+            { value: "team", label: "Team", description: "Multi-user", disabled: false },
+          ]}
+          orientation="vertical"
+        />
+      </form>
+    </FormProvider>
+  );
+}
+```
+
+**WCAG-AA contract:**
+- `role="radiogroup"` + `aria-labelledby` on container
+- `role="radio"` + `aria-checked` + roving `tabIndex` per option
+- `aria-labelledby` per option → its visible label span
+- `aria-describedby` per option → its description span (when present)
+- `aria-disabled` on disabled options; disabled options skipped in arrow nav
+- `aria-orientation` reflects `orientation` prop
+
+Field primitives (Textarea, Select, MultiSelect, RadioGroup, FieldArray) land in T12-T20 — see `docs/v0.3.0-plan.md` §7.
+| `<MultiSelect name="..." label="..." options={...} placeholder? disabled? searchable? maxItems? />` | Multi-value dropdown. RHF value is `string[]`. Selected items render as removable chips (Backspace/Delete on trigger removes last, per-chip × removes specific). WCAG-AA combobox (`role=combobox aria-multiselectable=true`), Arrow/Enter keyboard nav, optional case-insensitive search, optional `maxItems` cap. |
+
+Remaining field primitives (Input + Textarea + MultiSelect shipped T11/T12/T15; Select, Checkbox, RadioGroup, FieldArray) land in T13-T20 — see `docs/v0.3.0-plan.md` §7.
+| `<Select name="..." label="..." options={[...]} />` | Single-select dropdown (combobox+listbox APG). Optional `searchable` prop enables in-popup filter. Full keyboard nav + type-ahead. WCAG-AA strict. |
+
+Field primitives (Input, Textarea, Checkbox, MultiSelect, RadioGroup, FieldArray) land in T11, T14-T20 — see `docs/v0.3.0-plan.md` §7.
+
+
+
 ## Server (MCP UI)
 
 ```ts
@@ -64,6 +213,50 @@ const resource = createMosaicResource({
 // returns a SEP-1865-compliant MCP UI resource with text/html;profile=mcp-app MIME
 ```
 
+
+## Components
+
+### Display
+
+#### VirtualList
+
+Generic virtualized list for large datasets. Uses @tanstack/react-virtual v3 (already bundled via TableView). Cross-runtime: React 19 + Preact 10.
+
+```tsx
+import { VirtualList } from "@vantageos/mosaic/react/display";
+// Preact: import { VirtualList } from "@vantageos/mosaic/preact/display";
+
+type Task = { id: string; title: string; status: string };
+
+<VirtualList<Task>
+  items={tasks}
+  itemHeight={56}               // fixed px height
+  renderItem={(task, index) => (
+    <div key={task.id}>
+      <span>{task.title}</span>
+      <span>{task.status}</span>
+    </div>
+  )}
+  onRowClick={(task, index) => router.push('/tasks/' + task.id)}
+  overscan={5}                  // rows outside viewport (default 5)
+  className="task-list"
+  locale="en"                   // "en" | "fr"
+/>
+```
+
+**Props**
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `items` | `T[]` | required | Items to render |
+| `itemHeight` | `number` | -- | Fixed row height px (mutually exclusive with `estimateSize`) |
+| `estimateSize` | `(index) => number` | -- | Variable height estimator |
+| `renderItem` | `(item: T, index: number) => ReactNode` | required | Row renderer |
+| `onRowClick` | `(item: T, index: number) => void` | `undefined` | Click handler — triggers WCAG-AA a11y (role=button + tabIndex=0 + Enter/Space) |
+| `overscan` | `number` | `5` | Rows outside visible area |
+| `className` | `string` | `undefined` | CSS class on scroll container |
+| `locale` | `"en" or "fr"` | `"en"` | Built-in string locale |
+
 ## Doctrine
 
 - **Pattern 1 (Zod runtime validation)** — every component validates props at the MCP host boundary; invalid props render an a11y fallback (`role="alert"`), never white-screen.

package/dist/Alert.schema-LPJE5gFP.d.cts

@@ -0,0 +1,71 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { z } from 'zod';
+
+declare const TokenDisplayOnceModalPropsSchema: z.ZodObject<{
+    token: z.ZodString;
+    title: z.ZodString;
+    warningMessage: z.ZodString;
+    copyLabel: z.ZodString;
+    closeLabel: z.ZodString;
+    locale: z.ZodDefault<z.ZodEnum<["en", "fr"]>>;
+}, "strip", z.ZodTypeAny, {
+    locale: "en" | "fr";
+    title: string;
+    token: string;
+    warningMessage: string;
+    copyLabel: string;
+    closeLabel: string;
+}, {
+    title: string;
+    token: string;
+    warningMessage: string;
+    copyLabel: string;
+    closeLabel: string;
+    locale?: "en" | "fr" | undefined;
+}>;
+type TokenDisplayOnceModalProps = z.infer<typeof TokenDisplayOnceModalPropsSchema> & {
+    onClose: () => void;
+};
+declare function validateTokenDisplayOnceModalProps(raw: unknown): z.infer<typeof TokenDisplayOnceModalPropsSchema>;
+
+declare function TokenDisplayOnceModal(raw: Omit<TokenDisplayOnceModalProps, "locale"> & Partial<Pick<TokenDisplayOnceModalProps, "locale">>): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * Alert component props schema.
+ *
+ * Persistent inline banner (vs Toast which is ephemeral + auto-dismissing).
+ *
+ * variant      — controls visual style + ARIA role auto-assignment:
+ *                "error" → role="alert"  (assertive, interrupts screen reader)
+ *                all others → role="status" (polite, non-intrusive)
+ * title        — consumer-driven; caller passes already-localized string
+ * description  — optional supporting text beneath the title
+ * dismissible  — when true, renders a dismiss button (default: false)
+ * onDismiss    — callback fired when dismiss button is clicked
+ * locale       — controls dismiss button aria-label language
+ */
+declare const AlertPropsSchema: z.ZodObject<{
+    variant: z.ZodEnum<["success", "error", "info", "warning"]>;
+    title: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    dismissible: z.ZodDefault<z.ZodBoolean>;
+    locale: z.ZodDefault<z.ZodEnum<["en", "fr"]>>;
+}, "strip", z.ZodTypeAny, {
+    locale: "en" | "fr";
+    title: string;
+    variant: "warning" | "error" | "success" | "info";
+    dismissible: boolean;
+    description?: string | undefined;
+}, {
+    title: string;
+    variant: "warning" | "error" | "success" | "info";
+    locale?: "en" | "fr" | undefined;
+    description?: string | undefined;
+    dismissible?: boolean | undefined;
+}>;
+type AlertProps = z.infer<typeof AlertPropsSchema> & {
+    onDismiss?: () => void;
+};
+declare function validateAlertProps(raw: unknown): z.infer<typeof AlertPropsSchema>;
+
+export { type AlertProps as A, TokenDisplayOnceModal as T, AlertPropsSchema as a, type TokenDisplayOnceModalProps as b, TokenDisplayOnceModalPropsSchema as c, validateTokenDisplayOnceModalProps as d, validateAlertProps as v };

package/dist/Alert.schema-LPJE5gFP.d.ts

@@ -0,0 +1,71 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { z } from 'zod';
+
+declare const TokenDisplayOnceModalPropsSchema: z.ZodObject<{
+    token: z.ZodString;
+    title: z.ZodString;
+    warningMessage: z.ZodString;
+    copyLabel: z.ZodString;
+    closeLabel: z.ZodString;
+    locale: z.ZodDefault<z.ZodEnum<["en", "fr"]>>;
+}, "strip", z.ZodTypeAny, {
+    locale: "en" | "fr";
+    title: string;
+    token: string;
+    warningMessage: string;
+    copyLabel: string;
+    closeLabel: string;
+}, {
+    title: string;
+    token: string;
+    warningMessage: string;
+    copyLabel: string;
+    closeLabel: string;
+    locale?: "en" | "fr" | undefined;
+}>;
+type TokenDisplayOnceModalProps = z.infer<typeof TokenDisplayOnceModalPropsSchema> & {
+    onClose: () => void;
+};
+declare function validateTokenDisplayOnceModalProps(raw: unknown): z.infer<typeof TokenDisplayOnceModalPropsSchema>;
+
+declare function TokenDisplayOnceModal(raw: Omit<TokenDisplayOnceModalProps, "locale"> & Partial<Pick<TokenDisplayOnceModalProps, "locale">>): react_jsx_runtime.JSX.Element | null;
+
+/**
+ * Alert component props schema.
+ *
+ * Persistent inline banner (vs Toast which is ephemeral + auto-dismissing).
+ *
+ * variant      — controls visual style + ARIA role auto-assignment:
+ *                "error" → role="alert"  (assertive, interrupts screen reader)
+ *                all others → role="status" (polite, non-intrusive)
+ * title        — consumer-driven; caller passes already-localized string
+ * description  — optional supporting text beneath the title
+ * dismissible  — when true, renders a dismiss button (default: false)
+ * onDismiss    — callback fired when dismiss button is clicked
+ * locale       — controls dismiss button aria-label language
+ */
+declare const AlertPropsSchema: z.ZodObject<{
+    variant: z.ZodEnum<["success", "error", "info", "warning"]>;
+    title: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    dismissible: z.ZodDefault<z.ZodBoolean>;
+    locale: z.ZodDefault<z.ZodEnum<["en", "fr"]>>;
+}, "strip", z.ZodTypeAny, {
+    locale: "en" | "fr";
+    title: string;
+    variant: "warning" | "error" | "success" | "info";
+    dismissible: boolean;
+    description?: string | undefined;
+}, {
+    title: string;
+    variant: "warning" | "error" | "success" | "info";
+    locale?: "en" | "fr" | undefined;
+    description?: string | undefined;
+    dismissible?: boolean | undefined;
+}>;
+type AlertProps = z.infer<typeof AlertPropsSchema> & {
+    onDismiss?: () => void;
+};
+declare function validateAlertProps(raw: unknown): z.infer<typeof AlertPropsSchema>;
+
+export { type AlertProps as A, TokenDisplayOnceModal as T, AlertPropsSchema as a, type TokenDisplayOnceModalProps as b, TokenDisplayOnceModalPropsSchema as c, validateTokenDisplayOnceModalProps as d, validateAlertProps as v };

package/dist/ConfirmDialog-B3CQQGmJ.d.cts

@@ -0,0 +1,34 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { z } from 'zod';
+
+declare const ConfirmDialogPropsSchema: z.ZodObject<{
+    title: z.ZodString;
+    message: z.ZodString;
+    confirmLabel: z.ZodString;
+    cancelLabel: z.ZodString;
+    variant: z.ZodDefault<z.ZodEnum<["default", "danger"]>>;
+    locale: z.ZodDefault<z.ZodEnum<["en", "fr"]>>;
+}, "strip", z.ZodTypeAny, {
+    locale: "en" | "fr";
+    message: string;
+    title: string;
+    confirmLabel: string;
+    cancelLabel: string;
+    variant: "default" | "danger";
+}, {
+    message: string;
+    title: string;
+    confirmLabel: string;
+    cancelLabel: string;
+    locale?: "en" | "fr" | undefined;
+    variant?: "default" | "danger" | undefined;
+}>;
+type ConfirmDialogProps = z.infer<typeof ConfirmDialogPropsSchema> & {
+    onConfirm: () => void;
+    onCancel: () => void;
+};
+declare function validateConfirmDialogProps(raw: unknown): z.infer<typeof ConfirmDialogPropsSchema>;
+
+declare function ConfirmDialog(raw: Omit<ConfirmDialogProps, "variant" | "locale"> & Partial<Pick<ConfirmDialogProps, "variant" | "locale">>): react_jsx_runtime.JSX.Element | null;
+
+export { ConfirmDialog as C, type ConfirmDialogProps as a, ConfirmDialogPropsSchema as b, validateConfirmDialogProps as v };

package/dist/ConfirmDialog-B3CQQGmJ.d.ts

@@ -0,0 +1,34 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { z } from 'zod';
+
+declare const ConfirmDialogPropsSchema: z.ZodObject<{
+    title: z.ZodString;
+    message: z.ZodString;
+    confirmLabel: z.ZodString;
+    cancelLabel: z.ZodString;
+    variant: z.ZodDefault<z.ZodEnum<["default", "danger"]>>;
+    locale: z.ZodDefault<z.ZodEnum<["en", "fr"]>>;
+}, "strip", z.ZodTypeAny, {
+    locale: "en" | "fr";
+    message: string;
+    title: string;
+    confirmLabel: string;
+    cancelLabel: string;
+    variant: "default" | "danger";
+}, {
+    message: string;
+    title: string;
+    confirmLabel: string;
+    cancelLabel: string;
+    locale?: "en" | "fr" | undefined;
+    variant?: "default" | "danger" | undefined;
+}>;
+type ConfirmDialogProps = z.infer<typeof ConfirmDialogPropsSchema> & {
+    onConfirm: () => void;
+    onCancel: () => void;
+};
+declare function validateConfirmDialogProps(raw: unknown): z.infer<typeof ConfirmDialogPropsSchema>;
+
+declare function ConfirmDialog(raw: Omit<ConfirmDialogProps, "variant" | "locale"> & Partial<Pick<ConfirmDialogProps, "variant" | "locale">>): react_jsx_runtime.JSX.Element | null;
+
+export { ConfirmDialog as C, type ConfirmDialogProps as a, ConfirmDialogPropsSchema as b, validateConfirmDialogProps as v };

package/dist/MarkdownRenderer.schema-Rx7kIeVA.d.cts

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+
+declare const MarkdownRendererPropsSchema: z.ZodObject<{
+    content: z.ZodString;
+    locale: z.ZodEnum<["en", "fr"]>;
+    maxLength: z.ZodDefault<z.ZodNumber>;
+    allowHtml: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    locale: "en" | "fr";
+    content: string;
+    maxLength: number;
+    allowHtml: boolean;
+}, {
+    locale: "en" | "fr";
+    content: string;
+    maxLength?: number | undefined;
+    allowHtml?: boolean | undefined;
+}>;
+type MarkdownRendererProps = z.infer<typeof MarkdownRendererPropsSchema>;
+declare function validateProps(raw: unknown): MarkdownRendererProps;
+
+export { type MarkdownRendererProps as M, MarkdownRendererPropsSchema as a, validateProps as v };

package/dist/MarkdownRenderer.schema-Rx7kIeVA.d.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+
+declare const MarkdownRendererPropsSchema: z.ZodObject<{
+    content: z.ZodString;
+    locale: z.ZodEnum<["en", "fr"]>;
+    maxLength: z.ZodDefault<z.ZodNumber>;
+    allowHtml: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    locale: "en" | "fr";
+    content: string;
+    maxLength: number;
+    allowHtml: boolean;
+}, {
+    locale: "en" | "fr";
+    content: string;
+    maxLength?: number | undefined;
+    allowHtml?: boolean | undefined;
+}>;
+type MarkdownRendererProps = z.infer<typeof MarkdownRendererPropsSchema>;
+declare function validateProps(raw: unknown): MarkdownRendererProps;
+
+export { type MarkdownRendererProps as M, MarkdownRendererPropsSchema as a, validateProps as v };

package/dist/ProgressBar.schema-CdVYx0Wq.d.cts

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+
+declare const ProgressBarPropsSchema: z.ZodObject<{
+    value: z.ZodNumber;
+    label: z.ZodString;
+    locale: z.ZodDefault<z.ZodEnum<["en", "fr"]>>;
+    colorVariant: z.ZodDefault<z.ZodEnum<["default", "warning", "danger"]>>;
+}, "strip", z.ZodTypeAny, {
+    value: number;
+    label: string;
+    locale: "en" | "fr";
+    colorVariant: "default" | "warning" | "danger";
+}, {
+    value: number;
+    label: string;
+    locale?: "en" | "fr" | undefined;
+    colorVariant?: "default" | "warning" | "danger" | undefined;
+}>;
+type ProgressBarProps = z.infer<typeof ProgressBarPropsSchema>;
+declare function validateProps(raw: unknown): ProgressBarProps;
+
+export { type ProgressBarProps as P, ProgressBarPropsSchema as a, validateProps as v };