@xemahq/ui-kernel 0.9.0 → 0.9.1

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

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,42 @@
+/**
+ * `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 {
+  createContext,
+  useContext,
+  type ReactElement,
+  type ReactNode,
+} from 'react';
+
+import type { VistaTab } from './vista-model';
+
+/** Open (or replace) a tab and focus it. Mirrors `VistaTabsController.open`. */
+export type VistaOpenFn = (surface: VistaTab) => string;
+
+const VistaOpenContext = createContext<VistaOpenFn | null>(null);
+
+export function VistaOpenProvider({
+  open,
+  children,
+}: Readonly<{ open: VistaOpenFn; children: ReactNode }>): ReactElement {
+  return (
+    <VistaOpenContext.Provider value={open}>
+      {children}
+    </VistaOpenContext.Provider>
+  );
+}
+
+/** The panel's `open`, or `null` when no panel is mounted above. */
+export function useVistaOpen(): VistaOpenFn | null {
+  return useContext(VistaOpenContext);
+}