(context.hostContext);\n return (\n \n {layout === \"wide\"\n ? \n : }\n
\n );\n};\n```\n\n`hints` is any `{ deviceCapabilities?, containerDimensions? }` — the kit's `McpViewHostContext`\nsatisfies it structurally, so the entry never imports `@casys/mcp-view`. Touch follows the host's\n`deviceCapabilities` (`touch && hover !== true`: a touch-screen laptop driven by a mouse is no\nphone) and only falls back to `matchMedia(\"(pointer: coarse)\")` when the host says nothing.\n`?layout=mobile` in the page query string forces a treatment for reviewing it without the matching\ndevice; pass `{ forced: null }` to ignore the URL, or `{ forced: \"panel\" }` to pin one. The decision\nitself — `resolveViewerLayout`, `layoutWidth`, `touchInput`, `layoutFromSearch`, `viewerBoundsStyle`\n— is exported pure, and the two measuring hooks, `useContainerWidth()` and `useCoarsePointer()`, are\nexported on their own.\n\n## Focused viewers and technical details\n\n`FocusedView` keeps one primary visualization or reading prominent and puts optional technical\nmetadata behind a closed `Disclosure`. Its `status` slot stays outside that disclosure: warnings,\nunavailable evidence and literal verification state remain visible. The existing surface supplies\nthe frame, so the preset adds no card, shadow or application chrome.\n\n```tsx\nimport { FocusedView } from \"@casys/mcp-view-components/preact/components\";\n\n{recorded.message}}\n primary={}\n detailsLabel={labels.technicalDetails}\n details={}\n/>;\n```\n\nThe preset calls `useViewerLayout` with the host hints and applies its container ref, `data-layout`\nand height bounds. At a narrow desktop width it uses `panel`; under a finger it uses `mobile` with a\nlarger disclosure target. Pass `layout` only to review a forced treatment. The primary remains\nprovider-owned; the preset never invents a preview, a status or an evidence value.\n\nUse `Disclosure` on its own for an inline technical section: `label` is supplied by the caller,\n`children` hold the detail, and optional `open` / `onToggle(open)` expose its native state. Native\n`details` / `summary` provide keyboard behavior and expanded state. Omit `open` to start closed.\n`FocusedView` requires a `detailsLabel` whenever it receives `details`; omit both to render no\ntechnical control. Keep consequential state in `status` or `primary`.\n\n## Theme\n\n`installMcpViewTheme()` installs the shared CSS once. The defaults are light-first and include an\nexplicit dark mapping (`:root[data-theme=\"dark\"]`, or `prefers-color-scheme` unless the host pins\n`data-theme=\"light\"`). The surface is the one frame a viewer shows — border, radius, panel and a 2px\naccent→brand rule — and its stacked components are separated by hairlines, so a `stack` surface\ndefaults to `gap: \"none\"`. Inside, values sit in hairline cells rather than filled tiles.\n\nTypography has three roles: the heading face for titles and large values, the body face for prose,\nand the mono face for labels, keys, units, markers, verdicts, provenance and identifiers. Sizes come\nfrom a px scale (`--mcp-view-size-micro` 10px … `--mcp-view-size-metric` 22px) so a host that\nrescales `rem` cannot squash the datasheet. The preferred faces mirror the v2 reference\n(`Space Grotesk`, `Work Sans`, `JetBrains Mono`) and fall back to native families; the theme itself\nneither embeds fonts nor makes a network font request. Apps can override the stable variables\nexported as `MCP_VIEW_THEME_TOKENS`:\n\n```css\n:root {\n --mcp-view-accent: #0d7c8a;\n --mcp-view-brand: #8a4fa3;\n --mcp-view-font-heading: \"Space Grotesk\", \"Avenir Next\", sans-serif;\n --mcp-view-font-body: \"Work Sans\", Avenir, sans-serif;\n --mcp-view-font-mono: \"JetBrains Mono\", \"SFMono-Regular\", monospace;\n --mcp-view-radius: 8px;\n}\n```\n\n### Embedded fonts\n\nA viewer bundled into one HTML file and opened inside a host iframe usually has neither network\naccess nor a CSP that allows font requests, so the preferred faces would silently fall back. The\n`/fonts` entry embeds them (three variable faces, latin subset, ~137 KB of base64 woff2, SIL Open\nFont License 1.1). It is opt-in: import it only from the viewer bundle that wants it.\n\n```ts\nimport { installMcpViewTheme } from \"@casys/mcp-view-components\";\nimport { installMcpViewFonts } from \"@casys/mcp-view-components/fonts\";\n\ninstallMcpViewFonts();\ninstallMcpViewTheme();\n```\n\n`MCP_VIEW_FONT_FAMILIES` lists the families, their weight range and the theme role each serves. The\npayload lives in `src/fonts-data.ts`, generated by `deno task fonts:fetch` and drift-checked by\n`deno task fonts:check`.\n\n## Surface App\n\n`startSurfaceApp()` (`/surface` entry) runs the whole result-driven App lifecycle for a component\nregistry: it opens on a loading status, projects every tool result into one `SurfaceDisplayState`,\nmounts the host-selected surface (or the registry default), remounts it when the host context\nchanges, guards overtaken mounts, and converts every failure into a status instead of a blank page.\nA viewer supplies its registry, the projection and how a status is rendered; everything else —\n`strict`, `theme`, the status labels, `onError`, `viewerSession` — has a documented default.\n\n```ts\nimport { createTranslator } from \"@casys/mcp-view-components\";\nimport { startSurfaceApp } from \"@casys/mcp-view-components/surface\";\n\nconst messages = createTranslator({\n defaultLocale: \"en\",\n messages: {\n solvingTitle: \"Solving\",\n solvingMessage: \"The run is still open.\",\n },\n translations: {\n fr: {\n solvingTitle: \"Résolution\",\n solvingMessage: \"L’exécution est encore ouverte.\",\n },\n },\n});\n\nconst app = await startSurfaceApp({\n root,\n info: { name: \"Run viewer\", version: \"1.0.0\" },\n registry,\n strict: true,\n documentLanguage: messages.locale,\n fromToolResult: async (result, host) => {\n if (result.isError) return { kind: \"error\", message: toolErrorMessage(result) };\n const model = parseRun(result.structuredContent);\n if (!model) return { kind: \"empty\" };\n if (model.pending) {\n return {\n kind: \"notice\",\n title: (locale) => messages(locale)(\"solvingTitle\"),\n message: (locale) => messages(locale)(\"solvingMessage\"),\n busy: true,\n };\n }\n return { kind: \"result\", result: model };\n },\n renderStatus: (status) => renderMyStatus(status),\n});\n```\n\nThe projection may return a promise and may read server resources through `host.readServerResource`.\nWithout a projection, `validate` (a type guard) is applied to `structuredContent` with a JSON-text\nfallback; passing both is refused with `SURFACE_APP_PROJECTION_CONFLICT`.\n\nEvery non-result state reaches `renderStatus` as one `SurfaceStatus` — `kind`, `message`, `title?`,\n`tone`, `busy` and the caller's optional `code`:\n\n| `kind` | When | `tone` | `busy` |\n| ------------------ | ------------------------------------------------ | --------- | ------- |\n| `loading` | before the first result, and on tool input | `info` | `true` |\n| `empty` | `{ kind: \"empty\" }` or a rejected `validate` | `neutral` | `false` |\n| `error` | `{ kind: \"error\" }`, a rejected session | `danger` | `false` |\n| `notice` | `{ kind: \"notice\" }`, defaults `neutral`/`false` | given | given |\n| `surface-required` | component-only registry without a host selection | `warning` | `false` |\n\n`code` is passed through from a `notice` or `error` state and never invented, so a viewer can key\nits own recovery hints on it. A projection that throws becomes a `Result rejected` error status and\nwipes the previous result; to keep the last good values under the failure, return a `result` that\ncarries it — the scaffold does exactly that. A mount that fails or a malformed host selection stays\non the surface route as `Surface failed` or `Surface invalid`, so a corrected selection can recover\nin place. All three are reported to `onError` (default `console.error`) and the App keeps running.\n\n`surfaceFor(data)` lets a result own its composition: a returned surface is mounted as is, with\nneither the host selection nor the registry default consulted, so a recorded session that replaces\nthe whole read model composes itself while live results keep following the host. `undefined` keeps\nthe host flow. It is asked on every mount of that result, remounts included; a malformed owned\nsurface stays on the route as `Surface invalid` and names its owner. `onTeardown` runs once when the\nhost tears the App down or `dispose()` runs, before the surface is disposed — the place to close\nwhat the App holds outside its surface, such as a bridge to the parent page. Its throw goes to\n`onError`.\n\nThe projection and the session subscription are registered before the App connects, so nothing the\nhost sends during the handshake is lost. The host context is re-applied on every\n`hostcontextchanged`, including the notifications the runtime replays from the handshake; the\nsurface is remounted only while the surface route holds a result (a surface-route failure included)\nand the context object actually moved — never while a status is shown or a transition is in flight.\n`theme: false` skips the theme install at boot only — primitives still install it when they mount.\n\nFor a renderer that already follows the CSS theme tokens, `themeUpdates: \"in-place\"` keeps that\nrenderer mounted when only the host theme changes. This preserves local camera or interaction state.\nHosts that resend a complete JSON snapshot with new object identities but the same non-theme values\ndo not remount: comparison is structural (object key order ignored, array order kept). The default\nremains `\"remount\"`; do not opt in if a component reads theme colors only at mount. Locale,\ndimensions, styles, component selection and other value changes still remount normally in either\nmode.\n\nGeneric loading, empty and failure headings follow the host locale, including `Result rejected` and\n`Session rejected` after a locale change while that status is visible. `loadingLabel`, `emptyLabel`\nand `surfaceRequiredLabel` also accept `(locale) => string`. `error` and `notice` `title`/`message`\naccept the same `SurfaceLabel` callbacks, resolved on each visible status render so a provider\ndictionary can follow the host locale without re-running `fromToolResult`, session projection or\nresource reads. Literal titles, messages and `code` stay unchanged.\n`documentLanguage: messages.locale` sets `document.documentElement.lang` to the selected dictionary\nat boot and on locale changes; omit it to leave the document language untouched. The `messages`\noption accepts a `createTranslator` catalog for additional languages. Domain values, contract\nstates, raw provider messages, codes, identifiers, numbers and units remain literal. Tool-result and\nsession projections receive `host.locale` for interface wording, never for interpreting or\nvalidating domain values.\n\n`startPreactSurfaceApp()` (`/preact`) is the same App with statuses rendered through\n`renderStatusMessage`, plus `statusClassName` for viewer-owned styling hooks; its shell keeps the\n`mcp-view-preact-surface` class 0.5 viewers style (the core default is `mcp-view-surface-shell`).\nBoth return a `SurfaceAppHandle` whose `show(state)` drives the App from outside the MCP lifecycle\nand whose `dispose()` tears it down. Option conflicts throw `SurfaceAppError`, a `TypeError` with a\nstable `code` (`SURFACE_APP_PROJECTION_CONFLICT`) and a `data.recovery` sentence; `show()` on a\nhandle the host already tore down rejects with `SURFACE_APP_CLOSED`.\n\nWhole-view recorded sessions are declared in `@casys/mcp-view-contracts` and consumed through the\ncore resource lifecycle. `viewerSession` pairs a `validate` guard with a `toState` projection; the\nApp subscribes before it connects and the runtime buffers what arrives during the handshake, so a\none-shot session cannot be lost and no individual component claims `viewer.session.apply`. The 0.6\n`validateSession`/`mapSessionToData`/`onInvalidSession` options of `startPreactSurfaceApp()` are\ngone in 0.7.0; `viewerSession: { validate, toState, onInvalid }` is the one form.\n\n## Common compositions\n\nThe kit stays small and non-prescriptive, leaving assembly to the caller. When multiple viewers\nbuild the same assembly from the same primitives, this section is what they should have found first.\n\n### Named quantity section\n\n`Card` + `MetricGrid` carries one named group of measurements. Repeat the pattern for each domain\nregion; `EmptyState` handles the no-data case without shifting layout.\n\n```tsx\n\n {items.length === 0 ? No values recorded. : }\n;\n```\n\n### Datasheet body\n\nA card-density `SemanticElement` reads as a datasheet only while every figure has one place. The\nreadings strip is the headline, so it shows either every measurement or none — a subset picked by\nposition is not a headline. Its tiles wrap into rows and a short last row widens them, so five\nreadings are four and one wide, never four and a hole. The body is `ElementSection`s, each naming\nwhat it holds: measurements in a `DataTable` (one row per quantity, the unit in its own column),\ndocumentary facts in a `KeyValueList layout=\"facts\"`, artifacts in an `ArtifactRow`. Labels are\nworded for the reader, never raw field names. One fingerprint closes the sheet in\n`ElementProvenance`; nothing shown in a section is repeated there.\n\n```tsx\n}\n reading={observables.length <= READING_STRIP_LIMIT ? observables.map(toReading) : []}\n body={\n \n {observables.length > READING_STRIP_LIMIT && (\n \n \n \n )}\n \n \n \n \n \n }\n provenance={}\n/>;\n```\n\n### Artifact collection\n\n`CollectionCard` + `ArtifactRow` keeps a single outer border for a bounded list of immutable\nartifacts. Thread the count through `eyebrow` or `actions`; `EmptyState` fills the list body when\nthere is nothing to show. `CollectionCard` is available since 0.3.x; the `eyebrow` slot on `Card`\naccepts any `ComponentChildren`, so a plain count string requires no extra component.\n\n```tsx\n 0 ? `${artifacts.length} items` : undefined}\n>\n {artifacts.length === 0\n ? No artifacts recorded.\n : artifacts.map((a) => (\n \n ))}\n;\n```\n\n## Contributing interface translations\n\nEnglish is the default and reference language. French is an optional existing translation;\nadditional languages are contributions, not a prerequisite for building or improving a viewer.\n\n`createTranslator` is a small renderer-neutral dictionary helper from the package root. Keep stable\nkeys in a complete base dictionary, and add language dictionaries as partial overrides. Select the\ntranslator from the current host locale when rendering, so the same recorded result can change its\ninterface language without changing its data.\n\n```ts\nimport { createTranslator } from \"@casys/mcp-view-components\";\n\nconst en = {\n technicalDetails: \"Technical details\",\n revisionLabel: \"Revision {revision}\",\n};\nconst fr: Partial> = {\n technicalDetails: \"Détails techniques\",\n revisionLabel: \"Révision {revision}\",\n};\nconst messages = createTranslator({ defaultLocale: \"en\", messages: en, translations: { fr } });\nconst t = messages(context.hostContext.locale);\nt(\"technicalDetails\");\nt(\"revisionLabel\", { revision: 17 });\nmessages.locale(\"fr-CA\"); // \"fr\" — the dictionary actually selected\n```\n\nLookup falls back **per key** through the exact locale, its language parents, then the base\ndictionary: with an English base, `fr-CA` → `fr` → English. A missing entry in a partial dictionary\ndoes not hide the base text. An absent or invalid host locale uses the configured default locale;\nthere is no global mutable locale. `messages.locale(hostLocale)` uses that same chain and returns\nthe exact registered locale, the matched parent, or the canonical default — pass it as\n`documentLanguage` so `document.documentElement.lang` names the selected dictionary. Keep\ninterpolation names such as `{revision}` intact. Render returned messages as text, never as HTML.\n\nTranslate interface labels and helper text only. Preserve authored names, payload values, units,\nidentifiers, digests, server messages and literal contract states such as `documentary`,\n`unverified`, `unresolved` or `TRACE GAP`. Use `Intl.NumberFormat` and `Intl.DateTimeFormat` with\nthe host locale for presentation; formatting must not convert units or overwrite the stored\nevidence.\n\nFor a new locale contribution, use this short PR checklist:\n\n- Name the locale tag and the dictionary being extended (shared interface or a particular MCP).\n- Keep existing keys stable; add any new key to the base dictionary first.\n- List deliberately missing translations and preserve every interpolation placeholder.\n- Include one small example showing a translated label and fallback for an untranslated key.\n- Check the changed wording in a narrow viewer, including accessible labels and technical details.\n- Confirm that authored data and contract states retain their original bytes and meaning.\n\nThe kit exports its English and French interface dictionaries as `MCP_VIEW_MESSAGES_EN` and\n`MCP_VIEW_MESSAGES_FR`. MCPs keep their domain-specific interface dictionaries beside their viewers;\nthey can reuse the same helper without importing a new localization runtime.\n\n## Result-viewer scaffold (Deno/JSR only)\n\nThe project generator intentionally uses Deno filesystem APIs and `deno fmt`. The generated\n`src/main.ts` is a component registry plus one `fromToolResult` projection handed to\n`startSurfaceApp()` from `@casys/mcp-view-components/surface`; it hand-rolls no App lifecycle. Its\n`build.ts` accepts `MCP_VIEW_MODULE` and `MCP_VIEW_COMPONENTS_MODULE` overrides (the `mod.ts` of a\nlocal checkout); the `/surface` entry is derived from the latter unless\n`MCP_VIEW_COMPONENTS_SURFACE_MODULE` names it. Run the generator from JSR:\n\n```sh\ndeno run -A jsr:@casys/mcp-view-components@0.9.0/scaffold result-viewer ./result-viewer\n```\n\nThe npm package contains only the runtime and presentation entry points. It does not export or ship\n`@casys/mcp-view-components/scaffold`; Node ESM imports and CommonJS requires of that subpath are\nexpected to fail with `ERR_PACKAGE_PATH_NOT_EXPORTED` rather than loading a Deno-only module.\n","readmeFilename":"README.md"}