@volter/editor-game 0.5.65

package/src/host/stories/story-media-presence.ts

@@ -0,0 +1,152 @@
+/**
+ * WHICH COMPONENT BOARDS THIS PROJECT HAS — the one answer all three boards'
+ * existence keys on.
+ *
+ * A component board exists because the project has STORIES of that board's
+ * medium, never because it declares a root of some kind (owner ruling,
+ * 2026-08-15; ARCHITECTURE-CORE §center-surface ontology). Root kinds are
+ * irrelevant to presence: a project with a three root and no three story has
+ * nothing to lay out on a 3D board, and a project whose UI components live
+ * inside an ingested game — no `dom` root anywhere in its manifest — still has
+ * a UI board the moment one of those components declares a story.
+ *
+ * ## Medium is DECLARED, not mounted
+ *
+ * ARCHITECTURE-CORE §Zero inference: the system answers this question from
+ * the story's CSF tag, the adapter's `include`/`mounts`, and the manifest
+ * root entry. See `story-declared-medium.ts`. A story the declarations
+ * cannot place is a named gap — it does not create a board, and nothing
+ * mounts it to guess.
+ *
+ * ## It is a LATCHING answer, and that is deliberate
+ *
+ * Classification is now synchronous, but a registry refresh can still
+ * replace one settled answer with another. During a refresh the PREVIOUS
+ * verdict stands rather than collapsing to "no boards": a project that has
+ * boards must not have them blink out of the workspace every time a story
+ * file is saved. The first pass over an empty registry therefore reports
+ * every medium false — a project with no stories has never had a board and
+ * never gets one — while a later pass only ever replaces one settled answer
+ * with another.
+ *
+ * A pass superseded by a newer registry change is abandoned; only the newest
+ * pass publishes.
+ */
+
+import { getProjectStoryRegions } from '@volter/editor-core/stories/project-story-regions';
+import {
+  __resetUndeclaredStoryMediumReportsForTest,
+  declaredStoryMedium,
+  reportUndeclaredStoryMedium,
+  type StoryMedium,
+} from '@volter/editor-core/stories/story-declared-medium';
+import { getProjectStoryModules, subscribeProjectStoryModules } from '@volter/editor-core/stories/story-registry';
+
+/** Which component boards the project's stories call for. */
+export interface StoryMediaPresence {
+  /** ≥1 story declared as `three` — the 3D board's existence. */
+  readonly three: boolean;
+  /** ≥1 story declared as `canvas` — the 2D board's existence. */
+  readonly canvas: boolean;
+  /** ≥1 story declared as `dom` — the UI board's existence. */
+  readonly dom: boolean;
+}
+
+const NONE: StoryMediaPresence = { three: false, canvas: false, dom: false };
+
+let _presence: StoryMediaPresence = NONE;
+let _pass = 0;
+const _listeners = new Set<() => void>();
+let _subscribed = false;
+
+/** The current verdict (stable reference between changes). */
+export function getStoryMediaPresence(): StoryMediaPresence {
+  ensureSubscribed();
+  return _presence;
+}
+
+/** Subscribe to verdict changes. Returns an unsubscribe function. */
+export function subscribeStoryMediaPresence(listener: () => void): () => void {
+  ensureSubscribed();
+  _listeners.add(listener);
+  return () => {
+    _listeners.delete(listener);
+  };
+}
+
+function ensureSubscribed(): void {
+  if (_subscribed) return;
+  _subscribed = true;
+  subscribeProjectStoryModules(() => {
+    void recomputeStoryMediaPresence();
+  });
+  void recomputeStoryMediaPresence();
+}
+
+function publish(next: StoryMediaPresence): void {
+  if (
+    next.three === _presence.three &&
+    next.canvas === _presence.canvas &&
+    next.dom === _presence.dom
+  )
+    return;
+  _presence = next;
+  for (const listener of _listeners) listener();
+}
+
+function classifyDeclared(story: { readonly modulePath?: string }): StoryMedium | undefined {
+  const declared = declaredStoryMedium({
+    modulePath: story.modulePath,
+    regions: getProjectStoryRegions(),
+  });
+  if (declared.medium) return declared.medium;
+  if (story.modulePath) reportUndeclaredStoryMedium(story.modulePath, declared.reason);
+  return undefined;
+}
+
+/**
+ * Re-read the open project's story media from declarations. Exported so a
+ * caller that just refreshed the registry can await the verdict instead of
+ * racing it — the subscription above drives the ordinary case.
+ *
+ * Never throws. Never mounts. An undeclared story is named once and does not
+ * count toward any board.
+ */
+export async function recomputeStoryMediaPresence(): Promise<StoryMediaPresence> {
+  const pass = ++_pass;
+  const stories = getProjectStoryModules().flatMap((module_) =>
+    module_.ok
+      ? module_.stories.map((story) => ({ ...story, modulePath: module_.modulePath }))
+      : [],
+  );
+
+  // The empty registry is the one case with no measuring to do, and the one
+  // case that must be able to take boards AWAY (a project whose last story was
+  // deleted, and — the common case — a project that never had one).
+  if (stories.length === 0) {
+    publish(NONE);
+    return _presence;
+  }
+
+  const found: Record<StoryMedium, boolean> = { three: false, canvas: false, dom: false };
+  for (const story of stories) {
+    const medium = classifyDeclared(story);
+    if (medium) found[medium] = true;
+    if (pass !== _pass) return _presence;
+  }
+  const { three, canvas, dom } = found;
+  if (pass !== _pass) return _presence;
+  publish({ three, canvas, dom });
+  return _presence;
+}
+
+/** Test-only: forget the current verdict and the registry subscription, so a
+ *  suite can drive `recomputeStoryMediaPresence` against its own fixtures
+ *  without a previous suite's answer latching into it. */
+export function __resetStoryMediaPresenceForTest(): void {
+  _presence = NONE;
+  _pass = 0;
+  _listeners.clear();
+  _subscribed = false;
+  __resetUndeclaredStoryMediumReportsForTest();
+}

package/src/host/surface-content.ts

@@ -0,0 +1,87 @@
+import type * as THREE from 'three';
+
+const RENDERABLE_DOM_TAGS = new Set([
+  'canvas',
+  'svg',
+  'img',
+  'picture',
+  'video',
+  'input',
+  'button',
+]);
+const NON_RENDERING_DOM_TAGS = new Set(['script', 'style', 'template']);
+
+function elementIsHidden(element: Element): boolean {
+  if (element.hasAttribute('hidden')) return true;
+  if (typeof getComputedStyle !== 'function') return false;
+  const style = getComputedStyle(element);
+  return style.display === 'none' || style.visibility === 'hidden' || style.opacity === '0';
+}
+
+function styledBoxRenders(element: Element): boolean {
+  if (typeof getComputedStyle !== 'function') return false;
+  const style = getComputedStyle(element);
+  const rect = element.getBoundingClientRect();
+  if (!(rect.width > 0 && rect.height > 0)) return false;
+  const hasBackground =
+    style.backgroundImage !== 'none' ||
+    (style.backgroundColor !== 'transparent' && style.backgroundColor !== 'rgba(0, 0, 0, 0)');
+  return hasBackground || style.borderTopStyle !== 'none' || style.outlineStyle !== 'none';
+}
+
+function domNodeRenders(node: Node): boolean {
+  if (node.nodeType === Node.TEXT_NODE) return Boolean(node.textContent?.trim());
+  if (!(node instanceof Element)) return false;
+  const tag = node.tagName.toLowerCase();
+  if (NON_RENDERING_DOM_TAGS.has(tag) || elementIsHidden(node)) return false;
+  if (RENDERABLE_DOM_TAGS.has(tag)) return true;
+  for (const child of node.childNodes) if (domNodeRenders(child)) return true;
+  return styledBoxRenders(node);
+}
+
+/** Structural DOM content test used after React has committed into a root. */
+export function domHasRenderableContent(root: HTMLElement): boolean {
+  for (const child of root.childNodes) if (domNodeRenders(child)) return true;
+  return false;
+}
+
+function threeObjectCanRender(object: THREE.Object3D, ignoredLayer?: number): boolean {
+  const candidate = object as THREE.Object3D & {
+    isMesh?: boolean;
+    isLine?: boolean;
+    isPoints?: boolean;
+    isSprite?: boolean;
+    material?: THREE.Material | THREE.Material[];
+  };
+  if (ignoredLayer !== undefined && candidate.layers.mask >>> 0 === (1 << ignoredLayer) >>> 0) {
+    return false;
+  }
+  if (!candidate.isMesh && !candidate.isLine && !candidate.isPoints && !candidate.isSprite) {
+    return false;
+  }
+  const materials = Array.isArray(candidate.material)
+    ? candidate.material
+    : candidate.material
+      ? [candidate.material]
+      : [];
+  return materials.length === 0 || materials.some((material) => material.visible);
+}
+
+/** Whether a Three scene can contribute pixels without editor-only helpers. */
+export function threeSceneHasRenderableContent(
+  scene: THREE.Scene,
+  options: { readonly includeBackground?: boolean; readonly ignoredLayer?: number } = {},
+): boolean {
+  if (options.includeBackground !== false && scene.background !== null) return true;
+  const pending: THREE.Object3D[] = [scene];
+  while (pending.length > 0) {
+    const object = pending.pop();
+    if (!object || !object.visible) continue;
+    if (object !== scene && threeObjectCanRender(object, options.ignoredLayer)) return true;
+    for (let index = object.children.length - 1; index >= 0; index -= 1) {
+      const child = object.children[index];
+      if (child) pending.push(child);
+    }
+  }
+  return false;
+}

package/src/host/take-named-export.ts

@@ -0,0 +1,23 @@
+/**
+ * Import a module by URL and take the export the adapter's scene table
+ * names — with the one refusal sentence both scene-loading surfaces show
+ * when the table and the module disagree. Byte-identical copies of this
+ * (refusal text included) lived in two components before this home.
+ */
+export async function takeNamedExport<T>(
+  url: string,
+  path: string,
+  exportName: string | undefined,
+): Promise<T> {
+  const module_ = (await import(/* @vite-ignore */ url)) as Record<string, unknown>;
+  const name = exportName ?? 'default';
+  const Component = module_[name];
+  if (typeof Component !== 'function') {
+    throw new Error(
+      `${path} does not export ${
+        exportName === undefined ? 'a default component' : `\`${exportName}\``
+      }, which is what the adapter's scene table names. The table and the module disagree.`,
+    );
+  }
+  return Component as T;
+}

package/src/host/three-ingest-runtime.ts

@@ -0,0 +1,76 @@
+/**
+ * Resolve the THREE primitives an INGEST root's capture trap is installed on
+ * from the same module graph as the game's own entry — the three sibling of
+ * `canvas-entry-runtime.ts`'s `resolveCanvasPixiForEditor`.
+ *
+ * See `../vite-plugin-module-doorways.ts` for the measured failure this
+ * closes and for why the ingest lane does not borrow `/__vgai-r3f-runtime`.
+ *
+ * A mount site resolves this ONCE and hands what it gets to everything it
+ * builds for that game. Nothing further down reaches for a static import: a
+ * namespace that could differ between two collaborators of the same game is
+ * the bug, not the seam.
+ */
+
+import * as shellThree from 'three';
+import { EffectComposer } from 'three/examples/jsm/postprocessing/EffectComposer.js';
+import { CSS3DRenderer } from 'three/examples/jsm/renderers/CSS3DRenderer.js';
+import { THREE_INGEST_RUNTIME_PATH } from '@volter/editor-sdk/host';
+import { isPackagedRuntime } from '@volter/editor-core/packaged-runtime';
+
+/**
+ * THE three of the graph an ingested game's modules resolve — the project's
+ * under the packaged runtime, this bundle's own copy otherwise (where one
+ * Vite instance's `resolve.dedupe` has already made them the same object, so
+ * the packaged branch's absence is not a degrade).
+ *
+ * The addons travel with the namespace deliberately: they are files inside
+ * the same `three` package tree, so "which three?" and "which EffectComposer?"
+ * are ONE question and answering them separately is how they drift.
+ */
+export interface ThreeIngestRuntime {
+  readonly three: typeof shellThree;
+  readonly EffectComposer: typeof EffectComposer;
+  readonly CSS3DRenderer: typeof CSS3DRenderer;
+}
+
+const shellRuntime: ThreeIngestRuntime = {
+  three: shellThree,
+  EffectComposer,
+  CSS3DRenderer,
+};
+
+let cachedPackagedRuntime: Promise<ThreeIngestRuntime> | null = null;
+
+async function packagedRuntime(): Promise<ThreeIngestRuntime> {
+  const mod = (await import(/* @vite-ignore */ THREE_INGEST_RUNTIME_PATH)) as {
+    projectThree?: unknown;
+    EffectComposer?: unknown;
+    CSS3DRenderer?: unknown;
+  };
+  const missing = (['projectThree', 'EffectComposer', 'CSS3DRenderer'] as const).filter(
+    (name) => mod[name] === undefined || mod[name] === null,
+  );
+  if (missing.length > 0) {
+    // Loud, not a fallback to the shell's copy: falling back would put the
+    // trap on a `WebGLRenderer.prototype` the game never constructs and the
+    // mount would then fail 10 seconds later saying the game "bundles its own
+    // (un-shared) copy of three" — a sentence about the GAME, for a defect in
+    // this host.
+    throw new Error(
+      "The packaged runtime's synthetic three-ingest module did not export " +
+        `${missing.join(', ')} — see vite-plugin-module-doorways.ts.`,
+    );
+  }
+  return {
+    three: mod.projectThree as typeof shellThree,
+    EffectComposer: mod.EffectComposer as typeof EffectComposer,
+    CSS3DRenderer: mod.CSS3DRenderer as typeof CSS3DRenderer,
+  };
+}
+
+export async function resolveThreeIngestRuntimeForEditor(): Promise<ThreeIngestRuntime> {
+  if (!(await isPackagedRuntime())) return shellRuntime;
+  if (!cachedPackagedRuntime) cachedPackagedRuntime = packagedRuntime();
+  return cachedPackagedRuntime;
+}

package/src/host/types-fastnoise-lite.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Ambient declaration for `fastnoise-lite`, which ships no types. It enters
+ * the editor only through the browser dependency table
+ * (`served-bundle-runtime-modules.ts`) so a hosted project importing it — the
+ * Godot compat noise protocols do — resolves; the editor never calls into it.
+ */
+declare module 'fastnoise-lite';

package/src/host/types-mikktspace.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Ambient declaration for three's MikkTSpace wasm helper. `@types/three`
+ * carried `examples/jsm/libs/mikktspace.module.d.ts` until 0.180, which ships
+ * types for `fflate`, `lil-gui`, `meshopt_decoder`, `stats` and `tween` only —
+ * so the module the browser dependency table registers
+ * (`served-bundle-runtime-modules.ts`, for a hosted project that computes tangents)
+ * became untyped in place. The shape below is the module's own export list
+ * (`three/examples/jsm/libs/mikktspace.module.js`).
+ */
+declare module 'three/addons/libs/mikktspace.module.js' {
+  /** Resolves once the embedded wasm module has been instantiated. */
+  export const ready: Promise<void>;
+  /** True after {@link ready} settles. */
+  export let isReady: boolean;
+  export function generateTangents(
+    position: Float32Array,
+    normal: Float32Array,
+    texcoord: Float32Array,
+  ): Float32Array;
+}

package/src/host/types-troika-three-text.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Ambient declaration for `troika-three-text`, which ships no types. It
+ * enters the editor only through the browser dependency table
+ * (`served-bundle-runtime-modules.ts`) so a hosted project importing it resolves;
+ * the editor never calls into it.
+ */
+declare module 'troika-three-text';

package/src/host/use-active-performance-source.ts

@@ -0,0 +1,53 @@
+/**
+ * THE one answer to "which profiler is the UI showing right now?".
+ *
+ * Subscribes to the three registries the answer depends on (workspace
+ * documents, performance sources, the inspected instance) and resolves the
+ * `workspace:game` → per-instance → per-document ladder. The header
+ * telemetry and the Performance panel both render THIS — two copies of the
+ * ladder is how the header and the panel silently disagree about which
+ * document's profiler they show.
+ */
+
+import { useSyncExternalStore } from 'react';
+import {
+  inspectedInstanceId,
+  inspectedInstanceVersion,
+  subscribeInspectedInstance,
+} from '@volter/editor-core/authoring/active-systems';
+import {
+  type EditorPerformanceSource,
+  performanceSourceForDocument,
+  performanceSourceForGameInstance,
+  performanceSourcesVersion,
+  subscribePerformanceSources,
+} from '@volter/editor-core/performance-sources';
+import {
+  activeWorkspaceDocumentId,
+  subscribeWorkspaceDocuments,
+  workspaceDocumentRegistryVersion,
+} from '@volter/editor-core/workspace-document-registry';
+
+export function useActivePerformanceSource(): EditorPerformanceSource | null {
+  useSyncExternalStore(
+    subscribeWorkspaceDocuments,
+    workspaceDocumentRegistryVersion,
+    workspaceDocumentRegistryVersion,
+  );
+  useSyncExternalStore(
+    subscribePerformanceSources,
+    performanceSourcesVersion,
+    performanceSourcesVersion,
+  );
+  useSyncExternalStore(
+    subscribeInspectedInstance,
+    inspectedInstanceVersion,
+    inspectedInstanceVersion,
+  );
+  const documentId = activeWorkspaceDocumentId();
+  return (
+    (documentId === 'workspace:game'
+      ? performanceSourceForGameInstance(inspectedInstanceId())
+      : null) ?? performanceSourceForDocument(documentId)
+  );
+}

package/src/host/viewport-pose-memory.ts

@@ -0,0 +1,48 @@
+/**
+ * The Scene viewport camera pose a reader left behind, remembered per project.
+ *
+ * WHY. A reload auto-framed from scratch, so the view someone had carefully
+ * settled on was gone after every F5 and they had to hunt for their objects
+ * again (runhuman pass 56). The auto-frame design's own outranking rule
+ * (auto-frame-window.ts: "the reader's first camera gesture ends the window")
+ * already says what a remembered pose is — a gesture that has ALREADY
+ * happened — so restoring one replaces the whole window: no measured framing,
+ * no game-camera seed. A project with no remembered pose (first ever open)
+ * keeps the designed first-look framing untouched.
+ *
+ * Storage: the `viewportPose` section of the project-local document
+ * (`project-local-state.ts`) — per checkout, keyed by the folder itself.
+ */
+
+import type * as THREE from 'three';
+import { projectLocalSection, writeProjectLocalSection } from '@volter/editor-core/project-local-state';
+
+/** The section of the project-local document this module owns. */
+const SECTION = 'viewportPose';
+
+export interface ViewportPose {
+  readonly position: readonly [number, number, number];
+  readonly target: readonly [number, number, number];
+}
+
+/** The remembered pose for the OPEN project, or null (first ever open). */
+export function savedViewportPose(): ViewportPose | null {
+  const pose = projectLocalSection<ViewportPose>(SECTION);
+  return pose &&
+    Array.isArray(pose.position) &&
+    pose.position.length === 3 &&
+    pose.position.every(Number.isFinite) &&
+    Array.isArray(pose.target) &&
+    pose.target.length === 3 &&
+    pose.target.every(Number.isFinite)
+    ? pose
+    : null;
+}
+
+/** Remember where the reader's gesture left the camera. */
+export function saveViewportPose(camera: THREE.PerspectiveCamera, target: THREE.Vector3): void {
+  writeProjectLocalSection(SECTION, {
+    position: [camera.position.x, camera.position.y, camera.position.z],
+    target: [target.x, target.y, target.z],
+  } satisfies ViewportPose);
+}

package/src/host/viewport-root-presentation.ts

@@ -0,0 +1,40 @@
+import type { ViewportRoot } from '@volter/editor-sdk/host';
+import { stampMountedAuthoringIds } from './authoring/mounted-authoring';
+import type { EditorShellStore } from '@volter/editor-core/editor-shell-store';
+import { stampThreeIdentities } from '@volter/editor-core/projection/three';
+
+/**
+ * The Three viewport's PRESENTER — what `the world root's stage` binds as
+ * `host.viewport.presentRoots` (`viewport-door.ts`). The lane that mounted
+ * the roots sees only the returned presentation handle. Native Three scene
+ * adoption, identity stamping, and restoration stay here, beside the
+ * viewport surface that understands them. A composition with no Three root
+ * simply has no subject for this viewport to present.
+ */
+export function presentThreeRoots(
+  store: Pick<EditorShellStore, 'enterPlayScene' | 'releaseAdoptedScene'>,
+  roots: readonly ViewportRoot[],
+): { readonly worldId: string; dispose(): void } | null {
+  const world = roots.find((candidate) => candidate.mounted.kind === 'three');
+  if (!world || world.mounted.kind !== 'three') return null;
+  const scene = world.mounted.scene;
+  const mountedAuthoring = world.mounted.authoring;
+  if (mountedAuthoring) stampMountedAuthoringIds(scene, mountedAuthoring);
+  stampThreeIdentities(scene, liveWorldId(world.id));
+  store.enterPlayScene(scene, world.mounted.rendererConfig);
+  let disposed = false;
+  return {
+    worldId: world.id,
+    dispose(): void {
+      if (disposed) return;
+      disposed = true;
+      store.releaseAdoptedScene(scene);
+    },
+  };
+}
+
+/** The id namespace minted ids carry. The fallback supports legacy sessions
+ * that predate manifest root identity. */
+export function liveWorldId(worldId: string | null): string {
+  return worldId ?? 'main';
+}