@xemahq/ui-kernel 0.8.0 → 0.9.1

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

@@ -0,0 +1,119 @@
+/**
+ * The text-bodied first-party surfaces: `code`, `json`, `diff`.
+ *
+ * Each accepts an inline `content` or a workspace `path` resolved through the
+ * host {@link VistaFileSource}, so a panel can open a file lazily without the
+ * kernel knowing anything about the host's file endpoints.
+ *
+ * `code` is a mono pane — it is also where a plain-text file lands (the legacy
+ * `plain` tab kind was collapsed into it; one kind, one renderer, no alias).
+ */
+
+import { useVistaCodeRenderer } from '../vista-code-renderer';
+import { VistaFileText } from '../vista-file-source';
+
+import type { VistaTextPayload } from '../vista-payloads';
+import type { ReactElement, ReactNode } from 'react';
+
+const PANE_STYLE = {
+  height: '100%',
+  width: '100%',
+  margin: 0,
+  overflow: 'auto',
+  padding: '14px 16px',
+  fontSize: 12,
+  lineHeight: 1.6,
+  color: 'hsl(var(--ink-2))',
+  whiteSpace: 'pre-wrap' as const,
+};
+
+/** Render inline content, or fetch the path first — one seam for all three. */
+function TextBody({
+  payload,
+  render,
+}: Readonly<{
+  payload: VistaTextPayload;
+  render: (content: string) => ReactNode;
+}>): ReactElement {
+  if (payload.content !== undefined) return <>{render(payload.content)}</>;
+  // `validateTextPayload` guarantees exactly one of content/path.
+  return <VistaFileText path={payload.path as string} render={render} />;
+}
+
+export function CodeSurface(payload: VistaTextPayload): ReactElement {
+  // A host that ships a code editor provides it through
+  // `VistaCodeRendererProvider`; with none the mono pane below IS the intended
+  // rendering (see `vista-code-renderer.tsx`).
+  const hostRenderer = useVistaCodeRenderer();
+  return (
+    <TextBody
+      payload={payload}
+      render={(content) =>
+        hostRenderer === null ? (
+          <pre className="mono" style={PANE_STYLE}>
+            {content}
+          </pre>
+        ) : (
+          hostRenderer({
+            content,
+            ...(payload.path === undefined ? {} : { path: payload.path }),
+            ...(payload.language === undefined
+              ? {}
+              : { language: payload.language }),
+          })
+        )
+      }
+    />
+  );
+}
+
+/**
+ * `json` — pretty-printed and inspectable. An inline payload carries parsed
+ * `data`; a path-backed one carries the raw text, which is re-serialised when it
+ * parses and shown VERBATIM when it does not (a malformed JSON file is shown as
+ * it is, never swallowed).
+ */
+export function JsonSurface({ data }: Readonly<{ data: unknown }>): ReactElement {
+  let text: string;
+  try {
+    text = JSON.stringify(data, null, 2) ?? String(data);
+  } catch {
+    text = String(data);
+  }
+  return (
+    <pre className="mono" style={PANE_STYLE}>
+      {text}
+    </pre>
+  );
+}
+
+/** Colour a unified-diff line by its leading marker. */
+function diffLineColor(line: string): string | undefined {
+  if (line.startsWith('+++') || line.startsWith('---')) return 'hsl(var(--ink-3))';
+  if (line.startsWith('@@')) return 'hsl(var(--info))';
+  if (line.startsWith('+')) return 'hsl(var(--success))';
+  if (line.startsWith('-')) return 'hsl(var(--destructive, var(--danger)))';
+  return undefined;
+}
+
+export function DiffSurface(payload: VistaTextPayload): ReactElement {
+  return (
+    <TextBody
+      payload={payload}
+      render={(content) => (
+        <pre className="mono" style={PANE_STYLE}>
+          {content.split('\n').map((line, index) => (
+            <div
+              // A diff has no stable per-line identity other than its position.
+               
+              key={index}
+              style={{ color: diffLineColor(line) }}
+            >
+              {line === '' ? ' ' : line}
+            </div>
+          ))}
+        </pre>
+      )}
+    />
+  );
+}

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.tsx

@@ -0,0 +1,46 @@
+/**
+ * `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 {
+  createContext,
+  useContext,
+  type ReactElement,
+  type ReactNode,
+} from 'react';
+
+/** Draw a code body. `path` is present for a file-backed surface. */
+export type VistaCodeRenderer = (args: {
+  readonly content: string;
+  readonly path?: string;
+  readonly language?: string;
+}) => ReactNode;
+
+const VistaCodeRendererContext = createContext<VistaCodeRenderer | null>(null);
+
+export function VistaCodeRendererProvider({
+  renderer,
+  children,
+}: Readonly<{ renderer: VistaCodeRenderer; children: ReactNode }>): ReactElement {
+  return (
+    <VistaCodeRendererContext.Provider value={renderer}>
+      {children}
+    </VistaCodeRendererContext.Provider>
+  );
+}
+
+/** The host's code renderer, or `null` for the built-in mono pane. */
+export function useVistaCodeRenderer(): VistaCodeRenderer | null {
+  return useContext(VistaCodeRendererContext);
+}

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

@@ -0,0 +1,163 @@
+/**
+ * `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 {
+  createContext,
+  useContext,
+  useEffect,
+  useState,
+  type ReactElement,
+  type ReactNode,
+} from 'react';
+
+/** Host-supplied byte access for path-backed surfaces. */
+export interface VistaFileSource {
+  /** Read a workspace-relative path as text. Rejects on failure. */
+  readText(path: string): Promise<string>;
+  /**
+   * Resolve a workspace-relative path to a fetchable URL (`blob:`, `data:`, or
+   * a durable `https:` URL) for binary surfaces. Rejects on failure.
+   *
+   * The host owns the lifetime of anything it creates (e.g. revoking an object
+   * URL); the surface only reads.
+   */
+  resolveUrl(path: string): Promise<string>;
+  /**
+   * Opaque revision token. Change it to make every mounted path-backed surface
+   * re-read (the host bumps it on a workspace file-change event).
+   */
+  readonly revision?: string | number;
+}
+
+const VistaFileSourceContext = createContext<VistaFileSource | null>(null);
+
+export function VistaFileSourceProvider({
+  source,
+  children,
+}: Readonly<{ source: VistaFileSource; children: ReactNode }>): ReactElement {
+  return (
+    <VistaFileSourceContext.Provider value={source}>
+      {children}
+    </VistaFileSourceContext.Provider>
+  );
+}
+
+/** The active file source, or `null` when no provider is mounted. */
+export function useVistaFileSource(): VistaFileSource | null {
+  return useContext(VistaFileSourceContext);
+}
+
+/** 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-host.tsx

@@ -0,0 +1,78 @@
+/**
+ * `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. The surface's transport posts to an ABSOLUTE service URL taken from the
+ *      validated payload (see `validateFormPayload`, which rejects a relative
+ *      URL). There is no host-relative path, so it cannot be pointed at the
+ *      app's own BFF/chat transport.
+ *
+ * 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 { createContext, useContext, type ReactElement, type ReactNode } from 'react';
+
+/**
+ * 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 interface VistaFormOutcome {
+  /** Always `true`: an unsettled elicitation produces no outcome at all. */
+  readonly submitted: true;
+  /** The elicitation reference the agent polls. Opaque, non-secret. */
+  readonly ref: string;
+  /** The connection the submission provisioned, when the service reported one. */
+  readonly connectionId: string | null;
+}
+
+/** Host-supplied capabilities for the `form` surface. */
+export interface VistaFormHost {
+  /**
+   * The SUBJECT's own access token. Called once per request so a refreshed
+   * token is picked up without remounting the surface.
+   */
+  getAccessToken(): Promise<string>;
+  /**
+   * Called exactly once when the elicitation settles. The host relays this to
+   * whatever needs to know (cache invalidation, the agent session). By type it
+   * can carry nothing but the outcome.
+   */
+  onOutcome(outcome: VistaFormOutcome): void;
+}
+
+const VistaFormHostContext = createContext<VistaFormHost | null>(null);
+
+export function VistaFormHostProvider({
+  host,
+  children,
+}: Readonly<{ host: VistaFormHost; children: ReactNode }>): ReactElement {
+  return (
+    <VistaFormHostContext.Provider value={host}>
+      {children}
+    </VistaFormHostContext.Provider>
+  );
+}
+
+/** The active form host, or `null` when no provider is mounted. */
+export function useVistaFormHost(): VistaFormHost | null {
+  return useContext(VistaFormHostContext);
+}