@xemahq/ui-kernel 0.9.0 → 0.9.1

package/src/vista/html/custom-ui-srcdoc.spec.ts

@@ -0,0 +1,151 @@
+/**
+ * Custom-UI srcdoc / CSP builder — the security invariant lives HERE.
+ *
+ * These assertions pin the strict-CSP posture that makes running author- and
+ * agent-authored content safe, on BOTH forms the frame renders: the compiled,
+ * SRI-pinned chunk (`script-src '<hash>'`) and the untrusted static document
+ * (`script-src 'none'`). The mutation blocks prove the invariants IN ISOLATION:
+ * the suite goes RED if the CSP `script-src` hash is dropped or loosened (e.g.
+ * to `'unsafe-inline'` / a wildcard), or if the static-document policy ever
+ * grew a script source.
+ *
+ * Migrated verbatim from `app-forge-web` when the frame was promoted into the
+ * UI kernel; runs under the host-web vitest mirror (this package carries no
+ * vitest dep).
+ */
+import { describe, expect, it } from 'vitest';
+
+import {
+  buildCustomUiFrameCsp,
+  buildCustomUiSrcDoc,
+  buildUntrustedHtmlFrameCsp,
+  buildUntrustedHtmlSrcDoc,
+  CustomUiSrcDocError,
+} from './custom-ui-srcdoc';
+
+const INTEGRITY = 'sha384-AbC123+/def456Ghi789jklMnoPqr==';
+const COMPILED = 'export default function C(){return null}';
+
+describe('buildCustomUiFrameCsp', () => {
+  it('emits the exact airtight directive string, pinning the server hash', () => {
+    expect(buildCustomUiFrameCsp(INTEGRITY)).toBe(
+      `default-src 'none'; script-src '${INTEGRITY}'; style-src 'unsafe-inline'; base-uri 'none'; form-action 'none'`,
+    );
+  });
+
+  it('script-src carries the server integrity token verbatim', () => {
+    expect(buildCustomUiFrameCsp(INTEGRITY)).toContain(
+      `script-src '${INTEGRITY}'`,
+    );
+  });
+
+  it('never grants scripts unsafe-inline or a wildcard', () => {
+    const csp = buildCustomUiFrameCsp(INTEGRITY);
+    expect(csp).not.toContain("script-src 'unsafe-inline'");
+    expect(csp).not.toContain('script-src *');
+    expect(csp).toContain(`default-src 'none'`);
+  });
+});
+
+describe('buildCustomUiSrcDoc', () => {
+  const srcDoc = buildCustomUiSrcDoc({
+    compiledOutput: COMPILED,
+    integrity: INTEGRITY,
+    styleCss: ':root{--x:1}',
+  });
+
+  it('embeds the pinned CSP as a meta http-equiv', () => {
+    expect(srcDoc).toContain(
+      `<meta http-equiv="Content-Security-Policy" content="${buildCustomUiFrameCsp(
+        INTEGRITY,
+      )}" />`,
+    );
+  });
+
+  it('inlines the chunk verbatim as the one module script (hash must match)', () => {
+    expect(srcDoc).toContain(`<script type="module">${COMPILED}</script>`);
+  });
+
+  it('carries the #root mount point the self-mount wrapper renders into', () => {
+    expect(srcDoc).toContain('<div id="root"></div>');
+  });
+
+  it('inlines the design-system style (style-src unsafe-inline)', () => {
+    expect(srcDoc).toContain('<style>:root{--x:1}</style>');
+  });
+
+  it('refuses a chunk containing a literal </script (would truncate the module)', () => {
+    expect(() =>
+      buildCustomUiSrcDoc({
+        compiledOutput: 'const x = "a</script><script>alert(1)</script>";',
+        integrity: INTEGRITY,
+        styleCss: '',
+      }),
+    ).toThrow(CustomUiSrcDocError);
+  });
+
+  // ── MUTATION TEST (security invariant, isolated) ───────────────────────────
+  // A loosened policy that drops the hash pin must FAIL these assertions. This
+  // proves the guard is load-bearing: remove/loosen the script-src hash and the
+  // suite goes red.
+  it('MUTATION: dropping the script-src hash makes the CSP invalid — caught', () => {
+    const loosened = `default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; base-uri 'none'; form-action 'none'`;
+    // The real builder must NOT equal the loosened (hash-dropped) policy…
+    expect(buildCustomUiFrameCsp(INTEGRITY)).not.toBe(loosened);
+    // …and the real policy MUST pin the exact hash the loosened one dropped.
+    expect(buildCustomUiFrameCsp(INTEGRITY)).toContain(
+      `script-src '${INTEGRITY}'`,
+    );
+  });
+});
+
+describe('buildUntrustedHtmlFrameCsp', () => {
+  it('emits the same airtight policy with script-src none', () => {
+    expect(buildUntrustedHtmlFrameCsp()).toBe(
+      `default-src 'none'; script-src 'none'; style-src 'unsafe-inline'; base-uri 'none'; form-action 'none'`,
+    );
+  });
+});
+
+describe('buildUntrustedHtmlSrcDoc', () => {
+  const DOCUMENT = '<h1>Report</h1><p>Static, agent-authored markup.</p>';
+  const srcDoc = buildUntrustedHtmlSrcDoc({
+    document: DOCUMENT,
+    styleCss: ':root{--x:1}',
+  });
+
+  it("pins script-src 'none' — an authored <script> can NEVER execute", () => {
+    expect(srcDoc).toContain(
+      `<meta http-equiv="Content-Security-Policy" content="${buildUntrustedHtmlFrameCsp()}" />`,
+    );
+    expect(srcDoc).toContain(`script-src 'none'`);
+    // No script source of any kind may be granted on the static path.
+    expect(srcDoc).not.toContain("script-src 'unsafe-inline'");
+    expect(srcDoc).not.toContain('script-src *');
+    expect(srcDoc).not.toContain('script-src sha384-');
+    expect(srcDoc).toContain(`default-src 'none'`);
+    expect(srcDoc).toContain(`base-uri 'none'`);
+    expect(srcDoc).toContain(`form-action 'none'`);
+  });
+
+  it('emits the document verbatim with the inlined styles', () => {
+    expect(srcDoc).toContain('<style>:root{--x:1}</style>');
+    expect(srcDoc).toContain(DOCUMENT);
+  });
+
+  it('refuses a document containing a literal </script (fail-closed)', () => {
+    expect(() =>
+      buildUntrustedHtmlSrcDoc({
+        document: '<p>ok</p></script><script>alert(1)</script>',
+        styleCss: '',
+      }),
+    ).toThrow(CustomUiSrcDocError);
+  });
+
+  // ── MUTATION TEST (static-document invariant, isolated) ────────────────────
+  it('MUTATION: granting the static document any script source is caught', () => {
+    const loosened = `default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; base-uri 'none'; form-action 'none'`;
+    expect(buildUntrustedHtmlFrameCsp()).not.toBe(loosened);
+    expect(buildUntrustedHtmlFrameCsp()).toContain(`script-src 'none'`);
+  });
+});

package/src/vista/html/custom-ui-srcdoc.ts

@@ -0,0 +1,193 @@
+/**
+ * Builds the `srcdoc` document for a sandbox frame, and the strict
+ * Content-Security-Policy that makes rendering untrusted content safe.
+ *
+ * A sandboxed, opaque-origin frame cannot receive an HTTP CSP header from us
+ * (there is no HTTP response — the bytes come from `srcdoc`), so the policy is
+ * embedded as a `<meta http-equiv="Content-Security-Policy">`. The policy is
+ * airtight by construction:
+ *
+ *   default-src 'none'      — no network of ANY kind (no fetch, no our-origin,
+ *                             no img/font/frame). The frame cannot phone home.
+ *   script-src 'sha384-…'   — ONLY the one chunk whose SRI hash the SERVER
+ *                             computed may execute. No 'unsafe-inline', no
+ *                             scheme-source, no wildcard — a hash source pins
+ *                             the exact bytes. The chunk is inlined as one
+ *                             <script type="module"> whose body IS those exact
+ *                             bytes, so its computed hash matches the token.
+ *                             For a STATIC document (no compiled chunk) the
+ *                             source is `'none'`: script never runs at all.
+ *   style-src 'unsafe-inline'— allows the inlined design-system <style> and any
+ *                             inline styles components set. Styles are not a
+ *                             script vector under default-src 'none'.
+ *   base-uri 'none'         — the frame cannot repoint relative URLs.
+ *   form-action 'none'      — the frame cannot submit a form anywhere.
+ *
+ * The chunk document also carries `<div id="root">` — the mount point the
+ * broker's self-mount wrapper renders into (it throws if the element is
+ * missing).
+ *
+ * Promoted from `app-forge-web` into the UI kernel (Canopy §8.3). The policy
+ * string and the `</script` fail-closed guard are carried over VERBATIM.
+ */
+
+/** A minimal reset so a frame document has sane base geometry. */
+export const CUSTOM_UI_FRAME_RESET_CSS = `
+*, *::before, *::after { box-sizing: border-box; }
+html, body { margin: 0; padding: 0; }
+body {
+  font-family: ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, sans-serif;
+  color: hsl(var(--foreground, 228 14% 11%));
+  background: transparent;
+}
+#root { min-height: 100%; }
+`;
+
+/**
+ * The frame CSP over an already-quoted `script-src` source expression. Private:
+ * the only two source expressions this plane ever emits are a pinned SRI hash
+ * and `'none'`, exposed through the two named builders below. There is no seam
+ * for an arbitrary caller-supplied source.
+ */
+function buildFrameCsp(scriptSource: string): string {
+  return [
+    `default-src 'none'`,
+    `script-src ${scriptSource}`,
+    `style-src 'unsafe-inline'`,
+    `base-uri 'none'`,
+    `form-action 'none'`,
+  ].join('; ');
+}
+
+/**
+ * The exact CSP directive string for a COMPILED custom-UI frame. `integrity` is
+ * the server-issued Subresource-Integrity / CSP token (`sha384-<base64>`)
+ * pinning the compiled chunk's bytes; it is embedded verbatim as the sole
+ * `script-src` source.
+ */
+export function buildCustomUiFrameCsp(integrity: string): string {
+  return buildFrameCsp(`'${integrity}'`);
+}
+
+/**
+ * The CSP for an UNTRUSTED static document: identical to the compiled-frame
+ * policy but with `script-src 'none'` — no script may execute at all.
+ */
+export function buildUntrustedHtmlFrameCsp(): string {
+  return buildFrameCsp(`'none'`);
+}
+
+/** Inputs for {@link buildCustomUiSrcDoc}. */
+export interface CustomUiSrcDocInput {
+  /** The compiled, self-mounting ESM chunk (verbatim script body). */
+  readonly compiledOutput: string;
+  /** Server SRI/CSP token (`sha384-<base64>`) pinning `compiledOutput`. */
+  readonly integrity: string;
+  /**
+   * Host design-system CSS inlined into the frame so components render styled
+   * with zero network. Placed in a `<style>` (allowed by
+   * `style-src 'unsafe-inline'`).
+   */
+  readonly styleCss: string;
+}
+
+/**
+ * Thrown when a document cannot be assembled SAFELY. The caller renders a
+ * visible notice — never a silently-truncated or unpinned frame.
+ */
+export class CustomUiSrcDocError extends Error {}
+
+/**
+ * Reject content that would truncate the inline module. The broker minifies +
+ * esbuild escapes `</script>` inside string literals to `<\/script>`, so a
+ * well-formed chunk never contains a literal `</script`. We do NOT rely on that
+ * implicitly — a chunk that DID contain it would let the HTML parser truncate
+ * the module early (a mis-render, not an XSS: the CSP + opaque origin still
+ * contain it). We assert it and throw so the caller surfaces a visible error
+ * instead of shipping a silently-truncated frame.
+ */
+function assertNoScriptTerminator(source: string, what: string): void {
+  if (/<\/script/i.test(source)) {
+    throw new CustomUiSrcDocError(
+      `${what} contains a literal "</script" — it would truncate the inline ` +
+        'module. The producer must emit escaped bytes; refusing to build a ' +
+        'mis-rendered frame.',
+    );
+  }
+}
+
+/**
+ * Assemble the full `srcdoc` HTML for a COMPILED custom-UI frame: the pinned
+ * CSP, the inlined design-system styles, the `#root` mount point, and the
+ * SRI-matched ESM chunk as a single inline module script.
+ *
+ * The chunk bytes are emitted verbatim (NOT HTML-escaped): the CSP hash was
+ * computed over exactly these bytes, so any transformation would break the
+ * match and the browser would refuse to execute the script — a fail-closed
+ * property we rely on rather than sanitizing.
+ */
+export function buildCustomUiSrcDoc({
+  compiledOutput,
+  integrity,
+  styleCss,
+}: CustomUiSrcDocInput): string {
+  assertNoScriptTerminator(compiledOutput, 'compiled custom-UI chunk');
+  const csp = buildCustomUiFrameCsp(integrity);
+  return [
+    `<!doctype html>`,
+    `<html>`,
+    `<head>`,
+    `<meta charset="utf-8" />`,
+    `<meta http-equiv="Content-Security-Policy" content="${csp}" />`,
+    `<style>${styleCss}</style>`,
+    `</head>`,
+    `<body>`,
+    `<div id="root"></div>`,
+    `<script type="module">${compiledOutput}</script>`,
+    `</body>`,
+    `</html>`,
+  ].join('\n');
+}
+
+/** Inputs for {@link buildUntrustedHtmlSrcDoc}. */
+export interface UntrustedHtmlSrcDocInput {
+  /** The untrusted HTML document/fragment, emitted verbatim into `<body>`. */
+  readonly document: string;
+  /** Styles inlined ahead of the document. */
+  readonly styleCss: string;
+}
+
+/**
+ * Assemble the `srcdoc` for an UNTRUSTED, agent-authored HTML document — the
+ * Vista `html` surface's static form.
+ *
+ * Identical containment to the compiled path (opaque origin, `default-src
+ * 'none'`, `base-uri`/`form-action` `'none'`) with `script-src 'none'`: the
+ * markup and styles render, and any `<script>` the author included NEVER
+ * executes. There is no "trusted document" mode and no way to opt into script
+ * without a server-issued SRI token.
+ *
+ * A document containing a literal `</script` is REJECTED for the same
+ * truncation reason as a chunk: a partially-parsed document is a mis-render,
+ * and we surface it rather than ship it.
+ */
+export function buildUntrustedHtmlSrcDoc({
+  document,
+  styleCss,
+}: UntrustedHtmlSrcDocInput): string {
+  assertNoScriptTerminator(document, 'untrusted HTML document');
+  const csp = buildUntrustedHtmlFrameCsp();
+  return [
+    `<!doctype html>`,
+    `<html>`,
+    `<head>`,
+    `<meta charset="utf-8" />`,
+    `<meta http-equiv="Content-Security-Policy" content="${csp}" />`,
+    `<style>${styleCss}</style>`,
+    `</head>`,
+    `<body>`,
+    document,
+    `</body>`,
+    `</html>`,
+  ].join('\n');
+}

package/src/vista/html/index.ts

@@ -0,0 +1,13 @@
+/**
+ * The hardened untrusted-UI frame — ONE implementation for every plane that
+ * renders author- or agent-authored content (App Forge runtime views, the Vista
+ * `html` surface).
+ *
+ * Promoted from `app-forge-web` (Canopy §8.3). The security properties are
+ * load-bearing, not stylistic — see the module docs for each.
+ */
+export * from './custom-ui-frame-contract';
+export * from './custom-ui-intents';
+export * from './custom-ui-srcdoc';
+export * from './custom-ui-frame-bridge';
+export * from './CustomUiFrame';

package/src/vista/index.ts

@@ -0,0 +1,48 @@
+/**
+ * Vista — the agent-driven, biome-extensible render plane (Canopy Plane ④).
+ *
+ * What this subpath ships:
+ *   • the surface REGISTRY (built on the shared contribution-registry core),
+ *     the catalogue sync that lights up biome-contributed kinds with a generic
+ *     schema-driven renderer, and the safe fallback card — the three-layer
+ *     guarantee: a biome's own renderer wins, else a generic schema-driven
+ *     renderer, else a fallback card with a typed reason. Never a throw, never
+ *     a blank;
+ *   • the TAB SHELL — `useVistaTabs` (state) + `VistaPanel` (chrome, built on
+ *     `OverflowTabs`). ONE implementation; the thin session workspace and the
+ *     Design-System-Builder preview both compose it;
+ *   • the FIRST-PARTY renderers the kernel owns (see `./surfaces`), registered
+ *     as a side effect of importing this module;
+ *   • the hardened untrusted-UI frame promoted from App Forge (`./html`);
+ *   • the `.tabs.json` manifest parser lifted out of the DSB page;
+ *   • the agent-facing `vista_*` tool contract + frontend dispatcher.
+ *
+ * Host-coupled first-party kinds (`markdown`, `chart`, `web`, `biome-route`,
+ * `object`, `graph`, `app`) are registered by the HOST — see `./surfaces` for
+ * the partition and why it is drawn there.
+ *
+ * The `form` kind (secure elicitation) is kernel-owned but needs the SUBJECT's
+ * bearer token and an outcome sink: the host supplies both through
+ * `VistaFormHostProvider` (`./vista-form-host`), the same shape of seam as
+ * `VistaFileSourceProvider`. No provider ⇒ the surface refuses to submit,
+ * visibly.
+ */
+export * from './surface-registry';
+export * from './surface-catalogue';
+export * from './surface-icons';
+export * from './GenericCatalogueSurface';
+export * from './SurfaceFallbackCard';
+export * from './vista-model';
+export * from './vista-payloads';
+export * from './vista-tabs-manifest';
+export * from './vista-file-source';
+export * from './vista-form-host';
+export * from './vista-code-renderer';
+export * from './vista-open-context';
+export * from './use-vista-tabs';
+export * from './VistaPanel';
+export * from './vista-tools';
+export * from './html';
+// Imported for its REGISTRATION side effect as well as its exports: pulling in
+// `@xemahq/ui-kernel/vista` wires the kernel-owned first-party renderers.
+export * from './surfaces';

package/src/vista/surface-catalogue.spec.ts

@@ -0,0 +1,140 @@
+/**
+ * Guards the Vista three-layer zero-maintenance guarantee:
+ *   1. a biome's OWN renderer always wins;
+ *   2. a biome-contributed kind with no renderer gets the GENERIC
+ *      schema-driven renderer derived from its catalogue `payloadSchema`;
+ *   3. anything still unknown resolves to a typed fallback reason — never a
+ *      throw, never a blank.
+ *
+ * Runs under the host-web vitest mirror (this package carries no vitest dep).
+ */
+import {
+  SurfaceKind,
+  SurfaceKindSource,
+  type SurfaceKindCatalogueEntry,
+} from '@xemahq/kernel-contracts/surface';
+import { createElement } from 'react';
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { deriveGenericSurfaceFields } from './GenericCatalogueSurface';
+import {
+  __resetSurfaceCatalogueSyncForTests,
+  syncSurfaceCatalogue,
+} from './surface-catalogue';
+import { vistaSurfaceRegistry } from './surface-registry';
+import { ContributionFallbackReason } from '../lib/contribution-registry';
+
+function entry(
+  overrides: Partial<SurfaceKindCatalogueEntry> = {},
+): SurfaceKindCatalogueEntry {
+  return {
+    kind: 'acme:invoice',
+    version: 1,
+    displayName: 'Invoice',
+    summary: 'An invoice preview.',
+    payloadSchema: {
+      type: 'object',
+      properties: {
+        number: { type: 'string', title: 'Invoice #' },
+        total: { type: 'number' },
+      },
+    },
+    source: SurfaceKindSource.Biome,
+    biomeId: 'acme',
+    ...overrides,
+  };
+}
+
+afterEach(() => {
+  vistaSurfaceRegistry.__resetOpenForTests();
+  __resetSurfaceCatalogueSyncForTests();
+});
+
+describe('Vista surface registry', () => {
+  it('reserves every first-party SurfaceKind against biome shadowing', () => {
+    for (const kind of Object.values(SurfaceKind)) {
+      expect(vistaSurfaceRegistry.isReserved(kind)).toBe(true);
+    }
+    expect(() =>
+      vistaSurfaceRegistry.register(SurfaceKind.Markdown, {
+        version: 1,
+        validate: (p) => p,
+        render: () => createElement('div'),
+      }),
+    ).toThrow(/reserved/);
+  });
+
+  it('falls back with a typed reason for an unknown kind', () => {
+    const resolution = vistaSurfaceRegistry.resolve({
+      kind: 'acme:nope',
+      version: 1,
+      payload: {},
+    });
+    expect(resolution).toMatchObject({
+      matched: false,
+      reason: ContributionFallbackReason.UnknownKind,
+    });
+  });
+});
+
+describe('syncSurfaceCatalogue', () => {
+  it('registers a generic renderer only where the biome shipped none', async () => {
+    const own = {
+      version: 1,
+      validate: (p: unknown) => p,
+      render: () => createElement('div', null, 'own'),
+    };
+    vistaSurfaceRegistry.register('acme:invoice', own);
+    await syncSurfaceCatalogue(() =>
+      Promise.resolve([
+        entry(),
+        entry({ kind: 'acme:ledger', displayName: 'Ledger' }),
+      ]),
+    );
+    // The biome's own renderer survived; the un-rendered kind got the generic.
+    expect(vistaSurfaceRegistry.get('acme:invoice')).toBe(own);
+    expect(vistaSurfaceRegistry.get('acme:ledger')).toBeDefined();
+    const resolution = vistaSurfaceRegistry.resolve({
+      kind: 'acme:ledger',
+      version: 1,
+      payload: { number: 'INV-1' },
+    });
+    expect(resolution.matched).toBe(true);
+  });
+
+  it('skips first-party entries', async () => {
+    await syncSurfaceCatalogue(() =>
+      Promise.resolve([
+        entry({
+          kind: SurfaceKind.Markdown,
+          source: SurfaceKindSource.FirstParty,
+        }),
+      ]),
+    );
+    expect(vistaSurfaceRegistry.listOpen()).toEqual([]);
+  });
+
+  it('leaves the registry untouched and retryable when the fetch fails', async () => {
+    await syncSurfaceCatalogue(() => Promise.reject(new Error('offline')));
+    expect(vistaSurfaceRegistry.listOpen()).toEqual([]);
+    await syncSurfaceCatalogue(() => Promise.resolve([entry()]));
+    expect(vistaSurfaceRegistry.listOpen()).toEqual(['acme:invoice']);
+  });
+});
+
+describe('deriveGenericSurfaceFields', () => {
+  it('orders schema-declared keys first, then undeclared payload keys', () => {
+    const fields = deriveGenericSurfaceFields(entry().payloadSchema, {
+      total: 12,
+      extra: true,
+    });
+    expect(fields.map((f) => f.key)).toEqual(['number', 'total', 'extra']);
+    expect(fields[0]?.label).toBe('Invoice #');
+    expect(fields[1]?.label).toBe('total');
+  });
+
+  it('degrades to plain payload entries when the schema declares no properties', () => {
+    const fields = deriveGenericSurfaceFields({ type: 'object' }, { a: 1, b: 2 });
+    expect(fields.map((f) => f.key)).toEqual(['a', 'b']);
+  });
+});

package/src/vista/surface-catalogue.ts

@@ -0,0 +1,84 @@
+/**
+ * Vista surface-kind catalogue sync.
+ *
+ * Mirrors the shipped ChatWidget catalogue sync: read the surface-kind
+ * catalogue (first-party + every biome-contributed kind, each with a payload
+ * JSON Schema) and register any BIOME-contributed kind that does NOT yet have a
+ * renderer into the OPEN registry, using the generic schema-driven renderer.
+ *
+ * Why a generic renderer — the three-layer zero-maintenance guarantee:
+ *   1. A biome that ships a frontend biome registers its OWN renderer via
+ *      `vistaSurfaceRegistry.register('<biomeId>:<kind>', …)` from
+ *      `FrontendBiome.init()`. That ALWAYS wins: this sync only registers where
+ *      `has(kind)` is false.
+ *   2. A biome that contributed the kind on the BACKEND but has not (yet)
+ *      shipped a frontend renderer still gets a structured, KNOWN rendering
+ *      derived from its catalogue `payloadSchema`.
+ *   3. Anything still unknown draws `SurfaceFallbackCard` with a typed reason.
+ *
+ * First-party kinds are skipped — they are registered statically by the
+ * first-party surface renderers. The fetch is BEST-EFFORT: any failure leaves
+ * the registry EXACTLY as the static builtins left it (layer 3 still handles
+ * every unknown kind) and clears the one-shot guard so a later call retries.
+ * Idempotent — safe to call on every session load.
+ *
+ * The catalogue TRANSPORT is injected rather than imported: `@xemahq/ui-kernel`
+ * is host-framework-agnostic and carries no generated API client, so the host
+ * passes a fetcher bound to its own client (exactly as the ChatWidget sync
+ * calls its Orval `widgetCatalogueControllerList`).
+ */
+import {
+  SurfaceKindSource,
+  type SurfaceKindCatalogueEntry,
+} from '@xemahq/kernel-contracts/surface';
+
+import { makeGenericSurfaceRenderer } from './GenericCatalogueSurface';
+import { vistaSurfaceRegistry } from './surface-registry';
+
+/** Host-supplied transport for the surface-kind catalogue. */
+export type SurfaceCatalogueFetcher = () => Promise<
+  readonly SurfaceKindCatalogueEntry[]
+>;
+
+let synced = false;
+
+/** Reset the one-shot guard — tests only. */
+export function __resetSurfaceCatalogueSyncForTests(): void {
+  synced = false;
+}
+
+/**
+ * Fetch the surface-kind catalogue and register biome-contributed kinds into
+ * the open registry with a generic schema-driven renderer. Runs at most once
+ * per app load. Never throws.
+ */
+export async function syncSurfaceCatalogue(
+  fetchCatalogue: SurfaceCatalogueFetcher,
+): Promise<void> {
+  if (synced) return;
+  synced = true;
+  try {
+    const entries = await fetchCatalogue();
+    for (const entry of entries) {
+      // Only biome-contributed kinds need registering here; first-party kinds
+      // are already registered by the static builtins.
+      if (entry.source !== SurfaceKindSource.Biome) continue;
+      // Never shadow a biome's own (or an already-registered) renderer.
+      if (vistaSurfaceRegistry.has(entry.kind)) continue;
+      vistaSurfaceRegistry.register(entry.kind, {
+        version: entry.version,
+        validate: (payload) =>
+          payload !== null && typeof payload === 'object' ? payload : null,
+        render: makeGenericSurfaceRenderer(
+          entry.displayName,
+          entry.payloadSchema,
+        ),
+      });
+    }
+  } catch {
+    // Best-effort: leave the registry exactly as the static builtins left it.
+    // The safe fallback card still renders any kind we did not learn about.
+    // Clearing the guard lets a later call retry.
+    synced = false;
+  }
+}

package/src/vista/surface-icons.ts

@@ -0,0 +1,57 @@
+/**
+ * Tab glyph per surface kind. Presentation only — a kind with no glyph renders
+ * a label-only tab, which is a complete rendering, not a degraded one.
+ *
+ * The map is EXHAUSTIVE over {@link SurfaceKind} (a `Record` over the enum), so
+ * adding a first-party kind is a compile error here until it gets a glyph.
+ * Biome-contributed (`<biomeId>:<kind>`) tabs are label-only by design: the
+ * kernel does not ship an icon vocabulary biomes must map into.
+ */
+import { SurfaceKind } from '@xemahq/kernel-contracts/surface';
+import {
+  AppWindow,
+  BarChart3,
+  Braces,
+  FileCode,
+  FileText,
+  FileType2,
+  Film,
+  Folder,
+  Globe,
+  Image,
+  LayoutGrid,
+  Share2,
+  SquarePen,
+  Table2,
+  TextCursorInput,
+} from 'lucide-react';
+
+import type { ComponentType } from 'react';
+
+type Glyph = ComponentType<{ className?: string }>;
+
+const SURFACE_KIND_ICON: Record<SurfaceKind, Glyph> = {
+  [SurfaceKind.Url]: Globe,
+  [SurfaceKind.Web]: AppWindow,
+  [SurfaceKind.Html]: LayoutGrid,
+  [SurfaceKind.Markdown]: FileText,
+  [SurfaceKind.Code]: FileCode,
+  [SurfaceKind.Diff]: SquarePen,
+  [SurfaceKind.Json]: Braces,
+  [SurfaceKind.Table]: Table2,
+  [SurfaceKind.Chart]: BarChart3,
+  [SurfaceKind.Pdf]: FileType2,
+  [SurfaceKind.Image]: Image,
+  [SurfaceKind.Media]: Film,
+  [SurfaceKind.Object]: LayoutGrid,
+  [SurfaceKind.BiomeRoute]: AppWindow,
+  [SurfaceKind.Form]: TextCursorInput,
+  [SurfaceKind.App]: AppWindow,
+  [SurfaceKind.Files]: Folder,
+  [SurfaceKind.Graph]: Share2,
+};
+
+/** Glyph for a surface kind, or `undefined` for a biome-contributed kind. */
+export function surfaceKindIcon(kind: string): Glyph | undefined {
+  return SURFACE_KIND_ICON[kind as SurfaceKind];
+}