@xemahq/ui-kernel 0.11.0 → 0.11.2

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

@@ -1,132 +0,0 @@
-/**
- * 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-context';
-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 {
-    const serialized: unknown = JSON.stringify(data, null, 2);
-    text = typeof serialized === 'string' ? serialized : 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

@@ -1,196 +0,0 @@
-/**
- * `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

@@ -1,16 +0,0 @@
-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

@@ -1,35 +0,0 @@
-/**
- * `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

@@ -1,14 +0,0 @@
-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

@@ -1,141 +0,0 @@
-/**
- * `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

@@ -1,20 +0,0 @@
-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

@@ -1,48 +0,0 @@
-/**
- * `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>
-  );
-}