@xemahq/ui-kernel 0.8.0 → 0.9.1

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 };
+}

package/src/vista/vista-tools.ts

@@ -0,0 +1,220 @@
+/**
+ * The agent-facing Vista tool contract — `vista_open` / `vista_update` /
+ * `vista_close` / `vista_list` (Canopy §8.2).
+ *
+ * This module is the BROWSER-side definition of those four calls: their names,
+ * their argument shapes, their result shapes, and the dispatcher that performs
+ * them against a {@link VistaTabsController}.
+ *
+ * ── One wire contract, two projections ──────────────────────────────────────
+ * The server half lives in `canopy-api`'s `vista/vista-tool.contract.ts`. The
+ * two files are VALUE-IDENTICAL by construction — same tool names, same
+ * argument shapes, same {@link VistaToolError} members, same result envelope —
+ * and both derive the `vista_open` argument from the kernel's
+ * `VistaSurfaceSchema`, which is the single structural source of truth. They
+ * are two projections rather than one import because this package is a React
+ * UI package (a NestJS service must not depend on it) and the kernel contracts
+ * package does not yet carry the three tiny argument schemas. Consolidating
+ * them into `@xemahq/kernel-contracts/surface` is the correct end state; until
+ * then, a change to either file MUST be mirrored in the other in the same
+ * change-set, exactly like the curated `ConnectorKind` parity rule.
+ *
+ * ── How a call gets here ────────────────────────────────────────────────────
+ * Vista is a BROWSER surface: no server can render a tab. So the backend never
+ * "performs" these tools — it VALIDATES, applies its own tab projection,
+ * RELAYS the call to the browser over the EXISTING agent-session realtime
+ * channel, and returns the browser's {@link VistaToolResult} to the model
+ * verbatim. A session where no panel answers returns
+ * `{ ok: false, error: 'no-panel' }` — an explicit refusal, never a silent
+ * success.
+ *
+ * The host binds `dispatchVistaTool` to its panel's controller and feeds it the
+ * relayed `{ tool, args }`; see the host's `use-vista-tool-bridge`.
+ */
+import { VistaSurfaceSchema } from '@xemahq/kernel-contracts/surface';
+import { z } from 'zod';
+
+import type { VistaSurfacePatch, VistaTabsController } from './use-vista-tabs';
+
+/** The closed set of Vista tools. Values are the wire tool names. */
+export enum VistaToolName {
+  Open = 'vista_open',
+  Update = 'vista_update',
+  Close = 'vista_close',
+  List = 'vista_list',
+}
+
+/**
+ * `vista_open(surface) -> { tabId }`.
+ *
+ * The argument IS the kernel tab envelope — not a wrapper around it — so the
+ * JSON Schema the model is shown is exactly `VistaSurface`. `kind` is an open
+ * string on purpose: an unrecognised kind is NOT an error, it opens a tab that
+ * renders the fallback card.
+ */
+export const VistaOpenArgsSchema = VistaSurfaceSchema;
+export type VistaOpenArgs = z.infer<typeof VistaOpenArgsSchema>;
+
+/**
+ * `vista_update(tabId, …) -> { updated: true }`.
+ *
+ * Flat, and deliberately narrower than {@link VistaSurfacePatch}: `kind` and
+ * `version` are NOT patchable, because the browser has already resolved a
+ * renderer for the live tab and swapping the kind under it would strand that
+ * renderer. Close and re-open instead. Every remaining field is optional; an
+ * empty patch is a no-op, not an error.
+ */
+export const VistaUpdateArgsSchema = z.object({
+  tabId: z.string().min(1),
+  title: z.string().min(1).optional(),
+  payload: z.unknown().optional(),
+  pinned: z.boolean().optional(),
+});
+export type VistaUpdateArgs = z.infer<typeof VistaUpdateArgsSchema>;
+
+/** `vista_close(tabId) -> { closed: true }`. A pinned tab refuses to close. */
+export const VistaCloseArgsSchema = z.object({ tabId: z.string().min(1) });
+export type VistaCloseArgs = z.infer<typeof VistaCloseArgsSchema>;
+
+/** `vista_list() -> { tabs }`. No arguments. */
+export const VistaListArgsSchema = z.object({});
+export type VistaListArgs = z.infer<typeof VistaListArgsSchema>;
+
+/** Why a Vista tool call could not be performed. Closed set. */
+export enum VistaToolError {
+  /** No Vista panel answered the relay — nothing is on screen to drive. */
+  NoPanel = 'no-panel',
+  /** The arguments failed schema validation at a wire boundary. */
+  InvalidArgs = 'invalid-args',
+  /** The tool name is not a member of {@link VistaToolName}. */
+  UnknownTool = 'unknown-tool',
+  /** `tabId` names a tab that is not open. */
+  UnknownTab = 'unknown-tab',
+  /**
+   * The tab exists but refuses the operation — it is pinned (close), or it is
+   * a HOST tab whose content the host's own data flow owns (update). `detail`
+   * names which.
+   */
+  TabRefused = 'tab-refused',
+}
+
+/** The result envelope every Vista tool returns. */
+export type VistaToolResult<TValue = unknown> =
+  | { readonly ok: true; readonly value: TValue }
+  | {
+      readonly ok: false;
+      readonly error: VistaToolError;
+      readonly detail?: string;
+    };
+
+/**
+ * Wire validator for {@link VistaToolResult}. The browser's answer crosses back
+ * into the server and then into the model's context, so the server validates
+ * the ENVELOPE with this shape before relaying it on — a browser cannot inject
+ * an arbitrary object where a typed result is expected.
+ */
+export const VistaToolResultSchema: z.ZodType<VistaToolResult> = z.union([
+  z.object({ ok: z.literal(true), value: z.unknown() }),
+  z.object({
+    ok: z.literal(false),
+    error: z.nativeEnum(VistaToolError),
+    detail: z.string().optional(),
+  }),
+]) as z.ZodType<VistaToolResult>;
+
+/**
+ * Perform a relayed Vista tool call against a mounted panel's controller.
+ *
+ * Fail-fast on bad input: arguments are re-validated here (the frontend never
+ * trusts that the backend validated), and a violation returns
+ * {@link VistaToolError.InvalidArgs} naming the offending path rather than a
+ * partially-applied change. Pass `controller: null` for a document with no
+ * mounted panel — that returns {@link VistaToolError.NoPanel}.
+ */
+export function dispatchVistaTool(
+  controller: VistaTabsController | null,
+  tool: string,
+  args: unknown,
+): VistaToolResult {
+  if (controller === null) {
+    return { ok: false, error: VistaToolError.NoPanel };
+  }
+  switch (tool) {
+    case VistaToolName.Open: {
+      const parsed = VistaOpenArgsSchema.safeParse(args);
+      if (!parsed.success) return invalid(parsed.error);
+      return { ok: true, value: { tabId: controller.open(parsed.data) } };
+    }
+    case VistaToolName.Update: {
+      const parsed = VistaUpdateArgsSchema.safeParse(args);
+      if (!parsed.success) return invalid(parsed.error);
+      const { tabId, ...patch } = parsed.data;
+      const refusal = refusalFor(controller, tabId);
+      if (refusal !== null) return refusal;
+      if (!controller.update(tabId, patch as VistaSurfacePatch)) {
+        // The tab is listed but not opened-tab-owned: it is a HOST tab, and a
+        // patch to it would be overwritten by the host's next reconcile.
+        return {
+          ok: false,
+          error: VistaToolError.TabRefused,
+          detail: `Tab "${tabId}" is host-owned; its content is driven by the host, not by vista_update.`,
+        };
+      }
+      return { ok: true, value: { updated: true } };
+    }
+    case VistaToolName.Close: {
+      const parsed = VistaCloseArgsSchema.safeParse(args);
+      if (!parsed.success) return invalid(parsed.error);
+      const { tabId } = parsed.data;
+      const refusal = refusalFor(controller, tabId);
+      if (refusal !== null) return refusal;
+      if (!controller.close(tabId)) {
+        return {
+          ok: false,
+          error: VistaToolError.TabRefused,
+          detail: `Tab "${tabId}" is pinned and cannot be closed.`,
+        };
+      }
+      return { ok: true, value: { closed: true } };
+    }
+    case VistaToolName.List: {
+      const parsed = VistaListArgsSchema.safeParse(args ?? {});
+      if (!parsed.success) return invalid(parsed.error);
+      return { ok: true, value: { tabs: controller.list() } };
+    }
+    default:
+      return {
+        ok: false,
+        error: VistaToolError.UnknownTool,
+        detail: `'${tool}' is not a Vista tool.`,
+      };
+  }
+}
+
+/**
+ * `unknown-tab` when the panel does not hold `tabId` at all. Returning `null`
+ * means the tab exists and the operation may proceed.
+ */
+function refusalFor(
+  controller: VistaTabsController,
+  tabId: string,
+): VistaToolResult | null {
+  if (controller.list().some((tab) => tab.tabId === tabId)) {
+    return null;
+  }
+  return {
+    ok: false,
+    error: VistaToolError.UnknownTab,
+    detail: `No tab "${tabId}" is open.`,
+  };
+}
+
+function invalid(error: z.ZodError): VistaToolResult {
+  return {
+    ok: false,
+    error: VistaToolError.InvalidArgs,
+    detail: error.issues
+      .map((i) => `${i.path.join('.') || '(root)'}: ${i.message}`)
+      .join('; '),
+  };
+}