@xemahq/ui-kernel 0.11.1 → 0.12.0

package/src/vista/surfaces/elicitation-transport.ts

@@ -1,367 +0,0 @@
-// ═══════════════════════════════════════════════════════════════════════════
-// The `form` surface's transport — browser → owning service, direct.
-//
-// This module is the ONLY code that ever reads a captured field value out of
-// the form surface, and it does exactly one thing with it: put it in the body
-// of a `fetch` to an endpoint derived from the HOST-CONFIGURED trusted
-// elicitation-service base URL, bearing the SUBJECT's own JWT.
-//
-// Three properties make "the agent cannot receive the value" structural:
-//
-//   • the value is a PARAMETER, never a return: every exported function returns
-//     `VistaFormOutcome | null`, a closed scalar-only shape (see
-//     `../vista-form-host`). The values object is not reachable from any
-//     return, any thrown error, or any callback;
-//   • the response is PROJECTED, not passed through: `toOutcome` constructs a
-//     fresh object with exactly three keys, so a service that echoed a secret
-//     back could still not leak one through this boundary;
-//   • the payload carries only an opaque ref. It has NO network authority. This
-//     module validates the host-configured base URL and derives the exact
-//     status/submit paths before a bearer token or field value reaches fetch.
-//
-// Errors carry the SERVICE's message verbatim (that is how the backend's hard
-// 400 on an empty credential form becomes readable UI copy) and never the
-// request body.
-// ═══════════════════════════════════════════════════════════════════════════
-import { isValidVistaFormRef } from '../vista-payloads';
-
-import type { VistaFormOutcome } from '../vista-form-context';
-
-/** A non-2xx answer from the owning service, carrying its message verbatim. */
-export class VistaFormSubmitError extends Error {
-  constructor(
-    readonly status: number,
-    message: string,
-  ) {
-    super(message);
-    this.name = 'VistaFormSubmitError';
-  }
-}
-
-/** Invalid trusted-host transport configuration or unsafe path input. */
-export class VistaFormTransportConfigError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = 'VistaFormTransportConfigError';
-  }
-}
-
-export interface TrustedElicitationEndpoints {
-  readonly statusUrl: string;
-  readonly submitUrl: string;
-}
-
-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;
-}
-
-/**
- * Unwrap the platform `{ data: … }` envelope when present. Total: a flat body
- * is returned as-is, so the transport works against either wire shape without
- * a second code path.
- */
-function unwrapEnvelope(body: unknown): UnknownRecord | null {
-  const record = asRecord(body);
-  if (record === null) {
-    return null;
-  }
-  const inner = asRecord(record.data);
-  return inner ?? record;
-}
-
-/**
- * Best-effort extraction of the SERVICE's error message. Falls back to a
- * status-derived sentence — never to an empty string, because an empty error is
- * indistinguishable from success in the UI.
- */
-export function extractServiceMessage(body: unknown, status: number): string {
-  const record = asRecord(body);
-  const candidate =
-    record === null
-      ? undefined
-      : (record.message ?? asRecord(record.error)?.message ?? record.error);
-  if (typeof candidate === 'string' && candidate.length > 0) {
-    return candidate;
-  }
-  if (Array.isArray(candidate)) {
-    const joined = candidate
-      .filter((m): m is string => typeof m === 'string')
-      .join(' ');
-    if (joined.length > 0) {
-      return joined;
-    }
-  }
-  if (typeof body === 'string' && body.length > 0) {
-    return body;
-  }
-  return `The service rejected the submission (HTTP ${status}).`;
-}
-
-async function readBody(response: Response): Promise<unknown> {
-  const contentType = response.headers.get('content-type');
-  try {
-    if (contentType !== null && contentType.includes('application/json')) {
-      return await response.json();
-    }
-    return await response.text();
-  } catch {
-    return null;
-  }
-}
-
-/**
- * Project a service response onto {@link VistaFormOutcome}. Constructs a FRESH
- * object with exactly three keys — nothing else from the response survives.
- * Returns `null` when the service reports the elicitation is not settled.
- */
-function toOutcome(body: unknown, ref: string): VistaFormOutcome | null {
-  const record = unwrapEnvelope(body);
-  if (record === null) {
-    return null;
-  }
-  const submitted =
-    record.submitted === true ||
-    (typeof record.status === 'string' && record.status === 'submitted');
-  if (!submitted) {
-    return null;
-  }
-  const connectionId =
-    typeof record.connectionId === 'string' && record.connectionId.length > 0
-      ? record.connectionId
-      : null;
-  return { submitted: true, ref, connectionId };
-}
-
-/** The `Authorization`/`Content-Type` pair every request here carries. */
-function authHeaders(
-  accessToken: string,
-  json: boolean,
-): Record<string, string> {
-  const headers: Record<string, string> = {
-    Authorization: `Bearer ${accessToken}`,
-    Accept: 'application/json',
-  };
-  if (json) {
-    headers['Content-Type'] = 'application/json';
-  }
-  return headers;
-}
-
-function browserOrigin(): string | undefined {
-  return typeof globalThis.location === 'undefined'
-    ? undefined
-    : globalThis.location.origin;
-}
-
-function isLoopbackHostname(hostname: string): boolean {
-  return (
-    hostname === 'localhost' ||
-    hostname.endsWith('.localhost') ||
-    hostname === '127.0.0.1' ||
-    hostname === '[::1]'
-  );
-}
-
-/**
- * Parse the host's deploy-time trust anchor. It must be a canonical absolute
- * HTTP(S) URL without credentials/query/fragment. HTTPS is mandatory except
- * for loopback or same-host HTTP when the page itself is also served over HTTP.
- */
-function trustedApiBaseUrl(
-  raw: string,
-  activeBrowserOrigin: string | undefined,
-): URL {
-  if (raw.length === 0 || raw.trim() !== raw) {
-    throw new VistaFormTransportConfigError(
-      'The trusted elicitation API base URL is empty or contains whitespace.',
-    );
-  }
-
-  let url: URL;
-  try {
-    url = new URL(raw);
-  } catch {
-    throw new VistaFormTransportConfigError(
-      'The trusted elicitation API base URL must be absolute.',
-    );
-  }
-
-  if (
-    (url.protocol !== 'https:' && url.protocol !== 'http:') ||
-    url.username.length > 0 ||
-    url.password.length > 0 ||
-    url.search.length > 0 ||
-    url.hash.length > 0
-  ) {
-    throw new VistaFormTransportConfigError(
-      'The trusted elicitation API base URL must use HTTP(S) and contain no credentials, query, or fragment.',
-    );
-  }
-
-  const canonicalPath =
-    url.pathname === '/' ? '' : url.pathname.replace(/\/+$/, '');
-  const canonical = `${url.origin}${canonicalPath}`;
-  const suppliedWithoutOneTrailingSlash = raw.endsWith('/')
-    ? raw.slice(0, -1)
-    : raw;
-  if (suppliedWithoutOneTrailingSlash !== canonical) {
-    throw new VistaFormTransportConfigError(
-      'The trusted elicitation API base URL must be canonical and contain no traversal or ambiguous path.',
-    );
-  }
-
-  if (url.protocol === 'http:' && !isLoopbackHostname(url.hostname)) {
-    let page: URL | null = null;
-    if (activeBrowserOrigin !== undefined) {
-      try {
-        page = new URL(activeBrowserOrigin);
-      } catch {
-        page = null;
-      }
-    }
-    if (
-      page === null ||
-      page.protocol !== 'http:' ||
-      page.hostname !== url.hostname
-    ) {
-      throw new VistaFormTransportConfigError(
-        'Insecure elicitation HTTP is allowed only on loopback or the same host as an HTTP development page.',
-      );
-    }
-  }
-
-  return new URL(canonical);
-}
-
-/**
- * Derive the only two authenticated endpoints from trusted host configuration
- * plus one opaque path segment. Calling this directly remains safe even if a
- * caller bypasses the surface-payload validator.
- */
-export function resolveTrustedElicitationEndpoints(
-  apiBaseUrl: string,
-  ref: string,
-  activeBrowserOrigin: string | undefined = browserOrigin(),
-): TrustedElicitationEndpoints {
-  if (!isValidVistaFormRef(ref)) {
-    throw new VistaFormTransportConfigError(
-      'The elicitation reference is not a valid opaque base64url path segment.',
-    );
-  }
-  const base = trustedApiBaseUrl(apiBaseUrl, activeBrowserOrigin)
-    .toString()
-    .replace(/\/$/, '');
-  const statusUrl = `${base}/${ref}`;
-  return { statusUrl, submitUrl: `${statusUrl}/submit` };
-}
-
-/**
- * Resolve an unauthenticated launch path under the SAME trusted service origin.
- * Absolute/network-path URLs and dot-segment traversal fail closed.
- */
-export function resolveTrustedElicitationLaunchUrl(
-  apiBaseUrl: string,
-  path: string,
-  activeBrowserOrigin: string | undefined = browserOrigin(),
-): string {
-  const base = trustedApiBaseUrl(apiBaseUrl, activeBrowserOrigin);
-  if (
-    !path.startsWith('/') ||
-    path.startsWith('//') ||
-    path.includes('\\') ||
-    path.includes('#')
-  ) {
-    throw new VistaFormTransportConfigError(
-      'The elicitation launch target must be a root-relative service path.',
-    );
-  }
-  const resolved = new URL(path, `${base.origin}/`);
-  if (
-    resolved.origin !== base.origin ||
-    `${resolved.pathname}${resolved.search}` !== path
-  ) {
-    throw new VistaFormTransportConfigError(
-      'The elicitation launch path contains traversal or an ambiguous encoding.',
-    );
-  }
-  return resolved.toString();
-}
-
-/**
- * POST the captured fields to the owning service.
- *
- * @throws {VistaFormSubmitError} on a non-2xx answer, carrying the service's
- * own message so a hard 400 (e.g. "no credential form is declared") is what the
- * user reads.
- */
-export async function submitElicitationFields(args: {
-  readonly apiBaseUrl: string;
-  readonly ref: string;
-  readonly accessToken: string;
-  readonly fields: Readonly<Record<string, string>>;
-}): Promise<VistaFormOutcome> {
-  const { submitUrl } = resolveTrustedElicitationEndpoints(
-    args.apiBaseUrl,
-    args.ref,
-  );
-  const response = await fetch(submitUrl, {
-    method: 'POST',
-    headers: authHeaders(args.accessToken, true),
-    body: JSON.stringify({ fields: args.fields }),
-    credentials: 'omit',
-    // A 307/308 could otherwise replay the credential body to a different
-    // origin. Authenticated elicitation endpoints must never redirect.
-    redirect: 'error',
-  });
-  const body = await readBody(response);
-  if (!response.ok) {
-    throw new VistaFormSubmitError(
-      response.status,
-      extractServiceMessage(body, response.status),
-    );
-  }
-  const outcome = toOutcome(body, args.ref);
-  if (outcome === null) {
-    throw new VistaFormSubmitError(
-      response.status,
-      'The service accepted the request but did not report the elicitation as submitted.',
-    );
-  }
-  return outcome;
-}
-
-/**
- * Read the elicitation's current state. Used by the OAuth / app-install handoff,
- * where completion happens in another window and the only signal available to
- * this tab is the service's own record.
- *
- * Returns `null` while still pending — an explicit "not yet", never a guess.
- */
-export async function readElicitationStatus(args: {
-  readonly apiBaseUrl: string;
-  readonly ref: string;
-  readonly accessToken: string;
-}): Promise<VistaFormOutcome | null> {
-  const { statusUrl } = resolveTrustedElicitationEndpoints(
-    args.apiBaseUrl,
-    args.ref,
-  );
-  const response = await fetch(statusUrl, {
-    method: 'GET',
-    headers: authHeaders(args.accessToken, false),
-    credentials: 'omit',
-    redirect: 'error',
-  });
-  const body = await readBody(response);
-  if (!response.ok) {
-    throw new VistaFormSubmitError(
-      response.status,
-      extractServiceMessage(body, response.status),
-    );
-  }
-  return toOutcome(body, args.ref);
-}

package/src/vista/surfaces/file-surface-utils.ts

@@ -1,69 +0,0 @@
-import type { VistaFileEntry } from '../vista-payloads';
-
-interface FileExtMeta {
-  readonly color: string;
-  readonly tag: string;
-}
-
-const EXT_META: Readonly<Record<string, FileExtMeta>> = {
-  ts: { color: 'hsl(var(--info))', tag: 'TS' },
-  tsx: { color: 'hsl(var(--info))', tag: 'TSX' },
-  js: { color: 'hsl(var(--warning))', tag: 'JS' },
-  jsx: { color: 'hsl(var(--warning))', tag: 'JSX' },
-  json: { color: 'hsl(var(--ink-3))', tag: 'JSON' },
-  md: { color: 'hsl(var(--p-people))', tag: 'MD' },
-  css: { color: 'hsl(var(--p-sales))', tag: 'CSS' },
-  html: { color: 'hsl(var(--p-sales))', tag: 'HTML' },
-  yaml: { color: 'hsl(var(--ink-3))', tag: 'YAML' },
-  yml: { color: 'hsl(var(--ink-3))', tag: 'YAML' },
-};
-
-export function fileExtMeta(name: string): FileExtMeta {
-  if (/\.test\.[tj]sx?$/.test(name) || /\.spec\.[tj]sx?$/.test(name)) {
-    return { color: 'hsl(var(--success))', tag: 'TEST' };
-  }
-  const ext = name.split('.').pop() ?? '';
-  return (
-    EXT_META[ext] ?? {
-      color: 'hsl(var(--ink-4))',
-      tag: (ext || 'FILE').toUpperCase().slice(0, 4),
-    }
-  );
-}
-
-export interface VistaFileGroup {
-  readonly dir: string;
-  readonly files: readonly VistaFileEntry[];
-}
-
-function compareDirs(a: string, b: string): number {
-  if (a === '') {
-    return -1;
-  }
-  if (b === '') {
-    return 1;
-  }
-  return a.localeCompare(b);
-}
-
-export function groupFilesByFolder(
-  files: readonly VistaFileEntry[],
-): VistaFileGroup[] {
-  const groups = new Map<string, VistaFileEntry[]>();
-  for (const file of files) {
-    const slash = file.path.lastIndexOf('/');
-    const dir = slash < 0 ? '' : file.path.slice(0, slash);
-    const bucket = groups.get(dir);
-    if (bucket) {
-      bucket.push(file);
-    } else {
-      groups.set(dir, [file]);
-    }
-  }
-  return [...groups.keys()].sort(compareDirs).map((dir) => ({
-    dir,
-    files: [...(groups.get(dir) ?? [])].sort((a, b) =>
-      a.path.localeCompare(b.path),
-    ),
-  }));
-}

package/src/vista/surfaces/index.ts

@@ -1,24 +0,0 @@
-import './register-surfaces';
-
-export { ChartSurface } from './ChartSurface';
-export { FilesSurface } from './FilesSurface';
-export {
-  fileExtMeta,
-  groupFilesByFolder,
-  type VistaFileGroup,
-} from './file-surface-utils';
-export { FormSurface } from './FormSurface';
-export {
-  extractServiceMessage,
-  readElicitationStatus,
-  resolveTrustedElicitationEndpoints,
-  resolveTrustedElicitationLaunchUrl,
-  submitElicitationFields,
-  VistaFormSubmitError,
-  VistaFormTransportConfigError,
-} from './elicitation-transport';
-export { HtmlSurface } from './HtmlSurface';
-export { TableSurface } from './TableSurface';
-export { UrlSurface } from './UrlSurface';
-export { CodeSurface, DiffSurface, JsonSurface } from './text-surfaces';
-export { ImageSurface, MediaSurface, PdfSurface } from './blob-surfaces';

package/src/vista/surfaces/register-surfaces.tsx

@@ -1,139 +0,0 @@
-/**
- * Registration of the first-party surface renderers the UI KERNEL owns.
- *
- * ── The partition (deliberate, and the reason there is no slot-soup) ─────────
- * A kind is registered HERE when the kernel can render it standalone from its
- * payload (plus, for a file-backed kind, the host's injected `VistaFileSource`):
- *
- *     url · html · code · json · diff · table · chart · files · image · media ·
- *     pdf · form
- *
- * `form` (secure elicitation) belongs here even though it talks to a service:
- * it does so through the host-supplied `VistaFormHost` seam, exactly the way a
- * file-backed surface reads through `VistaFileSource`. The kernel owns the
- * renderer; the host owns only the token and the outcome sink.
- *
- * The remaining first-party kinds are HOST-COUPLED — they need the host's
- * router, its object views, its markdown renderer, or its biome registry — so
- * the HOST registers them with
- * `vistaSurfaceRegistry.registerFirstParty(...)`:
- *
- *     markdown · web · biome-route · object · graph · app
- *
- * Every unregistered kind resolves to `SurfaceFallbackCard` with
- * `unknown-kind` — visible, typed, never blank.
- *
- * Importing this module REGISTERS. It is imported for its side effect by
- * `../index.ts`, so any consumer of `@xemahq/ui-kernel/vista` gets the kernel
- * builtins wired without an explicit call.
- */
-import { SurfaceKind } from '@xemahq/kernel-contracts/surface';
-
-import { ImageSurface, MediaSurface, PdfSurface } from './blob-surfaces';
-import { ChartSurface } from './ChartSurface';
-import { FilesSurface } from './FilesSurface';
-import { FormSurface } from './FormSurface';
-import { HtmlSurface } from './HtmlSurface';
-import { TableSurface } from './TableSurface';
-import { CodeSurface, DiffSurface, JsonSurface } from './text-surfaces';
-import { UrlSurface } from './UrlSurface';
-import { vistaSurfaceRegistry } from '../surface-registry';
-import { VISTA_SURFACE_VERSION } from '../vista-model';
-import {
-  validateBlobPayload,
-  validateChartPayload,
-  validateDiffPayload,
-  validateFilesPayload,
-  validateFormPayload,
-  validateHtmlPayload,
-  validateJsonPayload,
-  validateTablePayload,
-  validateTextPayload,
-  validateUrlPayload,
-  type VistaBlobPayload,
-} from '../vista-payloads';
-
-/**
- * `media` additionally REQUIRES `contentType`: choosing between `<audio>` and
- * `<video>` from a URL would be a heuristic that fails on an extension-less
- * URL, and this plane does not ship heuristics that can be wrong.
- */
-function validateMediaPayload(raw: unknown): VistaBlobPayload | null {
-  const payload = validateBlobPayload(raw);
-  if (payload === null) {
-    return null;
-  }
-  return payload.contentType === undefined ? null : payload;
-}
-
-vistaSurfaceRegistry.registerFirstParty(SurfaceKind.Url, {
-  version: VISTA_SURFACE_VERSION,
-  validate: validateUrlPayload,
-  render: (payload) => <UrlSurface {...payload} />,
-});
-
-vistaSurfaceRegistry.registerFirstParty(SurfaceKind.Html, {
-  version: VISTA_SURFACE_VERSION,
-  validate: validateHtmlPayload,
-  render: (payload) => <HtmlSurface {...payload} />,
-});
-
-vistaSurfaceRegistry.registerFirstParty(SurfaceKind.Code, {
-  version: VISTA_SURFACE_VERSION,
-  validate: validateTextPayload,
-  render: (payload) => <CodeSurface {...payload} />,
-});
-
-vistaSurfaceRegistry.registerFirstParty(SurfaceKind.Json, {
-  version: VISTA_SURFACE_VERSION,
-  validate: validateJsonPayload,
-  render: (payload) => <JsonSurface data={payload.data} />,
-});
-
-vistaSurfaceRegistry.registerFirstParty(SurfaceKind.Diff, {
-  version: VISTA_SURFACE_VERSION,
-  validate: validateDiffPayload,
-  render: (payload) => <DiffSurface {...payload} />,
-});
-
-vistaSurfaceRegistry.registerFirstParty(SurfaceKind.Table, {
-  version: VISTA_SURFACE_VERSION,
-  validate: validateTablePayload,
-  render: (payload) => <TableSurface {...payload} />,
-});
-
-vistaSurfaceRegistry.registerFirstParty(SurfaceKind.Chart, {
-  version: VISTA_SURFACE_VERSION,
-  validate: validateChartPayload,
-  render: (payload) => <ChartSurface {...payload} />,
-});
-
-vistaSurfaceRegistry.registerFirstParty(SurfaceKind.Files, {
-  version: VISTA_SURFACE_VERSION,
-  validate: validateFilesPayload,
-  render: (payload) => <FilesSurface {...payload} />,
-});
-
-vistaSurfaceRegistry.registerFirstParty(SurfaceKind.Image, {
-  version: VISTA_SURFACE_VERSION,
-  validate: validateBlobPayload,
-  render: (payload) => <ImageSurface {...payload} />,
-});
-
-vistaSurfaceRegistry.registerFirstParty(SurfaceKind.Media, {
-  version: VISTA_SURFACE_VERSION,
-  validate: validateMediaPayload,
-  render: (payload) => <MediaSurface {...payload} />,
-});
-
-vistaSurfaceRegistry.registerFirstParty(SurfaceKind.Pdf, {
-  version: VISTA_SURFACE_VERSION,
-  validate: validateBlobPayload,
-  render: (payload) => <PdfSurface {...payload} />,
-});
-
-vistaSurfaceRegistry.registerFirstParty(SurfaceKind.Form, {
-  version: VISTA_SURFACE_VERSION,
-  validate: validateFormPayload,
-  render: (payload) => <FormSurface {...payload} />,
-});