@xemahq/ui-kernel 0.9.0 → 0.9.1

package/src/vista/html/custom-ui-frame-bridge.spec.ts

@@ -0,0 +1,191 @@
+/**
+ * The host-side inbound-message classifier — the security gate for every
+ * message the host acts on. Proves it REJECTS a wrong-source message, a
+ * wrong-protocol message, an unknown type, and a well-formed envelope carrying
+ * an unknown intent; and that it correctly classifies frameReady / a valid
+ * intent / a render error. Also proves frameReady is answered with a hostProps
+ * message (via the paired builder), and that a frame mounted with the EMPTY
+ * intent set can never get an intent performed.
+ *
+ * Migrated from `app-forge-web` when the frame was promoted into the UI kernel
+ * (the intent parser is now an argument instead of a hard-wired import — every
+ * gate is otherwise unchanged); runs under the host-web vitest mirror.
+ */
+import { describe, expect, it } from 'vitest';
+
+import { classifyFrameMessage } from './custom-ui-frame-bridge';
+import {
+  CUSTOM_UI_FRAME_PROTOCOL,
+  CustomUiFrameMessageType,
+  hostPropsMessage,
+} from './custom-ui-frame-contract';
+import {
+  CustomUiIntentKind,
+  NO_CUSTOM_UI_INTENTS,
+  parseCustomUiIntent,
+} from './custom-ui-intents';
+
+// A stand-in for the iframe's contentWindow — identity is all the gate checks.
+const FRAME_WINDOW = { name: 'frame' } as unknown as Window;
+const OTHER_WINDOW = { name: 'other' } as unknown as Window;
+
+function evt(
+  data: unknown,
+  source: Window | null,
+): Pick<MessageEvent, 'source' | 'data'> {
+  return { data, source };
+}
+
+describe('classifyFrameMessage', () => {
+  it('classifies a valid frameReady', () => {
+    const result = classifyFrameMessage(
+      evt(
+        {
+          type: CustomUiFrameMessageType.FrameReady,
+          protocol: CUSTOM_UI_FRAME_PROTOCOL,
+        },
+        FRAME_WINDOW,
+      ),
+      FRAME_WINDOW,
+      parseCustomUiIntent,
+    );
+    expect(result).toEqual({ kind: 'ready' });
+  });
+
+  it('classifies a valid frameIntent into a typed intent', () => {
+    const result = classifyFrameMessage(
+      evt(
+        {
+          type: CustomUiFrameMessageType.FrameIntent,
+          protocol: CUSTOM_UI_FRAME_PROTOCOL,
+          intent: { kind: 'navigate', href: '/apps/x/page' },
+        },
+        FRAME_WINDOW,
+      ),
+      FRAME_WINDOW,
+      parseCustomUiIntent,
+    );
+    expect(result).toEqual({
+      kind: 'intent',
+      intent: { kind: CustomUiIntentKind.Navigate, href: '/apps/x/page' },
+    });
+  });
+
+  it('classifies a frameError, surfacing the message', () => {
+    const result = classifyFrameMessage(
+      evt(
+        {
+          type: CustomUiFrameMessageType.FrameError,
+          protocol: CUSTOM_UI_FRAME_PROTOCOL,
+          message: 'boom',
+        },
+        FRAME_WINDOW,
+      ),
+      FRAME_WINDOW,
+      parseCustomUiIntent,
+    );
+    expect(result).toEqual({ kind: 'error', message: 'boom' });
+  });
+
+  it('REJECTS a message from the wrong source window', () => {
+    const result = classifyFrameMessage(
+      evt(
+        {
+          type: CustomUiFrameMessageType.FrameReady,
+          protocol: CUSTOM_UI_FRAME_PROTOCOL,
+        },
+        OTHER_WINDOW,
+      ),
+      FRAME_WINDOW,
+      parseCustomUiIntent,
+    );
+    expect(result).toEqual({ kind: 'ignored' });
+  });
+
+  it('REJECTS a message with the wrong protocol', () => {
+    const result = classifyFrameMessage(
+      evt(
+        { type: CustomUiFrameMessageType.FrameReady, protocol: 999 },
+        FRAME_WINDOW,
+      ),
+      FRAME_WINDOW,
+      parseCustomUiIntent,
+    );
+    expect(result).toEqual({ kind: 'ignored' });
+  });
+
+  it('REJECTS an unknown message type', () => {
+    const result = classifyFrameMessage(
+      evt(
+        {
+          type: 'xema.customui.somethingElse',
+          protocol: CUSTOM_UI_FRAME_PROTOCOL,
+        },
+        FRAME_WINDOW,
+      ),
+      FRAME_WINDOW,
+      parseCustomUiIntent,
+    );
+    expect(result).toEqual({ kind: 'ignored' });
+  });
+
+  it('REJECTS a well-formed envelope carrying an unknown intent', () => {
+    const result = classifyFrameMessage(
+      evt(
+        {
+          type: CustomUiFrameMessageType.FrameIntent,
+          protocol: CUSTOM_UI_FRAME_PROTOCOL,
+          intent: { kind: 'wipe-db' },
+        },
+        FRAME_WINDOW,
+      ),
+      FRAME_WINDOW,
+      parseCustomUiIntent,
+    );
+    expect(result).toEqual({ kind: 'ignored' });
+  });
+
+  it('REJECTS when no frame window is mounted yet', () => {
+    const result = classifyFrameMessage(
+      evt(
+        {
+          type: CustomUiFrameMessageType.FrameReady,
+          protocol: CUSTOM_UI_FRAME_PROTOCOL,
+        },
+        FRAME_WINDOW,
+      ),
+      null,
+      parseCustomUiIntent,
+    );
+    expect(result).toEqual({ kind: 'ignored' });
+  });
+
+  // The intent set is now supplied by the mounting surface — a frame mounted
+  // with the EMPTY set has no authority, so even a perfectly-formed navigate
+  // envelope is ignored.
+  it('REJECTS every intent when mounted with the EMPTY intent set', () => {
+    const result = classifyFrameMessage(
+      evt(
+        {
+          type: CustomUiFrameMessageType.FrameIntent,
+          protocol: CUSTOM_UI_FRAME_PROTOCOL,
+          intent: { kind: 'navigate', href: '/apps/x/page' },
+        },
+        FRAME_WINDOW,
+      ),
+      FRAME_WINDOW,
+      NO_CUSTOM_UI_INTENTS.parse,
+    );
+    expect(result).toEqual({ kind: 'ignored' });
+  });
+
+  it('answers frameReady with a hostProps message (paired builder)', () => {
+    const props = { records: [{ id: 'r1' }] };
+    const message = hostPropsMessage(props);
+    expect(message).toEqual({
+      type: CustomUiFrameMessageType.HostProps,
+      protocol: CUSTOM_UI_FRAME_PROTOCOL,
+      props,
+    });
+  });
+});

package/src/vista/html/custom-ui-frame-bridge.ts

@@ -0,0 +1,92 @@
+/**
+ * The host-side inbound-message classifier for the sandbox-frame bridge.
+ *
+ * Every `message` event the host window receives while a frame is mounted
+ * passes through {@link classifyFrameMessage}. It enforces the security gate
+ * BEFORE the host acts on anything:
+ *
+ *   1. SOURCE IDENTITY — `event.source` must be the frame's own
+ *      `contentWindow`. We compare the window identity, NOT `event.origin`: an
+ *      opaque-origin sandbox frame (no `allow-same-origin`) reports its origin
+ *      as the string `"null"`, so origin is useless as an allow-check. Window
+ *      identity is unforgeable across the boundary.
+ *   2. PROTOCOL — `event.data.protocol` must equal the pinned protocol version.
+ *   3. TYPE — `event.data.type` must be a member of the closed
+ *      {@link CustomUiFrameMessageType} set.
+ *
+ * Anything failing any gate is classified `ignored` and the host does nothing.
+ * A valid message is narrowed to a typed, discriminated result the caller acts
+ * on. The intent payload is parsed against the mounting surface's CLOSED intent
+ * set here too, so a frame that posts a well-formed envelope but an
+ * unknown/invalid intent is still `ignored` — never performed.
+ *
+ * Promoted from `app-forge-web` into the UI kernel (Canopy §8.3). The only
+ * change is that the intent set is a parameter instead of a hard-wired import;
+ * every gate is carried over verbatim.
+ */
+import {
+  CUSTOM_UI_FRAME_PROTOCOL,
+  CustomUiFrameMessageType,
+} from './custom-ui-frame-contract';
+
+/** The typed outcome of classifying one inbound frame message. */
+export type ClassifiedFrameMessage<TIntent> =
+  | { readonly kind: 'ready' }
+  | { readonly kind: 'intent'; readonly intent: TIntent }
+  | { readonly kind: 'error'; readonly message: string }
+  | { readonly kind: 'ignored' };
+
+const IGNORED: ClassifiedFrameMessage<never> = { kind: 'ignored' };
+
+/**
+ * Classify an inbound `message` event from a sandbox frame. `frameWindow` is the
+ * mounted iframe's `contentWindow` (may be `null` before mount); `parseIntent`
+ * is the mounting surface's closed-set parser (returns `null` to reject).
+ * Returns a typed result; every rejection path returns `ignored` (fail-safe —
+ * the host performs nothing on a message it cannot fully validate).
+ */
+export function classifyFrameMessage<TIntent>(
+  event: Pick<MessageEvent, 'source' | 'data'>,
+  frameWindow: Window | null,
+  parseIntent: (raw: unknown) => TIntent | null,
+): ClassifiedFrameMessage<TIntent> {
+  // Gate 1: source identity. Reject if we have no frame yet or the message did
+  // not come from THIS frame's window.
+  if (frameWindow === null || event.source !== frameWindow) return IGNORED;
+
+  const data = event.data;
+  if (data === null || typeof data !== 'object') return IGNORED;
+  const envelope = data as {
+    protocol?: unknown;
+    type?: unknown;
+    intent?: unknown;
+    message?: unknown;
+  };
+
+  // Gate 2: protocol version.
+  if (envelope.protocol !== CUSTOM_UI_FRAME_PROTOCOL) return IGNORED;
+
+  // Gate 3: closed message-type set.
+  switch (envelope.type) {
+    case CustomUiFrameMessageType.FrameReady:
+      return { kind: 'ready' };
+    case CustomUiFrameMessageType.FrameIntent: {
+      const intent = parseIntent(envelope.intent);
+      // A valid envelope carrying an unknown/invalid intent is rejected, not
+      // performed.
+      return intent === null ? IGNORED : { kind: 'intent', intent };
+    }
+    case CustomUiFrameMessageType.FrameError:
+      return {
+        kind: 'error',
+        message:
+          typeof envelope.message === 'string'
+            ? envelope.message
+            : 'The custom view failed to render.',
+      };
+    default:
+      // Includes HostProps (host→frame only, never inbound) and any unknown
+      // string — ignored.
+      return IGNORED;
+  }
+}

package/src/vista/html/custom-ui-frame-contract.ts

@@ -0,0 +1,88 @@
+/**
+ * The frozen custom-UI frame wire contract — the HOST side of the ONLY channel
+ * across the sandbox-frame boundary.
+ *
+ * Promoted from `app-forge-web` into the UI kernel (Canopy §8.3) so every plane
+ * that renders untrusted, author-authored UI — App Forge's runtime views AND
+ * the Vista `html` surface — speaks ONE protocol through ONE hardened frame.
+ *
+ * A compiled custom-UI chunk (self-mounting ESM, running inside a strict-CSP,
+ * opaque-origin iframe) speaks exactly these four message `type`s at exactly
+ * this protocol version. The chunk's self-mount wrapper is generated by the
+ * app-function-broker from its OWN copy of these values
+ * (`repos/xema-cultivars/biomes/platform/app-function-broker/api/src/compile/ui/custom-ui-frame-contract.ts`),
+ * so the enum members and protocol number here MUST stay byte-for-byte
+ * identical to that source of truth. Changing a value is a coordinated,
+ * breaking wire change: bump the protocol on BOTH sides in lockstep.
+ *
+ * The chunk never touches host state directly — it announces readiness, the
+ * host pushes props, the component asks the host to perform intents, and a
+ * render throw is reported back. The host validates every inbound message
+ * (source identity + protocol + closed `type` set) before acting.
+ */
+
+/** The frozen protocol version stamped on every frame message. */
+export const CUSTOM_UI_FRAME_PROTOCOL = 1 as const;
+
+/**
+ * The closed set of message `type`s exchanged across the frame boundary. The
+ * string values are the wire contract and must never diverge from the broker's.
+ *
+ *  - {@link FrameReady}  frame → host: mounted, ready for props (no payload).
+ *  - {@link HostProps}   host → frame: `{ props }`; repeatable to re-render.
+ *  - {@link FrameIntent} frame → host: `{ intent }` — the host validates+performs.
+ *  - {@link FrameError}  frame → host: `{ message }` — the render threw.
+ */
+export enum CustomUiFrameMessageType {
+  FrameReady = 'xema.customui.frameReady',
+  HostProps = 'xema.customui.hostProps',
+  FrameIntent = 'xema.customui.frameIntent',
+  FrameError = 'xema.customui.frameError',
+}
+
+/** frame → host: emitted once on load. */
+export interface FrameReadyMessage {
+  readonly type: CustomUiFrameMessageType.FrameReady;
+  readonly protocol: typeof CUSTOM_UI_FRAME_PROTOCOL;
+}
+
+/** host → frame: the props to render the component with. */
+export interface HostPropsMessage {
+  readonly type: CustomUiFrameMessageType.HostProps;
+  readonly protocol: typeof CUSTOM_UI_FRAME_PROTOCOL;
+  readonly props: CustomUiComponentProps;
+}
+
+/** frame → host: the component asked the host to perform an action. */
+export interface FrameIntentMessage {
+  readonly type: CustomUiFrameMessageType.FrameIntent;
+  readonly protocol: typeof CUSTOM_UI_FRAME_PROTOCOL;
+  readonly intent: unknown;
+}
+
+/** frame → host: the component's render threw. */
+export interface FrameErrorMessage {
+  readonly type: CustomUiFrameMessageType.FrameError;
+  readonly protocol: typeof CUSTOM_UI_FRAME_PROTOCOL;
+  readonly message: string;
+}
+
+/**
+ * The read-only props payload handed to a custom-UI component. It MUST be a
+ * plain, structured-clone-serializable object — it crosses the frame boundary
+ * via `postMessage`. The component also receives an injected `xemaEmit(intent)`
+ * function (added inside the frame by the self-mount wrapper, NOT sent over the
+ * wire), so this shape carries data only.
+ */
+export type CustomUiComponentProps = Record<string, unknown>;
+
+/** Build the host→frame props message (single seam so the shape can't drift). */
+export function hostPropsMessage(
+  props: CustomUiComponentProps,
+): HostPropsMessage {
+  return {
+    type: CustomUiFrameMessageType.HostProps,
+    protocol: CUSTOM_UI_FRAME_PROTOCOL,
+    props,
+  };
+}

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

@@ -0,0 +1,133 @@
+/**
+ * Custom-UI intent parsing/dispatch — the frame asks, the host validates+
+ * performs. Proves the closed set rejects unknown kinds and out-of-policy
+ * (external) navigation targets, that a valid intent dispatches to its handler,
+ * and that the two shipped intent SETS behave as their names promise: the
+ * built-in navigate set parses+performs exactly one kind, and
+ * `NO_CUSTOM_UI_INTENTS` grants a frame no authority at all.
+ *
+ * Migrated 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, vi } from 'vitest';
+
+import {
+  createNavigateIntentSet,
+  CustomUiIntentKind,
+  NO_CUSTOM_UI_INTENTS,
+  parseCustomUiIntent,
+  performCustomUiIntent,
+  type CustomUiIntentHandlers,
+} from './custom-ui-intents';
+
+describe('parseCustomUiIntent', () => {
+  it('parses a valid host-relative navigate intent', () => {
+    expect(
+      parseCustomUiIntent({ kind: 'navigate', href: '/apps/x/page' }),
+    ).toEqual({ kind: CustomUiIntentKind.Navigate, href: '/apps/x/page' });
+  });
+
+  it('rejects an unknown intent kind', () => {
+    expect(parseCustomUiIntent({ kind: 'delete-everything' })).toBeNull();
+  });
+
+  it('rejects a navigate to an external (protocol-relative) URL', () => {
+    expect(
+      parseCustomUiIntent({ kind: 'navigate', href: '//evil.example.com' }),
+    ).toBeNull();
+  });
+
+  it('rejects a navigate to an absolute external URL', () => {
+    expect(
+      parseCustomUiIntent({ kind: 'navigate', href: 'https://evil.example' }),
+    ).toBeNull();
+  });
+
+  // Regression: a backslash normalises to a forward slash (WHATWG), so `/\host`
+  // is protocol-relative and resolves to a FOREIGN origin — the exact bypass a
+  // prefix-only check (`startsWith('/') && !startsWith('//')`) missed. The
+  // origin-resolution validator MUST reject every backslash form.
+  it('rejects a navigate whose backslash form resolves to a foreign origin', () => {
+    for (const href of [
+      '/\\evil.example.com',
+      '/\\\\evil.example.com',
+      '/\\/evil.example.com',
+      '\\/evil.example.com',
+    ]) {
+      expect(parseCustomUiIntent({ kind: 'navigate', href })).toBeNull();
+    }
+  });
+
+  it('rejects a navigate href containing whitespace or control chars', () => {
+    expect(
+      parseCustomUiIntent({ kind: 'navigate', href: '/ /evil' }),
+    ).toBeNull();
+    expect(parseCustomUiIntent({ kind: 'navigate', href: '/\tx' })).toBeNull();
+  });
+
+  it('rejects a navigate with a non-string href', () => {
+    expect(parseCustomUiIntent({ kind: 'navigate', href: 42 })).toBeNull();
+  });
+
+  it('rejects non-object payloads', () => {
+    expect(parseCustomUiIntent(null)).toBeNull();
+    expect(parseCustomUiIntent('navigate')).toBeNull();
+  });
+});
+
+describe('performCustomUiIntent', () => {
+  it('dispatches a navigate intent to the navigate handler', () => {
+    const navigate = vi.fn();
+    const handlers: CustomUiIntentHandlers = {
+      [CustomUiIntentKind.Navigate]: navigate,
+    };
+    performCustomUiIntent(
+      { kind: CustomUiIntentKind.Navigate, href: '/apps/x' },
+      handlers,
+    );
+    expect(navigate).toHaveBeenCalledWith({
+      kind: CustomUiIntentKind.Navigate,
+      href: '/apps/x',
+    });
+  });
+});
+
+describe('createNavigateIntentSet', () => {
+  it('parses and performs a host-relative navigate, and only that', () => {
+    const navigate = vi.fn();
+    const set = createNavigateIntentSet({
+      [CustomUiIntentKind.Navigate]: navigate,
+    });
+
+    const intent = set.parse({ kind: 'navigate', href: '/apps/x' });
+    expect(intent).toEqual({
+      kind: CustomUiIntentKind.Navigate,
+      href: '/apps/x',
+    });
+    if (intent === null) throw new Error('expected a parsed navigate intent');
+    set.perform(intent);
+    expect(navigate).toHaveBeenCalledWith({
+      kind: CustomUiIntentKind.Navigate,
+      href: '/apps/x',
+    });
+
+    // Anything outside the closed set is rejected by `parse` — never performed.
+    expect(set.parse({ kind: 'wipe-db' })).toBeNull();
+    expect(
+      set.parse({ kind: 'navigate', href: 'https://evil.example' }),
+    ).toBeNull();
+  });
+});
+
+describe('NO_CUSTOM_UI_INTENTS', () => {
+  it('grants the frame NO authority: every payload is rejected', () => {
+    for (const raw of [
+      { kind: 'navigate', href: '/apps/x' },
+      { kind: 'wipe-db' },
+      null,
+      'navigate',
+    ]) {
+      expect(NO_CUSTOM_UI_INTENTS.parse(raw)).toBeNull();
+    }
+  });
+});

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

@@ -0,0 +1,151 @@
+/**
+ * The intent plane of the custom-UI frame bridge — now PLUGGABLE.
+ *
+ * A component running inside the sandbox frame NEVER acts with the user's
+ * authority. It posts an intent across the boundary; the host validates it
+ * against a CLOSED set and performs it. An unrecognised or malformed intent is
+ * rejected — never coerced, never silently dropped into a default action.
+ *
+ * Promoting this out of App Forge required one change and one only: WHICH
+ * closed set applies is now supplied by the mounting surface
+ * ({@link CustomUiIntentSet}) instead of being hard-wired. The security shape is
+ * unchanged — a set is still a `parse` that returns `null` for anything outside
+ * it, plus a `perform` that is exhaustive over it. There is no "accept any
+ * intent" set and no free-form action strings.
+ *
+ * {@link createNavigateIntentSet} is the built-in set every host gets.
+ */
+
+/**
+ * A closed intent set: parse-or-reject, then perform. `parse` MUST be total and
+ * MUST NOT throw — returning `null` is the ONLY way to reject, and the bridge
+ * turns that into `ignored`.
+ */
+export interface CustomUiIntentSet<TIntent> {
+  parse(raw: unknown): TIntent | null;
+  perform(intent: TIntent): void;
+}
+
+/** Closed set of intent kinds the built-in set understands. */
+export enum CustomUiIntentKind {
+  /** Navigate the host to an in-app path. */
+  Navigate = 'navigate',
+}
+
+/**
+ * Navigate intent — the host routes to `href`. Constrained to a host-relative
+ * path (leading `/`, no scheme, no protocol-relative `//`) so a frame can never
+ * drive the host to an arbitrary external origin.
+ */
+export interface NavigateIntent {
+  readonly kind: CustomUiIntentKind.Navigate;
+  readonly href: string;
+}
+
+/** The discriminated union of every intent the BUILT-IN set performs. */
+export type CustomUiIntent = NavigateIntent;
+
+/**
+ * Typed handler set for the built-in intents. Exhaustive over
+ * {@link CustomUiIntentKind} by construction — adding a kind forces adding a
+ * handler here (a compile error otherwise), so no intent kind can ship without
+ * a host-side performer.
+ */
+export interface CustomUiIntentHandlers {
+  readonly [CustomUiIntentKind.Navigate]: (intent: NavigateIntent) => void;
+}
+
+/**
+ * True for a same-origin, host-relative path — the only href a frame may request.
+ *
+ * A prefix check (`startsWith('/') && !startsWith('//')`) is NOT sufficient:
+ * browsers (WHATWG URL) normalize a backslash to a forward slash for special
+ * schemes, so `"/\\evil.com"` is protocol-relative and resolves to a FOREIGN
+ * origin — a `router.push` of it hard-navigates the victim's top window off to
+ * `evil.com` (open redirect / phishing). Author code runs inside the frame and
+ * an authored app is viewed by OTHER users, so this is a real cross-user
+ * surface. We therefore RESOLVE the href against the current origin and require
+ * the resolved origin to be identical — the browser's own parser decides, so no
+ * textual-prefix trick (`\`, control chars, whitespace, embedded scheme) can
+ * slip a foreign origin past us. A relative href that cannot be parsed, or that
+ * escapes the origin, is rejected.
+ */
+function isHostRelativePath(href: string): boolean {
+  // Must be rooted at '/'.
+  if (!href.startsWith('/')) return false;
+  // A backslash is a protocol-relative/scheme trick after WHATWG normalisation
+  // ("/\\evil.com" -> //evil.com -> foreign origin); whitespace / control
+  // chars can also confuse the parser. Reject any before resolving.
+  if (href.includes('\\')) return false;
+  // eslint-disable-next-line no-control-regex
+  if (/[\u0000-\u0020\u007f]/.test(href)) return false;
+  let resolved: URL;
+  try {
+    resolved = new URL(href, window.location.origin);
+  } catch {
+    return false;
+  }
+  // The browser's parser is authoritative: the resolved origin MUST equal ours.
+  return resolved.origin === window.location.origin;
+}
+
+/**
+ * Parse an untrusted intent payload (arrived from the sandbox frame) into a
+ * typed {@link CustomUiIntent}, or `null` if it is not a recognized, valid
+ * member of the closed set. Fail-safe: unknown `kind`, wrong payload shape, or
+ * an out-of-policy value all return `null` — the caller rejects it.
+ */
+export function parseCustomUiIntent(raw: unknown): CustomUiIntent | null {
+  if (raw === null || typeof raw !== 'object') return null;
+  const candidate = raw as { kind?: unknown; href?: unknown };
+  switch (candidate.kind) {
+    case CustomUiIntentKind.Navigate:
+      if (typeof candidate.href !== 'string') return null;
+      if (!isHostRelativePath(candidate.href)) return null;
+      return { kind: CustomUiIntentKind.Navigate, href: candidate.href };
+    default:
+      return null;
+  }
+}
+
+/**
+ * Dispatch a parsed intent to its handler. Exhaustive `switch` over the closed
+ * set — a new kind added to {@link CustomUiIntentKind} without a `case` here is
+ * a compile error (the `never` guard), so the set can never be silently
+ * under-served.
+ */
+export function performCustomUiIntent(
+  intent: CustomUiIntent,
+  handlers: CustomUiIntentHandlers,
+): void {
+  switch (intent.kind) {
+    case CustomUiIntentKind.Navigate:
+      handlers[CustomUiIntentKind.Navigate](intent);
+      return;
+    default: {
+      const exhaustive: never = intent.kind;
+      throw new Error(`Unhandled custom-UI intent kind: ${String(exhaustive)}`);
+    }
+  }
+}
+
+/** The built-in intent set: host-relative navigation and nothing else. */
+export function createNavigateIntentSet(
+  handlers: CustomUiIntentHandlers,
+): CustomUiIntentSet<CustomUiIntent> {
+  return {
+    parse: parseCustomUiIntent,
+    perform: (intent) => performCustomUiIntent(intent, handlers),
+  };
+}
+
+/**
+ * The EMPTY intent set — parses nothing, performs nothing. Mount a frame with
+ * this when the rendered content must be strictly presentational (the Vista
+ * `html` surface's static-document form). It is an explicit "this frame has no
+ * authority", not an absent configuration.
+ */
+export const NO_CUSTOM_UI_INTENTS: CustomUiIntentSet<never> = {
+  parse: () => null,
+  perform: () => undefined,
+};