@xemahq/ui-kernel 0.9.0 → 0.9.2

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

@@ -0,0 +1,188 @@
+/**
+ * `useVistaTabs` — the ONE tab-state machine behind every Vista panel.
+ *
+ * Lifted from `SessionWorkspaceThin`'s (already host-agnostic) chrome and
+ * generalised to {@link VistaSurface} envelopes, so the thin session workspace,
+ * the Design-System-Builder preview, and the agent-driven `vista_*` tools all
+ * drive the SAME state. Behaviours carried over verbatim:
+ *
+ *   • PINNED FIRST TAB. A surface with `pinned: true` sorts first and can never
+ *     be closed (`close()` returns `false`).
+ *   • HOST TABS vs. OPENED TABS. `hostTabs` are host-driven (a live workspace
+ *     scan, an artifact list) and reconcile every render; `open()` tabs are
+ *     user/agent-driven and persist until closed.
+ *   • CLOSED-HOST-TAB MEMORY. Closing a host tab records its id so the next
+ *     scan does NOT resurrect a tab the user dismissed. The record is pruned
+ *     when the host stops offering that id, so a genuinely new occurrence shows
+ *     again — no stale suppression.
+ *   • ACTIVE RECONCILIATION. If the active tab disappears, the first remaining
+ *     tab becomes active (never a dangling id, never a blank pane).
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+
+import type { VistaTab } from './vista-model';
+
+/** A partial update applied to an open tab (`vista_update`). */
+export interface VistaSurfacePatch {
+  readonly kind?: string;
+  readonly version?: number;
+  readonly title?: string;
+  readonly payload?: unknown;
+  readonly pinned?: boolean;
+}
+
+/** A tab summary — what `vista_list()` returns to the agent. */
+export interface VistaTabSummary {
+  readonly tabId: string;
+  readonly kind: string;
+  readonly title: string;
+  readonly pinned: boolean;
+  readonly active: boolean;
+}
+
+/** The tab-state surface a panel (and the `vista_*` dispatcher) drives. */
+export interface VistaTabsController {
+  /** Host tabs (reconciled) followed by opened tabs, pinned ones first. */
+  readonly tabs: readonly VistaTab[];
+  readonly activeTabId: string | null;
+  /** Activate a tab. No-op for an id that is not open. */
+  activate(tabId: string): void;
+  /** Open (or REPLACE, when `tabId` is already open) a surface, and focus it. */
+  open(surface: VistaTab): string;
+  /** Patch an open tab. `false` when the tab is not open. */
+  update(tabId: string, patch: VistaSurfacePatch): boolean;
+  /** Close a tab. `false` when it is not open or is pinned. */
+  close(tabId: string): boolean;
+  /** Snapshot of every open tab. */
+  list(): readonly VistaTabSummary[];
+}
+
+export interface UseVistaTabsOptions {
+  /**
+   * Host-driven tabs, reconciled live (a workspace scan, an artifact set). A
+   * pinned entry here is the panel's permanent first tab.
+   */
+  readonly hostTabs?: readonly VistaTab[];
+  /** Tab active on first render. Falls back to the first tab. */
+  readonly initialActiveTabId?: string;
+}
+
+const NO_HOST_TABS: readonly VistaTab[] = [];
+
+/** Pinned tabs first, otherwise insertion order (stable). */
+function sortPinnedFirst(tabs: readonly VistaTab[]): VistaTab[] {
+  const pinned = tabs.filter((t) => t.pinned === true);
+  const rest = tabs.filter((t) => t.pinned !== true);
+  return [...pinned, ...rest];
+}
+
+export function useVistaTabs({
+  hostTabs = NO_HOST_TABS,
+  initialActiveTabId,
+}: UseVistaTabsOptions = {}): VistaTabsController {
+  const [openedTabs, setOpenedTabs] = useState<readonly VistaTab[]>([]);
+  const [closedHostTabIds, setClosedHostTabIds] = useState<readonly string[]>(
+    [],
+  );
+  const [activeTabId, setActiveTabId] = useState<string | null>(
+    initialActiveTabId ?? null,
+  );
+
+  const tabs = useMemo(
+    () =>
+      sortPinnedFirst([
+        ...hostTabs.filter((t) => !closedHostTabIds.includes(t.tabId)),
+        ...openedTabs,
+      ]),
+    [hostTabs, closedHostTabIds, openedTabs],
+  );
+
+  // Prune `closedHostTabIds` entries the host no longer offers, so if the same
+  // id reappears later it shows again (no stale suppression).
+  useEffect(() => {
+    setClosedHostTabIds((prev) => {
+      const next = prev.filter((id) => hostTabs.some((t) => t.tabId === id));
+      return next.length === prev.length ? prev : next;
+    });
+  }, [hostTabs]);
+
+  // Keep the active tab valid as host/opened tabs change. If it disappears (or
+  // was never set), fall back to the first available tab.
+  useEffect(() => {
+    setActiveTabId((current) => {
+      if (current !== null && tabs.some((t) => t.tabId === current)) {
+        return current;
+      }
+      return tabs[0]?.tabId ?? null;
+    });
+  }, [tabs]);
+
+  // A stable snapshot for `list()` — the controller identity must not change on
+  // every render, so the callbacks read through a ref instead of closing over
+  // `tabs`.
+  const tabsRef = useRef(tabs);
+  tabsRef.current = tabs;
+  const openedTabsRef = useRef(openedTabs);
+  openedTabsRef.current = openedTabs;
+  const activeRef = useRef(activeTabId);
+  activeRef.current = activeTabId;
+
+  const activate = useCallback((tabId: string): void => {
+    if (!tabsRef.current.some((t) => t.tabId === tabId)) return;
+    setActiveTabId(tabId);
+  }, []);
+
+  const open = useCallback((surface: VistaTab): string => {
+    setOpenedTabs((prev) => {
+      const index = prev.findIndex((t) => t.tabId === surface.tabId);
+      if (index === -1) return [...prev, surface];
+      // Re-opening the same tabId REPLACES it (the `VistaSurface` contract).
+      const next = [...prev];
+      next[index] = surface;
+      return next;
+    });
+    // Re-opening a host tab the user had dismissed un-dismisses it.
+    setClosedHostTabIds((prev) => prev.filter((id) => id !== surface.tabId));
+    setActiveTabId(surface.tabId);
+    return surface.tabId;
+  }, []);
+
+  const update = useCallback(
+    (tabId: string, patch: VistaSurfacePatch): boolean => {
+      // A HOST tab is owned by the host's data flow — a patch here would be
+      // overwritten on the next reconcile, so it is REFUSED rather than
+      // silently lost. Ownership is decided synchronously from the ref, not
+      // inside the state updater (which React may invoke twice).
+      if (!openedTabsRef.current.some((t) => t.tabId === tabId)) return false;
+      setOpenedTabs((prev) =>
+        prev.map((tab) => (tab.tabId === tabId ? { ...tab, ...patch } : tab)),
+      );
+      return true;
+    },
+    [],
+  );
+
+  const close = useCallback((tabId: string): boolean => {
+    const tab = tabsRef.current.find((t) => t.tabId === tabId);
+    if (tab === undefined || tab.pinned === true) return false;
+    setOpenedTabs((prev) => prev.filter((t) => t.tabId !== tabId));
+    setClosedHostTabIds((prev) =>
+      prev.includes(tabId) ? prev : [...prev, tabId],
+    );
+    return true;
+  }, []);
+
+  const list = useCallback(
+    (): readonly VistaTabSummary[] =>
+      tabsRef.current.map((tab) => ({
+        tabId: tab.tabId,
+        kind: tab.kind,
+        title: tab.title,
+        pinned: tab.pinned === true,
+        active: tab.tabId === activeRef.current,
+      })),
+    [],
+  );
+
+  return { tabs, activeTabId, activate, open, update, close, list };
+}

package/src/vista/vista-code-renderer-context.ts

@@ -0,0 +1,16 @@
+import { createContext, useContext } from 'react';
+
+import type { ReactNode } from 'react';
+
+export type VistaCodeRenderer = (args: {
+  readonly content: string;
+  readonly path?: string;
+  readonly language?: string;
+}) => ReactNode;
+
+export const VistaCodeRendererContext =
+  createContext<VistaCodeRenderer | null>(null);
+
+export function useVistaCodeRenderer(): VistaCodeRenderer | null {
+  return useContext(VistaCodeRendererContext);
+}

package/src/vista/vista-code-renderer.tsx

@@ -0,0 +1,34 @@
+/**
+ * `VistaCodeRenderer` — the seam through which a host swaps in a real code
+ * editor for the `code` surface.
+ *
+ * The kernel ships NO syntax-highlighting engine (a Monaco/Prism dependency in
+ * a host-framework-agnostic package would be imposed on every consumer), so
+ * {@link CodeSurface}'s built-in body is a mono `<pre>`. That is a COMPLETE
+ * rendering of a file's bytes, not a degraded one — but a host that already
+ * ships an editor (host-web ships Monaco) provides it here and every `code`
+ * tab picks it up.
+ *
+ * This is an extension point, not a fallback chain: with no provider the mono
+ * pane is the intended rendering, and with a provider the host's renderer is
+ * the intended rendering. Neither is an error path.
+ */
+import {
+  type ReactElement,
+  type ReactNode,
+} from 'react';
+import {
+  VistaCodeRendererContext,
+  type VistaCodeRenderer,
+} from './vista-code-renderer-context';
+
+export function VistaCodeRendererProvider({
+  renderer,
+  children,
+}: Readonly<{ renderer: VistaCodeRenderer; children: ReactNode }>): ReactElement {
+  return (
+    <VistaCodeRendererContext.Provider value={renderer}>
+      {children}
+    </VistaCodeRendererContext.Provider>
+  );
+}

package/src/vista/vista-file-context.ts

@@ -0,0 +1,14 @@
+import { createContext, useContext } from 'react';
+
+export interface VistaFileSource {
+  readText(path: string): Promise<string>;
+  resolveUrl(path: string): Promise<string>;
+  readonly revision?: string | number;
+}
+
+export const VistaFileSourceContext =
+  createContext<VistaFileSource | null>(null);
+
+export function useVistaFileSource(): VistaFileSource | null {
+  return useContext(VistaFileSourceContext);
+}

package/src/vista/vista-file-source.tsx

@@ -0,0 +1,140 @@
+/**
+ * `VistaFileSource` — the ONE seam through which a file-backed surface reads
+ * bytes.
+ *
+ * `@xemahq/ui-kernel` is host-framework-agnostic and carries no API client, so
+ * a `code`/`markdown`/`pdf`/`image` surface addressed by a workspace `path`
+ * cannot fetch on its own. The host provides a source (bound to its own
+ * session-file / artifact endpoints) exactly once, at the panel boundary; every
+ * first-party renderer reads through it.
+ *
+ * There is deliberately NO default: a path-backed surface mounted without a
+ * provider renders a visible error, never a blank pane and never a silent
+ * "content unavailable".
+ */
+import {
+  useEffect,
+  useState,
+  type ReactElement,
+  type ReactNode,
+} from 'react';
+import {
+  VistaFileSourceContext,
+  useVistaFileSource,
+  type VistaFileSource,
+} from './vista-file-context';
+
+export function VistaFileSourceProvider({
+  source,
+  children,
+}: Readonly<{ source: VistaFileSource; children: ReactNode }>): ReactElement {
+  return (
+    <VistaFileSourceContext.Provider value={source}>
+      {children}
+    </VistaFileSourceContext.Provider>
+  );
+}
+
+/** Async load state for a path-backed surface. */
+type LoadState =
+  | { readonly status: 'loading' }
+  | { readonly status: 'ready'; readonly value: string }
+  | { readonly status: 'error'; readonly message: string };
+
+const LOADING: LoadState = { status: 'loading' };
+
+function useResolvedFile(
+  path: string,
+  mode: 'text' | 'url',
+): LoadState {
+  const source = useVistaFileSource();
+  const revision = source?.revision;
+  const [state, setState] = useState<LoadState>(LOADING);
+
+  useEffect(() => {
+    if (source === null) {
+      setState({
+        status: 'error',
+        message:
+          'No file source is mounted for this panel, so path-backed content cannot be read.',
+      });
+      return;
+    }
+    let cancelled = false;
+    setState(LOADING);
+    const promise =
+      mode === 'text' ? source.readText(path) : source.resolveUrl(path);
+    promise.then(
+      (value) => {
+        if (!cancelled) setState({ status: 'ready', value });
+      },
+      (error: unknown) => {
+        if (cancelled) return;
+        setState({
+          status: 'error',
+          message: error instanceof Error ? error.message : String(error),
+        });
+      },
+    );
+    return () => {
+      cancelled = true;
+    };
+  }, [source, path, mode, revision]);
+
+  return state;
+}
+
+function LoadNotice({
+  state,
+}: Readonly<{ state: Exclude<LoadState, { status: 'ready' }> }>): ReactElement {
+  return (
+    <div
+      role={state.status === 'error' ? 'alert' : undefined}
+      style={{
+        display: 'flex',
+        height: '100%',
+        alignItems: 'center',
+        justifyContent: 'center',
+        padding: 24,
+        fontSize: 12.5,
+        textAlign: 'center',
+        color:
+          state.status === 'error'
+            ? 'hsl(var(--destructive))'
+            : 'hsl(var(--ink-4))',
+      }}
+    >
+      {state.status === 'loading' ? 'Loading…' : state.message}
+    </div>
+  );
+}
+
+/**
+ * Render a path-backed surface body from its TEXT content. The load/error
+ * states are explicit and visible — a failed read never renders as empty
+ * content.
+ */
+export function VistaFileText({
+  path,
+  render,
+}: Readonly<{
+  path: string;
+  render: (content: string) => ReactNode;
+}>): ReactElement {
+  const state = useResolvedFile(path, 'text');
+  if (state.status !== 'ready') return <LoadNotice state={state} />;
+  return <>{render(state.value)}</>;
+}
+
+/** Render a path-backed surface body from a resolved fetchable URL. */
+export function VistaFileUrl({
+  path,
+  render,
+}: Readonly<{
+  path: string;
+  render: (url: string) => ReactNode;
+}>): ReactElement {
+  const state = useResolvedFile(path, 'url');
+  if (state.status !== 'ready') return <LoadNotice state={state} />;
+  return <>{render(state.value)}</>;
+}

package/src/vista/vista-form-context.ts

@@ -0,0 +1,20 @@
+import { createContext, useContext } from 'react';
+
+export interface VistaFormOutcome {
+  readonly submitted: true;
+  readonly ref: string;
+  readonly connectionId: string | null;
+}
+
+export interface VistaFormHost {
+  readonly elicitationApiBaseUrl: string;
+  getAccessToken(): Promise<string>;
+  onOutcome(outcome: VistaFormOutcome): void;
+}
+
+export const VistaFormHostContext =
+  createContext<VistaFormHost | null>(null);
+
+export function useVistaFormHost(): VistaFormHost | null {
+  return useContext(VistaFormHostContext);
+}

package/src/vista/vista-form-host.tsx

@@ -0,0 +1,53 @@
+/**
+ * `VistaFormHost` — the ONE seam through which a `SurfaceKind.Form` surface
+ * gets the SUBJECT's bearer token and reports completion.
+ *
+ * ── Why this exists, and why the shapes are what they are ───────────────────
+ * The `form` surface is the secure-elicitation surface: an agent asks for a
+ * credential it must never see. The value therefore travels
+ * BROWSER → OWNING SERVICE, signed with the user's own JWT, and the agent
+ * learns only that the elicitation settled.
+ *
+ * That is enforced STRUCTURALLY, not by convention:
+ *
+ *   1. {@link VistaFormOutcome} is the ONLY thing the surface can report. It is
+ *      a closed interface with three scalar members and NO `unknown`, no index
+ *      signature, and no payload/values member. There is no shape a field value
+ *      could be assigned to. Widening it is the one change that would break the
+ *      guarantee — do not add a member that can hold arbitrary data.
+ *   2. `getAccessToken` returns the SUBJECT's token. The host binds it to the
+ *      logged-in user's session; it is never a service token and never the
+ *      agent's token, so the service authorizes the human, not the model.
+ *   3. `elicitationApiBaseUrl` is supplied by trusted host configuration, never
+ *      by the agent-controlled payload. The kernel validates its scheme and
+ *      canonical authority/path before deriving the status/submit endpoints.
+ *
+ * There is deliberately NO default host: a `form` surface mounted without a
+ * provider renders a visible refusal and cannot submit. Fail-closed — a form
+ * that silently posts nowhere would be worse than one that says it cannot.
+ */
+import {
+  type ReactElement,
+  type ReactNode,
+} from 'react';
+import {
+  VistaFormHostContext,
+  type VistaFormHost,
+} from './vista-form-context';
+
+/**
+ * Everything a settled elicitation reports. Closed, scalar-only, and
+ * value-identical to the service's `{ submitted, ref, connectionId }` — the
+ * persistence layer behind it has no column able to hold a field value, and
+ * neither does this type.
+ */
+export function VistaFormHostProvider({
+  host,
+  children,
+}: Readonly<{ host: VistaFormHost; children: ReactNode }>): ReactElement {
+  return (
+    <VistaFormHostContext.Provider value={host}>
+      {children}
+    </VistaFormHostContext.Provider>
+  );
+}

package/src/vista/vista-model.ts

@@ -0,0 +1,130 @@
+/**
+ * The Vista tab model — ONE tab vocabulary for every preview plane.
+ *
+ * Before this module the frontend carried THREE overlapping tab models with no
+ * shared code:
+ *   • `WorkspaceTabKind` (`files|code|md|diff|tests|url`) in the thin session
+ *     workspace;
+ *   • `PreviewTabKind` (`files|html|markdown|pdf|image|plain`) buried inside the
+ *     Design-System-Builder page;
+ *   • the App-Forge preview.
+ * All three collapse onto the kernel {@link SurfaceKind} (Canopy §8.5). A tab is
+ * just a {@link VistaSurface} envelope; the Vista registry resolves its `kind`
+ * to a renderer.
+ *
+ * Collapse notes (deliberate, documented decisions):
+ *   • `md` → {@link SurfaceKind.Markdown}.
+ *   • `plain` → {@link SurfaceKind.Code}. `Code` is "a source file", and the
+ *     code renderer is a mono pane; a separate "plain text" kind would be the
+ *     same renderer under a second name.
+ *   • `tests` had no kernel equivalent and was never a *render* kind — a test
+ *     report is a biome-owned surface, so it becomes a biome-contributed
+ *     `<biomeId>:tests` kind rather than a first-party one. Nothing in the tree
+ *     rendered it (the thin workspace's `renderTests` slot was never supplied).
+ */
+import { SurfaceKind, type VistaSurface } from '@xemahq/kernel-contracts/surface';
+
+/**
+ * Id of the pinned, UI-owned file-browser tab. It is owned by the panel, never
+ * declared by an agent, and never closeable.
+ */
+export const VISTA_FILES_TAB_ID = 'files';
+
+/** Current payload schema version of every first-party surface kind. */
+export const VISTA_SURFACE_VERSION = 1;
+
+/**
+ * A Vista tab. Structurally a {@link VistaSurface} — the tab model and the
+ * agent-facing envelope are the SAME shape on purpose, so `vista_open` needs no
+ * translation layer.
+ */
+export type VistaTab = VistaSurface;
+
+/** Extension → first-party surface kind. Closed, deterministic mapping. */
+const EXTENSION_KIND: Readonly<Record<string, SurfaceKind>> = {
+  html: SurfaceKind.Html,
+  htm: SurfaceKind.Html,
+  md: SurfaceKind.Markdown,
+  mdx: SurfaceKind.Markdown,
+  markdown: SurfaceKind.Markdown,
+  pdf: SurfaceKind.Pdf,
+  png: SurfaceKind.Image,
+  jpg: SurfaceKind.Image,
+  jpeg: SurfaceKind.Image,
+  gif: SurfaceKind.Image,
+  webp: SurfaceKind.Image,
+  svg: SurfaceKind.Image,
+  avif: SurfaceKind.Image,
+  mp4: SurfaceKind.Media,
+  webm: SurfaceKind.Media,
+  mov: SurfaceKind.Media,
+  mp3: SurfaceKind.Media,
+  wav: SurfaceKind.Media,
+  ogg: SurfaceKind.Media,
+  m4a: SurfaceKind.Media,
+  json: SurfaceKind.Json,
+  diff: SurfaceKind.Diff,
+  patch: SurfaceKind.Diff,
+};
+
+/**
+ * Resolve the surface kind a file path renders as. Deterministic and total:
+ * anything unrecognised is {@link SurfaceKind.Code} (a mono text pane), which is
+ * always a correct — if plain — rendering of a file's bytes.
+ */
+export function surfaceKindForPath(path: string): SurfaceKind {
+  const dot = path.lastIndexOf('.');
+  if (dot === -1) return SurfaceKind.Code;
+  const ext = path.slice(dot + 1).toLowerCase();
+  return EXTENSION_KIND[ext] ?? SurfaceKind.Code;
+}
+
+/** The `content-type` a media/blob surface reports for a path, when derivable. */
+const EXTENSION_CONTENT_TYPE: Readonly<Record<string, string>> = {
+  png: 'image/png',
+  jpg: 'image/jpeg',
+  jpeg: 'image/jpeg',
+  gif: 'image/gif',
+  webp: 'image/webp',
+  svg: 'image/svg+xml',
+  avif: 'image/avif',
+  pdf: 'application/pdf',
+  mp4: 'video/mp4',
+  webm: 'video/webm',
+  mov: 'video/quicktime',
+  mp3: 'audio/mpeg',
+  wav: 'audio/wav',
+  ogg: 'audio/ogg',
+  m4a: 'audio/mp4',
+};
+
+/** Content type for a path, or `null` when the extension is unknown. */
+export function contentTypeForPath(path: string): string | null {
+  const dot = path.lastIndexOf('.');
+  if (dot === -1) return null;
+  return EXTENSION_CONTENT_TYPE[path.slice(dot + 1).toLowerCase()] ?? null;
+}
+
+/** The last path segment — the default tab label for a file-backed surface. */
+export function labelForPath(path: string): string {
+  const segments = path.split('/');
+  return segments[segments.length - 1] || path;
+}
+
+/**
+ * Build a file-backed surface envelope for a path. One seam so every caller
+ * (the `.tabs.json` parser, the file browser, `vista_open`) derives kind + label
+ * + tab id identically.
+ */
+export function fileSurface(
+  path: string,
+  overrides?: Readonly<{ title?: string; kind?: SurfaceKind }>,
+): VistaTab {
+  return {
+    tabId: `file:${path}`,
+    kind: overrides?.kind ?? surfaceKindForPath(path),
+    version: VISTA_SURFACE_VERSION,
+    title: overrides?.title ?? labelForPath(path),
+    payload: { path },
+  };
+}

package/src/vista/vista-open-context.tsx

@@ -0,0 +1,32 @@
+/**
+ * `VistaOpenContext` — how a surface asks the panel to open ANOTHER surface.
+ *
+ * The registry's `render(payload)` is a pure function, so a renderer cannot
+ * receive an `onOpen` prop. The panel publishes its `open` through this context
+ * instead: the file browser opens a file tab, an object view opens a related
+ * object, and so on — all through the SAME `vista_open` semantics the agent
+ * uses, never a second code path.
+ *
+ * A surface mounted without a provider simply renders non-interactive rows
+ * (`useVistaOpen()` returns `null`) — an inert list, never a dead click that
+ * silently does nothing.
+ */
+import {
+  type ReactElement,
+  type ReactNode,
+} from 'react';
+import {
+  VistaOpenContext,
+  type VistaOpenFn,
+} from './vista-open-state';
+
+export function VistaOpenProvider({
+  open,
+  children,
+}: Readonly<{ open: VistaOpenFn; children: ReactNode }>): ReactElement {
+  return (
+    <VistaOpenContext.Provider value={open}>
+      {children}
+    </VistaOpenContext.Provider>
+  );
+}

package/src/vista/vista-open-state.ts

@@ -0,0 +1,11 @@
+import { createContext, useContext } from 'react';
+
+import type { VistaTab } from './vista-model';
+
+export type VistaOpenFn = (surface: VistaTab) => string;
+
+export const VistaOpenContext = createContext<VistaOpenFn | null>(null);
+
+export function useVistaOpen(): VistaOpenFn | null {
+  return useContext(VistaOpenContext);
+}