@opengeni/react 0.11.0 → 0.13.0

package/src/index.ts

@@ -12,31 +12,71 @@ export type { ClientOverride, OpenGeniContextValue, OpenGeniProviderProps } from
 export { useSession, isTitleEvent } from "./hooks/use-session";
 export type { UseSessionOptions, UseSessionResult } from "./hooks/use-session";
 export { useSessionEvents } from "./hooks/use-session-events";
-export type { SessionEventsConnectionState, UseSessionEventsOptions, UseSessionEventsResult } from "./hooks/use-session-events";
-export { useComposer, composeSendInput, shouldSubmitOnKey, FILE_ONLY_MESSAGE_TEXT } from "./hooks/use-composer";
-export type { ComposerMode, ComposerSendExtras, ComposerState, UseComposerOptions } from "./hooks/use-composer";
-export { useFileAttachments } from "./hooks/use-file-attachments";
-export type { FileAttachment, UseFileAttachmentsOptions, UseFileAttachmentsResult } from "./hooks/use-file-attachments";
+export type {
+  SessionEventsConnectionState,
+  UseSessionEventsOptions,
+  UseSessionEventsResult,
+} from "./hooks/use-session-events";
 export {
-  useTurnQueue,
-  isTurnQueueEvent,
-  queueFromTurns,
-  activeTurnFromTurns,
-  applyTurnEdit,
-  applyTurnReorder,
-  applyTurnRemoval,
-} from "./hooks/use-turn-queue";
+  useComposer,
+  composeSendInput,
+  shouldSubmitOnKey,
+  FILE_ONLY_MESSAGE_TEXT,
+} from "./hooks/use-composer";
+export type {
+  ComposerMode,
+  ComposerSendExtras,
+  ComposerState,
+  UseComposerOptions,
+} from "./hooks/use-composer";
+export { useFileAttachments } from "./hooks/use-file-attachments";
+export type {
+  FileAttachment,
+  UseFileAttachmentsOptions,
+  UseFileAttachmentsResult,
+} from "./hooks/use-file-attachments";
+export { useTurnQueue, isTurnQueueEvent } from "./hooks/use-turn-queue";
 export type { UseTurnQueueOptions, UseTurnQueueResult } from "./hooks/use-turn-queue";
 export { useGoal, isGoalEvent } from "./hooks/use-goal";
 export type { UseGoalOptions, UseGoalResult } from "./hooks/use-goal";
 export { useSessionControl } from "./hooks/use-session-control";
-export type { UseSessionControlOptions, UseSessionControlResult } from "./hooks/use-session-control";
+export type {
+  UseSessionControlOptions,
+  UseSessionControlResult,
+} from "./hooks/use-session-control";
 export { useScheduledTasks } from "./hooks/use-scheduled-tasks";
-export type { UseScheduledTasksOptions, UseScheduledTasksResult } from "./hooks/use-scheduled-tasks";
+export type {
+  UseScheduledTasksOptions,
+  UseScheduledTasksResult,
+} from "./hooks/use-scheduled-tasks";
 export { useWorkspaceSessions } from "./hooks/use-workspace-sessions";
-export type { UseWorkspaceSessionsOptions, UseWorkspaceSessionsResult } from "./hooks/use-workspace-sessions";
-export { useEnvironments } from "./hooks/use-environments";
-export type { UseEnvironmentsOptions, UseEnvironmentsResult } from "./hooks/use-environments";
+export type {
+  UseWorkspaceSessionsOptions,
+  UseWorkspaceSessionsResult,
+} from "./hooks/use-workspace-sessions";
+export { useSessionLineage, isLineageRefreshEvent } from "./hooks/use-session-lineage";
+export type {
+  UseSessionLineageOptions,
+  UseSessionLineageResult,
+} from "./hooks/use-session-lineage";
+export { useVariableSets, useEnvironments } from "./hooks/use-environments";
+export type {
+  UseVariableSetsOptions,
+  UseVariableSetsResult,
+  UseEnvironmentsOptions,
+  UseEnvironmentsResult,
+} from "./hooks/use-environments";
+export { useRigs, useRig, useRigVersions, useRigChanges } from "./hooks/use-rigs";
+export type {
+  UseRigsOptions,
+  UseRigsResult,
+  UseRigOptions,
+  UseRigResult,
+  UseRigVersionsOptions,
+  UseRigVersionsResult,
+  UseRigChangesOptions,
+  UseRigChangesResult,
+} from "./hooks/use-rigs";
 export { usePacks } from "./hooks/use-packs";
 export type { UsePacksOptions, UsePacksResult } from "./hooks/use-packs";
 export { useWorkspaces } from "./hooks/use-workspaces";
@@ -44,7 +84,10 @@ export type { UseWorkspacesOptions, UseWorkspacesResult } from "./hooks/use-work
 export { useBillingUsage } from "./hooks/use-billing-usage";
 export type { UseBillingUsageOptions, UseBillingUsageResult } from "./hooks/use-billing-usage";
 export { useAvailableModels } from "./hooks/use-available-models";
-export type { UseAvailableModelsOptions, UseAvailableModelsResult } from "./hooks/use-available-models";
+export type {
+  UseAvailableModelsOptions,
+  UseAvailableModelsResult,
+} from "./hooks/use-available-models";
 
 // Sandbox surfacing (Phase 5): capability negotiation + terminal/files/diff/desktop
 export { useSessionCapabilities } from "./hooks/use-session-capabilities";
@@ -84,6 +127,27 @@ export type {
 export { useSandboxGit } from "./hooks/use-sandbox-git";
 export type { UseSandboxGitOptions, UseSandboxGitResult } from "./hooks/use-sandbox-git";
 
+// Workbench v2 turn-end capture (the cold-paint data layer)
+export { useWorkspaceCapture } from "./hooks/use-workspace-capture";
+export type {
+  UseWorkspaceCaptureOptions,
+  UseWorkspaceCaptureResult,
+} from "./hooks/use-workspace-capture";
+export { useWorkspaceEdit } from "./hooks/use-workspace-edit";
+export type {
+  UseWorkspaceEditOptions,
+  UseWorkspaceEditResult,
+  WorkspaceEditConflict,
+  WorkspaceEditState,
+} from "./hooks/use-workspace-edit";
+export { deriveMachineChip, formatAsOf, useMachineChip } from "./hooks/use-machine-chip";
+export type {
+  DeriveMachineChipInput,
+  MachineChip,
+  MachineChipState,
+  UseMachineChipOptions,
+} from "./hooks/use-machine-chip";
+
 // Pending-approvals projection
 export { approvalsFromRequiresAction, projectPendingApprovals } from "./approvals";
 export type { PendingApproval } from "./approvals";
@@ -91,6 +155,7 @@ export type { PendingApproval } from "./approvals";
 // Timeline projection
 export {
   buildTimeline,
+  creditExhaustedFromEvents,
   extractSessionRef,
   groupTimeline,
   sessionStatusFromEvents,
@@ -99,6 +164,7 @@ export {
 export type {
   ActivityItem,
   AgentMessageItem,
+  AuthNeededItem,
   GoalItem,
   NoticeItem,
   ReasoningItem,
@@ -113,7 +179,12 @@ export type {
 } from "./timeline";
 
 // Tool-renderer registry + the per-tool renderers (the timeline's extension API)
-export { createDefaultToolRegistry, createToolRegistry, defaultToolRegistry, rawTypeOf } from "./timeline";
+export {
+  createDefaultToolRegistry,
+  createToolRegistry,
+  defaultToolRegistry,
+  rawTypeOf,
+} from "./timeline";
 export type {
   CreateToolRegistryOptions,
   ToolRegistry,
@@ -205,7 +276,11 @@ export type { MessageTimelineProps } from "./components/message-timeline";
 export { Markdown } from "./components/markdown";
 export type { MarkdownProps } from "./components/markdown";
 export { SessionStatus, StatusDot, SESSION_STATUS_META } from "./components/session-status";
-export type { SessionStatusProps, StatusDotProps, SessionStatusMeta } from "./components/session-status";
+export type {
+  SessionStatusProps,
+  StatusDotProps,
+  SessionStatusMeta,
+} from "./components/session-status";
 export { FleetTile, sessionDisplayTitle } from "./components/fleet-tile";
 export type { FleetTileProps } from "./components/fleet-tile";
 
@@ -229,12 +304,33 @@ export type { DesktopViewerProps } from "./components/desktop-viewer";
 export { WorkspaceDock } from "./components/workspace-dock";
 export type { WorkspaceDockProps, WorkspaceTab } from "./components/workspace-dock";
 
+// The embeddable dock "brain" (Workbench v2, M4): the whole session workspace as
+// one component + the tab-building hook + the pre-paint default-tab helper.
+export {
+  SandboxWorkspace,
+  useSandboxWorkspaceTabs,
+  initialWorkspaceTab,
+  WORKBENCH_TAB_CHANGES,
+  WORKBENCH_TAB_FILES,
+} from "./components/sandbox-workspace";
+export type {
+  SandboxWorkspaceProps,
+  UseSandboxWorkspaceTabsOptions,
+  UseSandboxWorkspaceTabsResult,
+  WorkspaceMachine,
+  WorkspaceNotification,
+} from "./components/sandbox-workspace";
+
 // Connected-machine UI moved to the "@opengeni/react/machines" subpath; re-exported
 // here for back-compat (#144).
 export * from "./machines";
 // Multi-account Codex (P1): accounts list + active-switch hook.
 export { useCodexAccounts, isCodexAccountEvent } from "./hooks/use-codex-accounts";
-export type { CodexAccountsClientLike, UseCodexAccountsOptions, UseCodexAccountsResult } from "./hooks/use-codex-accounts";
+export type {
+  CodexAccountsClientLike,
+  UseCodexAccountsOptions,
+  UseCodexAccountsResult,
+} from "./hooks/use-codex-accounts";
 
 // Sandbox helpers
 export { gitFileDiffToPatch } from "./lib/git-patch";
@@ -242,4 +338,13 @@ export { xtermThemeFromTokens } from "./lib/xterm-theme";
 
 // Utilities
 export { cn } from "./lib/cn";
-export { formatBytes, formatRelativeTime, humanizeFailureReason, stringifyPayload, truncate, tryParseJson } from "./lib/format";
+export {
+  CREDIT_EXHAUSTION_MESSAGE,
+  formatBytes,
+  formatRelativeTime,
+  humanizeFailureReason,
+  isCreditExhaustion,
+  stringifyPayload,
+  truncate,
+  tryParseJson,
+} from "./lib/format";

package/src/lib/format.ts

@@ -83,32 +83,70 @@ export function tryParseJson(text: string): unknown {
   }
 }
 
+/**
+ * The canonical credit-death sentence. Credit exhaustion is the one failure a
+ * user can fix themselves — the copy must say what happened (empty balance),
+ * what to do (add credits), and what is safe (nothing was lost). Crucially it
+ * must NOT say "send a message to revive": a revive turn burns credits the
+ * workspace no longer has.
+ */
+export const CREDIT_EXHAUSTION_MESSAGE =
+  "Out of OpenGeni credits — this workspace's balance is empty. Add credits to continue; the conversation is preserved.";
+
+/**
+ * Does this failure/completion payload (or raw error string) mean the
+ * workspace ran out of OpenGeni credits? Matches the engine's
+ * "insufficient OpenGeni credits" text (case-insensitive, substring — it
+ * arrives both bare and wrapped in "Activity task failed: …") and the
+ * budget-exhausted segment limit the engine stamps on a turn it ended early.
+ */
+export function isCreditExhaustion(
+  input: { error?: string | null; detail?: string | null; segmentLimit?: string | null } | string,
+): boolean {
+  if (typeof input === "string") {
+    return input.toLowerCase().includes("insufficient opengeni credits");
+  }
+  if (input.segmentLimit === "budget_exhausted") {
+    return true;
+  }
+  for (const text of [input.error, input.detail]) {
+    if (typeof text === "string" && text.toLowerCase().includes("insufficient opengeni credits")) {
+      return true;
+    }
+  }
+  return false;
+}
+
 /**
  * Humanize engine/provider failure text before it reaches the timeline or a
  * failure banner. Raw provider errors leak the wrong audience's instructions —
  * "Incorrect API key … find your API key at platform.openai.com" tells a
  * managed-deployment USER to fix credentials only an OPERATOR controls (and is
- * flatly wrong for Azure or subscription-backed engines). Auth and quota
- * failures collapse to one neutral, honest sentence; every other reason passes
- * through untouched. Raw payloads stay available in the debug surfaces.
+ * flatly wrong for Azure or subscription-backed engines). Auth, quota, and
+ * credit-exhaustion failures collapse to one neutral, honest sentence; every
+ * other reason passes through untouched. Raw payloads stay available in the
+ * debug surfaces.
  */
 export function humanizeFailureReason(reason: string | null): string | null {
   if (!reason) {
     return reason;
   }
+  if (isCreditExhaustion(reason)) {
+    return CREDIT_EXHAUSTION_MESSAGE;
+  }
   const normalized = reason.toLowerCase();
   const authFailure =
     normalized.includes("incorrect api key") ||
     normalized.includes("invalid api key") ||
     normalized.includes("invalid_api_key") ||
     normalized.includes("platform.openai.com/account/api-keys") ||
-    (normalized.includes("401") && (normalized.includes("api key") || normalized.includes("unauthorized")));
+    (normalized.includes("401") &&
+      (normalized.includes("api key") || normalized.includes("unauthorized")));
   if (authFailure) {
     return "The model provider rejected this deployment's engine credentials. Sending messages won't help until the deployment's engine configuration is fixed.";
   }
   const quotaFailure =
-    normalized.includes("insufficient_quota") ||
-    normalized.includes("exceeded your current quota");
+    normalized.includes("insufficient_quota") || normalized.includes("exceeded your current quota");
   if (quotaFailure) {
     return "The model provider refused the request: this deployment's provider quota is exhausted.";
   }

package/src/lib/xterm-renderer.ts

@@ -0,0 +1,65 @@
+/* ----------------------------------------------------------------------------
+   xterm renderer selection ladder: WebGL → 2D canvas → DOM.
+
+   WebGL is the fast path (GPU-composited cells — the whole point of the burst
+   responsiveness win). But a WebGL context can fail to init (headless / no GPU /
+   blocklisted driver) or be LOST at runtime (GPU reset, tab backgrounded). On
+   either, we dispose the addon and step down one tier so the terminal keeps
+   painting via the 2D canvas addon, and failing that xterm's built-in DOM
+   renderer (no addon).
+
+   `attachRenderer` is pure over its `loaders` (each closes over the xterm
+   instance and constructs+loads its addon, throwing on failure), so the ladder
+   + context-loss downgrade unit-test without a real WebGL context.
+   -------------------------------------------------------------------------- */
+
+export type RendererTier = "webgl" | "canvas" | "dom";
+
+export type RendererAddon = { dispose: () => void };
+
+/** A loader constructs + `loadAddon`s its renderer, wiring `onLoss` to the
+ *  addon's context-loss event, and throws if the renderer can't initialize. */
+export type RendererLoaders = {
+  webgl?: ((onLoss: () => void) => Promise<RendererAddon>) | undefined;
+  canvas?: (() => Promise<RendererAddon>) | undefined;
+};
+
+const ORDER: RendererTier[] = ["webgl", "canvas", "dom"];
+
+/** The next lower renderer tier, or null at the bottom (DOM). Pure. */
+export function nextRendererTier(tier: RendererTier): RendererTier | null {
+  const i = ORDER.indexOf(tier);
+  return i >= 0 && i < ORDER.length - 1 ? ORDER[i + 1]! : null;
+}
+
+/**
+ * Attach the highest renderer tier at or below `prefer` that initializes,
+ * reporting the settled tier via `onTier`. On a WebGL/canvas context loss the
+ * loader's `onLoss` re-enters at the next tier down, so `onTier` is called again
+ * with the downgraded tier. Returns the tier chosen on this pass.
+ */
+export async function attachRenderer(
+  prefer: RendererTier,
+  loaders: RendererLoaders,
+  onTier: (tier: RendererTier) => void,
+): Promise<RendererTier> {
+  const start = Math.max(0, ORDER.indexOf(prefer));
+  for (let i = start; i < ORDER.length; i++) {
+    const tier = ORDER[i]!;
+    if (tier === "dom") break;
+    const loader = tier === "webgl" ? loaders.webgl : loaders.canvas;
+    if (!loader) continue;
+    try {
+      const downgrade = nextRendererTier(tier) ?? "dom";
+      await loader(() => {
+        void attachRenderer(downgrade, loaders, onTier);
+      });
+      onTier(tier);
+      return tier;
+    } catch {
+      // Initialization failed — fall through to the next tier down.
+    }
+  }
+  onTier("dom");
+  return "dom";
+}

package/src/lib/xterm-theme.ts

@@ -1,31 +1,237 @@
 import type { XtermTheme } from "../components/sandbox-terminal";
 
+/* ----------------------------------------------------------------------------
+   xterm theming + font resolution from the `--og-*` token system.
+
+   xterm paints glyphs into a canvas (WebGL / 2D) and builds its font strings by
+   hand, so it can consume NEITHER CSS custom properties (`var(--og-font-mono)`
+   never resolves in a canvas font string) NOR a partial palette (an unset ANSI
+   slot falls back to xterm's stock VGA color). This module resolves both to
+   concrete values: a full 16-color ANSI ITheme designed against the og palette
+   for BOTH themes, and a concrete monospace family + px size.
+
+   The color-building + font-resolution cores are pure over a token `read`
+   function so they unit-test without a DOM; thin `*FromTokens` / `resolve*`
+   wrappers do the `getComputedStyle` read on the client.
+   -------------------------------------------------------------------------- */
+
+export type ThemeMode = "dark" | "light";
+
+/** Reads a resolved token value (already `getComputedStyle`-flattened). */
+export type TokenReader = (name: string) => string | undefined;
+
+/**
+ * The 16 ANSI colors + selection/cursor treatment, designed against the og
+ * OKLCH palette. Hues are borrowed from the og status ramp so terminal color
+ * reads as part of the same system: red≈status-failed(22), green≈status-idle
+ * (155), yellow≈status-running(80), blue≈accent(255), magenta≈status-waiting
+ * (305), cyan≈200. Dark uses lifted lightness on the dark slate ground; light
+ * uses deeper, more saturated inks on the near-white ground. Bright variants
+ * add lightness + a touch of chroma. `black`/`white` are neutral slate ramp
+ * stops (never pure #000/#fff — that clashes with the calm neutral ground).
+ */
+export type AnsiPalette = {
+  black: string;
+  red: string;
+  green: string;
+  yellow: string;
+  blue: string;
+  magenta: string;
+  cyan: string;
+  white: string;
+  brightBlack: string;
+  brightRed: string;
+  brightGreen: string;
+  brightYellow: string;
+  brightBlue: string;
+  brightMagenta: string;
+  brightCyan: string;
+  brightWhite: string;
+  /** Selection wash + its foreground; sits over the terminal ground. */
+  selectionBackground: string;
+  selectionForeground: string;
+  selectionInactiveBackground: string;
+};
+
+const DARK_ANSI: AnsiPalette = {
+  black: "oklch(0.3 0.014 260)",
+  red: "oklch(0.68 0.17 22)",
+  green: "oklch(0.75 0.13 155)",
+  yellow: "oklch(0.8 0.11 80)",
+  blue: "oklch(0.7 0.14 255)",
+  magenta: "oklch(0.72 0.13 305)",
+  cyan: "oklch(0.75 0.1 210)",
+  white: "oklch(0.8 0.01 260)",
+  brightBlack: "oklch(0.45 0.014 260)",
+  brightRed: "oklch(0.76 0.17 22)",
+  brightGreen: "oklch(0.82 0.14 155)",
+  brightYellow: "oklch(0.86 0.12 85)",
+  brightBlue: "oklch(0.78 0.13 255)",
+  brightMagenta: "oklch(0.8 0.13 305)",
+  brightCyan: "oklch(0.83 0.1 200)",
+  brightWhite: "oklch(0.97 0.005 260)",
+  selectionBackground: "oklch(0.72 0.15 255 / 0.34)",
+  selectionForeground: "oklch(0.985 0.005 260)",
+  selectionInactiveBackground: "oklch(0.72 0.02 260 / 0.22)",
+};
+
+const LIGHT_ANSI: AnsiPalette = {
+  black: "oklch(0.35 0.015 260)",
+  red: "oklch(0.52 0.19 22)",
+  green: "oklch(0.5 0.13 155)",
+  yellow: "oklch(0.56 0.13 80)",
+  blue: "oklch(0.52 0.18 255)",
+  magenta: "oklch(0.52 0.16 305)",
+  cyan: "oklch(0.52 0.1 210)",
+  white: "oklch(0.7 0.01 260)",
+  brightBlack: "oklch(0.5 0.014 260)",
+  brightRed: "oklch(0.55 0.2 22)",
+  brightGreen: "oklch(0.54 0.14 155)",
+  brightYellow: "oklch(0.6 0.14 80)",
+  brightBlue: "oklch(0.48 0.19 255)",
+  brightMagenta: "oklch(0.54 0.17 305)",
+  brightCyan: "oklch(0.54 0.11 210)",
+  brightWhite: "oklch(0.3 0.015 260)",
+  selectionBackground: "oklch(0.55 0.18 255 / 0.24)",
+  selectionForeground: "oklch(0.21 0.015 260)",
+  selectionInactiveBackground: "oklch(0.6 0.02 260 / 0.16)",
+};
+
+/** The designed ANSI-16 palette for a theme mode. Pure. */
+export function ogAnsiPalette(mode: ThemeMode): AnsiPalette {
+  return mode === "light" ? LIGHT_ANSI : DARK_ANSI;
+}
+
+/**
+ * Build a COMPLETE xterm ITheme from token values. Background/foreground/cursor
+ * come from the live `--og-*` tokens (so an embedder's rebrand flows through);
+ * the ANSI-16 + selection come from the designed palette for `mode`. Every ANSI
+ * slot is always set — xterm never falls back to its stock VGA colors. Pure.
+ */
+export function buildXtermTheme(read: TokenReader, mode: ThemeMode): XtermTheme {
+  const ansi = ogAnsiPalette(mode);
+  const bgFallback = mode === "light" ? "oklch(0.978 0.003 260)" : "oklch(0.155 0.012 260)";
+  const fgFallback = mode === "light" ? "oklch(0.21 0.015 260)" : "oklch(0.955 0.005 260)";
+  const bg = read("--og-color-bg") ?? bgFallback;
+  const fg = read("--og-color-fg") ?? fgFallback;
+  const accent = read("--og-color-accent") ?? ansi.brightBlue;
+  return {
+    // Match the dock surface the terminal paints on (`--og-color-bg`).
+    background: bg,
+    foreground: fg,
+    cursor: accent,
+    cursorAccent: bg,
+    selectionBackground: ansi.selectionBackground,
+    selectionForeground: ansi.selectionForeground,
+    selectionInactiveBackground: ansi.selectionInactiveBackground,
+    black: ansi.black,
+    red: ansi.red,
+    green: ansi.green,
+    yellow: ansi.yellow,
+    blue: ansi.blue,
+    magenta: ansi.magenta,
+    cyan: ansi.cyan,
+    white: ansi.white,
+    brightBlack: ansi.brightBlack,
+    brightRed: ansi.brightRed,
+    brightGreen: ansi.brightGreen,
+    brightYellow: ansi.brightYellow,
+    brightBlue: ansi.brightBlue,
+    brightMagenta: ansi.brightMagenta,
+    brightCyan: ansi.brightCyan,
+    brightWhite: ansi.brightWhite,
+  };
+}
+
+/** Which og theme is active for `el`, matching the `use-theme-type` convention
+ *  (nearest `data-og-theme` / `.og-light` ancestor; else the computed
+ *  `color-scheme`; else dark, the first-class default). */
+function detectMode(el: Element, style: CSSStyleDeclaration): ThemeMode {
+  const closest = el.closest?.bind(el);
+  if (closest) {
+    if (closest('[data-og-theme="light"]') || closest(".og-light")) return "light";
+    const explicit = closest("[data-og-theme]");
+    if (explicit) return explicit.getAttribute("data-og-theme") === "light" ? "light" : "dark";
+  }
+  const scheme = (
+    style.getPropertyValue("color-scheme").trim() ||
+    style.colorScheme ||
+    ""
+  ).toLowerCase();
+  if (scheme.includes("light") && !scheme.includes("dark")) return "light";
+  return "dark";
+}
+
 /**
- * Derive an xterm `ITheme` subset from the live OKLCH `--og-*` token system.
- * Reads the COMPUTED values so xterm — which
- * paints into a canvas and can't consume CSS vars — gets concrete colors. Call
- * on mount and re-derive on a `data-og-theme` flip.
+ * Derive a COMPLETE xterm `ITheme` from the live `--og-*` token system on the
+ * DOM. Reads the COMPUTED values so xterm gets concrete colors, detects the
+ * active theme mode, and fills every ANSI slot. Call on mount + re-derive on a
+ * `data-og-theme` flip. SSR-safe: returns undefined off the DOM.
  *
- * SSR-safe: returns undefined off the DOM (the caller keeps xterm's defaults).
+ * `root` should be an element INSIDE the themed subtree (e.g. the terminal
+ * container) so nested `[data-og-theme]` themes resolve correctly; when omitted
+ * it falls back to the nearest `[data-og-theme]` element, then documentElement.
  */
 export function xtermThemeFromTokens(root?: HTMLElement | null): XtermTheme | undefined {
   if (typeof window === "undefined" || typeof getComputedStyle === "undefined") return undefined;
-  const el = root ?? document.documentElement;
+  const el =
+    root ??
+    (typeof document !== "undefined"
+      ? ((document.querySelector("[data-og-theme]") as HTMLElement | null) ??
+        document.documentElement)
+      : null);
+  if (!el) return undefined;
   const style = getComputedStyle(el);
-  const read = (name: string): string | undefined => {
+  const read: TokenReader = (name) => {
     const value = style.getPropertyValue(name).trim();
     return value || undefined;
   };
-  const bg = read("--og-color-bg");
-  const fg = read("--og-color-fg");
-  const accent = read("--og-color-accent");
-  const theme: XtermTheme = {};
-  if (bg) theme.background = bg;
-  if (fg) theme.foreground = fg;
-  if (accent) {
-    theme.cursor = accent;
-    theme.selectionBackground = accent;
+  return buildXtermTheme(read, detectMode(el, style));
+}
+
+// ── Font resolution ──────────────────────────────────────────────────────────
+
+export type ResolvedTerminalFont = { fontFamily: string; fontSize: number; lineHeight: number };
+
+/** Concrete fallback if the token is unset or (defensively) still a `var()`. */
+const FALLBACK_MONO = "ui-monospace, SFMono-Regular, Menlo, Consolas, 'Liberation Mono', monospace";
+
+export type FontOverrides = { fontFamily?: string | undefined; fontSize?: number | undefined };
+
+/**
+ * Resolve xterm's font from token values. The critical bug this fixes:
+ * `fontFamily: "var(--og-font-mono)"` is measured by xterm via a canvas font
+ * string where `var()` does NOT resolve, so xterm silently mis-measures every
+ * glyph. Here the family is a CONCRETE stack; a `var(` in the input is treated
+ * as unresolved and replaced with the fallback. Pure over a token `read`.
+ */
+export function resolveTerminalFontFromReader(
+  read: TokenReader,
+  overrides?: FontOverrides,
+): ResolvedTerminalFont {
+  const rawFamily = overrides?.fontFamily ?? read("--og-font-mono");
+  const fontFamily =
+    rawFamily && rawFamily.trim() && !rawFamily.includes("var(") ? rawFamily.trim() : FALLBACK_MONO;
+
+  let fontSize = overrides?.fontSize;
+  if (fontSize == null) {
+    const raw = read("--og-code-font-size");
+    const parsed = raw ? Number.parseFloat(raw) : Number.NaN;
+    fontSize = Number.isFinite(parsed) && parsed > 0 ? parsed : 13;
   }
-  if (bg) theme.cursorAccent = bg;
-  return Object.keys(theme).length > 0 ? theme : undefined;
+
+  return { fontFamily, fontSize, lineHeight: 1.3 };
+}
+
+/** DOM wrapper: resolve the terminal font from an element's computed tokens. */
+export function resolveTerminalFont(
+  el: HTMLElement,
+  overrides?: FontOverrides,
+): ResolvedTerminalFont {
+  const style = getComputedStyle(el);
+  const read: TokenReader = (name) => {
+    const value = style.getPropertyValue(name).trim();
+    return value || undefined;
+  };
+  return resolveTerminalFontFromReader(read, overrides);
 }

package/src/machines.ts

@@ -37,9 +37,15 @@ export type { MachineCardProps } from "./components/machine-card";
 export { MachinesDashboard } from "./components/machines-dashboard";
 export type { MachinesDashboardProps } from "./components/machines-dashboard";
 export { MachineDockBar, SharedMachineDisclosure } from "./components/machine-dock-bar";
-export type { MachineDockBarProps, SharedMachineDisclosureProps } from "./components/machine-dock-bar";
+export type {
+  MachineDockBarProps,
+  SharedMachineDisclosureProps,
+} from "./components/machine-dock-bar";
 export { EnrollmentDeviceFlow } from "./components/enrollment-device-flow";
-export type { DeviceFlowPhase, EnrollmentDeviceFlowProps } from "./components/enrollment-device-flow";
+export type {
+  DeviceFlowPhase,
+  EnrollmentDeviceFlowProps,
+} from "./components/enrollment-device-flow";
 export { EnrollmentConsent } from "./components/enrollment-consent";
 export type {
   EnrollmentConsentMachine,
@@ -47,4 +53,8 @@ export type {
   EnrollmentConsentProps,
 } from "./components/enrollment-consent";
 export { useMachines } from "./hooks/use-machines";
-export type { MachinesClientLike, UseMachinesOptions, UseMachinesResult } from "./hooks/use-machines";
+export type {
+  MachinesClientLike,
+  UseMachinesOptions,
+  UseMachinesResult,
+} from "./hooks/use-machines";

package/src/provider.tsx

@@ -45,7 +45,9 @@ export function useOpenGeni(override: ClientOverride = {}): OpenGeniContextValue
  * Resolve the client only — for hooks that are not workspace-scoped
  * (`useWorkspaces`, `useBillingUsage`).
  */
-export function useOpenGeniClient(override: Pick<ClientOverride, "client"> = {}): SessionClientLike {
+export function useOpenGeniClient(
+  override: Pick<ClientOverride, "client"> = {},
+): SessionClientLike {
   const context = useContext(OpenGeniContext);
   const client = override.client ?? context?.client;
   if (!client) {