@volter/editor-core 0.5.57

package/src/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 vgai 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 { presentedPixiFrame } from './canvas-preview-frames';
+import { snapshotLiveFrame } from './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 presentedPixiFrame(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/live-document.ts

@@ -0,0 +1,279 @@
+/**
+ * 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/editor-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/editor-sdk/host';
+import type { ComponentType } from 'react';
+import { GAME_DOCUMENT_ID } from './workspace-document-ids';
+import {
+  activateWorkspaceDocument,
+  activeWorkspaceDocumentId,
+  closeWorkspaceDocument,
+  openWorkspaceDocument,
+  openWorkspaceDocuments,
+  type WorkspaceDocumentDescriptor,
+} from './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;
+
+interface LiveDocumentHooks {
+  /** The tab hand-off: activating the live document selects the play tab. */
+  onActivate(): void;
+}
+
+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;
+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 }),
+    onActivate: () => hooks.onActivate(),
+  };
+}
+
+/**
+ * Bind this editor session's tab hook. `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(hooks: LiveDocumentHooks): () => void {
+  _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 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`'s `store.setActiveViewportTab('play')`).
+ *
+ * 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;
+  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;
+  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 {
+  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;
+  _mountWaiters.clear();
+}

package/src/live-module-source.ts

@@ -0,0 +1,230 @@
+/**
+ * The module→`Object3D` step, IN THE BROWSER — the live twin of the bake
+ * lane's Node-side `module-source.ts`
+ * (`catalog/project-source/src/tools/module-source.ts`), and deliberately the
+ * SAME contract: a project TypeScript module whose export builds a native
+ * `THREE.Object3D`. `project.bake.module` / `project.bake.preview` /
+ * `vgai screenshot <module>` already define that contract; the live modeling
+ * document opens the same thing, so a module that bakes opens, and a module
+ * that opens bakes (docs/BLENDER-PARITY.md §The model file).
+ *
+ * TWO HALVES, ONE CONTRACT. Node imports a `file://` url and has no GPU; the
+ * browser imports the dev server's `/@fs/` url and IS the GPU. Nothing else
+ * differs, which is why this file re-states the resolution rather than
+ * importing the tool's copy: that copy is `host: 'node'` capability source
+ * (`node:fs/promises`, `node:url`) that a project's own tsconfig excludes from
+ * its browser build. Sharing the module would drag Node into the editor
+ * bundle; sharing the CONTRACT is what matters, and the contract is small
+ * enough to be stated twice and obviously identical.
+ *
+ * DETECTION IS STRUCTURAL, not a filename convention — the quarks precedent
+ * (`components/asset-viewers/JsonAssetDocument.tsx`: three.quarks names no
+ * extension of its own, so the file's own structure is what says whether it is
+ * a particle document). There is no `.model.ts`: a project `.ts`/`.tsx`
+ * whose export RESOLVES to an `Object3D` is a model module, and everything
+ * else falls back to the ordinary source viewer.
+ */
+
+import { liveModuleImportUrl } from '@volter/editor-sdk/session/project-module-url';
+import type * as THREE from 'three';
+
+/** Why this module is not a live model module — the sentence the document
+ *  shows, and the reason it fell back to the source viewer. */
+export type LiveModuleRefusal =
+  /** Nothing importable at all: a syntax error, a throwing top level, a
+   *  missing dependency. The one refusal that is USUALLY a defect in a module
+   *  that WAS a model module a moment ago, which is why the document keeps its
+   *  last good root on screen for it. */
+  | { readonly kind: 'import-failed'; readonly message: string; readonly stack?: string }
+  /** It imported fine, it is simply not a model module. */
+  | { readonly kind: 'not-a-model'; readonly message: string };
+
+export interface LiveModuleBuild {
+  readonly root: THREE.Object3D;
+  /** Which export produced it — `default`, or the single named export. */
+  readonly exportName: string;
+  /** The BUILDER's own teardown, when the export returned a build result that
+   *  carried one. The document runs it in place of the generic graph dispose:
+   *  a rig holds mixers, actions and materials a `traverse` walk cannot see. */
+  readonly dispose?: () => void;
+}
+
+export class LiveModuleError extends Error {
+  constructor(readonly refusal: LiveModuleRefusal) {
+    super(refusal.message);
+    this.name = 'LiveModuleError';
+  }
+}
+
+/** The module-namespace keys that are never a candidate export. */
+function candidateExportNames(namespace: Record<string, unknown>): string[] {
+  return Object.keys(namespace).filter(
+    (name) => name !== '__esModule' && name !== 'Symbol.toStringTag',
+  );
+}
+
+function isObject3D(value: unknown): value is THREE.Object3D {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    (value as { isObject3D?: unknown }).isObject3D === true
+  );
+}
+
+/**
+ * Pick the export this module offers as its subject, matching the bake lane's
+ * `exportName` default: the DEFAULT export, or — when there is no default —
+ * the single named export. Two named exports and no default is ambiguous and
+ * refuses by name rather than guessing; the bake verbs make the caller say
+ * which one, and a document has nobody to ask.
+ */
+export function pickLiveModuleExport(
+  namespace: Record<string, unknown>,
+): { readonly name: string; readonly value: unknown } | LiveModuleRefusal {
+  if ('default' in namespace) return { name: 'default', value: namespace['default'] };
+  const named = candidateExportNames(namespace);
+  if (named.length === 0) {
+    return { kind: 'not-a-model', message: 'This module exports nothing.' };
+  }
+  if (named.length > 1) {
+    return {
+      kind: 'not-a-model',
+      message:
+        `This module has no default export and ${named.length} named exports ` +
+        `(${named.join(', ')}), so there is no single subject to build. A model module ` +
+        'default-exports its builder.',
+    };
+  }
+  return { name: named[0]!, value: namespace[named[0]!] };
+}
+
+/**
+ * THE TWO SHAPES A MODEL MODULE MAY PRODUCE — the same pair the Node twin
+ * normalizes (`catalog/project-source/src/tools/module-source.ts`'s
+ * `asModuleBuild`), because a module that bakes must open and a module that
+ * opens must bake:
+ *
+ * 1. a bare `THREE.Object3D`;
+ * 2. a BUILD RESULT `{ root, animations?, dispose? }` — what every parametric
+ *    lib in the kit returns (`createBird`'s `BirdBuild` and its descendants),
+ *    and what `bakeObject3DSource`'s `build` callback has always taken.
+ *
+ * `animations` is written onto `root.animations`, three's own carrier for a
+ * model's clips — so the clip list travels with the graph the document mounts
+ * and every reader downstream (the Object3D document session, its animation
+ * transport) finds it where it finds a GLTF's.
+ */
+function asLiveModuleBuild(
+  built: unknown,
+): { root: THREE.Object3D; dispose?: () => void } | undefined {
+  if (isObject3D(built)) return { root: built };
+  if (!built || typeof built !== 'object') return undefined;
+  const result = built as { root?: unknown; animations?: unknown; dispose?: unknown };
+  if (!isObject3D(result.root)) return undefined;
+  const root = result.root;
+  if (Array.isArray(result.animations) && root.animations.length === 0) {
+    root.animations = result.animations as THREE.AnimationClip[];
+  }
+  return {
+    root,
+    ...(typeof result.dispose === 'function'
+      ? { dispose: () => (result.dispose as () => void).call(built) }
+      : {}),
+  };
+}
+
+/** What the export returned, for a refusal that can be acted on — `object`
+ *  alone cannot tell a build result with a mistyped key from a wrong value. */
+function describeReturn(built: unknown): string {
+  if (built === undefined) return 'undefined';
+  if (built === null) return 'null';
+  if (typeof built !== 'object') return typeof built;
+  if (Array.isArray(built)) return 'an array';
+  const keys = Object.keys(built);
+  return keys.length > 0
+    ? `an object with keys ${keys.slice(0, 8).join(', ')}`
+    : 'an object with no own keys';
+}
+
+const ACCEPTED_SHAPES =
+  'a model module returns a THREE.Object3D, or a build result ' +
+  '`{ root, animations?, dispose? }` whose `root` is one.';
+
+/**
+ * Resolve a picked export to an `Object3D`. A FUNCTION is called (its result
+ * may be a promise — the bake lane awaits it too); a VALUE is taken as-is, so
+ * `export default new THREE.Group()` is as legitimate a model module as
+ * `export default () => …`.
+ */
+export async function resolveLiveModuleExport(
+  name: string,
+  value: unknown,
+): Promise<LiveModuleBuild | LiveModuleRefusal> {
+  const direct = asLiveModuleBuild(value);
+  if (direct) return { ...direct, exportName: name };
+  if (typeof value !== 'function') {
+    return {
+      kind: 'not-a-model',
+      message:
+        `Export '${name}' is ${describeReturn(value)}, not a function and not a model — ` +
+        ACCEPTED_SHAPES,
+    };
+  }
+  let built: unknown;
+  try {
+    built = await (value as () => unknown)();
+  } catch (error) {
+    return {
+      kind: 'import-failed',
+      message: `Export '${name}' threw while building: ${messageOf(error)}`,
+      ...(error instanceof Error && error.stack ? { stack: error.stack } : {}),
+    };
+  }
+  const build = asLiveModuleBuild(built);
+  if (!build) {
+    return {
+      kind: 'not-a-model',
+      message: `Export '${name}' ran but returned ${describeReturn(built)} — ${ACCEPTED_SHAPES}`,
+    };
+  }
+  return { ...build, exportName: name };
+}
+
+function messageOf(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * Import `modulePath` from the dev server and build its `Object3D`.
+ *
+ * `revision` is the document's rebuild counter — see
+ * {@link liveModuleImportUrl} for why the url carries it and why that is only
+ * half the freshness story.
+ *
+ * Throws {@link LiveModuleError}; the `refusal.kind` is what the caller routes
+ * on (`not-a-model` falls back to the source viewer, `import-failed` keeps the
+ * last good root and shows the failure).
+ */
+export async function buildLiveModuleObject3D(
+  projectRoot: string,
+  modulePath: string,
+  revision: number,
+): Promise<LiveModuleBuild> {
+  let namespace: Record<string, unknown>;
+  try {
+    namespace = (await import(
+      /* @vite-ignore */ liveModuleImportUrl(projectRoot, modulePath, revision)
+    )) as Record<string, unknown>;
+  } catch (error) {
+    throw new LiveModuleError({
+      kind: 'import-failed',
+      message: messageOf(error),
+      ...(error instanceof Error && error.stack ? { stack: error.stack } : {}),
+    });
+  }
+  const picked = pickLiveModuleExport(namespace);
+  if ('kind' in picked) throw new LiveModuleError(picked);
+  const resolved = await resolveLiveModuleExport(picked.name, picked.value);
+  if ('kind' in resolved) throw new LiveModuleError(resolved);
+  return resolved;
+}