@volter/editor-core 0.5.57

package/src/projection/types.ts

@@ -0,0 +1,44 @@
+/**
+ * The PROJECTION family's surface-neutral shapes (ARCHITECTURE-CORE §The editor
+ * protocol).
+ *
+ * A projection answers "what nodes are in this world, what are their stable
+ * ids, and how do they nest" over the RUNTIME objects a mounted world is made
+ * of — the live `Object3D`/`Container`/DOM element, never an AST node. A walk
+ * always answers: an empty projection over a mounted world is a defect, never a
+ * fact.
+ *
+ * Only the shapes live here. The projectors themselves are per surface
+ * (`./three.ts`, `./pixi.ts`, `./dom.ts`), because what an
+ * object IS, how identity is minted and what an editor-owned object looks like
+ * are all surface facts.
+ */
+
+/**
+ * One projected authoring node.
+ *
+ * `parentId` is the nearest ADMITTED ancestor — not the runtime parent — so a
+ * projection that folds a library's internals into their owner reports the
+ * owner. `null` means this node is a root of the projection.
+ */
+export interface ProjectedNode<TObject> {
+  readonly object: TObject;
+  readonly id: string;
+  readonly parentId: string | null;
+  readonly childIds: string[];
+}
+
+/**
+ * One walk's product: every node by id, the roots in walk order, and whatever
+ * the surface counts about itself.
+ *
+ * `nodes` is keyed by the id the rest of the editor addresses the node by, so
+ * the id the gizmo binds to, the id the hierarchy row shows and the id
+ * `EditorShellStore.objectMap` indexes can never disagree — they are all this
+ * one map.
+ */
+export interface Projection<TObject, TStats> {
+  readonly nodes: Map<string, ProjectedNode<TObject>>;
+  readonly rootIds: string[];
+  readonly stats: TStats;
+}

package/src/readiness.ts

@@ -0,0 +1,113 @@
+/**
+ * DECLARED READINESS, per root — the facet that makes "is this game ready?" an
+ * answer with a stated PROVENANCE instead of a host-side guess nobody can see.
+ *
+ * ARCHITECTURE-CORE §The editor protocol, "Zero inference". The question has
+ * exactly three answerers, and this module is where each one's answer lands:
+ *
+ *   · `host-mount` — a HOST-MOUNTED (exported-composition) root. The host runs
+ *     the mount, so mount completion IS readiness; no game code is needed and
+ *     the answer is `declared` for every first-party project by construction.
+ *   · `contract-ready` — a SELF-BOOTING game that declares
+ *     `window.vgaiGame.ready` (`@volter/editor-project/adapter/ingest/game-contract`). Also
+ *     `declared`: the game stated it.
+ *   · `measured-wait` — a self-booting game that declares nothing. The measured
+ *     waits remain (they are the documented fallback), and this is the whole
+ *     point of the facet: that root reports `source: 'measured'`, so "nobody
+ *     stated this" is a visible fact rather than silence.
+ *
+ * Published as the `readiness` facet of `/__editor/state`
+ * (`command-listener.ts`'s `collectState`), which is what `vgai status` reads.
+ */
+
+import type {
+  MountFailureKind,
+  ReadinessSource,
+} from '@volter/editor-project/adapter/ingest/mount-readiness';
+
+/** How a root's readiness is answered. See this module's header for each. */
+export type ReadinessMechanism = 'host-mount' | 'contract-ready' | 'measured-wait';
+
+export interface RootReadiness {
+  /** The manifest root id, as every other per-root facet names it. */
+  readonly rootId: string;
+  readonly mechanism: ReadinessMechanism;
+  /** `declared` for `host-mount`/`contract-ready`, `measured` otherwise — the
+   *  one field that makes a fallback legible as a fallback. */
+  readonly source: ReadinessSource;
+  /** `waiting` is a real state, not a missing answer: a self-booting game on a
+   *  hidden tab parks there indefinitely and nothing is wrong. */
+  readonly state: 'waiting' | 'ready' | 'failed';
+  /** Which of M29's three blockers, for a `failed` root. */
+  readonly failure?: MountFailureKind;
+}
+
+/**
+ * RESOURCE OWNERSHIP: one entry per root, written by the mount path that owns
+ * that root's lifecycle (`play-mode.ts` for host-mounted roots,
+ * `authoring/ingest-root-adapter.ts` for self-booting ones) and cleared by that
+ * same path's teardown. `clearRootReadiness` is per-root for the reason
+ * `clearMountFailureReport` is: a composite manifest mounts roots
+ * independently, and a blanket clear on one root's teardown would erase a
+ * sibling's still-true answer.
+ */
+const _readiness = new Map<string, RootReadiness>();
+let _snapshot: readonly RootReadiness[] = [];
+const _listeners = new Set<() => void>();
+
+function publish(): void {
+  _snapshot = [..._readiness.values()];
+  for (const listener of _listeners) listener();
+}
+
+/** `useSyncExternalStore`-compatible subscription for viewport explanations. */
+export function subscribeRootReadiness(listener: () => void): () => void {
+  _listeners.add(listener);
+  return () => _listeners.delete(listener);
+}
+
+export function recordRootReadiness(entry: RootReadiness): void {
+  _readiness.set(entry.rootId, entry);
+  publish();
+}
+
+export function clearRootReadiness(rootId: string): void {
+  if (!_readiness.delete(rootId)) return;
+  publish();
+}
+
+/** Test seam. Every production teardown clears PER ROOT (see the ownership note
+ *  above), so nothing but a test has the whole map's lifetime to drop. */
+export function clearAllRootReadiness(): void {
+  if (_readiness.size === 0) return;
+  _readiness.clear();
+  publish();
+}
+
+/**
+ * Every root's readiness, in the order they were recorded. `[]` means nothing
+ * has mounted — deliberately NOT the same as "nothing is ready", which is what
+ * a bare boolean would have said.
+ */
+export function readinessFacet(): readonly RootReadiness[] {
+  return _snapshot;
+}
+
+/**
+ * The one sentence a reader gets when a project's readiness is entirely
+ * measured — i.e. no root stated it and every answer here is a host-side wait.
+ * `null` when there is nothing to say (nothing mounted, or at least one root
+ * declared), because a warning that fires on healthy projects is a warning
+ * people learn to skip.
+ */
+export function measuredReadinessWarning(): string | null {
+  const entries = readinessFacet();
+  if (entries.length === 0) return null;
+  const measured = entries.filter((entry) => entry.source === 'measured');
+  if (measured.length === 0) return null;
+  return (
+    `${measured.length} of ${entries.length} root(s) have NO readiness declaration ` +
+    `(${measured.map((entry) => entry.rootId).join(', ')}) — the host is measuring instead. ` +
+    'A self-booting game states it with `window.vgaiGame.ready`.'
+  );
+}

package/src/reflection-probe-helper.ts

@@ -0,0 +1,142 @@
+import { EDITOR_LAYER } from '@volter/editor-threejs/viewport/editor-layers';
+import { reflectionProbeOf } from '@volter/editor-threejs/adapter/reflection-probe';
+import { setUserData } from '@volter/editor-threejs/ecs/user-data';
+import * as THREE from 'three';
+
+const INFLUENCE = new THREE.Color(0x4aa8ff);
+const INFLUENCE_SELECTED = new THREE.Color(0x75c4ff);
+const PARALLAX = new THREE.Color(0xffb84a);
+const CAPTURE = new THREE.Color(0xffffff);
+
+/**
+ * Editor-only visualization for a project-owned reflection probe. It follows
+ * the live Object3D mark but owns every line and material it draws, so no
+ * helper enters the game's JSX tree or its runtime camera.
+ */
+export class ReflectionProbeHelper extends THREE.Group {
+  private signature = '';
+  private selected = false;
+
+  constructor(readonly source: THREE.Object3D) {
+    super();
+    this.name = 'Reflection Probe Helper';
+    this.matrixAutoUpdate = false;
+    this.renderOrder = 998;
+    setUserData(this, 'editorHelper', true);
+    setUserData(this, 'editorHelperType', 'reflection-probes');
+    this.layers.set(EDITOR_LAYER);
+    this.refresh(true);
+  }
+
+  setSelected(selected: boolean): void {
+    if (this.selected === selected) return;
+    this.selected = selected;
+    this.refresh(true);
+  }
+
+  update(): void {
+    this.refresh(false);
+    this.source.updateWorldMatrix(true, false);
+    this.matrix.copy(this.source.matrixWorld);
+    this.matrixWorldNeedsUpdate = true;
+  }
+
+  dispose(): void {
+    this.clearVisuals();
+    this.removeFromParent();
+  }
+
+  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: each branch draws one independently meaningful probe volume.
+  private refresh(force: boolean): void {
+    const probe = reflectionProbeOf(this.source);
+    if (!probe) return;
+    const config = probe.config;
+    const next = JSON.stringify(config);
+    if (!force && next === this.signature) return;
+    this.signature = next;
+    this.clearVisuals();
+
+    const influenceColor = this.selected ? INFLUENCE_SELECTED : INFLUENCE;
+    const influenceOpacity = this.selected ? 1 : 0.62;
+    const blend = Math.max(0, config.blendDistance);
+
+    if (config.shape === 'sphere') {
+      const radius = Math.max(0.01, config.radius);
+      this.addWire(new THREE.SphereGeometry(radius, 24, 16), influenceColor, influenceOpacity);
+      if (blend > 0 && radius - blend > 0.01) {
+        this.addWire(
+          new THREE.SphereGeometry(radius - blend, 20, 12),
+          influenceColor,
+          this.selected ? 0.55 : 0.28,
+        );
+      }
+    } else {
+      const [x, y, z] = config.size.map((value) => Math.max(0.01, value)) as [
+        number,
+        number,
+        number,
+      ];
+      this.addWire(new THREE.BoxGeometry(x, y, z), influenceColor, influenceOpacity);
+      const inner = [x - blend * 2, y - blend * 2, z - blend * 2] as const;
+      if (blend > 0 && inner.every((value) => value > 0.01)) {
+        this.addWire(
+          new THREE.BoxGeometry(inner[0], inner[1], inner[2]),
+          influenceColor,
+          this.selected ? 0.55 : 0.28,
+        );
+      }
+    }
+
+    if (config.parallaxProjection) {
+      const [x, y, z] = config.parallaxSize.map((value) => Math.max(0.01, value)) as [
+        number,
+        number,
+        number,
+      ];
+      const box = this.addWire(
+        new THREE.BoxGeometry(x, y, z),
+        PARALLAX,
+        this.selected ? 0.9 : 0.45,
+      );
+      box.position.fromArray(config.parallaxOffset);
+    }
+
+    const origin = this.addWire(
+      new THREE.OctahedronGeometry(this.selected ? 0.16 : 0.11),
+      CAPTURE,
+      this.selected ? 1 : 0.72,
+    );
+    origin.position.fromArray(config.captureOffset);
+    this.traverse((object) => object.layers.set(EDITOR_LAYER));
+  }
+
+  private addWire(
+    sourceGeometry: THREE.BufferGeometry,
+    color: THREE.Color,
+    opacity: number,
+  ): THREE.LineSegments {
+    const geometry = new THREE.EdgesGeometry(sourceGeometry);
+    sourceGeometry.dispose();
+    const material = new THREE.LineBasicMaterial({
+      color,
+      depthTest: false,
+      transparent: true,
+      opacity,
+      toneMapped: false,
+    });
+    const wire = new THREE.LineSegments(geometry, material);
+    wire.renderOrder = this.renderOrder;
+    this.add(wire);
+    return wire;
+  }
+
+  private clearVisuals(): void {
+    for (const child of [...this.children]) {
+      child.removeFromParent();
+      const line = child as THREE.LineSegments;
+      line.geometry?.dispose();
+      const materials = Array.isArray(line.material) ? line.material : [line.material];
+      for (const material of materials) material?.dispose();
+    }
+  }
+}

package/src/reported-play-state.ts

@@ -0,0 +1,90 @@
+/**
+ * Honest play-state reporting for the control API (`vgai status`) — the
+ * derivation half of the SimCity ledger's S-1 "false-alive ingest status".
+ *
+ * ## The defect this closes
+ *
+ * `EditorShellStore.playState` is EDITOR UI STATE. Every lane that mounts
+ * something writes `'playing'` into it, but only play mode's write is
+ * accompanied by a live `play-mode.ts` `_session`, which is the predicate the
+ * whole debug seam gates on (`isPlayModeActive()`, `command-listener.ts`'s
+ * `notPlayingResult`). `collectState` reported the store flag verbatim, so a
+ * mounted lane printed `playState: "playing"` while every `game.state()` /
+ * `game.command()` call refused with "not in play mode" — the two predicates
+ * disagreeing in the same breath.
+ *
+ * Worse, a lane sets `'playing'` BEFORE the mount is attempted (it is what
+ * swaps the viewport onto the live scene). A mount that then threw left the
+ * flag behind, so a DEAD game reported itself alive.
+ *
+ * ## The rule
+ *
+ * A reported play state is a claim about something that is actually running,
+ * so it is derived from the LIVE-SESSION REGISTRY (`live-session-registry.ts`)
+ * — the host's one question about what runs — never from the UI flag alone,
+ * and it names no lane:
+ *
+ *  - nothing mounted is `stopped`, whatever the stale flag says;
+ *  - a mount whose lane was not asked to run is `paused` — a freshly mounted,
+ *    still-cold session is `paused`, not `playing`;
+ *  - otherwise the store flag, which for a running lane is written in lockstep.
+ *
+ * Pure and injectable so the whole decision is unit-testable with no browser
+ * (`packages/editor/test/ingest-status.test.ts`).
+ *
+ * ## Why this is not folded back into the store's getter
+ *
+ * Because the two answer different questions, and the store's is the one the
+ * editor itself needs. `isPlayModeActive()` is `_instance.session !== null`,
+ * assigned only after the mount resolves — so a derived `store.playState` would
+ * read `'stopped'` for the whole play boot (manifest fetch, entry resolution,
+ * the mount itself), and the structural-edit block, the design session's
+ * suspend, the Play bar and the viewport-tab predicates would all act as though
+ * nothing were starting. The store's flag stays the editor's MODE; this stays
+ * the report.
+ */
+
+import type { MountFailureReport } from './authoring/mount-failure-report';
+
+/** The vocabulary `EditorShellStore.playState` and the SDK's status both use. */
+export type ReportedPlayState = 'stopped' | 'playing' | 'paused';
+
+/** Everything the derivation reads. Assembled by the caller from the live
+ *  module singletons so this module itself imports no session state. */
+export interface LiveSurfaceFacts {
+  /** `EditorShellStore.playState` — the UI flag, used only where it is backed. */
+  readonly storePlayState: ReportedPlayState;
+  /** `live-session-registry.ts`: some lane owns a canvas right now. */
+  readonly liveMounted: boolean;
+  /** `live-session-registry.ts`: some lane was asked to RUN content. */
+  readonly livePlaying: boolean;
+  /** Recorded mount failures (`authoring/mount-failure-report.ts`). */
+  readonly mountFailures: readonly MountFailureReport[];
+}
+
+/**
+ * The reported play state — derived from what is actually running, asked of
+ * the live-session registry so no lane is named: a held mount (a mounted game
+ * whose loop is stopped) is `paused`; a running one reports the store's
+ * playing/paused; nothing mounted is `stopped` whatever the store says.
+ */
+export function deriveReportedPlayState(facts: LiveSurfaceFacts): ReportedPlayState {
+  if (!facts.liveMounted) {
+    // Nothing is running. A leftover `'playing'`/`'paused'` here is exactly
+    // the false-alive report S-1 is about — a mount that threw after setting
+    // the flag.
+    return 'stopped';
+  }
+  if (!facts.livePlaying) return 'paused';
+  return facts.storePlayState === 'paused' ? 'paused' : 'playing';
+}
+
+/**
+ * True when the editor is reporting a world that FAILED to mount and has no
+ * live session to replace it. Consumers surface this as the "dead game" signal
+ * (`vgai status`'s `mountFailures`, the status bar's mount-failure item)
+ * rather than making a reader diff two other fields to notice.
+ */
+export function hasDeadMount(facts: LiveSurfaceFacts): boolean {
+  return facts.mountFailures.length > 0 && !facts.liveMounted;
+}

package/src/resolve-relative-specifier.ts

@@ -0,0 +1,33 @@
+/**
+ * Resolve a RELATIVE import specifier against an index of known project
+ * paths — the extensionless-import answer (`./x` → `x.tsx`/`x.ts`/index
+ * variants) answered from a REAL index, never by guessing an extension onto
+ * a path. `null` when the specifier is not relative or nothing in the index
+ * matches. The one algorithm behind both the component index and the
+ * project adapter's module resolver; two copies of the candidate list is
+ * how play and the finders disagree about which module a specifier names.
+ */
+export function resolveRelativeSpecifier(
+  specifier: string,
+  fromPath: string,
+  paths: ReadonlySet<string>,
+): string | null {
+  if (!specifier.startsWith('.')) return null;
+  const dir = fromPath.replaceAll('\\', '/').split('/').slice(0, -1);
+  for (const segment of specifier.split('/')) {
+    if (segment === '.' || segment === '') continue;
+    if (segment === '..') dir.pop();
+    else dir.push(segment);
+  }
+  const base = dir.join('/');
+  for (const candidate of [
+    base,
+    `${base}.tsx`,
+    `${base}.ts`,
+    `${base}/index.tsx`,
+    `${base}/index.ts`,
+  ]) {
+    if (paths.has(candidate)) return candidate;
+  }
+  return null;
+}