@xemahq/ui-kernel 0.9.0 → 0.9.2

package/src/vista/vista-payloads.ts

@@ -0,0 +1,512 @@
+/**
+ * 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 };
+}

package/src/vista/vista-tabs-manifest.ts

@@ -0,0 +1,123 @@
+/**
+ * `.tabs.json` — the agent-authored tab manifest for a file-backed Vista panel.
+ *
+ * Lifted VERBATIM (guards included) out of the 4970-line Design-System-Builder
+ * page, generalised over the artifact prefix, and re-keyed onto the kernel
+ * {@link SurfaceKind} (Canopy §8.5). It is the ONE parser for this format; the
+ * page no longer carries its own.
+ *
+ * ── The guards (all preserved, all fail-closed) ─────────────────────────────
+ *   1. `version` MUST be exactly `1`.
+ *   2. `tabs` MUST be an array.
+ *   3. Every entry's `path` MUST be a string INSIDE the caller's artifact
+ *      prefix — an agent cannot point a tab at an arbitrary workspace file.
+ *   4. No `..` anywhere in a path — no traversal out of the prefix.
+ *   5. A declared `kind` MUST be a member of {@link DECLARABLE_SURFACE_KINDS}.
+ *      {@link SurfaceKind.Files} is UI-owned (the pinned browser tab) and can
+ *      NEVER be declared by an agent.
+ *   6. ANY violation rejects the WHOLE manifest (returns `null`) — the caller
+ *      falls back to auto-discovery. A malformed file behaves exactly as an
+ *      absent one; there is no partial acceptance and no silent coercion.
+ *
+ * Kind vocabulary note: the legacy `plain` literal is GONE. Plain text is
+ * {@link SurfaceKind.Code} (a mono pane) — one kind, one renderer, no alias.
+ */
+import { SurfaceKind } from '@xemahq/kernel-contracts/surface';
+
+import { surfaceKindForPath } from './vista-model';
+
+/**
+ * The kinds an agent may declare in `.tabs.json`. Every one is file-backed.
+ * `files` is deliberately absent (UI-owned); so are the host-coupled kinds
+ * (`web`, `biome-route`, `object`, `graph`, `app`, `form`), which are not
+ * addressable by a workspace path and are opened through `vista_open` instead.
+ */
+export const DECLARABLE_SURFACE_KINDS: readonly SurfaceKind[] = [
+  SurfaceKind.Html,
+  SurfaceKind.Markdown,
+  SurfaceKind.Code,
+  SurfaceKind.Json,
+  SurfaceKind.Diff,
+  SurfaceKind.Pdf,
+  SurfaceKind.Image,
+  SurfaceKind.Media,
+];
+
+/** One declared tab. */
+export interface VistaTabSpec {
+  readonly path: string;
+  readonly kind: SurfaceKind;
+  readonly label?: string;
+}
+
+/** The parsed manifest. */
+export interface VistaTabsManifest {
+  readonly version: 1;
+  readonly tabs: readonly VistaTabSpec[];
+  /** Path of the tab the agent wants selected on open. */
+  readonly selectedPath?: string;
+}
+
+/** Options for {@link parseVistaTabsManifest}. */
+export interface VistaTabsManifestOptions {
+  /**
+   * Prefix every declared path MUST start with (e.g. `'deliverables/'`). The
+   * containment guard — an agent can only curate tabs over its own artifacts.
+   */
+  readonly pathPrefix: string;
+}
+
+function parseEntry(
+  entry: unknown,
+  pathPrefix: string,
+): VistaTabSpec | null {
+  if (!entry || typeof entry !== 'object') return null;
+  const record = entry as Record<string, unknown>;
+  if (typeof record.path !== 'string') return null;
+  // Containment: inside the artifact prefix, and no traversal out of it.
+  if (!record.path.startsWith(pathPrefix)) return null;
+  if (record.path.includes('..')) return null;
+  const kind =
+    typeof record.kind === 'string'
+      ? (record.kind as SurfaceKind)
+      : surfaceKindForPath(record.path);
+  // `files` is UI-owned (the pinned file browser) and must never be declared by
+  // the agent — an out-of-set kind rejects the whole manifest.
+  if (!DECLARABLE_SURFACE_KINDS.includes(kind)) return null;
+  const label = typeof record.label === 'string' ? record.label : undefined;
+  return label === undefined
+    ? { path: record.path, kind }
+    : { path: record.path, kind, label };
+}
+
+/**
+ * Parse a `.tabs.json` body. Returns `null` on ANY shape violation — the caller
+ * falls back to auto-discovery. No silent coercion: a malformed file is as if
+ * it were absent (the user sees the default view instead of a broken state).
+ */
+export function parseVistaTabsManifest(
+  raw: string,
+  { pathPrefix }: VistaTabsManifestOptions,
+): VistaTabsManifest | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw) as unknown;
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== 'object') return null;
+  const record = parsed as Record<string, unknown>;
+  if (record.version !== 1) return null;
+  if (!Array.isArray(record.tabs)) return null;
+  const tabs: VistaTabSpec[] = [];
+  for (const entry of record.tabs) {
+    const tab = parseEntry(entry, pathPrefix);
+    if (tab === null) return null;
+    tabs.push(tab);
+  }
+  const selectedPath =
+    typeof record.selectedPath === 'string' ? record.selectedPath : undefined;
+  return selectedPath === undefined
+    ? { version: 1, tabs }
+    : { version: 1, tabs, selectedPath };
+}