@volter/editor-core 0.5.57

package/src/stories/three-story-model.ts

@@ -0,0 +1,96 @@
+/**
+ * Shared, headless facts about a `three` STORY: whether a mounted story holds
+ * three content, and how a story's preview thumbnail is keyed in an in-memory
+ * cache. Kept pure and off the React tree so every one of them is
+ * unit-testable with no renderer.
+ *
+ * Membership belongs to the CONSUMER, never to the registry, and it is
+ * DECLARED (`story-declared-medium.ts`). The `3D Components` board admits
+ * stories whose medium is `three`, the canvas board admits `canvas`, the
+ * DOM design board admits `dom` ({@link domStoryBoardMembers}). An
+ * undeclared story is a named gap and is not a candidate on any board —
+ * nothing here mounts to guess. The project's story registry stays
+ * deliberately unfiltered.
+ */
+
+import type * as THREE from 'three';
+import { getProjectStoryRegions } from './project-story-regions';
+import { declaredStoryMedium, reportUndeclaredStoryMedium } from './story-declared-medium';
+
+/**
+ * Whether a mounted story's root wrapper actually holds `three` content.
+ *
+ * A story that renders nothing (or renders only React fragments/null) commits
+ * successfully into the wrapper group and yields an EMPTY `Object3D` — a
+ * successful mount with nothing in it. A surface shows a story that rendered
+ * something; "the mount succeeded" alone is not the test.
+ */
+export function mountedStoryHasThreeContent(root: THREE.Object3D): boolean {
+  return root.children.length > 0;
+}
+
+/**
+ * The DOM design board's membership — every story DECLARED as `dom`.
+ *
+ * An undeclared story is named once and is not a member. Nothing here
+ * mounts: medium is a declaration, and a last-resort mount would make
+ * "residue 0" unfalsifiable (the orphan would land on this board).
+ *
+ * The board (`authoring/design-time-layers.ts`) renders each member through
+ * `react-dom`, so a three story landing on it renders `<group>`/`<primitive>`
+ * as unknown DOM tags. Declaration is what keeps those stories off this
+ * board; the project's story registry stays deliberately unfiltered.
+ */
+export function domStoryBoardMembers<
+  T extends {
+    readonly id?: string;
+    readonly name?: string;
+    readonly modulePath?: string;
+    readonly tags?: readonly string[];
+  },
+>(stories: readonly T[]): T[] {
+  const regions = getProjectStoryRegions();
+  const members: T[] = [];
+  for (const story of stories) {
+    const declared = declaredStoryMedium({ modulePath: story.modulePath, regions });
+    if (declared.medium === 'dom') {
+      members.push(story);
+      continue;
+    }
+    if (declared.via === 'undeclared' && story.modulePath) {
+      reportUndeclaredStoryMedium(story.modulePath, declared.reason);
+    }
+  }
+  return members;
+}
+
+/**
+ * The in-memory thumbnail cache key: the story's identity plus the identity of
+ * the args it was captured with, so an arg edit re-captures rather than showing
+ * a stale picture of the previous value. Args are ordered by key so two equal
+ * arg sets never key differently.
+ *
+ * Non-serializable arg values (functions, symbols, cycles) are represented by
+ * their type rather than dropped — an arg that cannot be stringified must still
+ * take part in identity, and it must never make the key THROW.
+ */
+export function threeStoryThumbnailKey(storyId: string, args: Record<string, unknown>): string {
+  const parts: string[] = [];
+  for (const name of Object.keys(args).sort()) {
+    parts.push(`${name}=${stableArgValue(args[name])}`);
+  }
+  return `${storyId}|${parts.join('&')}`;
+}
+
+function stableArgValue(value: unknown): string {
+  if (typeof value === 'function') return 'fn';
+  if (typeof value === 'symbol') return 'symbol';
+  if (value === undefined) return 'undefined';
+  try {
+    return JSON.stringify(value) ?? 'undefined';
+  } catch {
+    // A cyclic or otherwise unserializable object: identity by type, which is
+    // stable for the lifetime of one composed story.
+    return `[${typeof value}]`;
+  }
+}

package/src/story-three-preview-runtime.ts

@@ -0,0 +1,56 @@
+/** React/Fiber primitives selected from the graph that owns a project story. */
+
+import { createRoot as staticCreateR3FRoot, extend as staticExtendThree } from '@react-three/fiber';
+import { createElement as staticCreateElement } from 'react';
+import * as staticThree from 'three';
+import { R3F_RUNTIME_PATH } from '@volter/editor-sdk/host';
+import { isPackagedRuntime } from './packaged-runtime';
+
+export interface StoryThreePreviewRuntime {
+  readonly packaged: boolean;
+  readonly createElement: typeof staticCreateElement;
+  readonly createR3FRoot: typeof staticCreateR3FRoot;
+  readonly extendThree: typeof staticExtendThree;
+  readonly three: typeof staticThree;
+}
+
+const STATIC_RUNTIME: StoryThreePreviewRuntime = {
+  packaged: false,
+  createElement: staticCreateElement,
+  createR3FRoot: staticCreateR3FRoot,
+  extendThree: staticExtendThree,
+  three: staticThree,
+};
+
+let cachedPackagedRuntime: Promise<StoryThreePreviewRuntime> | null = null;
+
+async function loadPackagedRuntime(): Promise<StoryThreePreviewRuntime> {
+  const mod = (await import(/* @vite-ignore */ R3F_RUNTIME_PATH)) as Record<string, unknown>;
+  for (const name of ['createElement', 'createR3FRoot', 'extendThree']) {
+    if (typeof mod[name] !== 'function') {
+      throw new Error(
+        `The packaged R3F preview runtime did not export ${name} as a function — see ` +
+          'vite-plugin-module-doorways.ts.',
+      );
+    }
+  }
+  if (typeof mod['projectThree'] !== 'object' || mod['projectThree'] === null) {
+    throw new Error(
+      'The packaged R3F preview runtime did not export projectThree — see ' +
+        'vite-plugin-module-doorways.ts.',
+    );
+  }
+  return {
+    packaged: true,
+    createElement: mod['createElement'] as typeof staticCreateElement,
+    createR3FRoot: mod['createR3FRoot'] as typeof staticCreateR3FRoot,
+    extendThree: mod['extendThree'] as typeof staticExtendThree,
+    three: mod['projectThree'] as typeof staticThree,
+  };
+}
+
+export async function resolveStoryThreePreviewRuntime(): Promise<StoryThreePreviewRuntime> {
+  if (!(await isPackagedRuntime())) return STATIC_RUNTIME;
+  if (!cachedPackagedRuntime) cachedPackagedRuntime = loadPackagedRuntime();
+  return cachedPackagedRuntime;
+}

package/src/surface-keyboard.ts

@@ -0,0 +1,112 @@
+/**
+ * DOES OUR SURFACE HOLD THE KEYBOARD? — the term the play-input predicate was
+ * missing, and it was missing because until the Code-OSS frame there was
+ * nothing else on the page that could want a keystroke.
+ *
+ * The documented rule is "game input only fires while play is running AND the
+ * Game tab is active" (the repo's CLAUDE.md, §Play-mode input isolation), and
+ * standalone `vgai edit` those two clauses are the whole truth: the editor page
+ * IS the surface, so a keystroke that reaches it was meant for it. Under the
+ * frame (WORK.md §The core is Code-OSS, U2) the page is a VS Code workbench and
+ * our stage is ONE EDITOR PANE in it. A person typing into Monaco in the group
+ * beside a running game is typing into the same `document` the game's listeners
+ * are on, and both clauses above are still true — the game is playing and the
+ * Game document is still the active vgai document, because activating another
+ * EDITOR did not close it. So the keystroke lands in the file AND moves the
+ * game. That is U6's incident (keys typed into Monaco reaching the vgai
+ * viewport as hotkeys, twice measured) repeated one layer down, on the GAME's
+ * input rather than the editor's, and U6's fix does not cover it: keyboard
+ * OWNERSHIP decides which dispatcher owns a chord, while this decides whether a
+ * running game hears raw DOM events at all.
+ *
+ * ## Why this is a third TERM and not a correction to the second
+ *
+ * The obvious-looking fix — have the frame write `activeViewportTab = 'edit'`
+ * when the pane stops being the active editor — is a defect, and the code says
+ * so out loud: `syncCenterDocuments` (`components/CenterDocuments.tsx`) reads an
+ * `'edit'` tab with the GAME document active as a genuine disagreement and
+ * activates the SCENE document to correct it. Under the frame the layout host
+ * renders the ACTIVE document into the editor pane, so that correction would
+ * unmount the Game document, release the live document's container out from
+ * under the running runtime, and end the game. The tab is about WHICH DOCUMENT
+ * is open, the probe below is about WHO IS TYPING, and conflating them costs
+ * the game.
+ *
+ * ## The shape
+ *
+ * A single installed probe, default absent, and absent means TRUE. Standalone
+ * nothing installs one and every predicate reads exactly as it did before this
+ * module existed — the same "an unset value is upstream's own behaviour"
+ * discipline U9's core edit follows. The frame installs one from the workbench's
+ * own notion of the active editor (`ActiveEditorContext` over the vgai pane's
+ * type id), which is the right question rather than DOM focus: clicking a game
+ * canvas that carries no `tabindex` moves focus to `body` while the pane stays
+ * the active editor, and gating on focus would have killed input on the first
+ * click into the game.
+ *
+ * ## Its readers, both of them, and why they are both needed
+ *
+ * `gated-globals.ts` covers every RAW `window`/`document` listener a project
+ * module registers — first-party games, ingest mounts and the module lane
+ * alike, since the dev server's lexical shadow is what they all go through.
+ * `@vgai/game`'s `play-mode.ts` covers the engine's own `InputManager`, which
+ * is NOT a project module (it is `@vgai/game-runtime`, resolved as a dependency) and
+ * therefore attaches to the real `window` unshadowed; it reads this through
+ * `instanceInputActive` and re-gates on this module's notification.
+ */
+
+type SurfaceKeyboardProbe = () => boolean;
+
+let probe: SurfaceKeyboardProbe | null = null;
+const listeners = new Set<() => void>();
+
+/**
+ * True while the surface a game is mounted in holds the keyboard.
+ *
+ * Absent probe = true, deliberately: the standalone editor page is the only
+ * surface there is, and a host that has not answered must never be read as a
+ * refusal — a silently dead keyboard is the worst failure this module could
+ * have.
+ */
+export function surfaceHoldsKeyboard(): boolean {
+  if (!probe) return true;
+  try {
+    return probe();
+  } catch {
+    // A probe that throws is a broken frame, not a person who stopped typing.
+    return true;
+  }
+}
+
+/**
+ * Install the frame's answer. Returns the uninstall, which restores the
+ * always-true default rather than leaving the last answer pinned — a frame
+ * going away must not leave a game deaf.
+ */
+export function setSurfaceKeyboardProbe(next: SurfaceKeyboardProbe | null): () => void {
+  probe = next;
+  notifySurfaceKeyboard();
+  return () => {
+    if (probe !== next) return;
+    probe = null;
+    notifySurfaceKeyboard();
+  };
+}
+
+/** The frame calls this when its answer changes; `gated-globals`' gates re-read
+ *  per event and need no notification, but `InputManager` is a latched
+ *  `setEnabled` and does. */
+export function notifySurfaceKeyboard(): void {
+  for (const listener of listeners) listener();
+}
+
+export function subscribeSurfaceKeyboard(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+/** Test-only reset. */
+export function __resetSurfaceKeyboardForTest(): void {
+  probe = null;
+  listeners.clear();
+}

package/src/surface-state.ts

@@ -0,0 +1,124 @@
+import type { MountFailureReport } from './authoring/mount-failure-report';
+import type { RootReadiness } from './readiness';
+
+export type SurfaceContentState = 'unknown' | 'present' | 'empty';
+export type SurfacePhase = 'loading' | 'ready';
+
+export interface SurfaceExplanation {
+  readonly tone: 'loading' | 'error' | 'neutral';
+  readonly title: string;
+  readonly description: string;
+}
+
+export interface ExplainSurfaceInput {
+  /** Human name of the surface, e.g. Scene, Game, or Story. */
+  readonly surface: string;
+  /** True when the surface's design mount is DELIBERATELY suspended because
+   *  the game is playing — the wait is not progress and must not read as one
+   *  (a human sat on "waiting for world to finish mounting" on an auto-played
+   *  example and reported the Scene tab broken — runhuman pass 37). */
+  readonly playSuspended?: boolean;
+  /** Exact root identities owned by this surface. Empty means not identified yet. */
+  readonly rootIds: readonly string[];
+  readonly phase: SurfacePhase;
+  readonly content: SurfaceContentState;
+  readonly readiness?: readonly RootReadiness[];
+  readonly failures?: readonly MountFailureReport[];
+}
+
+function quoted(ids: readonly string[]): string {
+  return ids.map((id) => `“${id}”`).join(', ');
+}
+
+function failureExplanation(
+  surface: string,
+  failures: readonly MountFailureReport[],
+): SurfaceExplanation {
+  const failedIds = failures.map((failure) => failure.worldId);
+  return {
+    tone: 'error',
+    title:
+      failedIds.length === 1
+        ? `${surface} root ${quoted(failedIds)} failed`
+        : `${failedIds.length} ${surface} roots failed`,
+    description: `${failures
+      .map(
+        (failure) =>
+          `${failure.worldId} (${failure.kind}, ${failure.identity}): ${failure.message}`,
+      )
+      .join(
+        '\n',
+      )}\nIf this followed an edit, Undo (Ctrl+Z) restores the previous source and remounts.`,
+  };
+}
+
+function loadingExplanation(surface: string, rootIds: readonly string[]): SurfaceExplanation {
+  const title =
+    rootIds.length === 0
+      ? `Loading ${surface}`
+      : rootIds.length === 1
+        ? `Loading ${surface} root ${quoted(rootIds)}`
+        : `Loading ${rootIds.length} ${surface} roots`;
+  return {
+    tone: 'loading',
+    title,
+    description:
+      rootIds.length === 0
+        ? 'Reading the project declaration to identify the root that belongs here.'
+        : `Waiting for ${quoted(rootIds)} to finish mounting.`,
+  };
+}
+
+function emptyExplanation(surface: string, rootIds: readonly string[]): SurfaceExplanation {
+  if (rootIds.length === 0) {
+    return {
+      tone: 'neutral',
+      title: `No ${surface} root`,
+      description: 'No declared root belongs to this surface.',
+    };
+  }
+  return {
+    tone: 'neutral',
+    title: 'No renderable content',
+    // The second sentence is load-bearing: a world whose content exists only
+    // under its game systems (the shipped shooters and strategy examples all
+    // do this) presents exactly this card the moment Play stops, and a human
+    // tester read it as breakage ("why did it stop? no renderable content" —
+    // runhuman pass 13, 2026-08-28). Name the way forward on the card itself.
+    description:
+      (rootIds.length === 1
+        ? `Root ${quoted(rootIds)} mounted successfully but currently produces no renderable content.`
+        : `Roots ${quoted(rootIds)} mounted successfully but currently produce no renderable content.`) +
+      ' If this world builds its content under its game systems, press Play (▶) to run it.',
+  };
+}
+
+/**
+ * The one precedence rule for a surface which otherwise has nothing to draw.
+ * A real rendered result always wins. When there is no result, a named failure
+ * wins over a named wait, which wins over the honest successful-empty state.
+ */
+export function explainSurface(input: ExplainSurfaceInput): SurfaceExplanation | null {
+  if (input.content === 'present') return null;
+
+  if (input.playSuspended) {
+    return {
+      tone: 'neutral',
+      title: 'Editing paused during Play',
+      description: `${quoted(input.rootIds)} is running in the Game tab. Press Stop (⏹) to edit it here.`,
+    };
+  }
+
+  const owned = new Set(input.rootIds);
+  const scopedFailures = (input.failures ?? []).filter((failure) => owned.has(failure.worldId));
+  if (scopedFailures.length > 0) return failureExplanation(input.surface, scopedFailures);
+
+  const waitingIds = (input.readiness ?? [])
+    .filter((entry) => entry.state === 'waiting' && owned.has(entry.rootId))
+    .map((entry) => entry.rootId);
+  const loadingIds = waitingIds.length > 0 ? waitingIds : input.rootIds;
+  if (input.phase === 'loading' || waitingIds.length > 0 || input.content === 'unknown') {
+    return loadingExplanation(input.surface, loadingIds);
+  }
+  return emptyExplanation(input.surface, input.rootIds);
+}