@xemahq/ui-kernel 0.8.0 → 0.9.1

package/src/vista/vista-model.ts

@@ -0,0 +1,130 @@
+/**
+ * The Vista tab model — ONE tab vocabulary for every preview plane.
+ *
+ * Before this module the frontend carried THREE overlapping tab models with no
+ * shared code:
+ *   • `WorkspaceTabKind` (`files|code|md|diff|tests|url`) in the thin session
+ *     workspace;
+ *   • `PreviewTabKind` (`files|html|markdown|pdf|image|plain`) buried inside the
+ *     Design-System-Builder page;
+ *   • the App-Forge preview.
+ * All three collapse onto the kernel {@link SurfaceKind} (Canopy §8.5). A tab is
+ * just a {@link VistaSurface} envelope; the Vista registry resolves its `kind`
+ * to a renderer.
+ *
+ * Collapse notes (deliberate, documented decisions):
+ *   • `md` → {@link SurfaceKind.Markdown}.
+ *   • `plain` → {@link SurfaceKind.Code}. `Code` is "a source file", and the
+ *     code renderer is a mono pane; a separate "plain text" kind would be the
+ *     same renderer under a second name.
+ *   • `tests` had no kernel equivalent and was never a *render* kind — a test
+ *     report is a biome-owned surface, so it becomes a biome-contributed
+ *     `<biomeId>:tests` kind rather than a first-party one. Nothing in the tree
+ *     rendered it (the thin workspace's `renderTests` slot was never supplied).
+ */
+import { SurfaceKind, type VistaSurface } from '@xemahq/kernel-contracts/surface';
+
+/**
+ * Id of the pinned, UI-owned file-browser tab. It is owned by the panel, never
+ * declared by an agent, and never closeable.
+ */
+export const VISTA_FILES_TAB_ID = 'files';
+
+/** Current payload schema version of every first-party surface kind. */
+export const VISTA_SURFACE_VERSION = 1;
+
+/**
+ * A Vista tab. Structurally a {@link VistaSurface} — the tab model and the
+ * agent-facing envelope are the SAME shape on purpose, so `vista_open` needs no
+ * translation layer.
+ */
+export type VistaTab = VistaSurface;
+
+/** Extension → first-party surface kind. Closed, deterministic mapping. */
+const EXTENSION_KIND: Readonly<Record<string, SurfaceKind>> = {
+  html: SurfaceKind.Html,
+  htm: SurfaceKind.Html,
+  md: SurfaceKind.Markdown,
+  mdx: SurfaceKind.Markdown,
+  markdown: SurfaceKind.Markdown,
+  pdf: SurfaceKind.Pdf,
+  png: SurfaceKind.Image,
+  jpg: SurfaceKind.Image,
+  jpeg: SurfaceKind.Image,
+  gif: SurfaceKind.Image,
+  webp: SurfaceKind.Image,
+  svg: SurfaceKind.Image,
+  avif: SurfaceKind.Image,
+  mp4: SurfaceKind.Media,
+  webm: SurfaceKind.Media,
+  mov: SurfaceKind.Media,
+  mp3: SurfaceKind.Media,
+  wav: SurfaceKind.Media,
+  ogg: SurfaceKind.Media,
+  m4a: SurfaceKind.Media,
+  json: SurfaceKind.Json,
+  diff: SurfaceKind.Diff,
+  patch: SurfaceKind.Diff,
+};
+
+/**
+ * Resolve the surface kind a file path renders as. Deterministic and total:
+ * anything unrecognised is {@link SurfaceKind.Code} (a mono text pane), which is
+ * always a correct — if plain — rendering of a file's bytes.
+ */
+export function surfaceKindForPath(path: string): SurfaceKind {
+  const dot = path.lastIndexOf('.');
+  if (dot === -1) return SurfaceKind.Code;
+  const ext = path.slice(dot + 1).toLowerCase();
+  return EXTENSION_KIND[ext] ?? SurfaceKind.Code;
+}
+
+/** The `content-type` a media/blob surface reports for a path, when derivable. */
+const EXTENSION_CONTENT_TYPE: Readonly<Record<string, string>> = {
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  gif: 'image/gif',
+  webp: 'image/webp',
+  svg: 'image/svg+xml',
+  avif: 'image/avif',
+  pdf: 'application/pdf',
+  mp4: 'video/mp4',
+  webm: 'video/webm',
+  mov: 'video/quicktime',
+  mp3: 'audio/mpeg',
+  wav: 'audio/wav',
+  ogg: 'audio/ogg',
+  m4a: 'audio/mp4',
+};
+
+/** Content type for a path, or `null` when the extension is unknown. */
+export function contentTypeForPath(path: string): string | null {
+  const dot = path.lastIndexOf('.');
+  if (dot === -1) return null;
+  return EXTENSION_CONTENT_TYPE[path.slice(dot + 1).toLowerCase()] ?? null;
+}
+
+/** The last path segment — the default tab label for a file-backed surface. */
+export function labelForPath(path: string): string {
+  const segments = path.split('/');
+  return segments[segments.length - 1] || path;
+}
+
+/**
+ * Build a file-backed surface envelope for a path. One seam so every caller
+ * (the `.tabs.json` parser, the file browser, `vista_open`) derives kind + label
+ * + tab id identically.
+ */
+export function fileSurface(
+  path: string,
+  overrides?: Readonly<{ title?: string; kind?: SurfaceKind }>,
+): VistaTab {
+  return {
+    tabId: `file:${path}`,
+    kind: overrides?.kind ?? surfaceKindForPath(path),
+    version: VISTA_SURFACE_VERSION,
+    title: overrides?.title ?? labelForPath(path),
+    payload: { path },
+  };
+}

package/src/vista/vista-open-context.tsx

@@ -0,0 +1,42 @@
+/**
+ * `VistaOpenContext` — how a surface asks the panel to open ANOTHER surface.
+ *
+ * The registry's `render(payload)` is a pure function, so a renderer cannot
+ * receive an `onOpen` prop. The panel publishes its `open` through this context
+ * instead: the file browser opens a file tab, an object view opens a related
+ * object, and so on — all through the SAME `vista_open` semantics the agent
+ * uses, never a second code path.
+ *
+ * A surface mounted without a provider simply renders non-interactive rows
+ * (`useVistaOpen()` returns `null`) — an inert list, never a dead click that
+ * silently does nothing.
+ */
+import {
+  createContext,
+  useContext,
+  type ReactElement,
+  type ReactNode,
+} from 'react';
+
+import type { VistaTab } from './vista-model';
+
+/** Open (or replace) a tab and focus it. Mirrors `VistaTabsController.open`. */
+export type VistaOpenFn = (surface: VistaTab) => string;
+
+const VistaOpenContext = createContext<VistaOpenFn | null>(null);
+
+export function VistaOpenProvider({
+  open,
+  children,
+}: Readonly<{ open: VistaOpenFn; children: ReactNode }>): ReactElement {
+  return (
+    <VistaOpenContext.Provider value={open}>
+      {children}
+    </VistaOpenContext.Provider>
+  );
+}
+
+/** The panel's `open`, or `null` when no panel is mounted above. */
+export function useVistaOpen(): VistaOpenFn | null {
+  return useContext(VistaOpenContext);
+}

package/src/vista/vista-payloads.ts

@@ -0,0 +1,514 @@
+/**
+ * Payload contracts + narrowing validators for the CLOSED first-party
+ * {@link SurfaceKind} set.
+ *
+ * Every validator is total and NEVER throws: it returns the narrowed payload or
+ * `null`, and `null` routes the envelope to `SurfaceFallbackCard` with
+ * `ContributionFallbackReason.InvalidPayload`. That is the contract the
+ * renderable registry depends on — a malformed payload degrades visibly, it is
+ * never coerced into a half-rendered surface.
+ *
+ * ── File-backed vs. inline ──────────────────────────────────────────────────
+ * Text/binary surfaces accept EITHER an inline `content`/`url` OR a workspace
+ * `path` resolved through the host-supplied {@link VistaFileSource}. Exactly one
+ * must be present — supplying both is a contradiction and is rejected, not
+ * silently preferred one way.
+ */
+import { validateCaptureFields } from '../ui/capture/field-spec-validate';
+
+import type { CaptureFieldSpec } from '../ui/capture/field-spec';
+import type { PreviewDevice } from '../ui/primitives/preview-device-frame';
+
+/** A record with unknown values — the shape every validator starts from. */
+type UnknownRecord = Readonly<Record<string, unknown>>;
+
+function asRecord(value: unknown): UnknownRecord | null {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? (value as UnknownRecord)
+    : null;
+}
+
+function optionalString(value: unknown): string | undefined | null {
+  if (value === undefined) return undefined;
+  return typeof value === 'string' ? value : null;
+}
+
+/**
+ * Narrow a "exactly one of `a` / `b`" pair of optional strings. Returns the
+ * pair when exactly one is a string, else `null`.
+ */
+function exactlyOne(
+  a: unknown,
+  b: unknown,
+): Readonly<{ a?: string; b?: string }> | null {
+  const left = typeof a === 'string' ? a : undefined;
+  const right = typeof b === 'string' ? b : undefined;
+  if ((left === undefined) === (right === undefined)) return null;
+  return left === undefined ? { b: right } : { a: left };
+}
+
+/** Where a text-backed surface reads its body from. */
+export interface VistaTextPayload {
+  /** Inline body. Mutually exclusive with {@link path}. */
+  readonly content?: string;
+  /** Workspace-relative path resolved through the host `VistaFileSource`. */
+  readonly path?: string;
+  /** Optional language hint for a `code` surface (presentation only). */
+  readonly language?: string;
+}
+
+export function validateTextPayload(raw: unknown): VistaTextPayload | null {
+  const record = asRecord(raw);
+  if (record === null) return null;
+  const source = exactlyOne(record.content, record.path);
+  if (source === null) return null;
+  const language = optionalString(record.language);
+  if (language === null) return null;
+  const base: VistaTextPayload =
+    source.a === undefined ? { path: source.b } : { content: source.a };
+  return language === undefined ? base : { ...base, language };
+}
+
+/** Where a binary surface (image / media / pdf) reads its bytes from. */
+export interface VistaBlobPayload {
+  /** Already-resolved fetchable URL (`https:`, `blob:`, `data:`). */
+  readonly url?: string;
+  /** Workspace-relative path resolved through the host `VistaFileSource`. */
+  readonly path?: string;
+  /** Alt text / accessible label. */
+  readonly alt?: string;
+  /** MIME type. Required by `media` (audio vs. video); optional elsewhere. */
+  readonly contentType?: string;
+}
+
+export function validateBlobPayload(raw: unknown): VistaBlobPayload | null {
+  const record = asRecord(raw);
+  if (record === null) return null;
+  const source = exactlyOne(record.url, record.path);
+  if (source === null) return null;
+  const alt = optionalString(record.alt);
+  if (alt === null) return null;
+  const contentType = optionalString(record.contentType);
+  if (contentType === null) return null;
+  const payload: {
+    url?: string;
+    path?: string;
+    alt?: string;
+    contentType?: string;
+  } = source.a === undefined ? { path: source.b } : { url: source.a };
+  if (alt !== undefined) payload.alt = alt;
+  if (contentType !== undefined) payload.contentType = contentType;
+  return payload;
+}
+
+/** `SurfaceKind.Url` — a live external URL inside mock browser chrome. */
+export interface VistaUrlPayload {
+  readonly url: string;
+  /** Device bezel to render the frame in. Defaults to `desktop`. */
+  readonly device?: PreviewDevice;
+  /** Bump to force the frame to reload without changing the URL. */
+  readonly reloadNonce?: number;
+}
+
+const PREVIEW_DEVICES: readonly PreviewDevice[] = [
+  'desktop',
+  'tablet',
+  'mobile',
+  'presentation',
+  'a4',
+];
+
+export function validateUrlPayload(raw: unknown): VistaUrlPayload | null {
+  const record = asRecord(raw);
+  if (record === null) return null;
+  if (typeof record.url !== 'string' || record.url.length === 0) return null;
+  const payload: { url: string; device?: PreviewDevice; reloadNonce?: number } =
+    { url: record.url };
+  if (record.device !== undefined) {
+    if (!PREVIEW_DEVICES.includes(record.device as PreviewDevice)) return null;
+    payload.device = record.device as PreviewDevice;
+  }
+  if (record.reloadNonce !== undefined) {
+    if (typeof record.reloadNonce !== 'number') return null;
+    payload.reloadNonce = record.reloadNonce;
+  }
+  return payload;
+}
+
+/**
+ * `SurfaceKind.Html` — UNTRUSTED HTML. Two mutually-exclusive forms:
+ *
+ *   • `document` — an agent-authored HTML document. Rendered with
+ *     `script-src 'none'`: markup and styles render, script NEVER runs.
+ *   • `compiledOutput` + `integrity` — a server-compiled, SRI-pinned custom-UI
+ *     chunk (App Forge Wave-12). Rendered with `script-src '<sha384-…>'`: ONLY
+ *     those exact bytes execute.
+ *
+ * Both run in an opaque-origin, `allow-scripts`-only sandbox frame.
+ */
+export type VistaHtmlPayload =
+  | { readonly document: string }
+  | {
+      readonly compiledOutput: string;
+      readonly integrity: string;
+      readonly styleCss?: string;
+    };
+
+/** `sha384-<base64>` — the only SRI token form the frame CSP accepts. */
+const SRI_TOKEN = /^sha384-[A-Za-z0-9+/]+={0,2}$/;
+
+export function validateHtmlPayload(raw: unknown): VistaHtmlPayload | null {
+  const record = asRecord(raw);
+  if (record === null) return null;
+  const hasDocument = typeof record.document === 'string';
+  const hasChunk = typeof record.compiledOutput === 'string';
+  if (hasDocument === hasChunk) return null;
+  if (hasDocument) return { document: record.document as string };
+  // A compiled chunk WITHOUT a well-formed integrity token is rejected: the
+  // CSP hash source is what makes executing it safe, so there is no
+  // "run it unpinned" path.
+  if (typeof record.integrity !== 'string' || !SRI_TOKEN.test(record.integrity))
+    return null;
+  const styleCss = optionalString(record.styleCss);
+  if (styleCss === null) return null;
+  const payload = {
+    compiledOutput: record.compiledOutput as string,
+    integrity: record.integrity,
+  };
+  return styleCss === undefined ? payload : { ...payload, styleCss };
+}
+
+/** `SurfaceKind.Json` — an inspectable JSON tree. */
+export interface VistaJsonPayload {
+  readonly data: unknown;
+}
+
+export function validateJsonPayload(raw: unknown): VistaJsonPayload | null {
+  const record = asRecord(raw);
+  if (record === null) return null;
+  if (!('data' in record)) return null;
+  return { data: record.data };
+}
+
+/** `SurfaceKind.Table` — generic columns + rows. */
+export interface VistaTablePayload {
+  readonly columns: readonly string[];
+  readonly rows: readonly (readonly unknown[])[];
+}
+
+export function validateTablePayload(raw: unknown): VistaTablePayload | null {
+  const record = asRecord(raw);
+  if (record === null) return null;
+  if (!Array.isArray(record.columns) || !Array.isArray(record.rows)) return null;
+  if (!record.columns.every((c) => typeof c === 'string')) return null;
+  if (!record.rows.every((r) => Array.isArray(r))) return null;
+  return {
+    columns: record.columns,
+    rows: record.rows as readonly (readonly unknown[])[],
+  };
+}
+
+/** Chart shapes the `chart` surface draws. Closed set. */
+export enum VistaChartKind {
+  Bar = 'bar',
+  Line = 'line',
+  Donut = 'donut',
+}
+
+/** One labelled point. Value-identical to the kernel `ChartDatum`. */
+export interface VistaChartDatum {
+  readonly label: string;
+  readonly value: number;
+}
+
+/** One named series. */
+export interface VistaChartSeries {
+  readonly name: string;
+  readonly points: readonly VistaChartDatum[];
+}
+
+/**
+ * `SurfaceKind.Chart`. At least one series is REQUIRED — `bar`/`donut` render
+ * the first one, so an empty `series` would have no defined rendering.
+ */
+export interface VistaChartPayload {
+  readonly kind: VistaChartKind;
+  readonly title: string;
+  readonly series: readonly [VistaChartSeries, ...VistaChartSeries[]];
+}
+
+const CHART_KINDS: readonly string[] = Object.values(VistaChartKind);
+
+export function validateChartPayload(raw: unknown): VistaChartPayload | null {
+  const record = asRecord(raw);
+  if (record === null) return null;
+  if (typeof record.kind !== 'string' || !CHART_KINDS.includes(record.kind))
+    return null;
+  if (typeof record.title !== 'string' || record.title.length === 0) return null;
+  if (!Array.isArray(record.series) || record.series.length === 0) return null;
+  const series: VistaChartSeries[] = [];
+  for (const entry of record.series) {
+    const row = asRecord(entry);
+    if (row === null || typeof row.name !== 'string') return null;
+    if (!Array.isArray(row.points)) return null;
+    const points: VistaChartDatum[] = [];
+    for (const point of row.points) {
+      const p = asRecord(point);
+      if (p === null || typeof p.label !== 'string') return null;
+      if (typeof p.value !== 'number') return null;
+      points.push({ label: p.label, value: p.value });
+    }
+    series.push({ name: row.name, points });
+  }
+  return {
+    kind: record.kind as VistaChartKind,
+    title: record.title,
+    series: series as [VistaChartSeries, ...VistaChartSeries[]],
+  };
+}
+
+/** `SurfaceKind.Diff` — a unified diff, inline or file-backed. */
+export type VistaDiffPayload = VistaTextPayload;
+export const validateDiffPayload = validateTextPayload;
+
+/** One row in the {@link SurfaceKind.Files} browser. */
+export interface VistaFileEntry {
+  /** Workspace-relative path (also the row key). */
+  readonly path: string;
+  /** Lines added (present only for changed files). */
+  readonly add?: number;
+  /** Lines deleted (present only for changed files). */
+  readonly del?: number;
+}
+
+/** `SurfaceKind.Files` — a file tree over a workspace / artifact set. */
+export interface VistaFilesPayload {
+  readonly files: readonly VistaFileEntry[];
+}
+
+export function validateFilesPayload(raw: unknown): VistaFilesPayload | null {
+  const record = asRecord(raw);
+  if (record === null) return null;
+  if (!Array.isArray(record.files)) return null;
+  const files: VistaFileEntry[] = [];
+  for (const entry of record.files) {
+    const row = asRecord(entry);
+    if (row === null || typeof row.path !== 'string') return null;
+    const file: { path: string; add?: number; del?: number } = {
+      path: row.path,
+    };
+    if (row.add !== undefined) {
+      if (typeof row.add !== 'number') return null;
+      file.add = row.add;
+    }
+    if (row.del !== undefined) {
+      if (typeof row.del !== 'number') return null;
+      file.del = row.del;
+    }
+    files.push(file);
+  }
+  return { files };
+}
+
+/**
+ * `SurfaceKind.BiomeRoute` — a biome's REAL React route, addressed by the
+ * existing `xema://biome/<biomeId>/<route>` deeplink. Validation here is
+ * structural only; the HOST parses the deeplink and enforces route access.
+ */
+export interface VistaBiomeRoutePayload {
+  readonly deeplink: string;
+}
+
+export function validateBiomeRoutePayload(
+  raw: unknown,
+): VistaBiomeRoutePayload | null {
+  const record = asRecord(raw);
+  if (record === null) return null;
+  return typeof record.deeplink === 'string' && record.deeplink.length > 0
+    ? { deeplink: record.deeplink }
+    : null;
+}
+
+/** `SurfaceKind.Object` — a `xema://<scope>/<kind>/<slug>` entity. */
+export interface VistaObjectPayload {
+  readonly ref: string;
+}
+
+export function validateObjectPayload(raw: unknown): VistaObjectPayload | null {
+  const record = asRecord(raw);
+  if (record === null) return null;
+  return typeof record.ref === 'string' && record.ref.length > 0
+    ? { ref: record.ref }
+    : null;
+}
+
+/** `SurfaceKind.Graph` — the capability graph, optionally anchored. */
+export interface VistaGraphPayload {
+  /** Anchor the view on a resource/capability ref. Absent = whole snapshot. */
+  readonly anchorRef?: string;
+  /** Traversal depth from the anchor. */
+  readonly depth?: number;
+}
+
+export function validateGraphPayload(raw: unknown): VistaGraphPayload | null {
+  const record = asRecord(raw);
+  if (record === null) return null;
+  const anchorRef = optionalString(record.anchorRef);
+  if (anchorRef === null) return null;
+  if (record.depth !== undefined && typeof record.depth !== 'number')
+    return null;
+  const payload: { anchorRef?: string; depth?: number } = {};
+  if (anchorRef !== undefined) payload.anchorRef = anchorRef;
+  if (record.depth !== undefined) payload.depth = record.depth;
+  return payload;
+}
+
+/** `SurfaceKind.Web` — a first-party in-app route rendered inside the tab. */
+export interface VistaWebPayload {
+  /** Host-relative path (leading `/`). */
+  readonly href: string;
+}
+
+export function validateWebPayload(raw: unknown): VistaWebPayload | null {
+  const record = asRecord(raw);
+  if (record === null) return null;
+  return typeof record.href === 'string' && record.href.startsWith('/')
+    ? { href: record.href }
+    : null;
+}
+
+/**
+ * An `http(s)` ABSOLUTE URL, or `null`.
+ *
+ * Every URL on a {@link VistaFormPayload} must be absolute. That is the
+ * structural half of "the value goes browser → service and never through the
+ * agent": a relative path would resolve against the HOST app's origin — i.e.
+ * its BFF, where the chat transport lives — so a relative submit target is
+ * rejected outright rather than normalised.
+ */
+function absoluteHttpUrl(value: unknown): string | null {
+  if (typeof value !== 'string' || value.length === 0) return null;
+  let parsed: URL;
+  try {
+    parsed = new URL(value);
+  } catch {
+    return null;
+  }
+  return parsed.protocol === 'https:' || parsed.protocol === 'http:' ? value : null;
+}
+
+/**
+ * The consent / install handoff of a {@link VistaFormPayload}.
+ *
+ * Present when the connector's app auth is `oauth2` or `app_install`: there is
+ * no field form to fill, only a link the user follows in another window. It is
+ * fully generic — the URL is minted per-provider by the owning service and
+ * carried here verbatim, so no provider is special-cased in the renderer.
+ */
+export interface VistaFormLaunch {
+  /** ABSOLUTE consent / install URL, opened in a new window. */
+  readonly url: string;
+  /** Button copy, e.g. "Install Acme" / "Continue to Acme". */
+  readonly label: string;
+  /** Optional explanation rendered above the button. */
+  readonly hint?: string;
+}
+
+/**
+ * `SurfaceKind.Form` — the SECURE ELICITATION surface.
+ *
+ * The agent opens it to walk a user through providing a credential it must
+ * never see. Two mutually-exclusive modes, chosen by the presence of
+ * {@link launch}:
+ *
+ *   • FIELD mode — render `fields`, POST them to `submitUrl` with the user's
+ *     own JWT;
+ *   • LAUNCH mode — render the consent/install link, then confirm completion
+ *     against `statusUrl`.
+ *
+ * Both settle into the same `{ submitted, ref }` shape, so the agent's view of
+ * the world does not depend on which mode ran.
+ */
+export interface VistaFormPayload {
+  /** Opaque, non-secret elicitation reference. The agent polls this. */
+  readonly ref: string;
+  /** Why the credential is being asked for — shown to the user verbatim. */
+  readonly purpose: string;
+  /** ABSOLUTE service URL the captured fields are POSTed to. */
+  readonly submitUrl: string;
+  /** ABSOLUTE service URL reporting whether the elicitation has settled. */
+  readonly statusUrl: string;
+  /** The onboarding form's fields. MAY be empty — the service is the authority. */
+  readonly fields: readonly CaptureFieldSpec[];
+  /** Optional heading override (defaults to the tab title). */
+  readonly heading?: string;
+  /** Submit-button copy for field mode. */
+  readonly submitLabel?: string;
+  /** Present ⇒ LAUNCH mode (oauth2 / app_install). */
+  readonly launch?: VistaFormLaunch;
+}
+
+export function validateFormPayload(raw: unknown): VistaFormPayload | null {
+  const record = asRecord(raw);
+  if (record === null) return null;
+  if (typeof record.ref !== 'string' || record.ref.length === 0) return null;
+  if (typeof record.purpose !== 'string') return null;
+
+  const submitUrl = absoluteHttpUrl(record.submitUrl);
+  if (submitUrl === null) return null;
+  const statusUrl = absoluteHttpUrl(record.statusUrl);
+  if (statusUrl === null) return null;
+
+  const fields = validateCaptureFields(record.fields);
+  if (fields === null) return null;
+
+  const heading = optionalString(record.heading);
+  if (heading === null) return null;
+  const submitLabel = optionalString(record.submitLabel);
+  if (submitLabel === null) return null;
+
+  let launch: VistaFormLaunch | undefined;
+  if (record.launch !== undefined) {
+    const raw_ = asRecord(record.launch);
+    if (raw_ === null) return null;
+    const url = absoluteHttpUrl(raw_.url);
+    if (url === null) return null;
+    if (typeof raw_.label !== 'string' || raw_.label.length === 0) return null;
+    const hint = optionalString(raw_.hint);
+    if (hint === null) return null;
+    launch = hint === undefined ? { url, label: raw_.label } : { url, label: raw_.label, hint };
+  }
+
+  const payload: {
+    ref: string;
+    purpose: string;
+    submitUrl: string;
+    statusUrl: string;
+    fields: readonly CaptureFieldSpec[];
+    heading?: string;
+    submitLabel?: string;
+    launch?: VistaFormLaunch;
+  } = { ref: record.ref, purpose: record.purpose, submitUrl, statusUrl, fields };
+  if (heading !== undefined) payload.heading = heading;
+  if (submitLabel !== undefined) payload.submitLabel = submitLabel;
+  if (launch !== undefined) payload.launch = launch;
+  return payload;
+}
+
+/** `SurfaceKind.App` — a runtime App-Platform app rendered in its own frame. */
+export interface VistaAppPayload {
+  readonly appId: string;
+  /** In-app route, defaults to the app's entry route. */
+  readonly path?: string;
+}
+
+export function validateAppPayload(raw: unknown): VistaAppPayload | null {
+  const record = asRecord(raw);
+  if (record === null) return null;
+  if (typeof record.appId !== 'string' || record.appId.length === 0) return null;
+  const path = optionalString(record.path);
+  if (path === null) return null;
+  return path === undefined
+    ? { appId: record.appId }
+    : { appId: record.appId, path };
+}