@volter/sdk 0.0.0-stage → 0.5.204

package/src/kit/light-explorer-model.ts

@@ -0,0 +1,134 @@
+import type { AuthoringAdapter, EditorNode, PropertyDescriptor } from '@volter/project/adapter';
+import { setAuthoringInspectorField } from './authoring/consumer-actions';
+import { forEachHierarchyNode } from './hierarchy-walk';
+
+export const LIGHT_EXPLORER_PATHS = {
+  enabled: 'visible',
+  color: 'light.color',
+  intensity: 'light.intensity',
+  range: 'light.distance',
+  shadows: 'shadow.cast',
+} as const;
+
+export type LightExplorerField = keyof typeof LIGHT_EXPLORER_PATHS;
+
+export interface LightExplorerCell<T> {
+  readonly supported: boolean;
+  readonly writable: boolean;
+  readonly value: T | null;
+}
+
+export interface LightExplorerRow {
+  readonly id: string;
+  readonly name: string;
+  readonly type: string;
+  readonly enabled: LightExplorerCell<boolean>;
+  readonly color: LightExplorerCell<string>;
+  readonly intensity: LightExplorerCell<number>;
+  readonly range: LightExplorerCell<number>;
+  readonly shadows: LightExplorerCell<boolean>;
+}
+
+interface HierarchyWithInternals {
+  /** Optional editor-side hierarchy projection used by component-owning
+   * adapters. These are still real adapter nodes; they are merely folded out
+   * of the ordinary tree until a person asks to reveal implementation parts. */
+  internalChildren?(id: string): EditorNode[] | undefined;
+}
+
+function lightNodes(adapter: AuthoringAdapter): EditorNode[] {
+  const result: EditorNode[] = [];
+  const hierarchyWithInternals = adapter as AuthoringAdapter & HierarchyWithInternals;
+  forEachHierarchyNode(
+    adapter.hierarchy,
+    (node) => {
+      if (node.kind === 'light') result.push(node);
+    },
+    { extraChildren: (id) => hierarchyWithInternals.internalChildren?.(id) },
+  );
+  return result;
+}
+
+export function activeLightCount(adapter: AuthoringAdapter): number {
+  return lightNodes(adapter).length;
+}
+
+function descriptorFor(
+  descriptors: readonly PropertyDescriptor[],
+  field: LightExplorerField,
+): PropertyDescriptor | null {
+  return descriptors.find((descriptor) => descriptor.path === LIGHT_EXPLORER_PATHS[field]) ?? null;
+}
+
+function cell<T>(
+  adapter: AuthoringAdapter,
+  id: string,
+  descriptors: readonly PropertyDescriptor[],
+  field: LightExplorerField,
+  accept: (value: unknown) => value is T,
+): LightExplorerCell<T> {
+  const descriptor = descriptorFor(descriptors, field);
+  if (!descriptor || !adapter.inspector) {
+    return { supported: false, writable: false, value: null };
+  }
+  let value: unknown;
+  try {
+    value = adapter.inspector.get(id, descriptor.path);
+  } catch {
+    value = undefined;
+  }
+  return {
+    supported: true,
+    writable: descriptor.readonly !== true,
+    value: accept(value) ? value : null,
+  };
+}
+
+const isBoolean = (value: unknown): value is boolean => typeof value === 'boolean';
+const isString = (value: unknown): value is string => typeof value === 'string';
+const isNumber = (value: unknown): value is number =>
+  typeof value === 'number' && Number.isFinite(value);
+
+export function lightExplorerRows(adapter: AuthoringAdapter): LightExplorerRow[] {
+  return lightNodes(adapter).map((node) => {
+    let descriptors: readonly PropertyDescriptor[] = [];
+    try {
+      descriptors = adapter.inspector?.properties(node.id) ?? [];
+    } catch {
+      // A broken per-node inspector must not take the scene-wide inventory down.
+    }
+    const nativeType = (adapter.hierarchy.object3D?.(node.id) as { readonly type?: string } | null | undefined)?.type;
+    return {
+      id: node.id,
+      name: node.label,
+      type: node.typeLabel ?? nativeType ?? 'Light',
+      enabled: cell(adapter, node.id, descriptors, 'enabled', isBoolean),
+      color: cell(adapter, node.id, descriptors, 'color', isString),
+      intensity: cell(adapter, node.id, descriptors, 'intensity', isNumber),
+      range: cell(adapter, node.id, descriptors, 'range', isNumber),
+      shadows: cell(adapter, node.id, descriptors, 'shadows', isBoolean),
+    };
+  });
+}
+
+export function setLightExplorerField(
+  adapter: AuthoringAdapter,
+  ids: readonly string[],
+  field: LightExplorerField,
+  value: unknown,
+): number {
+  if (!adapter.inspector) return 0;
+  let changed = 0;
+  for (const id of ids) {
+    let descriptor: PropertyDescriptor | null = null;
+    try {
+      descriptor = descriptorFor(adapter.inspector.properties(id), field);
+    } catch {
+      continue;
+    }
+    if (!descriptor || descriptor.readonly) continue;
+    setAuthoringInspectorField(adapter, id, descriptor.path, value);
+    changed++;
+  }
+  return changed;
+}

package/src/kit/live-canvas-frame.ts

@@ -0,0 +1,55 @@
+/**
+ * ONE `canvasFrame` seam (`composite-screenshot.ts`), for every pixel door.
+ *
+ * ## Why this exists
+ *
+ * A canvas is only `drawImage`-able after its frame when its WebGL context was
+ * created with `preserveDrawingBuffer: true`. Every canvas the volter RUNTIME
+ * mounts sets it; a canvas a GAME created is the game's own and almost never
+ * does. Two different mechanisms recover those pixels, one per substrate:
+ *
+ *  - a lane whose render pass owns the canvas (a three ingest) copies the
+ *    drawing buffer INSIDE that pass, asked through the live registry
+ *    (`LiveSession.snapshotFrame`, `ingest/ingest-frame-snapshot.ts`);
+ *  - a Pixi surface re-renders the stage through the renderer's own extractor
+ *    ({@link presentedPixiFrame}, `stories/story-pixi-preview.ts`).
+ *
+ * Both already existed. What did not was a single place that tries both, and
+ * that gap was VISIBLE AS A LIE: `command-listener.ts`'s `bridge-screenshot`
+ * passed only the three one and `editor-view-presentation.ts`'s
+ * `capture-active-document` passed only the Pixi one, so each door photographed
+ * one lane correctly and the other one BLANK — and a blank frame is the worst
+ * failure a look verb has, because nothing about it says it failed.
+ *
+ * Composing them is safe by construction: each half answers `null` — the seam's
+ * documented "read the canvas directly" — for a canvas it does not own, so a
+ * first-party runtime canvas still takes the ordinary path.
+ */
+
+import { presentedCanvasFrame } from '@volter/sdk/kit/canvas-frames';
+import { snapshotLiveFrame } from '@volter/sdk/kit/live-session-registry';
+
+/**
+ * Same-frame pixels for `canvas`, whichever live surface owns it, or `null`
+ * when none does.
+ *
+ * Order is the cheap test first: the registry's claim is an identity read
+ * against the mounted lane's canvas, while the Pixi leg walks the presented
+ * set and, on a hit, costs a real render.
+ */
+export async function liveCanvasFrame(
+  canvas: HTMLCanvasElement,
+): Promise<CanvasImageSource | null> {
+  const live = snapshotLiveFrame(canvas);
+  if (live) return live;
+  return presentedCanvasFrame(canvas);
+}
+
+/** A `CanvasImageSource` that can be read back as a PNG on its own — what the
+ *  canvas-only capture leg needs when it has no compositor to draw into.
+ *  Pixi's extractor hands back a real `HTMLCanvasElement`, but the seam's type
+ *  is the wider `CanvasImageSource`, so the door asks rather than casts. */
+export function readablePngSource(source: CanvasImageSource | null): HTMLCanvasElement | null {
+  const candidate = source as HTMLCanvasElement | null;
+  return candidate && typeof candidate.toDataURL === 'function' ? candidate : null;
+}

package/src/kit/live-document.ts

@@ -0,0 +1,296 @@
+/**
+ * THE LIVE DOCUMENT's lifetime — the host's one center document for running
+ * content (`workspace:game`, titled `Game`). When nothing runs there is no
+ * live document at all — no tab, no panel, no hidden-but-mounted host.
+ *
+ * The editor's standing center documents are the authoring ones (Scene / the
+ * world documents, `UI`, `3D`). The live document is not one of them: it is
+ * the running lane's own surface, so it EXISTS exactly as long as a runtime
+ * does. It is installed when a runtime is about to mount and closed when
+ * that runtime ends, through the ordinary `workspace-document-registry`
+ * path every other document uses — never a parallel host, never a
+ * permanently-mounted panel whose tab is hidden.
+ *
+ * ## Resource ownership (stated here, once)
+ *
+ * This module OWNS the open/close of `workspace:game`, the focus it borrows,
+ * and the CONTAINER element every lane mounts into. Sharers:
+ * `components/CenterDocuments.tsx` binds the session's tab hook
+ * ({@link bindLiveDocument}) and reports play-state edges
+ * ({@link syncLiveDocumentPlayState}); the package that runs things registers
+ * what the document DRAWS ({@link registerLiveDocumentContent}, through
+ * `@volter/sdk/host`'s `workspace.liveDocument`) and its panel reports
+ * the container's attach/detach ({@link setLiveDocumentContainer} /
+ * {@link releaseLiveDocumentContainer}); the runtimes that {@link
+ * acquireLiveDocument} are exactly the ones that MOUNT INTO the container —
+ * Play, the module lane's two enter paths, and each per-surface ingest mount
+ * — each acquiring immediately before it reads {@link liveDocumentContainer}.
+ * A dispatcher above them (`ingest/mount-ingest-root.ts`) never acquires: a
+ * second, earlier acquire there could only refuse ahead of the mount that
+ * owns the answer. {@link releaseLiveDocument} is the ONE teardown path and
+ * it is idempotent — a failed play calls it directly, and every ordinary stop
+ * reaches it through the playing → stopped edge.
+ *
+ * ## Why acquiring is asynchronous
+ *
+ * A runtime mounts into the document's own DOM (the registered content's
+ * panel), so the element only exists once React has committed the panel
+ * that this module just opened. `acquireLiveDocument` therefore opens the
+ * document and then waits for that commit, which the panel reports through
+ * {@link setLiveDocumentContainer}.
+ */
+
+import type { LiveDocumentContent, LiveDocumentContentProps } from '@volter/sdk/host';
+import type { ComponentType } from 'react';
+import { GAME_DOCUMENT_ID } from '@volter/sdk/kit/workspace-document-ids';
+import {
+  activateWorkspaceDocument,
+  activeWorkspaceDocumentId,
+  closeWorkspaceDocument,
+  openWorkspaceDocument,
+  openWorkspaceDocuments,
+  supersedeRestoredActivation,
+  type WorkspaceDocumentDescriptor,
+} from '@volter/sdk/kit/workspace-document-registry';
+
+/** How long an acquire waits for the panel's first commit before giving up.
+ *  The caller's failure message ("the game container is not mounted…") is the
+ *  honest report; hanging forever would be worse than a bounded refusal. */
+const CONTAINER_MOUNT_TIMEOUT_MS = 4000;
+
+/** The editor session's binding: the live document exists only while one is bound. */
+interface LiveDocumentHooks {
+  readonly session: true;
+}
+
+let _hooks: LiveDocumentHooks | null = null;
+let _content: LiveDocumentContent | null = null;
+let _container: HTMLElement | null = null;
+let _containerMounted = false;
+let _restoreDocumentId: string | null = null;
+let _wasLive = false;
+/** A runtime acquired the live document and has not released it. */
+let _held = false;
+const _mountWaiters = new Set<() => void>();
+
+/** Reached only when a lane acquires the document before any package
+ *  registered content — a build that mounts nothing never opens it. */
+const NoLiveContent: ComponentType<LiveDocumentContentProps> = () => null;
+
+function descriptor(): WorkspaceDocumentDescriptor | null {
+  const hooks = _hooks;
+  if (!hooks) return null;
+  const content = _content;
+  return {
+    id: GAME_DOCUMENT_ID,
+    title: 'Game',
+    kind: 'game',
+    workspaceRole: 'authored-subject',
+    Content: content?.Content ?? NoLiveContent,
+    // The document-local toolbar — the lane's own — appears only while the
+    // live document is active (§6.3).
+    ...(content?.Toolbar ? { Toolbar: content.Toolbar } : {}),
+    closeable: false,
+    presentation: () => ({ kind: 'workspace', id: GAME_DOCUMENT_ID }),
+  };
+}
+
+/**
+ * Bind this editor session. `useCenterDocuments` calls this in
+ * the same effect that installs the other center documents, and the returned
+ * cleanup releases the document with the session.
+ */
+export function bindLiveDocument(): () => void {
+  const hooks: LiveDocumentHooks = { session: true };
+  _hooks = hooks;
+  return () => {
+    if (_hooks !== hooks) return;
+    releaseLiveDocument();
+    _hooks = null;
+  };
+}
+
+/** The package that runs things registers what the document draws. While
+ *  the document is open, re-registering refreshes its mount slots. */
+export function registerLiveDocumentContent(content: LiveDocumentContent): () => void {
+  _content = content;
+  if (liveDocumentOpen()) {
+    const next = descriptor();
+    if (next) openWorkspaceDocument(next, { activate: false });
+  }
+  return () => {
+    if (_content === content) _content = null;
+  };
+}
+
+/**
+ * Whether a runtime holds the live document: acquired for Play and not yet
+ * released. Documents a project installs while it is held open behind it
+ * rather than in front of it — the person asked for the game.
+ */
+export function liveDocumentHeld(): boolean {
+  return _held && liveDocumentOpen();
+}
+
+/** Whether the live document is currently open. */
+export function liveDocumentOpen(): boolean {
+  return openWorkspaceDocuments().some((d) => d.descriptor.id === GAME_DOCUMENT_ID);
+}
+
+/**
+ * Bring the live document to the front, if it is open. Answers whether it was.
+ *
+ * ▶ IS A DELIBERATE ACT ON THE GAME, and this is the half a BOOT-MOUNTED
+ * ingest was missing. `landIngestBootInEdit` puts the authoring Scene in front
+ * at mount — correctly, because that mount IS edit mode — and until 2026-09-20
+ * nothing moved it back: the ingest transport's ▶ released content time and
+ * left the person looking at the Scene, which for `three-points-waves` is the
+ * honest "No renderable content" card while the points ran unseen behind it
+ * (walk 3, beat 19). A play-time mount already does this for itself
+ * (`deferred-ingest-play.ts` activates this document).
+ *
+ * It activates rather than writing the viewport tab because THIS module owns
+ * `workspace:game`: activation fires the descriptor's `onActivate`, which is
+ * the one place that writes `activeViewportTab = 'play'` — so the tab, the
+ * registry and the input gate cannot drift apart. A caller with no store in
+ * hand (the ingest play control is a pure control surface) needs exactly this.
+ */
+export function activateLiveDocument(): boolean {
+  if (!liveDocumentOpen()) return false;
+  supersedeRestoredActivation();
+  return activateWorkspaceDocument(GAME_DOCUMENT_ID);
+}
+
+/** The container element every lane mounts into, or null while no panel is
+ *  committed. */
+export function liveDocumentContainer(): HTMLElement | null {
+  return _container;
+}
+
+/** The panel's ATTACH half. */
+export function setLiveDocumentContainer(el: HTMLElement): void {
+  _container = el;
+  _containerMounted = true;
+  for (const waiter of [..._mountWaiters]) waiter();
+  _mountWaiters.clear();
+}
+
+/**
+ * The panel's DETACH half, keyed by the element it is letting go of — never
+ * a bare "set null".
+ *
+ * Two panel instances briefly coexist whenever the live document closes and
+ * reopens in one gesture (every ingest mount's `exitActiveIngest()` →
+ * `acquireLiveDocument()` sequence), and React gives no cross-component
+ * ordering promise between the old panel's cleanup ref and the new panel's
+ * attach ref. Measured on bubbo-bubbo (2026-08-21, probe in the mount path):
+ * the acquire resolved `true` in 36ms — the NEW panel's element had attached
+ * — and the container was null anyway, because the OLD panel's cleanup ran
+ * after the attach and clobbered the singleton. Keying the release on the
+ * element makes a stale panel's cleanup a no-op: only the panel that still
+ * OWNS the slot may empty it.
+ */
+export function releaseLiveDocumentContainer(el: HTMLElement): void {
+  if (_container !== el) return;
+  _container = null;
+  _containerMounted = false;
+}
+
+/**
+ * Install the live document and resolve once its container has mounted.
+ *
+ * Called by every runtime that mounts into that container — play, ingest and
+ * module mode — BEFORE it reads {@link liveDocumentContainer}. Resolves `false` when no
+ * session has bound a descriptor, or when the panel did not commit in time; the
+ * caller reports that as its own start failure rather than mounting into
+ * nothing.
+ *
+ * Opening ACTIVATES the document (entering a runtime is a deliberate act on the
+ * game), and remembers whichever document had focus so
+ * {@link releaseLiveDocument} can hand it back.
+ */
+export async function acquireLiveDocument(
+  timeoutMs = CONTAINER_MOUNT_TIMEOUT_MS,
+): Promise<boolean> {
+  const next = descriptor();
+  if (!next) return false;
+  supersedeRestoredActivation();
+  _held = true;
+  if (!liveDocumentOpen()) {
+    _restoreDocumentId = activeWorkspaceDocumentId();
+    openWorkspaceDocument(next);
+  } else {
+    activateWorkspaceDocument(next.id);
+  }
+  if (_containerMounted) return true;
+  return new Promise<boolean>((resolve) => {
+    const waiter = () => {
+      clearTimeout(timer);
+      resolve(true);
+    };
+    const timer = setTimeout(() => {
+      _mountWaiters.delete(waiter);
+      resolve(_containerMounted);
+    }, timeoutMs);
+    _mountWaiters.add(waiter);
+  });
+}
+
+/**
+ * The ONE teardown path: close the live document and give focus back to
+ * whatever held it before the runtime borrowed it. Idempotent — safe from a
+ * failed start and from an ordinary stop, both of which reach it.
+ */
+export function releaseLiveDocument(): void {
+  _held = false;
+  if (!_hooks || !liveDocumentOpen()) {
+    _restoreDocumentId = null;
+    return;
+  }
+  const restore = _restoreDocumentId;
+  _restoreDocumentId = null;
+  // THE LATCH GOES STALE-FALSE HERE, EAGERLY — before React has flushed the
+  // panel's unmount. Closing the document makes "the container is mounted"
+  // untrue at THIS line, but the panel's own detach only
+  // lands on the next React commit, so between here and that commit the latch
+  // used to still say true. A caller that tears a runtime down and
+  // immediately re-acquires (every ingest mount's `exitActiveIngest()` →
+  // `acquireLiveDocument()` sequence) then got an instant `true` from the
+  // stale latch, read the container in the unmount gap, and refused
+  // with "Game container not mounted" — measured on bubbo-bubbo (2026-08-21):
+  // every ▶ after a creation-site write failed this way, because the write is
+  // what first materializes the held ingest session the next play must tear
+  // down. Clearing the latch first makes the re-acquire genuinely WAIT for
+  // the reopened panel's commit, which is the contract its doc claims.
+  _containerMounted = false;
+  // `discardDirty` because the live document is never an authored draft — it
+  // has nothing to save and a close must never be refused.
+  closeWorkspaceDocument(GAME_DOCUMENT_ID, { discardDirty: true });
+  // Closing already activated a neighbour (the registry's own "there is always
+  // an active center document" fallback); restoring the pre-play document is
+  // only a correction of WHICH one, never a rescue from having none.
+  if (restore) activateWorkspaceDocument(restore);
+}
+
+/**
+ * Report the store's live/stopped state on every notify. A runtime ENDING is
+ * the edge that closes the document; the stopped state on its own must not,
+ * because {@link acquireLiveDocument} deliberately runs while the store still
+ * says stopped (a runtime needs the container before it can start).
+ */
+export function syncLiveDocumentPlayState(live: boolean): void {
+  if (_wasLive && !live) releaseLiveDocument();
+  _wasLive = live;
+}
+
+/** Test-only reset — drops the binding and every latch WITHOUT closing. */
+export function __resetLiveDocumentForTest(): void {
+  _hooks = null;
+  _content = null;
+  _container = null;
+  _containerMounted = false;
+  _restoreDocumentId = null;
+  _wasLive = false;
+  _held = false;
+  _mountWaiters.clear();
+}

package/src/kit/live-gesture-lock.ts

@@ -0,0 +1,50 @@
+/**
+ * "A continuous viewport gesture is happening right now" — the one fact the
+ * absorb-by-remount cycle needs from the gizmo.
+ *
+ * A source write remounts the world; a drag that is STILL RUNNING when the
+ * swap lands moves old-scene objects, and the adopted scene snaps them back
+ * to the written values — a human moving a three-cube selection "bit by bit"
+ * watched one member stay behind on every quick successive drag (runhuman
+ * passes 49/54, both ranked it their #1 fix). The design session builds the
+ * new world in parallel but awaits {@link whenLiveGestureIdle} before the
+ * swap, so a drag always completes on the objects it started on.
+ *
+ * Deliberately module-scoped and frameworkless: the setter is the viewport's
+ * `dragging-changed` handler and the consumer is the design session — no
+ * React context reaches both.
+ */
+
+let active = 0;
+let waiters: Array<() => void> = [];
+
+export function beginLiveGesture(): void {
+  active += 1;
+}
+
+export function endLiveGesture(): void {
+  active = Math.max(0, active - 1);
+  if (active === 0) {
+    const resolved = waiters;
+    waiters = [];
+    for (const resolve of resolved) resolve();
+  }
+}
+
+/** Whether any gesture (a drag, or a gesture's still-landing write) holds
+ *  the lock right now — the swap's settle loop re-checks this after each
+ *  wait, because a lock taken in the same task that released the previous
+ *  one can race a waiter that already resolved. */
+export function liveGestureActive(): boolean {
+  return active > 0;
+}
+
+/** Resolves immediately when no gesture is running, else on the current
+ *  gesture's end. */
+export function whenLiveGestureIdle(): Promise<void> {
+  return active === 0
+    ? Promise.resolve()
+    : new Promise((resolve) => {
+        waiters.push(resolve);
+      });
+}

package/src/kit/live-seam-evidence.ts

@@ -0,0 +1,11 @@
+/** One current-process evidence ledger shared by panels, relay consumers,
+ * coverage, status, and Doctor. It is intentionally ephemeral: project source
+ * remains truth and no Volter evidence sidecar is invented. */
+
+import { SeamEvidenceLedger, type SeamEvidenceReceipt } from '@volter/project/adapter';
+
+export const liveSeamEvidence = new SeamEvidenceLedger();
+
+export function recordLiveSeamEvidence(receipt: SeamEvidenceReceipt): void {
+  liveSeamEvidence.record(receipt);
+}