@volter/sdk 0.0.0-stage → 0.5.204

package/src/kit/cancellation-reason.ts

@@ -0,0 +1,58 @@
+/**
+ * IS THIS REJECTION A CANCELLATION? — the one predicate, shared by the two
+ * page-level `unhandledrejection` listeners this editor installs
+ * (`editor-presence.ts`'s boot reporter and `editor-console.ts`'s
+ * session-lifetime capture).
+ *
+ * ## Why this is not "exempting a source"
+ *
+ * The recorded doctrine at `installEditorConsoleCapture` is that SEVERITY
+ * decides what reaches the ledger and never SOURCE, "because exempting a
+ * source would teach the gate to find less". This is not that. A cancellation
+ * is not a low-severity error, it is the platform's word for *an operation
+ * that was asked to stop and did* — the same judgement the workbench makes
+ * about its own (`onUnexpectedError` returns early on `isCancellationError`)
+ * and the same one the Fetch and Streams specs make (`AbortError`). It is
+ * applied identically to OUR rejections and to anyone else's: a volter fetch
+ * abandoned because the document moved on is exactly as much of a non-event.
+ *
+ * ## What made it necessary
+ *
+ * MEASURED 2026-09-19, the Code-OSS frame's blind walk, beat 9: a
+ * `--template game` scaffold reported
+ * `[runtime] editor app failed to start: Canceled: Canceled` while its editor
+ * was running fine. Under the frame the page is a WORKBENCH, and a workbench
+ * raises `CancellationError` (`name === 'Canceled'`) whenever a quick input is
+ * dismissed or a search is superseded — none of which any page-level listener
+ * can attribute, because a rejection carries no author. The ledger spans two
+ * codebases there (docs/CODE-OSS.md, "The console ledger now spans two
+ * codebases"), and this is the one class of line that can be ruled on without
+ * asking WHOSE it is.
+ *
+ * ## Its own file, deliberately
+ *
+ * `editor-presence.ts` is the pre-React bootstrap module and is
+ * dependency-light on purpose (its own comments say so); importing the console
+ * from it would pull the console's whole closure into the page's first script.
+ * A five-line predicate copied into both is the duplication this codebase
+ * treats as a defect, so it is one module with no imports of its own.
+ */
+
+/**
+ * True when a rejection reason means "this was cancelled", by any of the three
+ * spellings in play on our page:
+ *
+ *  - VS Code's `CancellationError`, whose constructor sets
+ *    `name = message = 'Canceled'`;
+ *  - the platform's `AbortError` — a `DOMException` from `AbortSignal`, and
+ *    what `fetch` rejects with when its signal fires;
+ *  - the older `AbortError` shape any library may throw as a plain `Error`.
+ *
+ * Deliberately NOT a message match: a message is prose and drifts, while these
+ * names are contract.
+ */
+export function isCancellationReason(reason: unknown): boolean {
+  if (typeof reason !== 'object' || reason === null) return false;
+  const name = (reason as { name?: unknown }).name;
+  return name === 'Canceled' || name === 'CancellationError' || name === 'AbortError';
+}

package/src/kit/canvas-frames.ts

@@ -0,0 +1,88 @@
+/**
+ * A CANVAS'S SAME-FRAME PIXELS, answered by the medium that draws into it. A
+ * canvas a medium renders without `preserveDrawingBuffer` photographs blank if
+ * it is read after its frame, so the kit's compositor asks here instead of
+ * reading such a canvas directly. Two doors: the canvases a live surface is
+ * presenting now, and the canvases a mount the kit is about to photograph
+ * creates (a story's own `<Application>`). With no medium registered the kit
+ * reads every canvas directly.
+ */
+export type CanvasFrame = (canvas: HTMLCanvasElement) => Promise<CanvasImageSource | null>;
+
+let sources: readonly CanvasFrame[] = [];
+
+/** A medium's reader for the canvases its live surfaces present; it answers
+ *  `null` for a canvas it does not own. Returns the removal. */
+export function registerCanvasFrameSource(source: CanvasFrame): () => void {
+  sources = [...sources, source];
+  return () => {
+    sources = sources.filter((existing) => existing !== source);
+  };
+}
+
+/** The first registered source's pixels for `canvas`, or null when none owns it. */
+export async function presentedCanvasFrame(canvas: HTMLCanvasElement): Promise<CanvasImageSource | null> {
+  for (const source of sources) {
+    const frame = await source(canvas);
+    if (frame) return frame;
+  }
+  return null;
+}
+
+/** What a medium learned while a mount ran: when its surfaces have drawn their
+ *  first frame, and how to read their canvases. */
+export interface ObservedCanvasMount<T> {
+  readonly result: T;
+  settled(): Promise<void>;
+  readonly frame: CanvasFrame;
+}
+
+export interface CanvasMountObserver {
+  observe<T>(task: () => Promise<T>): Promise<ObservedCanvasMount<T>>;
+}
+
+let observer: CanvasMountObserver | null = null;
+
+/** The one medium that observes mounts for canvases it creates. Returns the removal. */
+export function registerCanvasMountObserver(next: CanvasMountObserver): () => void {
+  observer = next;
+  return () => {
+    if (observer === next) observer = null;
+  };
+}
+
+/** Run a mount under the registered observer, or plainly when none is. */
+export async function observeCanvasMount<T>(task: () => Promise<T>): Promise<ObservedCanvasMount<T>> {
+  if (observer) return observer.observe(task);
+  return { result: await task(), settled: async () => {}, frame: async () => null };
+}
+
+/** A medium's re-render of a canvas it owns at a requested size, for a caller
+ *  that photographs at its own scale (the editor chrome); `null` when the
+ *  canvas is not its. */
+export type CanvasRender = (
+  canvas: HTMLCanvasElement,
+  size: { readonly width: number; readonly height: number },
+) => Promise<CanvasImageSource | null> | null;
+
+let renders: readonly CanvasRender[] = [];
+
+export function registerCanvasRender(render: CanvasRender): () => void {
+  renders = [...renders, render];
+  return () => {
+    renders = renders.filter((existing) => existing !== render);
+  };
+}
+
+/** The first registered medium's rendering of `canvas` at `size`, or null. */
+export async function renderedCanvasFrame(
+  canvas: HTMLCanvasElement,
+  size: { readonly width: number; readonly height: number },
+): Promise<CanvasImageSource | null> {
+  for (const render of renders) {
+    const pending = render(canvas, size);
+    if (pending === null) continue;
+    return pending;
+  }
+  return null;
+}

package/src/kit/capture-camera-pose.ts

@@ -0,0 +1,77 @@
+/**
+ * THE FREE CAPTURE CAMERA AND CLIP POSE, validated at the relay boundary —
+ * `--azimuth/--elevation/--distance` and `--clip/--time` as they arrive on a
+ * capture command.
+ *
+ * Extracted from `command-listener.ts:1016,1053`, where both parsers were
+ * private to that module and already served TWO verbs:
+ * `capture-asset-preview`, which stays in that table, and
+ * `capture-story-variants`, which carries its own relay budget and so is a
+ * registered command (`stories/story-capture-command.ts`). Two callers before
+ * the move and two after; nothing here is new.
+ *
+ * THE VERB NAMES ITSELF. Both refusals used to spell `capture-asset-preview`
+ * unconditionally, so a bad `--azimuth` on the editor's `screenshot <module>.stories.tsx` command
+ * refused in the name of a command the caller never ran. The verb is a
+ * parameter now, which the extraction is what made visible.
+ */
+
+/** Validate an untrusted `camera` payload: the parsed choice, `undefined` when
+ *  absent, or the refusal message naming `verb`. */
+export function parseCameraChoice(
+  verb: string,
+  value: unknown,
+): { azimuthDegrees: number; elevationDegrees: number; distance?: number } | undefined | string {
+  if (value === undefined) return undefined;
+  const record = value as {
+    azimuthDegrees?: unknown;
+    elevationDegrees?: unknown;
+    distance?: unknown;
+  } | null;
+  if (
+    record === null ||
+    typeof record !== 'object' ||
+    typeof record.azimuthDegrees !== 'number' ||
+    !Number.isFinite(record.azimuthDegrees) ||
+    typeof record.elevationDegrees !== 'number' ||
+    !Number.isFinite(record.elevationDegrees) ||
+    record.elevationDegrees < -90 ||
+    record.elevationDegrees > 90 ||
+    (record.distance !== undefined &&
+      (typeof record.distance !== 'number' ||
+        !Number.isFinite(record.distance) ||
+        record.distance <= 0))
+  ) {
+    return (
+      `${verb} camera must be {azimuthDegrees, elevationDegrees in [-90, 90], ` +
+      'distance? > 0 meters}.'
+    );
+  }
+  return {
+    azimuthDegrees: record.azimuthDegrees,
+    elevationDegrees: record.elevationDegrees,
+    ...(record.distance === undefined ? {} : { distance: record.distance }),
+  };
+}
+
+/** Validate an untrusted `pose` payload: the parsed pose, `undefined` when
+ *  absent, or the refusal message naming `verb`. */
+export function parsePoseChoice(
+  verb: string,
+  value: unknown,
+): { clip: string; timeSeconds: number } | undefined | string {
+  if (value === undefined) return undefined;
+  const record = value as { clip?: unknown; timeSeconds?: unknown } | null;
+  if (
+    record === null ||
+    typeof record !== 'object' ||
+    typeof record.clip !== 'string' ||
+    record.clip.length === 0 ||
+    typeof record.timeSeconds !== 'number' ||
+    !Number.isFinite(record.timeSeconds) ||
+    record.timeSeconds < 0
+  ) {
+    return `${verb} pose must be {clip: non-empty string, timeSeconds >= 0}.`;
+  }
+  return { clip: record.clip, timeSeconds: record.timeSeconds };
+}

package/src/kit/capture-size.ts

@@ -0,0 +1,88 @@
+import type { CaptureDimensions } from '@volter/sdk';
+
+/**
+ * The dimensions a capture verb was asked for, or the refusal that names the
+ * value it was handed.
+ *
+ * SQUARE IS THE DEFAULT and `size` is how you ask for one. `width`+`height`
+ * together ask for a SHAPED frame — a video-aspect look that needs no crop
+ * afterwards — and are bounded per side and in TOTAL by the same relay budget
+ * the square ceiling comes from. Mixing the two forms is refused rather than
+ * silently resolved: a caller who sent both does not know which one they meant.
+ *
+ * `cmd` is WIRE INPUT — a JSON object from another process — so `cmd['size']`
+ * had never been anything but a cast (`as number | undefined`). A caller that
+ * sent a non-number got that value multiplied by 2 deep inside
+ * `_renderViewportImage` and `createImageData(NaN, NaN)` threw
+ * `TypeError: Value is not of type 'long'` from the middle of the render path;
+ * because the dispatcher's `.then()` had no rejection leg, the throw answered
+ * nobody and the caller waited out its whole budget for
+ * "the tab is present … and did not respond" — a message about the TAB for a
+ * defect in the argument. Measured on a racing-game ingest mount, 2026-08-15.
+ */
+export function captureSizeFromCommand(
+  cmd: Readonly<Record<string, unknown>>,
+): { size?: CaptureDimensions } | { error: string } {
+  const raw = cmd['size'];
+  const rawWidth = cmd['width'];
+  const rawHeight = cmd['height'];
+  const shaped = rawWidth !== undefined || rawHeight !== undefined;
+  if (shaped) {
+    if (raw !== undefined && raw !== null) {
+      return {
+        error:
+          `${String(cmd['type'])}: pass "size" (a square) OR "width"+"height" (a shaped frame), ` +
+          'never both.',
+      };
+    }
+    const dimension = (name: string, value: unknown): number | string => {
+      if (typeof value !== 'number' || !Number.isInteger(value)) {
+        return (
+          `${String(cmd['type'])}: "${name}" must be a whole number — got ` +
+          `${typeof value} ${JSON.stringify(value) ?? String(value)}.`
+        );
+      }
+      if (value < MIN_CAPTURE_DIMENSION || value > MAX_CAPTURE_DIMENSION) {
+        return `${String(cmd['type'])}: "${name}" must be ${MIN_CAPTURE_DIMENSION}-${MAX_CAPTURE_DIMENSION} — ${CAPTURE_BUDGET_REASON}`;
+      }
+      return value;
+    };
+    const width = dimension('width', rawWidth);
+    if (typeof width === 'string') return { error: width };
+    const height = dimension('height', rawHeight);
+    if (typeof height === 'string') return { error: height };
+    if (width * height > MAX_CAPTURE_DIMENSION * MAX_CAPTURE_DIMENSION) {
+      return {
+        error:
+          `${String(cmd['type'])}: ${width}x${height} is ${width * height} pixels, past the ` +
+          `${MAX_CAPTURE_DIMENSION}x${MAX_CAPTURE_DIMENSION} total — ${CAPTURE_BUDGET_REASON}`,
+      };
+    }
+    return { size: { width, height } };
+  }
+  if (raw === undefined || raw === null) return {};
+  if (typeof raw !== 'number' || !Number.isFinite(raw) || raw < 1) {
+    return {
+      error:
+        `${String(cmd['type'])}: "size" must be a finite number >= 1 — got ` +
+        `${typeof raw} ${JSON.stringify(raw) ?? String(raw)}.`,
+    };
+  }
+  return { size: raw };
+}
+
+/**
+ * The editor's own capture ceiling, and WHY it is this number.
+ *
+ * 64..1024 per side is `asset-preview.ts`'s `MIN_SIZE`/`MAX_SIZE`: the pixels
+ * cross the editor relay as base64 JSON, and 1024 is where even incompressible
+ * RGBA still fits its 50 MB request limit. A shaped frame is held to the same
+ * BUDGET rather than a laxer one — its total may not exceed a 1024 square —
+ * because the budget is about bytes on the wire, not about shape.
+ */
+const MIN_CAPTURE_DIMENSION = 64;
+const MAX_CAPTURE_DIMENSION = 1024;
+const CAPTURE_BUDGET_REASON =
+  "the editor's own ceiling: the pixels cross the relay as base64 JSON, and 1024 is where even " +
+  'incompressible RGBA still fits its 50 MB request limit. For more picture, take more views, ' +
+  'not bigger ones.';

package/src/kit/chrome-registry.ts

@@ -0,0 +1,159 @@
+/**
+ * CONTRIBUTED CHROME — the registry behind `@volter/sdk/chrome`: the
+ * palette actions, application-menu items and header items a package
+ * contributes.
+ *
+ * WHO READS IT, measured rather than assumed: `palette-action-publisher.tsx`
+ * takes {@link contributedActions} into the table the frame registers as
+ * `MenuId.CommandPalette` items (so ⌘⇧P lists a package's actions with its own
+ * labels); `components/ApplicationMenus.tsx` appends
+ * {@link contributedMenuItems} per menu id; `components/ProjectHeader.tsx` and
+ * `components/Object3DDocumentToolbar.tsx` draw {@link contributedHeaderItems}
+ * in the title bar and the document's own strip; `tool-loader.ts` registers
+ * what a package declares. Ids are namespaced `tool:` so they never collide
+ * with the host's.
+ */
+
+import type {
+  ActionContribution,
+  ContributableMenu,
+  ContributedAction,
+  ContributedMenuItem,
+  DocumentHeaderItemProps,
+  HeaderPlacement,
+  MenuContribution,
+} from '@volter/sdk/chrome';
+import type { ComponentType } from 'react';
+
+const CONTRIBUTABLE_MENUS: readonly ContributableMenu[] = [
+  'asset',
+  'view',
+  'window',
+  'debug',
+  'tools',
+  'help',
+];
+
+export interface ContributedHeaderItem {
+  readonly id: string;
+  readonly order: number;
+  readonly placement: HeaderPlacement;
+  readonly Component: ComponentType<DocumentHeaderItemProps>;
+}
+
+let headerItems: ContributedHeaderItem[] = [];
+let actionRegistrations: readonly ActionContribution[] = [];
+let menuItems: Array<{ menu: ContributableMenu; item: ContributedMenuItem }> = [];
+let version = 0;
+const listeners = new Set<() => void>();
+function notify(): void {
+  version++;
+  for (const listener of listeners) listener();
+}
+
+export function subscribeContributedChrome(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function contributedChromeVersion(): number {
+  return version;
+}
+
+/** Header items in `order`, ties by registration. */
+export function contributedHeaderItems(
+  placement: HeaderPlacement = 'transport',
+): readonly ContributedHeaderItem[] {
+  return headerItems
+    .filter((item) => item.placement === placement)
+    .sort((a, b) => a.order - b.order);
+}
+
+/** Register one header item (`.header.tsx`, `tool:<id>`). Returns the unregister. */
+export function registerContributedHeaderItem(item: ContributedHeaderItem): () => void {
+  if (headerItems.some((existing) => existing.id === item.id))
+    throw new Error(`header item "${item.id}" is already contributed.`);
+  headerItems = [...headerItems, item];
+  notify();
+  return () => {
+    headerItems = headerItems.filter((existing) => existing !== item);
+    notify();
+  };
+}
+
+export function contributedActions(): readonly ContributedAction[] {
+  const seen = new Set<string>();
+  const out: ContributedAction[] = [];
+  for (const registration of actionRegistrations) {
+    const list =
+      typeof registration.actions === 'function' ? registration.actions() : registration.actions;
+    for (const action of list) {
+      const id = `tool:${action.id}`;
+      // A live set may repeat a static id across its own reads; first wins.
+      if (seen.has(id)) continue;
+      seen.add(id);
+      out.push({ ...action, id });
+    }
+  }
+  return out;
+}
+
+export function contributedMenuItems(menu: ContributableMenu): readonly ContributedMenuItem[] {
+  return menuItems.filter((entry) => entry.menu === menu).map((entry) => entry.item);
+}
+
+export function isContributableMenu(value: unknown): value is ContributableMenu {
+  return typeof value === 'string' && (CONTRIBUTABLE_MENUS as readonly string[]).includes(value);
+}
+
+/**
+ * Register a contribution's actions, each under `tool:<id>`. A fixed list is
+ * checked for duplicate ids now; a live one (`actions` as a function) is read
+ * on every listing and re-listed whenever its `subscribe` fires. Returns the
+ * unregister.
+ */
+export function registerContributedActions(contribution: ActionContribution): () => void {
+  if (typeof contribution.actions !== 'function') {
+    const listed = contributedActions();
+    for (const action of contribution.actions)
+      if (listed.some((existing) => existing.id === `tool:${action.id}`))
+        throw new Error(`action "tool:${action.id}" is already contributed.`);
+  }
+  actionRegistrations = [...actionRegistrations, contribution];
+  const stop = contribution.subscribe?.(notify);
+  notify();
+  return () => {
+    stop?.();
+    actionRegistrations = actionRegistrations.filter((existing) => existing !== contribution);
+    notify();
+  };
+}
+
+/** Register a contribution's menu items on one menu. Returns the unregister. */
+export function registerContributedMenu(contribution: MenuContribution): () => void {
+  const added = contribution.items.map((item) => ({
+    menu: contribution.menu,
+    item: { ...item, id: `tool:${item.id}` },
+  }));
+  for (const entry of added)
+    if (menuItems.some((existing) => existing.item.id === entry.item.id))
+      throw new Error(`menu item "${entry.item.id}" is already contributed.`);
+  menuItems = [...menuItems, ...added];
+  notify();
+  return () => {
+    menuItems = menuItems.filter((entry) => !added.includes(entry));
+    notify();
+  };
+}
+
+/**
+ * A fingerprint of every contributed item's CURRENT `disabled` answer, across
+ * every menu. The point (`@volter/sdk/chrome`) promises that `disabled`
+ * is asked at render and may follow session state — which is only true if
+ * something re-renders the bar when that state moves. `ApplicationMenus`
+ * samples this on the shared availability tick while a menu is OPEN, so an
+ * item can go live or dead under the cursor and costs nothing when closed.
+ */
+export function contributedDisabledFingerprint(): string {
+  return menuItems.map((entry) => (entry.item.disabled?.({}) ? '1' : '0')).join('');
+}

package/src/kit/chrome-slot-registry.ts

@@ -0,0 +1,91 @@
+/**
+ * A CHROME SLOT IS A PLACE, NOT A PANEL — the third registry in the same
+ * family as `workspace-document-restore.ts` (a kind owns its persisted state)
+ * and `document-open-registry.ts` (a kind owns how it opens). Here: the host
+ * owns WHERE something sits and how big it is; a package owns WHAT sits there.
+ *
+ * WHY IT EXISTS. The host's chrome had two places whose CONTENT was a product
+ * opinion rather than a workbench concern: the `agent` static panel
+ * (`components/workspace-static-panel-registry.tsx` imported
+ * `ConversationPanel`) and the bottom bar beside the status line
+ * (`components/EditorBottomBar.tsx` imported `HarnessConversationTray`). Both
+ * are an AGENT-HARNESS conversation surface — it talks to coding harnesses, not
+ * to a game, not to a document — so a base library for making IDEs should not
+ * carry it, and neither of the two existing seams fits: it is not a document,
+ * so it neither opens nor persists (WORK.md §The open-source launch, phase 1
+ * unit 6 half A).
+ *
+ * WHAT A SLOT ID IS. A plain string in the host's own vocabulary, spelled at
+ * the ONE host call site that renders the slot. The host declares the place in
+ * its own layout inventory (`workspace-static-panels.ts` still lists the
+ * `agent` panel's title, hotkey scope and placement, because the frame
+ * PERSISTS panel ids and the tab's own chrome is the dock's); what it no
+ * longer holds is the surface.
+ *
+ * NOTHING REGISTERED IS A REAL ANSWER. A build whose package list carries no
+ * filler for a slot renders nothing there — the same honest emptiness a
+ * document kind with no registered opener gives.
+ */
+
+import type { ComponentType } from 'react';
+
+export interface ChromeSlotFiller {
+  /** The place, in the host's vocabulary (`panel:agent`, `bottom-bar`). */
+  readonly slot: string;
+  /** Which module registered it. Re-registering the same owner+slot REPLACES,
+   *  so an HMR re-evaluation leaves one filler, not two. */
+  readonly owner: string;
+  /** Ascending; ties keep registration order. */
+  readonly order?: number;
+  readonly Content: ComponentType;
+}
+
+const _fillers = new Map<string, ChromeSlotFiller[]>();
+const listeners = new Set<() => void>();
+let version = 0;
+
+function publish(): void {
+  version++;
+  for (const listener of listeners) listener();
+}
+
+/** Install a filler. Returns the teardown. */
+export function registerChromeSlot(filler: ChromeSlotFiller): () => void {
+  const existing = _fillers.get(filler.slot) ?? [];
+  const next = existing.filter((item) => item.owner !== filler.owner);
+  next.push(filler);
+  next.sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
+  _fillers.set(filler.slot, next);
+  publish();
+  return () => {
+    const current = _fillers.get(filler.slot);
+    if (!current) return;
+    const remaining = current.filter((item) => item !== filler);
+    if (remaining.length === 0) _fillers.delete(filler.slot);
+    else _fillers.set(filler.slot, remaining);
+    publish();
+  };
+}
+
+/** Everything registered for `slot`, in order. A stable array per version, so
+ *  it is a safe `useSyncExternalStore` snapshot. */
+export function chromeSlotFillers(slot: string): readonly ChromeSlotFiller[] {
+  return _fillers.get(slot) ?? EMPTY;
+}
+
+const EMPTY: readonly ChromeSlotFiller[] = [];
+
+export function subscribeChromeSlots(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function chromeSlotRegistryVersion(): number {
+  return version;
+}
+
+/** Test-only reset (mirrors the restore and open registries' own). */
+export function __resetChromeSlotsForTest(): void {
+  _fillers.clear();
+  publish();
+}