@vantageos/mosaic 0.3.1 → 0.5.0

package/CHANGELOG.md

@@ -9,15 +9,99 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+---
+
+## [0.5.0] — 2026-10-11 — MCP App kit for ChatGPT and Claude (D0)
+
+### Added
+- **Behaviour change — declared secrets never reach `content[]`.** `createMosaicResource` (published `./server`) now strips every field declared in `MOSAIC_NEVER_SERIALISE` from the embedded props BY DEFAULT; pass `includeSecrets: true` to keep the previous behaviour. `createMosaicToolResult` carries a declared secret only in `_meta["mosaic/secrets"]` and throws `MosaicSecretLeakError` (naming the field, never the value) if one appears in `content[]`, or if a declared field does not exist on the view. A `TableView` column flagged `sensitive` is masked in markdown and stripped from the embedded props. `TokenDisplayOnceModal`'s fallback carries label, scope, expiry and an issuer-supplied fingerprint, never the token.
+- **Behaviour notes for the #75 fallbacks.** `openLink` now hands the host the PARSED href, so `https://x.example` is sent as `https://x.example/` (trailing slash; a raw string with an embedded newline can no longer reach the host). The TransactionPreview markdown fallback joins the swap route with `→` instead of `>` (`USDC → WFUSE → FUSE`), because `>` is escaped as markdown. The secret guard in `createMosaicToolResult` compares case-folded and NFKC-normalised text on both sides.
+- **Gate 4 script fail-closed** (`scripts/cross-runtime-subpath-coverage-check.py`): exit 2 naming the input for any unreadable input (package root, `package.json`, registry, built entry, empty category set, a registry that yields no categories or has no `components` list, or the PyYAML and built-in readers disagreeing) and exit 1 only for a real coverage gap; the default `--package-root` is the package the script lives in, not the working directory; the registry cross-check no longer skips without PyYAML (built-in reader) or with a missing registry (`--skip-registry-check` is the explicit opt-out).
+- **MCP Apps views and host layer, delivery 2 (task k17ehg71z31ec50fkh95p3xxr58fjm98; Eta corrections k178bt8enj99wv1gtc8h3315kx8g0w13).**
+  - **Views** (React + Preact barrels, FR+EN, Zod, Skeleton loading, `{}` parses as an empty state, A-1 markdown): `StatCard` (R08) and `BalanceCard` (R09, Fuse balance, exact decimal strings) in `display`; `MessageFeed` (R03, read-only, plain text, safe links) and `PipelineBoard` (R06, read-only, fullscreen board / inline summary, stage filter chips) in `display`; `Timeline` (R02) in `progress`; `TransactionPreview` (R11, prepare-only, swap-quote variant, **no sign / send / approve control**, "NOT SIGNED - preparation only") in `confirmation`.
+  - **`TableView` extended** (R01 / R10, every new prop optional): sortable columns with `aria-sort`, `single` / `multiple` selection (`onSelectionChange` rows + keys), sticky header, compact density, column `align` / `width`, `amount` (exact decimal string compare) and `icon` cell kinds, `loading` Skeleton, serialisable `rows` in the schema.
+  - **`RadioGroup` / `MultiSelect`** (R25): `appearance` `segmented` | `chips` (RadioGroup) and `chips` (MultiSelect: visible toggle buttons, `aria-pressed`, no dropdown).
+  - **Host layer** (`./host`, `./react/host`, `./preact/host`): safe-area insets (H01), host style variables bridged onto mosaic-tokens + host fonts + transparent background (H02), `sendMessage` / `openLink` helpers that refuse what the host cannot honour (H04, H18), typed model-context blocks + `openai/modelContext` read + `selectionModelContext` (H03), hooks `useMosaicHostLayout`, `useSendMessage`, `useOpenLink`.
+  - **Server**: `buildMcpAppResource({ visibility, hostFonts })` (H05); `createMosaicToolResult` returning `content: [text, ui:// resource]` (A-1) and a `<name>ToMarkdown` for all 12 components (H17). `createMosaicResource` now supports 12 components, honours its `uri` and `markdownFallback` options, and `_meta.ui.fallback` (kept: published contract) carries the data instead of a title and note.
+  - **Adapter**: `startSizeReporting` / `postSizeChanged` send `ui/notifications/size-changed` from the raw adapter (H15).
+- **Fix — host-context dispatcher** (Eta #74 re-gate): a foreign handler that overwrites `app.onhostcontextchanged` while subscribers are live is adopted as `previous` and the dispatcher reinstalled on the next subscribe; resubscribe-after-full-unsubscribe is pinned by a test that goes RED when `dispatchers.delete(app)` is removed.
+- **MCP Apps host layer for ChatGPT and Claude (task k17ehg71z31ec50fkh95p3xxr58fjm98, items 1-2).** New subpaths `./host` (framework-agnostic core: host theme/display mode/locale/container dimensions, `openai/deepLink` when present, `requestDisplayMode` limited to inline | fullscreen with a typed AND runtime refusal of `pip` for a ChatGPT host, `updateModelContext` over `ui/update-model-context`, host theme mapped onto mosaic-tokens `data-theme`), `./react/host` and `./preact/host` (hooks over the core) and `./server/resource` (`buildMcpAppResource`: pure, no React/DOM; `_meta.ui` standard keys first with the four csp arrays explicit, `domain` derived from `servedUrl` for Claude, `openai/*` keys only when passed: `_meta["openai/ui"]` display modes on the resource, `openai/outputTemplate` and `openai/ui` entrypoints on the tool; deepLink typed as `{ url }`; ChatGPT detected from `openai/*` keys, no user-agent sniffing). Composes with ext-apps `registerAppResource`/`registerAppTool`, which pass `_meta` through. No new dependency: the ext-apps `App` is typed structurally.
+- **Fix — `react/media` and `preact/media` were empty barrels; Gate 4 passed anyway.** Both now re-export `StatusBadge` (+ props type, schema, validator) from the existing `display` components (display exports kept, no new component), and Gate 4 now fails any runtime subpath entry whose built `.js` or `.d.ts` exports zero symbols, naming the entry (`exports-zero-symbols`).
+
+---
+
+## [0.4.0] — 2026-10-04
+
 ### Added
+- **Badge primitive, cross-runtime.** `Badge` is exported from `./display`, `./react/display` and
+  `./preact/display`, with its schema, stories, i18n strings and a 205-line React test. Landed on
+  `main` in #61 against `target 0.3.2` and unpublished until this release, so no consumer could
+  import it.
+- **`docs/GA-RELEASE-V0.3.1.md`** — the canonical release procedure (bilingual EN+FR): the five
+  fail-closed CI gate jobs, the `ETA_APPROVED_TASK_ID` approval hook, the
+  `prepublishOnly`/`postpublish` workspace-rewrite pattern, the 0.3.0 → 0.3.1 incident and its
+  lesson, the cross-runtime architecture and the migration guide. Written for 0.3.1 and itself
+  unpublished until now, which is why this release follows it rather than a recalled procedure.
+
+### Documentation
+- **The package README was frozen at 0.3.1 and is rewritten against the built artifact.**
+  It told a consumer to `npm install @vantageos/mosaic@^0.2.0 @vantageos/mosaic-tokens@^0.2.0`,
+  neither of which is what ships. Corrected to the versions actually published.
+- **Six sentences claiming form primitives were still unshipped are deleted.** Each had
+  been appended as a primitive landed and never removed, so each sat directly above a
+  table row documenting the very primitive it called missing. All of Input, Textarea,
+  Select, Checkbox, MultiSelect, RadioGroup and FieldArray are exported — read from
+  `dist/react/forms.d.ts`, not from the prose.
+- **A derived per-subpath export inventory replaces a partial list that read as complete.**
+  It records that `media` exports no components although it is one of the seven categories
+  gated for cross-runtime parity.
+- **Bundle sizes are the `size-limit` output with their gates**, replacing figures for
+  surfaces the gate no longer measures.
+- **The changelog link pointed at the repo root**, which is not the file the tarball
+  carries; it now points at this one.
+- **The README stated MIT while `package.json` carried no `license` field** and `files`
+  shipped no LICENSE, so every version up to 0.3.1 reached consumers with no licence terms
+  at all.
+
+### Added — licence
+- **`FSL-1.1-Apache-2.0` is now declared and shipped.** `package.json` carries the
+  `license` field, `LICENSE` is in `files`, and the file is byte-identical to the one every
+  sibling `@vantageos` package ships
+  (sha256 `3d458972e6e84e5d2361a886ef64b07aefdc38dd8955e281ea8c2ae8849646a4`). Verified
+  against what the registry serves for `mosaic-blocks`, `mosaic-tokens` and `mcp-doctor` —
+  this package was the only one of the four publishing `license: NONE`. Nothing about the
+  terms is new; they were simply never attached to this package.
+
+### Changed
+- **`@vantageos/mosaic-tokens` moves from `^0.2.0` to `^0.7.0`** in the published manifest. This is
+  why the release is `0.4.0` and not the `0.3.2` the source commit targeted: `^0.2.0` does **not**
+  satisfy `0.7.0` (a caret on a `0.x` range pins the minor), so a consumer upgrading receives a
+  five-minor jump in a runtime dependency. On a `0.x` package the minor is the only available
+  signal for that, and a patch number would have understated it.
+
+  The range was never edited by hand — the manifest carries `workspace:*` and `prepublishOnly`
+  resolves it to whatever the sibling package is at, which is now `0.7.0`. That is correct
+  behaviour and it is precisely why the published version has to be derived from the packed
+  tarball rather than from the commit that said `target 0.3.2`.
+
+### Note on this release
+Nothing else changed in the source. `latest` served `0.3.1` from 2026-06-13 until this version, so
+the items above are the entire delta a consumer receives — derived by locating the commit that set
+the version to `0.3.1` and listing what touched `packages/mosaic` after it, not by reading a date
+window (a date window includes the release commits themselves and reported 19).
+
+
+### Recorded late — shipped by 0.4.0 at the latest, never listed in a release section
+
+These entries sat under `[Unreleased]` after their code had shipped. Each one's commit is an ancestor of the 0.4.0 release commit `12475a6` (`git merge-base --is-ancestor <sha> 12475a6`).
+
 - **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
+#### 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/*`.
@@ -28,6 +112,8 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+---
+
 ## [0.3.1] — 2026-06-13 — hotfix: workspace:* leak in published 0.3.0 manifest (Path B — root-cause fix)
 
 ### Fixed

package/LICENSE

@@ -0,0 +1,110 @@
+Functional Source License, Version 1.1, Apache 2.0 Future License
+
+Abbreviation
+
+FSL-1.1-Apache-2.0
+
+Notice
+
+Copyright 2026 VantageOS (ElPi Corp)
+
+Terms and Conditions
+
+Licensor:             VantageOS (ElPi Corp)
+
+Licensed Work:        VantagePeers
+                      The Licensed Work is (c) 2026 VantageOS (ElPi Corp)
+
+Additional Use Grant: You may make production use of the Licensed Work,
+                      provided Your use does not include offering the Licensed
+                      Work to third parties as a hosted or managed service
+                      where the service provides users with access to any
+                      substantial set of the features or functionality of the
+                      Licensed Work.
+
+Change Date:          2028-04-03 (two years from publication)
+
+Change License:       Apache License, Version 2.0
+
+For information about alternative licensing arrangements for the Licensed Work,
+please contact: contact@vantageos.com
+
+License text below is provided for informational purposes only.
+
+---
+
+Functional Source License, Version 1.1, Apache 2.0 Future License
+
+1. Purpose
+
+This license gives you broad permission to use, modify, and share this
+software, with one important condition: you may not use it to compete with us.
+
+2. Acceptance
+
+To use the software, you must agree to these terms. If you do not agree, you
+may not use the software.
+
+3. Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide, non-
+sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject
+to the limitations below.
+
+4. Limitations
+
+You may not make the functionality of the software available to third parties
+as a service, or otherwise use the software to provide a service to third
+parties that competes with the licensor.
+
+5. Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license or becomes able to license, to make, have made, use, sell, offer for
+sale, import, and have imported the software, in each case subject to the
+limitations and conditions in this license.
+
+6. Fair Use
+
+This license is not intended to limit any rights you may have under applicable
+fair use or other laws.
+
+7. No Other Rights
+
+These terms do not grant any other rights. The licensor reserves all rights not
+expressly granted.
+
+8. Termination
+
+Your license is automatically terminated if you violate the terms. However, if
+you cure the violation within 30 days of discovering it, your license is
+reinstated retroactively.
+
+9. Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED.
+
+10. Limitation of Liability
+
+TO THE EXTENT PERMITTED BY LAW, THE LICENSOR IS NOT LIABLE FOR ANY DAMAGES
+ARISING FROM THE USE OF THE SOFTWARE.
+
+11. Change Date and License
+
+After the Change Date, the licensor grants you the rights under the Change
+License.
+
+12. Definitions
+
+"Compete" means providing a product or service that is substantially similar
+to, or a replacement for, all or a significant portion of the Licensed Work.
+
+---
+
+Apache License, Version 2.0
+
+After the Change Date (2028-04-03), this software will be available under the
+Apache License, Version 2.0. See https://www.apache.org/licenses/LICENSE-2.0
+for full text.

package/README.md

@@ -1,15 +1,15 @@
 # @vantageos/mosaic
 
-Fleet-wide MCP UI design system. Zod-validated, taxonomy-organized (6 categories: progress, input, display, artifacts, confirmation, media), streaming-ready, **cross-runtime React 19 + Preact 10**. Built for MCP Apps (SEP-1865 extension).
+Fleet-wide MCP UI design system. Zod-validated, taxonomy-organized (7 categories: artifacts, confirmation, display, forms, input, media, progress), streaming-ready, **cross-runtime React 19 + Preact 10**. Built for MCP Apps (SEP-1865 extension).
 
 ## Install
 
 ```sh
 # React 19
-npm install @vantageos/mosaic@^0.2.0 @vantageos/mosaic-tokens@^0.2.0 react react-dom
+npm install @vantageos/mosaic@^0.5.0 @vantageos/mosaic-tokens@^0.7.0 react react-dom
 
 # Preact 10
-npm install @vantageos/mosaic@^0.2.0 @vantageos/mosaic-tokens@^0.2.0 preact
+npm install @vantageos/mosaic@^0.5.0 @vantageos/mosaic-tokens@^0.7.0 preact
 ```
 
 All runtime peers are marked optional via `peerDependenciesMeta` — install only what your runtime needs.
@@ -32,19 +32,22 @@ This constraint is codified locally via the `build` script (the `NODE_OPTIONS` p
 |---|---|---|
 | `@vantageos/mosaic` | React 19 (back-compat) | v0.1.x consumers (Sigma VP, Theta CRM) |
 | `@vantageos/mosaic/<cat>` | React 19 (back-compat) | Tree-shakable category imports v0.1.x style |
-| `@vantageos/mosaic/react` | React 19 | New v0.2.0+ React consumers — explicit runtime opt-in |
+| `@vantageos/mosaic/react` | React 19 | React consumers — explicit runtime opt-in (the preferred surface since v0.2.0) |
 | `@vantageos/mosaic/react/<cat>` | React 19 | Tree-shakable category imports under explicit react/ prefix |
 | `@vantageos/mosaic/preact` | Preact 10 | Mu vantage-bridge iframe, Chi gptpowerups (LLM-host target) |
 | `@vantageos/mosaic/preact/<cat>` | Preact 10 | Tree-shakable category imports under preact/ prefix |
 | `@vantageos/mosaic/tokens` | runtime-free | Re-export of `@vantageos/mosaic-tokens` |
 | `@vantageos/mosaic/server` | Node | `createMosaicResource()` MCP UI builder (runtime-agnostic) |
+| `@vantageos/mosaic/server/resource` | Node | `buildMcpAppResource()` MCP Apps `_meta` helper (pure, no React, no DOM) |
+| `@vantageos/mosaic/host` | runtime-free | Host-context core (theme, display mode, locale, model context) |
+| `@vantageos/mosaic/react/host` · `/preact/host` | React 19 · Preact 10 | Hooks over the host-context core |
 
 `<cat>` = `progress` | `input` | `display` | `artifacts` | `confirmation` | `media`.
 
 ## Quick start
 
 ```tsx
-// React 19 — preferred v0.2.0+ surface
+// React 19 — the preferred runtime-explicit surface
 import { ProgressBar } from "@vantageos/mosaic/react/progress";
 import { ConfirmDialog } from "@vantageos/mosaic/react/confirmation";
 import "@vantageos/mosaic-tokens/css"; // declares --mosaic-* vars on :root
@@ -64,7 +67,7 @@ export function MyComponent({ progress, label }: { progress: number; label: stri
 }
 ```
 
-## Forms (v0.3.0-alpha.1)
+## Forms
 
 `@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.
 
@@ -130,17 +133,14 @@ export function SignupForm({ onSubmit }: { onSubmit: (data: z.infer<typeof schem
 | `<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
 
@@ -191,13 +191,10 @@ export function PlanSelector() {
 - `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.
 
 
 
@@ -214,10 +211,163 @@ const resource = createMosaicResource({
 ```
 
 
+## MCP Apps host layer (ChatGPT and Claude)
+
+Standard MCP Apps keys come first; `openai/*` keys are strictly additive. A view built
+on this layer works with no `openai` key at all, and never requests `pip` for ChatGPT.
+`@modelcontextprotocol/ext-apps` is **not** a dependency: the core types the `App`
+structurally, so any `App` instance fits.
+
+### Resource helper (server, pure)
+
+```ts
+import { buildMcpAppResource } from "@vantageos/mosaic/server/resource";
+
+const { resource, toolMeta } = buildMcpAppResource({
+  uri: "ui://mosaic/tasks",
+  html,                                  // your bundled single-file view
+  csp: { connectDomains: ["https://api.example.com"] }, // the 4 arrays are always emitted
+  servedUrl: "https://example.com/mcp",  // Claude `ui.domain` is DERIVED from it, never typed
+  prefersBorder: true,
+  openai: { outputTemplate: "ui://mosaic/tasks", preferredDisplayMode: "inline" }, // optional
+});
+// resource._meta = { ui: { csp, prefersBorder, domain }, "openai/ui"?: { availableDisplayModes?, preferredDisplayMode? } }
+// toolMeta       = { ui: { resourceUri }, "openai/outputTemplate"?, "openai/ui"?: { entrypoints } }
+```
+
+`domain` is `{sha256(servedUrl) first 32 hex}.claudemcpcontent.com` and is absent when
+`servedUrl` is not given. `openai.availableDisplayModes` / `preferredDisplayMode` accept
+`inline` | `fullscreen` only; `pip` throws.
+
+It composes with `@modelcontextprotocol/ext-apps/server`: `registerAppResource` and
+`registerAppTool` pass `_meta` through (they only default the MIME type and back-fill the
+deprecated flat `ui/resourceUri`), so feed them `resource._meta` and `toolMeta`; this helper adds
+the csp defaults, the derived Claude `domain` and the additive `openai/*` keys they do not produce.
+
+### Host context (view)
+
+```tsx
+import { useMosaicHostTheme, useRequestDisplayMode, useUpdateModelContext } from "@vantageos/mosaic/react/host";
+// Preact: the same names from "@vantageos/mosaic/preact/host"
+
+const ctx = useMosaicHostTheme(app); // theme, displayMode, locale, containerDimensions, deepLink
+const goFullscreen = useRequestDisplayMode(app);   // "inline" | "fullscreen"; pip refused for ChatGPT
+const tellModel = useUpdateModelContext(app);      // ui/update-model-context
+```
+
+`ctx.theme` is mapped onto mosaic-tokens (`data-theme` light/dark, applied to `<html>`).
+`ctx.deepLink` reads `hostContext["openai/deepLink"]` (`{ url }`) when present and is `undefined`
+otherwise. ChatGPT is detected from `openai/*` keys in the host context or experimental host
+capabilities (the spec defines no host-identification field; no user-agent sniffing). Framework-free equivalents (`readHostContext`, `requestDisplayMode`,
+`updateModelContext`, `subscribeHostContext`, `applyMosaicTheme`) live in
+`@vantageos/mosaic/host`.
+
+### Host layout, messages and links (view)
+
+```tsx
+import { useMosaicHostLayout, useSendMessage, useOpenLink } from "@vantageos/mosaic/react/host";
+
+useMosaicHostLayout(app); // data-theme + safe-area padding + host style variables + host fonts
+const send = useSendMessage(app); // ui/message: await send("Show the overdue tasks")
+const open = useOpenLink(app);    // ui/open-link: await open("https://wallet.example/swap?q=1")
+```
+
+* **Safe-area insets** (`hostContext.safeAreaInsets`, MCP Apps spec): applied as root padding and as
+  `--mosaic-safe-area-<side>` variables (for `scroll-padding`).
+* **Host style variables** (`hostContext.styles.variables`, 76 standardized keys) are written on the
+  root and bridged onto the mosaic-tokens custom properties they correspond to (`HOST_TO_MOSAIC_TOKENS`);
+  variables the host does not pass leave the mosaic-tokens defaults untouched. Host fonts
+  (`styles.css.fonts`) are injected once; add the Claude font origin to `csp.resourceDomains` with
+  `buildMcpAppResource({ hostFonts: true })`. `applyTransparentBackground(document)` sets html/body to
+  `transparent` (Claude transparent theming).
+* **`sendMessage`**: options `{ target, send }` need the host to advertise `openai/message` and a
+  non-mobile platform; otherwise it THROWS rather than silently dropping `send: false`.
+* **`openLink`**: http(s) only; the host's denial reason is thrown (`HostRequestError`).
+* **Typed model context**: `textBlock(text, { title, thumbnail, background })` builds blocks with
+  `_meta["openai/title"]`, `_meta["openai/thumbnail"]` and `annotations.audience: ["assistant"]`;
+  `selectionModelContext(rows, columns, locale)` turns a table selection into one titled block (feed it
+  to `updateModelContext` from `onSelectionChange`); `hostContext["openai/modelContext"]` is read into
+  `ctx.modelContext` (`null` = cleared by the user).
+* **Tool visibility**: `buildMcpAppResource({ visibility: ["app"] })` emits `_meta.ui.visibility`
+  (omitted = the spec default `["model", "app"]`).
+* **Size reporting**: a view that talks to the host through the raw adapter calls
+  `startSizeReporting()` (`ui/notifications/size-changed` through a ResizeObserver). The ext-apps `App`
+  does this itself with `autoResize`.
+
+### Tool results with an A-1 markdown fallback (server)
+
+```ts
+import { createMosaicToolResult } from "@vantageos/mosaic/server";
+
+return createMosaicToolResult("PipelineBoard", { stages, currency: "EUR" }, "en");
+// { content: [ { type: "text", text: "# Pipeline\n\n| Stage | Deals | Total | ..." },
+//              { type: "resource", resource: { uri: "ui://mosaic/pipelineboard", ... } } ] }
+```
+
+The text block carries the view's DATA (App standard A-1: a client with no UI layer gets an equivalent,
+meaningful answer). All 12 supported components have a pure `<name>ToMarkdown(props, locale)`, also
+exported from `@vantageos/mosaic/server`. `_meta.ui.fallback` is kept (it is part of the published
+`createMosaicResource` result) and now holds the same text instead of a title and a note. A one-time
+token's value is never written into `content[]`.
+
+**Secret guard.** `MOSAIC_NEVER_SERIALISE` lists, per view, the fields whose value must never reach
+`content[]`. `createMosaicToolResult` renders the fallback from the props without them, delivers them in
+the result `_meta["mosaic/secrets"]`, and refuses (`MosaicSecretLeakError`) if any non-empty declared
+value still appears, at any length. The comparison is case-folded and NFKC-normalised on both sides, so
+`ABCD` is an echo of `abcd`; a very short secret can therefore also collide with unrelated text and
+refuse loudly (the issuer keeps it out of the other props).
+
 ## Components
 
+### What each subpath actually exports
+
+Derived from the built type declarations, not maintained by hand:
+
+```sh
+# capitalised exports per subpath, excluding the
+# Props/Schema/Validated/Option/Args/Return/Options/Shape/Mode/Type/Controls suffixes
+node -e '...' # see the release PR for the exact script
+```
+
+| Subpath | Exports |
+|---|---|
+| `forms` | Checkbox, ErrorDisplay, FieldArray, FormField, FormProvider, Input, MultiSelect, RadioGroup, Select, SubmitButton, Textarea |
+| `display` | BalanceCard, Badge, EmptyState, MessageFeed, PipelineBoard, Skeleton, StatCard, StatusBadge, StreamingTableView, TableView, VirtualList |
+| `progress` | ProgressBar, Timeline |
+| `input` | Tabs |
+| `confirmation` | Alert, ConfirmDialog, ConfirmModal, TokenDisplayOnceModal, TransactionPreview |
+| `artifacts` | MarkdownRenderer |
+| `media` | *(none)* |
+
+Two things this table says that prose would have hidden. **`media` exports no
+components**, although it is one of the seven categories gated for cross-runtime
+parity — the subpath exists and is empty of components. And the sections below
+document only a few of these; the table is the inventory, the sections are
+examples. Previously the sections WERE presented as the inventory, which is how
+six separate sentences came to claim that form primitives were still unshipped
+while a table row documenting each one sat directly beneath them.
+
+The same list for `preact` is identical by construction — cross-runtime parity is
+gated in CI (`scripts/verify-build-parity.sh`).
+
 ### Display
 
+#### Badge
+
+Static label primitive, cross-runtime. New in 0.4.0 — it was merged to `main` well
+before and shipped in no published version until then.
+
+```tsx
+import { Badge } from "@vantageos/mosaic/react/display";
+// Preact: import { Badge } from "@vantageos/mosaic/preact/display";
+
+<Badge variant="success">Active</Badge>
+```
+
+See `src/components/display/Badge.schema.ts` for the prop contract and
+`Badge.stories.tsx` for the rendered variants — both ship in the repo, and the
+schema is the authority on the props rather than this snippet.
+
 #### VirtualList
 
 Generic virtualized list for large datasets. Uses @tanstack/react-virtual v3 (already bundled via TableView). Cross-runtime: React 19 + Preact 10.
@@ -260,7 +410,7 @@ type Task = { id: string; title: string; status: string };
 ## 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.
-- **Pattern 2 (6-category taxonomy)** — components live under exactly one category. Bilingual `category.meta.json` per category.
+- **Pattern 2 (category taxonomy)** — components live under exactly one category. Bilingual `category.meta.json` per category. The category list is the bare subpaths in the `exports` map, which is the authority; a count written here would be wrong at the next category added, as it was.
 - **Pattern 3 (Registry-gated)** — `registry.yaml` declares every component; CI gate ensures parity between source and registry.
 - **Pattern 4 (Streaming-hydration ready)** — components opt-in to MCP Apps streaming via `getStreamFor()` callbacks.
 
@@ -278,18 +428,40 @@ Consumer-driven i18n contract: components NEVER render raw alphabetic text as JS
 // <ProgressBar value={50} label="Uploading…" />
 ```
 
-## Bundle sizes (v0.2.0)
+## Bundle sizes
 
-| Surface | gz |
-|---|---|
-| `@vantageos/mosaic-tokens/dist/index.js` | 649 B (87% under the 5 KB gate) |
-| `@vantageos/mosaic-tokens/src/tokens.css` | 560 B (81% under the 3 KB gate) |
-| Per-component subpath (React) | tree-shakeable, see size-limit.json |
+Every figure below is the output of `pnpm --filter @vantageos/mosaic run size-limit`
+against the built `dist/`, and the gates are the `limit` values in
+`packages/mosaic/.size-limit.json`. Re-run the command rather than trusting this
+table: a size written by hand is wrong at the next dependency bump.
+
+| Surface | gz | gate |
+|---|---|---|
+| `dist/index.js` | 133.21 kB | 250 kB |
+| `dist/react/forms.js` | 20.79 kB | 50 kB |
+| `dist/preact/forms.js` | 20.79 kB | 50 kB |
+
+Per-component subpaths are tree-shakeable; only the three surfaces above are gated.
 
 ## License
 
-MIT. © VantageOS / ElPi Corp.
+**FSL-1.1-Apache-2.0** — Functional Source License, Version 1.1, Apache 2.0 Future
+License. © VantageOS / ElPi Corp.
+
+The full text ships in the published tarball as [`LICENSE`](./LICENSE), and
+`package.json` carries `"license": "FSL-1.1-Apache-2.0"`, so a consumer receives the
+terms with the package rather than having to find them.
+
+This is the same licence as every sibling `@vantageos` package — verified against
+what the registry actually serves for `@vantageos/mosaic-blocks`,
+`@vantageos/mosaic-tokens` and `@vantageos/mcp-doctor`, not against a convention
+recalled from elsewhere, and the file is byte-identical to theirs
+(sha256 `3d458972e6e84e5d2361a886ef64b07aefdc38dd8955e281ea8c2ae8849646a4`).
+
+Versions up to and including 0.3.1 shipped with no licence field and no licence
+file. From 0.4.0 they are present.
 
 ## Changelog
 
-See repo root [`CHANGELOG.md`](../../CHANGELOG.md).
+[`CHANGELOG.md`](./CHANGELOG.md), which ships inside the published tarball — the
+repo-root file this used to point at is not what a consumer receives.