@volter/editor-game 0.5.65

package/src/react/story-paint-bounds.ts

@@ -0,0 +1,94 @@
+/**
+ * The union of what a mounted DOM story actually PAINTS, in the mount box's
+ * own authored pixels — the measurement half of "mount in the truth, frame the
+ * subject" for the UI board (the capture lane's alpha-bounds scan is the same
+ * decision made on pixels; a live card cannot rasterize per frame, so this
+ * walks the DOM instead).
+ *
+ * The filter matters more than the union: a translated uGUI screen is nested
+ * full-bleed wrapper boxes (anchor stretch, transparent) around a few painted
+ * leaves, so a naive union of ALL element rects is always the whole mount box
+ * and the crop never fires. An element counts only when it paints something a
+ * viewer can see: a non-transparent background, a background image, replaced
+ * content, a visible border/shadow, or its own text.
+ */
+
+/** True when this element itself puts pixels on screen. */
+export function elementPaints(element: Element): boolean {
+  const tag = element.tagName;
+  if (
+    tag === 'IMG' ||
+    tag === 'VIDEO' ||
+    tag === 'CANVAS' ||
+    tag === 'svg' ||
+    tag === 'SVG' ||
+    tag === 'PICTURE'
+  ) {
+    return true;
+  }
+  const style = getComputedStyle(element);
+  if (style.visibility === 'hidden' || style.display === 'none') return false;
+  if (backgroundColorPaints(style.backgroundColor)) return true;
+  if (style.backgroundImage && style.backgroundImage !== 'none') return true;
+  if (style.boxShadow && style.boxShadow !== 'none') return true;
+  if (
+    style.borderStyle !== 'none' &&
+    style.borderStyle !== '' &&
+    (parseFloat(style.borderTopWidth) > 0 ||
+      parseFloat(style.borderRightWidth) > 0 ||
+      parseFloat(style.borderBottomWidth) > 0 ||
+      parseFloat(style.borderLeftWidth) > 0)
+  ) {
+    return true;
+  }
+  for (const node of element.childNodes) {
+    if (node.nodeType === Node.TEXT_NODE && (node.textContent ?? '').trim() !== '') return true;
+  }
+  return false;
+}
+
+/** `transparent` serializes as `rgba(0, 0, 0, 0)`; anything with alpha paints. */
+function backgroundColorPaints(color: string): boolean {
+  if (!color || color === 'transparent') return false;
+  const rgba = /^rgba\(\s*[\d.]+\s*,\s*[\d.]+\s*,\s*[\d.]+\s*,\s*([\d.]+)\s*\)$/.exec(color);
+  if (rgba) return parseFloat(rgba[1]!) > 0;
+  return true;
+}
+
+export interface PaintedBounds {
+  readonly x: number;
+  readonly y: number;
+  readonly width: number;
+  readonly height: number;
+}
+
+/**
+ * Union of the painted descendants' boxes in the mount box's authored px, or
+ * `null` when nothing paints. Rects are read through the live client transform
+ * (the board zooms its canvas), so the mount box's own client width supplies
+ * the scale — self-normalizing, no zoom parameter to drift.
+ */
+export function paintedContentBounds(
+  content: HTMLElement,
+  rectOf: (element: Element) => DOMRect = (element) => element.getBoundingClientRect(),
+): PaintedBounds | null {
+  const home = rectOf(content);
+  const authoredWidth = content.offsetWidth;
+  if (home.width <= 0 || authoredWidth <= 0) return null;
+  const scale = home.width / authoredWidth;
+  let left = Number.POSITIVE_INFINITY;
+  let top = Number.POSITIVE_INFINITY;
+  let right = Number.NEGATIVE_INFINITY;
+  let bottom = Number.NEGATIVE_INFINITY;
+  for (const element of content.querySelectorAll('*')) {
+    if (!elementPaints(element)) continue;
+    const rect = rectOf(element);
+    if (rect.width <= 0 || rect.height <= 0) continue;
+    left = Math.min(left, (rect.left - home.left) / scale);
+    top = Math.min(top, (rect.top - home.top) / scale);
+    right = Math.max(right, (rect.right - home.left) / scale);
+    bottom = Math.max(bottom, (rect.bottom - home.top) / scale);
+  }
+  if (right <= left || bottom <= top) return null;
+  return { x: left, y: top, width: right - left, height: bottom - top };
+}

package/src/react/ui-board-document.tsx

@@ -0,0 +1,101 @@
+import { registerAvailableWorkspaceDocument } from '@volter/editor-core/workspace-available-documents';
+/**
+ * THE `UI` BOARD's DOCUMENT — what `ui-component-board.ts` installs, kept in
+ * its own module so the registration's eager closure is the verdict and
+ * nothing else. This half reaches the host's whole root-document machinery
+ * (and through it the design-time layer stack); loading that at contribution
+ * time for a project that has no dom stories is what the lazy `install`
+ * contract exists to avoid — the 2D board's own reason, applied to all three.
+ *
+ * It was `openUiBoard` inside `@editor/components/world-documents.tsx`, one
+ * arm of a literal table of three media that the host reconciled against a
+ * CSF census it also imported. What is dom-specific about it — that its
+ * medium is `dom`, that it exists because this project has `dom` stories,
+ * what a human should be told when it does not, and that its captured frame
+ * round-trips through the remembered portable story — travels here. What is
+ * HOST machinery stays host and is called through: `RootDocumentContent` (the
+ * board substrate every root document mounts, which draws the infinite canvas,
+ * the selection overlay, the rulers and the surface-state explanation) and the
+ * workspace document registry.
+ *
+ * A DOM ROOT IS NOT WHY THIS BOARD EXISTS — it only decides what the board is
+ * a document OF. With a dom root the board carries that root's provenance and
+ * its route, so `activateRootDocument(rootId)` reaches it; without one the
+ * board is still the project's UI component gallery, mounted rootless on
+ * `projectStoryBoardDescriptor()`.
+ */
+
+import {
+  designTimeRootDescriptors,
+  projectStoryBoardDescriptor,
+  rememberedPortableStory,
+} from '@volter/editor-core/authoring/design-time-layers';
+import type { ComponentBoardContext } from '@volter/editor-core/component-board-registry';
+import { RootDocumentContent } from '@volter/editor-core/components/world-documents';
+import type { DocumentPreviewSource } from '@volter/editor-core/document-preview-source';
+import { getCurrentProject } from '@volter/editor-core/project-manager';
+import {
+  getProjectPreviewStories,
+  subscribeProjectStoryModules,
+} from '@volter/editor-core/stories/story-registry';
+import { UI_COMPONENTS_DOCUMENT_ID } from '@volter/editor-core/workspace-document-ids';
+import type { WorkspaceDocumentContentProps } from '@volter/editor-core/workspace-document-registry';
+
+import { UI_COMPONENTS_TITLE } from './ui-board-title';
+
+const uiCanvasPreview: DocumentPreviewSource = {
+  revision: () =>
+    JSON.stringify(getProjectPreviewStories().map(({ id, modulePath }) => [id, modulePath])),
+  subscribe: subscribeProjectStoryModules,
+  capture: async ({ width, height }) => {
+    const { captureDomStoryBoardPreview } = await import('@volter/editor-core/stories/story-capture');
+    return captureDomStoryBoardPreview(width, height);
+  },
+};
+
+export function installUiBoard({ store, composite }: ComponentBoardContext): void {
+  const descriptor =
+    designTimeRootDescriptors(composite).find((root) => root.kind === 'dom') ??
+    projectStoryBoardDescriptor();
+  const Content = (props: WorkspaceDocumentContentProps) => (
+    <RootDocumentContent {...props} composite={composite} descriptor={descriptor} store={store} />
+  );
+  registerAvailableWorkspaceDocument(
+    {
+      id: UI_COMPONENTS_DOCUMENT_ID,
+      title: UI_COMPONENTS_TITLE,
+      kind: 'world',
+      workspaceRole: 'authored-subject',
+      provenance: {
+        rootId: descriptor.worldId,
+        ...(descriptor.path ? { sourcePath: descriptor.path } : {}),
+      },
+      Content,
+      preview: uiCanvasPreview,
+      presentation: () => {
+        // Round-trip the board's active frame: a captured view names the
+        // story it was on (the design ledger's board story selector).
+        const projectRoot = getCurrentProject()?.rootPath;
+        const story = projectRoot
+          ? rememberedPortableStory(projectRoot, descriptor.worldId)
+          : undefined;
+        return {
+          kind: 'workspace',
+          id: UI_COMPONENTS_DOCUMENT_ID,
+          ...(story ? { story } : {}),
+        };
+      },
+      onActivate: () => store.setActiveViewportTab('edit'),
+    },
+    // A board NEVER steals focus — presence is answered asynchronously, so a
+    // board that arrives late would otherwise yank the author off whatever
+    // they were looking at (measured: the canvas root's `Scene` opened, then a
+    // board landed a second later and took the tab).
+    {
+      category: 'canvas',
+      default: !composite
+        .childAdapters()
+        .some((root) => root.kind === 'three' || root.kind === 'canvas'),
+    },
+  );
+}

package/src/react/ui-board-title.ts

@@ -0,0 +1,9 @@
+/** The tab reads `UI`, the peer of `Scene` and `3D` in the center strip. The
+ *  document ID keeps its longer historical spelling because persisted layouts
+ *  address panels by id (and deriving either from the root only made the panel
+ *  identity churn on a rename, stranding the old panel in every layout).
+ *
+ *  Its own module because the registration reads it for the host's absence
+ *  prose while the DOCUMENT reads it for the tab, and the two halves are
+ *  deliberately in different closures. */
+export const UI_COMPONENTS_TITLE = 'UI';

package/src/react/ui-component-board.ts

@@ -0,0 +1,72 @@
+/**
+ * THE `UI` BOARD's registration — the dom medium's answer to
+ * `@editor/component-board-registry` (WORK.md §The open-source launch item
+ * 18a).
+ *
+ * It was one arm of a literal table of three media inside
+ * `@editor/components/world-documents.tsx`, which the host reconciled against
+ * a CSF census it imported itself. What is dom-specific about it — that its
+ * medium is `dom`, that the board exists because this project has `dom`
+ * stories, and what a human should be told when it does not — lives here; the
+ * document it installs is `ui-board-document.tsx`, loaded only for a project
+ * whose verdict is `'present'`.
+ */
+
+import { commandLine } from '@volter/editor-core/product-command';
+import type { ComponentBoard, ComponentBoardContext } from '@volter/editor-core/component-board-registry';
+import { editorConsole } from '@volter/editor-core/editor-console';
+import {
+  getStoryMediaPresence,
+  subscribeStoryMediaPresence,
+} from '../host/stories/story-media-presence';
+import { projectStoriesReady, subscribeProjectStoryModules } from '@volter/editor-core/stories/story-registry';
+import { UI_COMPONENTS_DOCUMENT_ID } from '@volter/editor-core/workspace-document-ids';
+import { UI_COMPONENTS_TITLE } from './ui-board-title';
+
+export const uiComponentBoard: ComponentBoard = {
+  medium: 'dom',
+  owner: '@volter/editor-game/react/ui-board',
+  documentId: UI_COMPONENTS_DOCUMENT_ID,
+  title: UI_COMPONENTS_TITLE,
+  // A COMPONENT BOARD EXISTS BECAUSE THE PROJECT HAS STORIES OF ITS MEDIUM,
+  // and for no other reason (owner ruling, 2026-08-15; ARCHITECTURE-CORE
+  // §center-surface ontology). Root kinds are irrelevant: a project whose UI
+  // components live inside an ingested game — no `dom` root in its manifest at
+  // all — still gets this board the moment one of them declares a story.
+  //
+  // `null` while discovery has not published: an empty UNREADY registry is
+  // boot in flight, never a verdict (`story-registry.ts` says so at the flag
+  // itself). That tri-state is what the host used to spell for itself as
+  // `projectStoriesReady()` in its own gap thunks.
+  presence: () =>
+    !projectStoriesReady() ? null : getStoryMediaPresence().dom ? 'present' : 'absent',
+  subscribe: (listener) => {
+    // Two signals, because the verdict is a function of both: the census
+    // (which media the project's stories declare) and the discovery flag that
+    // decides whether the census counts yet.
+    const stopPresence = subscribeStoryMediaPresence(listener);
+    const stopRegistry = subscribeProjectStoryModules(listener);
+    return () => {
+      stopPresence();
+      stopRegistry();
+    };
+  },
+  install: async (context: ComponentBoardContext) => {
+    try {
+      const { installUiBoard } = await import('./ui-board-document');
+      installUiBoard(context);
+    } catch (error: unknown) {
+      editorConsole.error(
+        `Failed to load the ${UI_COMPONENTS_TITLE} board: ${String(error)}`,
+        'scene',
+      );
+      throw error;
+    }
+  },
+  absentReason: () =>
+    `This project has no ${UI_COMPONENTS_TITLE} board (${UI_COMPONENTS_DOCUMENT_ID}): board ` +
+    "presence keys on STORIES, not on roots, and none of this project's stories declares the " +
+    '"dom" medium. Declare it — a manifest root entry naming the story\'s module, or a ' +
+    `\`vgai.adapter.ts\` regionInclude that covers it — and the board appears. ${commandLine('console')} ` +
+    'names every story it could not place.',
+};

package/src/services/audio-pose-guard.ts

@@ -0,0 +1,81 @@
+/**
+ * THE AUDIO-POSE GUARD: the editor never drives Web Audio with a pose that is
+ * not a number.
+ *
+ * ## The failure this ends
+ *
+ * The editor draws scene graphs it did not author. `WebGLRenderer.render`
+ * calls `scene.updateMatrixWorld()` (three's own first line, gated only on
+ * `scene.matrixWorldAutoUpdate`), and that recursion reaches every
+ * `THREE.AudioListener` / `THREE.PositionalAudio` in the tree. Both override
+ * `updateMatrixWorld` to push their world pose straight into Web Audio via
+ * `AudioParam.linearRampToValueAtTime`, which **throws** on a non-finite
+ * value. So one NaN anywhere above an audio node turns the editor's own draw
+ * of an adopted play scene into a thrown error, once per frame.
+ *
+ * The NaN is not hypothetical and its cause is already measured in this repo
+ * (`content-bounds.ts`, same measurement, same game): a physics binding writes
+ * `object.matrix` from worker buffers the worker has not answered into yet, so
+ * at frame zero real nodes carry `NaN` transforms. In racing-game that
+ * propagates two ways — a `<PositionalAudio>` parented under the cannon-driven
+ * chassis, and the game camera, whose pose is lerped from a physics-derived
+ * speed and which every drei-minted `AudioListener` is a child of. A single
+ * NaN lerp poisons that camera permanently; there is no re-seed.
+ *
+ * (The design-time half of the same root cause is fixed differently and
+ * upstream: `authoring/design-time-settle.ts` runs the world's physics for a
+ * bounded settle at mount, so Edit mode is no longer looking at unanswered
+ * worker buffers at all. This guard is what covers PLAY, where the game's own
+ * loop is running and the editor is a second reader of its graph.)
+ *
+ * ## Why the guard is on the audio node, and not on the render call
+ *
+ * The throw happens INSIDE three's `updateMatrixWorld` recursion, so nothing
+ * that wraps `composer.render` can intercept a single node, and
+ * `matrixWorldAutoUpdate` cannot help: the subclass body runs after
+ * `super.updateMatrixWorld()` regardless of any flag. The one honest intercept
+ * is the two prototypes themselves. Prototype-level (not per-instance) is
+ * required because these nodes are minted LATE — drei's `<PositionalAudio>`
+ * does `camera.add(new AudioListener())` in an effect after its buffer
+ * resolves — so any walk done at adoption time would miss them.
+ *
+ * Patching a library prototype to host a foreign game is an established
+ * mechanism here, not a new one: `@volter/threejs-runtime/adapter/ingest/scene-capture` traps
+ * `WebGLRenderer.prototype.render` for exactly the same reason (the host must
+ * observe a game it does not own, at a seam the game never offered).
+ *
+ * ## What it does, precisely
+ *
+ * The scene graph stays EXACTLY correct — `Object3D.prototype.updateMatrixWorld`
+ * (which is what both overrides call as `super`) always runs, so children,
+ * bounds, picking and selection see the truth including the NaN. Only the Web
+ * Audio push is conditional: a running context and finite pose use three's
+ * own implementation; otherwise the node keeps its last good audio pose.
+ * A suspended context cannot consume pose ramps, so scheduling them every
+ * render would grow its automation queue while its audio clock stands still.
+ *
+ * The shared engine guard also installs through setupAudio in exported games.
+ * Its prototype marker prevents duplicate wrapping when the packaged editor
+ * and source-served runtime import separate copies against the same Three.
+ */
+
+import { editorHost } from '@volter/editor-sdk/host';
+import { installAudioPoseGuard as installSharedAudioPoseGuard } from '@volter/game-runtime/audio/pose-guard';
+
+export { audioPoseUpdatesDropped } from '@volter/game-runtime/audio/pose-guard';
+
+let reported = false;
+
+/** Attach the editor diagnostic to the shared runtime guard. */
+export function installAudioPoseGuard(): void {
+  installSharedAudioPoseGuard((type) => {
+    if (reported) return;
+    reported = true;
+    editorHost().console.log(
+      `[audio-pose-guard] dropped a Web Audio pose update for a ${type} whose ` +
+        'world matrix is not finite — the scene graph is unchanged and the node keeps its ' +
+        'last good pose. Reported once; see audioPoseUpdatesDropped() for the running count.',
+      'authoring',
+    );
+  });
+}

package/src/services/game-audio-unlock.ts

@@ -0,0 +1,48 @@
+/**
+ * HOST-LEVEL audio unlock for game-created AudioContexts.
+ *
+ * A game running in the editor's page can create its AudioContext before the
+ * visitor's first gesture (survivor's auto-attack lands kills while they are
+ * still reading), and browsers with a strict autoplay policy then hold it
+ * suspended until `resume()` runs INSIDE a trusted input handler. The game's
+ * own unlock listeners go through the realm's gated re-dispatch, which is no
+ * longer that trusted stack — two human passes heard both flagship canvas
+ * games silent on first load and cured them only by restarting under a
+ * gesture (runhuman 23/33).
+ *
+ * The EDITOR owns the page, so it does what a game cannot: wrap the page's
+ * AudioContext constructor once at boot to track instances, and resume any
+ * suspended one from capture-phase pointerdown/keydown handlers — the real,
+ * trusted stack. Contexts already running are untouched; the listeners stay
+ * (cheap) so a context created later unlocks on the next gesture.
+ */
+
+const tracked = new Set<WeakRef<AudioContext>>();
+
+function resumeSuspended(): void {
+  for (const ref of tracked) {
+    const ctx = ref.deref();
+    if (!ctx || ctx.state === 'closed') {
+      tracked.delete(ref);
+      continue;
+    }
+    if (ctx.state === 'suspended') void ctx.resume();
+  }
+}
+
+/** Install once at editor boot (main.tsx). Idempotent. */
+export function installGameAudioUnlock(): void {
+  const host = window as unknown as { __vgaiAudioUnlock?: boolean } & typeof window;
+  if (host.__vgaiAudioUnlock) return;
+  host.__vgaiAudioUnlock = true;
+  const Orig = window.AudioContext;
+  if (typeof Orig !== 'function') return;
+  window.AudioContext = class extends Orig {
+    constructor(...args: ConstructorParameters<typeof AudioContext>) {
+      super(...args);
+      tracked.add(new WeakRef(this));
+    }
+  };
+  window.addEventListener('pointerdown', resumeSuspended, { capture: true });
+  window.addEventListener('keydown', resumeSuspended, { capture: true });
+}