@xemahq/ui-kernel 0.11.1 → 0.12.0

package/src/vista/vista-payloads.ts

@@ -1,635 +0,0 @@
-/**
- * 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;
-}
-
-/**
- * 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 owning service supplies a path under the host-configured
- * trusted service origin, so no provider is special-cased in the renderer and
- * an agent-controlled payload never selects a network authority.
- */
-export interface VistaFormLaunch {
-  /** Root-relative consent / install path on the trusted elicitation service. */
-  readonly path: 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 through the host's trusted
- *     elicitation-service base URL with the user's own JWT;
- *   • LAUNCH mode — render the consent/install link, then confirm completion
- *     through that same trusted service.
- *
- * 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;
-  /** 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;
-}
-
-const VISTA_FORM_REF_PATTERN = /^[A-Za-z0-9_-]{1,256}$/;
-
-/** Whether a value is one opaque base64url elicitation path segment. */
-export function isValidVistaFormRef(value: unknown): value is string {
-  return typeof value === 'string' && VISTA_FORM_REF_PATTERN.test(value);
-}
-
-export function validateFormPayload(raw: unknown): VistaFormPayload | null {
-  const record = asRecord(raw);
-  if (record === null) {
-    return null;
-  }
-  // The service generates base64url refs. Keeping the accepted alphabet closed
-  // makes the ref safe as exactly one URL path segment; dot segments, slashes,
-  // percent escapes and Unicode lookalikes are all rejected.
-  if (!isValidVistaFormRef(record.ref)) {
-    return null;
-  }
-  if (typeof record.purpose !== 'string') {
-    return null;
-  }
-  // Deliberately reject the old contract rather than silently ignoring its
-  // payload-selected network targets.
-  if ('submitUrl' in record || 'statusUrl' in record) {
-    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;
-    }
-    if ('url' in raw_) {
-      return null;
-    }
-    if (
-      typeof raw_.path !== 'string' ||
-      !raw_.path.startsWith('/') ||
-      raw_.path.startsWith('//') ||
-      raw_.path.includes('\\')
-    ) {
-      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
-        ? { path: raw_.path, label: raw_.label }
-        : { path: raw_.path, label: raw_.label, hint };
-  }
-
-  const payload: {
-    ref: string;
-    purpose: string;
-    fields: readonly CaptureFieldSpec[];
-    heading?: string;
-    submitLabel?: string;
-    launch?: VistaFormLaunch;
-  } = { ref: record.ref, purpose: record.purpose, 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 };
-}