@xemahq/ui-kernel 0.9.0 → 0.9.2

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(),
+  }),
+]);
+
+/**
+ * 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)) {
+        // 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('; '),
+  };
+}

package/dist/lib/biome-host/response-envelope.d.ts

@@ -1,3 +0,0 @@
-export declare function unwrapList<T>(value: unknown): T[];
-export declare function unwrapData<T>(value: unknown): T;
-//# sourceMappingURL=response-envelope.d.ts.map

package/dist/lib/biome-host/response-envelope.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"response-envelope.d.ts","sourceRoot":"","sources":["../../../src/lib/biome-host/response-envelope.ts"],"names":[],"mappings":"AA+BA,wBAAgB,UAAU,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,GAAG,CAAC,EAAE,CAYjD;AAeD,wBAAgB,UAAU,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,GAAG,CAAC,CAU/C"}

package/dist/lib/biome-host/response-envelope.js

@@ -1,21 +0,0 @@
-export function unwrapList(value) {
-    if (Array.isArray(value)) {
-        return value;
-    }
-    if (value !== null &&
-        typeof value === 'object' &&
-        Array.isArray(value.data)) {
-        return value.data;
-    }
-    return [];
-}
-export function unwrapData(value) {
-    if (value !== null &&
-        typeof value === 'object' &&
-        'data' in value &&
-        !('pagination' in value)) {
-        return value.data;
-    }
-    return value;
-}
-//# sourceMappingURL=response-envelope.js.map

package/dist/lib/biome-host/response-envelope.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"response-envelope.js","sourceRoot":"","sources":["../../../src/lib/biome-host/response-envelope.ts"],"names":[],"mappings":"AA+BA,MAAM,UAAU,UAAU,CAAI,KAAc;IAC1C,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,KAAY,CAAC;IACtB,CAAC;IACD,IACE,KAAK,KAAK,IAAI;QACd,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,CAAC,OAAO,CAAE,KAA4B,CAAC,IAAI,CAAC,EACjD,CAAC;QACD,OAAQ,KAAuB,CAAC,IAAI,CAAC;IACvC,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAeD,MAAM,UAAU,UAAU,CAAI,KAAc;IAC1C,IACE,KAAK,KAAK,IAAI;QACd,OAAO,KAAK,KAAK,QAAQ;QACzB,MAAM,IAAK,KAAiC;QAC5C,CAAC,CAAC,YAAY,IAAK,KAAiC,CAAC,EACrD,CAAC;QACD,OAAQ,KAAqB,CAAC,IAAI,CAAC;IACrC,CAAC;IACD,OAAO,KAAU,CAAC;AACpB,CAAC"}

package/src/lib/biome-host/response-envelope.ts

@@ -1,69 +0,0 @@
-/**
- * Frontend mirror of the backend `ResponseEnvelopeInterceptor`.
- *
- * Every 2xx body the platform returns is wrapped as `{ data: T }`, or
- * `{ data: T[], pagination }` for a paginated list (single source of truth:
- * `@xemahq/platform-common`'s `ResponseEnvelopeInterceptor`). Orval's
- * `custom-fetch` mutators usually peel that envelope at the HTTP boundary, but
- * spec drift (a controller typed `T[]` that emits `{ data }`), public clients
- * that DON'T peel, and transient partial responses leave a `.data`-wrapped or
- * mis-shaped value where biome code expects a bare value/array — and a raw
- * `.map` on it white-screens the route.
- *
- * These are the ONE shared, pure unwrap helpers — no host context, no fetch.
- * Biomes (and the host shell's own `unwrap-list.ts`) should adopt these instead
- * of re-implementing the guard. This is the shared helper only; adopters are
- * migrated incrementally, not in a blanket rewrite.
- */
-
-/**
- * Resilient list unwrap for DISPLAY surfaces — normalises a React-Query `.data`
- * to an array so the page renders its empty/error state instead of crashing:
- *
- *   - already an array        → returned as-is
- *   - `{ data: T[] }` envelope → `value.data`
- *   - anything else            → `[]`
- *
- * Deliberately NON-throwing: the query's own `isError`/`isLoading` flags drive
- * the visible error/empty UI; this only guards the render path. For
- * mutation/single-resource flows where an unexpected shape is a real bug, use
- * {@link unwrapData} (fail-fast) instead.
- */
-export function unwrapList<T>(value: unknown): T[] {
-  if (Array.isArray(value)) {
-    return value as T[];
-  }
-  if (
-    value !== null &&
-    typeof value === 'object' &&
-    Array.isArray((value as { data?: unknown }).data)
-  ) {
-    return (value as { data: T[] }).data;
-  }
-  return [];
-}
-
-/**
- * Fail-fast single-resource unwrap. Returns `value.data` when the value is a
- * `{ data }` envelope; returns the value unchanged when it is already the
- * unwrapped resource (an Orval client that peeled the envelope at the boundary).
- *
- * Use this on mutation / single-resource flows where the response SHOULD be a
- * concrete object — unlike {@link unwrapList}, it does not silently coerce, so
- * a genuinely-unexpected shape surfaces as the value rather than being masked.
- *
- * A paginated envelope (`{ data, pagination }`) is returned INTACT — callers
- * that need both fields read them off the returned object; peeling only `data`
- * would drop the pagination cursor.
- */
-export function unwrapData<T>(value: unknown): T {
-  if (
-    value !== null &&
-    typeof value === 'object' &&
-    'data' in (value as Record<string, unknown>) &&
-    !('pagination' in (value as Record<string, unknown>))
-  ) {
-    return (value as { data: T }).data;
-  }
-  return value as T;
-}