@volter/editor-game 0.5.65

package/src/host/authoring/canvas-runtime-recognition.ts

@@ -0,0 +1,50 @@
+/**
+ * Recognizing WHICH canvas runtime a mounted game is actually running, from
+ * that realm's own public handles.
+ *
+ * The host never infers a library from the manifest: a canvas root says
+ * `canvas`, and which of Pixi/Phaser/Babylon draws on it is a fact about the
+ * live realm. These two probes read the runtimes' OWN documented registries, so
+ * a game that ships neither is answered `null` — and the mount fails by name
+ * rather than being presented as a library it is not, or as an editable tree
+ * the editor fabricated.
+ */
+
+import type { BabylonEngineLike } from './babylon-authoring-adapter';
+import type { PhaserGameLike } from './phaser-live-authoring-adapter';
+
+export interface PhaserRealmLike {
+  Phaser?: { GAMES?: PhaserGameLike[] };
+  /** Phaser 3.16 predates `Phaser.GAMES`; this is its standard public handle. */
+  game?: PhaserGameLike;
+}
+
+export interface BabylonRealmLike {
+  BABYLON?: { Engine?: { Instances?: BabylonEngineLike[] } };
+  /** Host build seam for module-bundled Babylon, where no BABYLON global exists. */
+  __vgaiBabylon?: {
+    engines?: BabylonEngineLike[];
+    /** Optional boot promise published by a host-built classic bundle. */
+    ready?: PromiseLike<unknown>;
+  };
+}
+
+/** Recognize Phaser through public realm handles across old and new Phaser 3. */
+export function findPhaserGame(realm: PhaserRealmLike | null): PhaserGameLike | null {
+  if (typeof realm?.game?.scene?.getScenes === 'function') return realm.game;
+  const games = realm?.Phaser?.GAMES;
+  if (!Array.isArray(games)) return null;
+  return games.find((game) => typeof game?.scene?.getScenes === 'function') ?? null;
+}
+
+/** Recognize Babylon from its public engine registry or the module-build host seam. */
+export function findBabylonEngine(realm: BabylonRealmLike | null): BabylonEngineLike | null {
+  const bridged = realm?.__vgaiBabylon?.engines;
+  const engines = Array.isArray(bridged) ? bridged : realm?.BABYLON?.Engine?.Instances;
+  if (!Array.isArray(engines)) return null;
+  return (
+    [...engines]
+      .reverse()
+      .find((engine) => Array.isArray(engine?.scenes) && engine.scenes.length > 0) ?? null
+  );
+}

package/src/host/authoring/contract-hierarchy-authoring.ts

@@ -0,0 +1,144 @@
+/**
+ * Projects an ingested game's declared semantic hierarchy groups onto the
+ * ordinary AuthoringAdapter hierarchy. The shell remains content-blind: the
+ * game supplies ids, labels, and live counts; this decorator only translates
+ * them into EditorNode currency and keeps the captured render tree available
+ * under one explicitly named folder.
+ */
+
+import type { AuthoringAdapter, EditorNode, HierarchyProvider } from '@volter/editor-project/adapter';
+import type {
+  VgaiGameHierarchyGroup,
+  VgaiGameHierarchyProvider,
+} from '@volter/editor-project/adapter/ingest/game-contract';
+import { editorConsole } from '@volter/editor-core/editor-console';
+
+const GROUP_PREFIX = 'contract-hierarchy:group:';
+const RENDER_TREE_ID = 'contract-hierarchy:render-tree';
+
+function groupNodeId(id: string): string {
+  return `${GROUP_PREFIX}${encodeURIComponent(id)}`;
+}
+
+function groupNode(group: VgaiGameHierarchyGroup): EditorNode {
+  return {
+    id: groupNodeId(group.id),
+    label: group.label,
+    secondaryLabel: `${group.count} ${group.count === 1 ? 'item' : 'items'}`,
+    role: 'folder',
+    kind: 'group',
+    parentId: null,
+    childIds: [],
+  };
+}
+
+function assertGroups(value: unknown): VgaiGameHierarchyGroup[] {
+  if (!Array.isArray(value)) throw new Error('hierarchy() did not return an array');
+  const ids = new Set<string>();
+  for (const group of value) {
+    if (
+      typeof group !== 'object' ||
+      group === null ||
+      typeof group.id !== 'string' ||
+      group.id.trim().length === 0 ||
+      typeof group.label !== 'string' ||
+      group.label.trim().length === 0 ||
+      typeof group.count !== 'number' ||
+      !Number.isInteger(group.count) ||
+      group.count < 0
+    ) {
+      throw new Error('hierarchy() returned an invalid { id, label, count } group');
+    }
+    if (ids.has(group.id)) throw new Error(`hierarchy() returned duplicate id "${group.id}"`);
+    ids.add(group.id);
+  }
+  return value;
+}
+
+/** Identity-preserving when the game declares no hierarchy surface. */
+export function withContractHierarchy(
+  base: AuthoringAdapter,
+  provider: VgaiGameHierarchyProvider | undefined,
+): AuthoringAdapter {
+  if (!provider) return base;
+
+  let warned = false;
+  const groups = (): VgaiGameHierarchyGroup[] => {
+    try {
+      return assertGroups(provider());
+    } catch (error) {
+      if (!warned) {
+        warned = true;
+        editorConsole.warn(
+          `Ignored invalid game-contract hierarchy: ${error instanceof Error ? error.message : String(error)}`,
+          'ingest',
+        );
+      }
+      return [];
+    }
+  };
+
+  const roots = () => {
+    const semantic = groups();
+    const rendered = base.hierarchy.roots();
+    if (semantic.length === 0) return rendered;
+    return [
+      ...semantic.map(groupNode),
+      {
+        id: RENDER_TREE_ID,
+        label: 'Rendered objects',
+        secondaryLabel: 'live tree',
+        role: 'folder',
+        kind: 'group',
+        parentId: null,
+        childIds: rendered.map((node) => node.id),
+      },
+    ];
+  };
+  const node = (id: string) => {
+    const semantic = groups();
+    const group = semantic.find((candidate) => groupNodeId(candidate.id) === id);
+    if (group) return groupNode(group);
+    if (semantic.length > 0 && id === RENDER_TREE_ID) {
+      const rendered = base.hierarchy.roots();
+      return {
+        id: RENDER_TREE_ID,
+        label: 'Rendered objects',
+        secondaryLabel: 'live tree',
+        role: 'folder',
+        kind: 'group',
+        parentId: null,
+        childIds: rendered.map((node) => node.id),
+      };
+    }
+    const rendered = base.hierarchy.node(id);
+    return semantic.length > 0 && rendered?.parentId === null
+      ? { ...rendered, parentId: RENDER_TREE_ID }
+      : rendered;
+  };
+  const hierarchy = new Proxy(base.hierarchy, {
+    get(target, property) {
+      if (property === 'roots') return roots;
+      if (property === 'node') return node;
+      const value = Reflect.get(target, property, target);
+      return typeof value === 'function' ? value.bind(target) : value;
+    },
+  }) satisfies HierarchyProvider;
+  const subscribe = (listener: () => void): (() => void) => {
+    const unsubscribeBase = base.subscribe?.(listener);
+    const unsubscribeContract = provider.subscribe?.(listener);
+    return () => {
+      unsubscribeBase?.();
+      unsubscribeContract?.();
+    };
+  };
+
+  return new Proxy(base, {
+    get(target, property) {
+      if (property === 'hierarchy') return hierarchy;
+      if (property === 'subscribe') return subscribe;
+      const value = Reflect.get(target, property, target);
+      return typeof value === 'function' ? value.bind(target) : value;
+    },
+  });
+}

package/src/host/authoring/contract-scenes-stories.ts

@@ -0,0 +1,204 @@
+/**
+ * Projects an ingested game's declared SCENES (`window.vgaiGame.scenes`, see
+ * `@volter/editor-project/adapter/ingest/game-contract`) onto the ordinary
+ * {@link StoriesProvider} the editor's story picker already reads — the sibling
+ * of `contract-hierarchy-authoring.ts`, which does the same job for the
+ * contract's `hierarchy` member.
+ *
+ * Why stories: a multi-screen game's screens ARE the design-time states of its
+ * world, and the editor's stories vocabulary is exactly "the states a world can
+ * be put into". Projecting rather than adding a second door means the picker,
+ * the inspector's serialized subject and `adapter.stories` all work on an
+ * ingested game unchanged and unaware of the provenance.
+ *
+ * SCOPE IS WORLD-LEVEL — `storiesFor`/`active` ignore `nodeId` entirely, the
+ * same scope `ReactRootAuthoringAdapter.stories` has (B2). A game's screen is a
+ * property of the whole world, not of the node the author happens to have
+ * selected, and pretending otherwise would need a per-node scene model no game
+ * declares.
+ *
+ * `isolate` is deliberately ABSENT: an ingested game cannot render ONE of its
+ * display objects against a scene — the scene IS the game's whole screen. An
+ * absent optional member is the honest answer; a no-op one would advertise a
+ * capability that does nothing.
+ */
+
+import type {
+  LiveSceneSwitch,
+  LiveSceneSwitchSettled,
+  LiveSceneTable,
+} from '@volter/editor-sdk/host';
+import type { StoriesProvider, StoryRef } from '@volter/editor-project/adapter';
+import type { VgaiGameContract, VgaiGameScene } from '@volter/editor-project/adapter/ingest/game-contract';
+import { readGameScenes } from '@volter/editor-project/adapter/ingest/game-contract';
+import { editorConsole } from '@volter/editor-core/editor-console';
+
+function assertScenes(value: unknown): VgaiGameScene[] {
+  if (!Array.isArray(value)) throw new Error('scenes.list() did not return an array');
+  const ids = new Set<string>();
+  for (const scene of value) {
+    if (
+      typeof scene !== 'object' ||
+      scene === null ||
+      typeof scene.id !== 'string' ||
+      scene.id.trim().length === 0 ||
+      typeof scene.label !== 'string' ||
+      scene.label.trim().length === 0
+    ) {
+      throw new Error('scenes.list() returned an invalid { id, label } scene');
+    }
+    if (ids.has(scene.id)) throw new Error(`scenes.list() returned duplicate id "${scene.id}"`);
+    ids.add(scene.id);
+  }
+  return value;
+}
+
+/**
+ * The switch vocabulary is the SDK's (`LiveSceneSwitch`), not this lane's.
+ * It was declared here and the host's live registry imported it, which is how
+ * the ingest game contract reached a core host module; the contract now states
+ * its own result and this lane implements it (phase 1 of the open-source
+ * launch, 2026-09-18). The aliases stay because this module's own readers
+ * speak scenes, not "live scene tables".
+ */
+export type SceneSwitchSettled = LiveSceneSwitchSettled;
+export type SceneSwitch = LiveSceneSwitch;
+
+/**
+ * The scenes projection: the ordinary {@link StoriesProvider} the picker reads,
+ * plus `goToScene` — the SAME switch with its answer kept instead of dropped.
+ *
+ * One path, two callers. `apply` is `StoriesProvider`'s synchronous,
+ * answer-less shape (the picker has `active()` to read afterwards); the `open`
+ * protocol verb needs the game's answer and the refusal as VALUES, and getting
+ * them by calling the contract's `goTo` directly would route around the
+ * membership check this module owns.
+ */
+export type ContractScenesStories = LiveSceneTable;
+
+/** True when `provider` is a scenes projection — i.e. carries the awaited,
+ *  membership-checked switch above. A plain `StoriesProvider` (a react world's
+ *  CSF states) does not, and must not be navigated as though it were a game's
+ *  own screens. */
+export function isContractScenesStories(
+  provider: StoriesProvider | null | undefined,
+): provider is ContractScenesStories {
+  return typeof (provider as ContractScenesStories | null | undefined)?.goToScene === 'function';
+}
+
+/** What the MOUNT contributes to a switch this projection accepted. */
+export interface ContractScenesSeams {
+  /**
+   * Called synchronously the moment a switch is ACCEPTED — before the game's
+   * own `goTo` settles, because the host's held-mount repaint has to draw
+   * frames DURING the transition rather than after it lands
+   * (`ingest/held-scene-repaint.ts`). Never called for a refused switch.
+   *
+   * A seam rather than a wrapper around the returned object: `apply` and
+   * `goToScene` are ONE path through this module, and a mount that wrapped only
+   * the outer member would leave the picker's own switches unpainted.
+   */
+  readonly onSwitchAccepted?: (sceneId: string) => void;
+}
+
+/**
+ * The stories collaborator for a game that declared a usable scene surface, or
+ * `null` for one that declared none — the ABSENCE the mount then passes on, so
+ * the coverage report names the missing provider instead of the picker showing
+ * an empty list.
+ *
+ * A declared-but-unusable surface is refused loudly (by name, once) rather than
+ * bound: `readGameScenes` owns that shape check.
+ */
+export function createContractScenesStories(
+  contract: VgaiGameContract | null | undefined,
+  seams: ContractScenesSeams = {},
+): ContractScenesStories | null {
+  const { scenes, malformed } = readGameScenes(contract);
+  if (malformed !== null) {
+    editorConsole.warn(`Ignored the game contract's \`scenes\` surface: ${malformed}`, 'ingest');
+  }
+  if (!scenes) return null;
+
+  let warned = false;
+  const list = (): VgaiGameScene[] => {
+    try {
+      return assertScenes(scenes.list());
+    } catch (error) {
+      if (!warned) {
+        warned = true;
+        editorConsole.warn(
+          `Ignored invalid game-contract scenes: ${error instanceof Error ? error.message : String(error)}`,
+          'ingest',
+        );
+      }
+      return [];
+    }
+  };
+
+  const goToScene = (sceneId: string): SceneSwitch => {
+    const known = list().map((scene) => scene.id);
+    if (!known.includes(sceneId)) {
+      return {
+        ok: false,
+        error: `scenes.goTo: "${sceneId}" is not one of this game's scenes (${
+          known.length > 0 ? known.join(', ') : 'it lists none'
+        }).`,
+        known,
+      };
+    }
+    seams.onSwitchAccepted?.(sceneId);
+    // The game's own navigation call. It commonly loads the scene's assets
+    // first, so a rejection is REPORTED rather than swallowed — and reported as
+    // a value, beside the scene the game is actually in, which is read off the
+    // game's own model either way.
+    const settled = (async (): Promise<SceneSwitchSettled> => {
+      try {
+        await scenes.goTo(sceneId);
+        return { requested: sceneId, current: scenes.current() };
+      } catch (error) {
+        return {
+          requested: sceneId,
+          current: scenes.current(),
+          error: error instanceof Error ? error.message : String(error),
+        };
+      }
+    })();
+    return { ok: true, settled };
+  };
+
+  return {
+    // The game calls these SCENES, so every surface that presents them does
+    // too — the projection borrows the stories seam, never its vocabulary.
+    title: 'Scenes',
+    storiesFor: (_nodeId): StoryRef[] => list().map(({ id, label }) => ({ id, label })),
+    active: (_nodeId) => scenes.current(),
+    goToScene,
+    apply: (_nodeId, storyId) => {
+      if (storyId === null) {
+        // The picker's "(none)" clears a story back to the document's default.
+        // A running game has no such state — it is always in SOME scene — so
+        // this refuses and says why rather than pretending to clear one.
+        editorConsole.warn(
+          'This game’s scenes cannot be cleared: it is always in one of its own scenes. ' +
+            'Pick the scene to switch to instead.',
+          'ingest',
+        );
+        return;
+      }
+      // THE SAME SWITCH the `open` verb takes — `apply` differs only in what it
+      // does with the answer: nothing waits on it here, because
+      // `StoriesProvider.apply` is synchronous and the picker's authoritative
+      // reading is `active()`.
+      const switched = goToScene(storyId);
+      if (!switched.ok) {
+        editorConsole.warn(`${switched.error} — ignoring.`, 'ingest');
+        return;
+      }
+      void switched.settled.then((result) => {
+        if (result.error === undefined) return;
+        editorConsole.error(`scenes.goTo("${storyId}") failed: ${result.error}`, 'ingest');
+      });
+    },
+  };
+}

package/src/host/authoring/creation-site-related.ts

@@ -0,0 +1,55 @@
+/**
+ * CREATION-SITE RELATED LINKS — a kit piece of the live-adapter toolbox
+ * (owner-directed program, 2026-08-22: everything substrate-neutral is
+ * shared, so a new substrate adapter costs only its projection).
+ *
+ * The ONE jump a live subject honestly has is to the source line that
+ * constructs it — the serve-time OID stamp for a fiber world, the `new` site
+ * for a structural one. This existed twice, self-admittedly ("the canvas
+ * lane's method transcribed"): `PixiAuthoringAdapter.creationSiteLinks` and
+ * `ThreeAuthoringAdapter.related`. One producer now; an adapter hands in only
+ * its own site resolution.
+ *
+ * Only a SOURCE anchor names a `file:line` the editor's source-locator door
+ * speaks; an unanchored or level-data subject reports no link at all (the
+ * inspector's creation-site note already says why, in its own words) — a link
+ * titled "unknown" would be a jump to nowhere. Opening reuses
+ * `runInstanceSourceAction` verbatim, so no lane can drift into a second
+ * sentence for the same act. The locator is a standalone object and NOT a
+ * `sourceLocation` method on any adapter, for the reason the Pixi lane
+ * records: that name is duck-typed by `instanceSourceLocatorFor` to decide
+ * which rows get hierarchy source items.
+ */
+
+import type { NodeCreationSite, RelatedSubjectsProvider } from '@volter/editor-project/adapter';
+import { type InstanceSourceLocator, runInstanceSourceAction } from '@volter/editor-core/instance-source-actions';
+import { showTransientHint } from '@volter/editor-core/transient-hint';
+
+/** The related provider for an adapter whose truth can place a subject at a
+ *  creation site. `resolveSite` is the adapter's own id→site hop. */
+export function creationSiteRelated(
+  resolveSite: (id: string) => NodeCreationSite,
+): RelatedSubjectsProvider {
+  const locator: InstanceSourceLocator = {
+    sourceLocation: (id) => {
+      const site = resolveSite(id);
+      if (!site.anchored || site.kind !== 'source') return undefined;
+      return { file: site.file, line: site.line };
+    },
+  };
+  return {
+    links: (id) => {
+      const site = resolveSite(id);
+      if (!site.anchored || site.kind !== 'source') return [];
+      return [
+        {
+          id: `creation-site:${site.file}:${site.line}:${site.col}`,
+          title: `Constructed at ${site.display}`,
+          open: () => {
+            void runInstanceSourceAction(locator, id, 'callsite').then(showTransientHint);
+          },
+        },
+      ];
+    },
+  };
+}

package/src/host/authoring/ephemeral-persistence.ts

@@ -0,0 +1,29 @@
+/**
+ * Ephemeral persistence provider — for sessions whose edits must NOT survive past
+ * the session (play-mode's adoption of the live game scene; design).
+ *
+ * `isDirty()` is hard-coded `false`: nothing here is ever "unsaved" because there
+ * is nowhere for it to go — a no-op `save()` that pretended otherwise would lie in
+ * the save-status UI. Per the contract, the host never calls `save()` when
+ * `isDirty()` is false, so `save()` below is a documented no-op, not a silent
+ * swallow of a real write.
+ *
+ * EPHEMERAL IS A PIPE DESTINATION, not a parallel stack: an edit made here
+ * resolves `live-only` at {@link EPHEMERAL_DESTINATION} through
+ * `write-pipe.ts`, which is why the destination string is owned there beside
+ * the other two rather than here.
+ */
+
+import type { PersistenceProvider } from '@volter/editor-project/adapter';
+import { EPHEMERAL_DESTINATION } from '@volter/editor-core/authoring/write-pipe';
+
+export function createEphemeralPersistence(): PersistenceProvider {
+  return {
+    isDirty: () => false,
+    save: async () => {
+      // Never called by the host (isDirty() is always false — see doc comment
+      // above). No-op: there is nothing to write, not a swallowed failure.
+    },
+    destination: EPHEMERAL_DESTINATION,
+  };
+}

package/src/host/authoring/gesture-persist.ts

@@ -0,0 +1,84 @@
+/**
+ * PERSIST ONE CHANNEL WRITE — a kit piece of the live-adapter toolbox
+ * (ARCHITECTURE-CORE §Roots, the four kit rules).
+ *
+ * Extracted from the cited twins `ThreeAuthoringAdapter.pipedWrite` and
+ * `pixi-live-write-target`'s `persistOrJournal` resolution (whose own header
+ * declares the transcription). The core is the ONE decision every live lane
+ * must make identically when a gesture closes on a single property: resolve
+ * the subject, ask the backend's GATE first — because it names the precise
+ * reason (no source stamp, an expression-bound prop, a game that is playing
+ * rather than held) — then honor the planned LANE second, as the structural
+ * guarantee that a subject classified `live-only` can never reach a dialect
+ * writer even if a gate waved it through. The two copies had drifted on
+ * exactly this order (the canvas copy checked the lane first), so live-only
+ * subjects earned different refusal sentences per lane; the documented order
+ * wins and is now the only spelling.
+ *
+ * The LIVE-ONLY path stays fully SYNCHRONOUS through the pipe: `runWritePipe`
+ * awaits nothing before `record` on that arm, so an `endEdit(); undo()`
+ * sequence still finds its history entry. A cheap-gate refusal is reported on
+ * the same surface as the deep ones, and only while the backend is armed — a
+ * refusal on every frame of a game somebody is playing is noise.
+ *
+ * What stays per-lane, by the kit rules: the gesture-close POLICY (which
+ * channels count as changed — the canvas lane's origin-move rule is
+ * load-bearing and different), the history journaling itself (`journal` is
+ * the lane's own push), and every identity/anchor hop (`subject` is resolved
+ * lazily, inside the pipe, by the lane's own planner).
+ */
+
+import type { WriteAck, WriteAnchorKind } from '@volter/editor-project/adapter';
+import type { ChannelValue } from '@volter/editor-core/creation-site-edit';
+import type { SourcePersistenceBackend, SourceWriteSubject } from './source-persistence-backend';
+import { resolvesLiveOnly, runWritePipe, type WriteResolution } from '@volter/editor-core/authoring/write-pipe';
+
+/** The one-property-per-gesture refusal, spelled once — it is the persistence
+ *  pipeline's own rule, not any substrate's voice. */
+export function multiChannelRefusal(changed: readonly string[]): string {
+  return (
+    `this gesture changed ${changed.length} properties at once (${changed.join(', ')}), and ` +
+    'creation-site write-back plans one property per gesture'
+  );
+}
+
+export interface ChannelWriteRequest {
+  readonly backend: SourcePersistenceBackend;
+  /** The lane's own id+property → subject hop, resolved INSIDE the pipe. */
+  readonly subject: () => SourceWriteSubject;
+  readonly baseline: ChannelValue;
+  readonly next: ChannelValue;
+  /** History label for the transaction ("Transform Sun"). */
+  readonly label: string;
+  /** The lane's own live-only journal push (captures its `before` snapshot). */
+  readonly journal: () => void;
+}
+
+/** One channel write through the pipe: `resolve → write → record`. The
+ *  persisted path's own transaction carries BOTH halves (the file and the
+ *  live value), so the journal fires only when nothing persisted. */
+export function persistChannelWrite(request: ChannelWriteRequest): Promise<WriteAck> {
+  const { backend, label } = request;
+  return runWritePipe({
+    resolve: (): WriteResolution => {
+      const subject = request.subject();
+      const verdict = backend.gate(subject);
+      if (!verdict.ok) return resolvesLiveOnly(verdict.reason);
+      const kind: WriteAnchorKind = subject.anchorKind;
+      if (kind === 'live-only') return resolvesLiveOnly(backend.describe(subject));
+      return {
+        reaches: 'writer',
+        anchorKind: kind,
+        destination: backend.destination(),
+        write: () =>
+          backend.write({ ...subject, baseline: request.baseline, next: request.next, label }),
+      };
+    },
+    record: (persisted) => {
+      if (!persisted) request.journal();
+    },
+    report: (reason) => {
+      if (backend.armed()) backend.report(label, reason);
+    },
+  });
+}