@vgai/editor 0.2.0

package/src/authoring/viewport-pick-context.ts

@@ -0,0 +1,31 @@
+/**
+ * Viewport pick context (B4, D12) — the camera/canvas seam that
+ * `VgaiSceneAuthoringAdapter.pickable.pick` needs but cannot own itself: both
+ * live on `EditorViewport`, not on the adapter (the adapter only ever held a
+ * `store` — see its own doc comment). A tiny module-level slot, same shape as
+ * `./active-systems.ts`: `EditorViewport`'s constructor sets it once its
+ * camera/canvas exist; its `dispose()` clears it.
+ *
+ * Absent (module load, a headless unit test that builds the adapter with no
+ * live viewport, or after `dispose()`) ⇒ `pick()` returns `null` — an honest
+ * degrade, never a throw.
+ */
+
+import type * as THREE from 'three';
+
+export interface ViewportPickContext {
+  readonly camera: THREE.Camera;
+  readonly canvas: HTMLCanvasElement;
+}
+
+let _ctx: ViewportPickContext | null = null;
+
+/** Install/clear the live viewport's pick context (`EditorViewport` ctor/dispose). */
+export function setViewportPickContext(ctx: ViewportPickContext | null): void {
+  _ctx = ctx;
+}
+
+/** The live viewport's camera/canvas, or `null` when none is mounted. */
+export function getViewportPickContext(): ViewportPickContext | null {
+  return _ctx;
+}

package/src/authoring/viewport-raycast.ts

@@ -0,0 +1,80 @@
+/**
+ * Shared threejs viewport raycast pick (B4, D12) — the adapter-AGNOSTIC
+ * entity-under-the-pointer raycast, extracted verbatim from
+ * `editor-viewport.ts`'s former `_raycastEntity` so EVERY threejs-backed
+ * authoring adapter whose live objects sit in `store.objectMap` reuses the
+ * exact same logic:
+ *   - first-party `VgaiSceneAuthoringAdapter` (edit mode's focused world),
+ *   - `IngestAuthoringAdapter` (an ingested foreign threejs game — bare ingest
+ *     mode AND the threejs child of a multi-world PLAY composite).
+ *
+ * Pre-B4, `_onPointerUp` ran this raycast UNCONDITIONALLY against
+ * `store.objectMap` regardless of which adapter was active, so an ingest/
+ * multi-world-play canvas click selected the object under the pointer. B4's
+ * `pickTopmost` routes through the active adapter's `pickable` instead, so
+ * that behavior only survives if each threejs adapter exposes a `pickable`
+ * backed by THIS helper (the raycast never depended on `SceneEntity`/`.vscn` —
+ * only on `store.objectMap` + `userData.entityId` + `store.isEntityLocked`,
+ * all of which an ingest mount populates identically to a first-party one).
+ *
+ * The camera/canvas live only on `EditorViewport`, reached through the
+ * `viewport-pick-context.ts` seam (its ctor/`dispose()` set/clear it). Absent
+ * (a headless unit test, or no live viewport mounted) ⇒ `null`, an honest
+ * degrade rather than a throw. Uses its OWN `THREE.Raycaster` with
+ * `layers.enableAll()` replicated so it hits gizmo-adjacent EDITOR_LAYER-tagged
+ * geometry exactly like the original.
+ */
+
+import { getUserData } from '@engine/scene/user-data';
+import * as THREE from 'three';
+import type { EditorStore } from '../editor-store';
+import { getViewportPickContext } from './viewport-pick-context';
+
+/** Raycast `store.objectMap` and return the entity id under `(clientX,
+ *  clientY)`, or `null`. Skips editor-helper geometry and locked entities,
+ *  identical to the pre-B4 viewport raycast. */
+export function raycastPick(store: EditorStore, clientX: number, clientY: number): string | null {
+  const ctx = getViewportPickContext();
+  if (!ctx) return null; // no live viewport mounted — honest degrade
+  const rect = ctx.canvas.getBoundingClientRect();
+  const mouse = new THREE.Vector2(
+    ((clientX - rect.left) / rect.width) * 2 - 1,
+    -((clientY - rect.top) / rect.height) * 2 + 1,
+  );
+  const raycaster = new THREE.Raycaster();
+  raycaster.layers.enableAll();
+  raycaster.setFromCamera(mouse, ctx.camera);
+
+  const entityObjects: THREE.Object3D[] = [];
+  for (const obj of store.objectMap.values()) entityObjects.push(obj);
+
+  const intersects = raycaster.intersectObjects(entityObjects, true);
+  for (const isect of intersects) {
+    // Skip editor helper geometry (wireframes, frustum lines, etc.) — these
+    // are visual-only; selection should go through the entity mesh or icon
+    // billboard.
+    let isHelper = false;
+    let walk: THREE.Object3D | null = isect.object;
+    while (walk) {
+      if (getUserData(walk, 'editorHelper')) {
+        isHelper = true;
+        break;
+      }
+      if (getUserData(walk, 'entityId')) break;
+      walk = walk.parent;
+    }
+    if (isHelper) continue;
+
+    // Walk up to find the entity root.
+    let hit: THREE.Object3D | null = isect.object;
+    while (hit && !getUserData(hit, 'entityId')) {
+      hit = hit.parent;
+    }
+    if (hit) {
+      const eid = getUserData(hit, 'entityId') as string;
+      // Skip locked entities in viewport selection.
+      if (!store.isEntityLocked(eid)) return eid;
+    }
+  }
+  return null;
+}

package/src/authoring/world-overlay.ts

@@ -0,0 +1,76 @@
+/**
+ * Manifest-era world overlay persistence (T6.1 slice 3, docs/MULTI-WORLD-DESIGN.md
+ * §1.G) — overlay storage for a `WorldMountSpec` id in the multi-world play path,
+ * keyed by the manifest's own `world.id` (unlike `ingest-overlay.ts`'s game id or
+ * `world2d-overlay.ts`'s `2d-`-prefixed silo id). Same overlay-file MECHANICS as
+ * those two (a JSON blob keyed by structural-path ids, reapplied on remount), but
+ * a DIFFERENT root: `.vgai/overlays/<world-id>.json` under the PROJECT ROOT, not
+ * under `public/`.
+ *
+ * Why a separate root from the (now-deleted) `world2d-overlay.ts`'s `2d-`-prefixed
+ * silo: those overlays went through `StorageBackend` (`getStorageBackend()`), and
+ * in server mode that is `HttpStorage`, which is hard-rooted at `<projectRoot>/public/`
+ * (its own doc comment says so) — so a `.vgai/overlays/<id>.json` written through
+ * it actually landed at `<projectRoot>/public/.vgai/overlays/<id>.json`, contradicting
+ * the overlay path functions' "project-root-relative" doc comments. That finding is
+ * recorded in `docs/BACKBONE-TASKS.md`'s T3.3 close-out. This module was the first
+ * "unify toward one namespace" half of §1.G: NEW manifest-world-id overlays are
+ * honestly project-root-relative from the start, using:
+ *   - server mode: the dedicated `/__editor/vgai-file` route pair
+ *     (`editor-server.ts`), which reads/writes `<projectRoot>/.vgai/...` directly
+ *     via `node:fs` — the SAME root the editor-state/thumbnail machinery already
+ *     uses, bypassing `HttpStorage`'s `public/` rooting entirely.
+ *   - browser mode: `getStorageBackend()` directly — `OpfsStorage`/`FsaStorage`
+ *     (`HandleStorage`) root at the TRUE project folder (OPFS root / the
+ *     FSA-picked directory), with no `public/` insertion at all, so no duality
+ *     exists there to work around.
+ * `ingest-overlay.ts`'s `loadOverlay`/`saveOverlay` later adopted this EXACT
+ * mode-branched pattern too (the T3.3 finding's remediation) — both overlay
+ * families now share the one project-root `.vgai/` namespace, via the SAME
+ * `/__editor/vgai-file` route pair in server mode.
+ */
+
+import { getEditorMode } from '../editor-mode';
+import { getStorageBackend } from '../storage';
+
+const BASE = '/__editor';
+
+/** Where a manifest world's overlay lives, project-root-relative (§1.G). */
+export function worldOverlayPath(worldId: string): string {
+  return `.vgai/overlays/${worldId}.json`;
+}
+
+/** Load a manifest world's saved overlay, or `{}` if none exists / is unreadable. */
+export async function loadWorldOverlay<T extends object = Record<string, unknown>>(
+  worldId: string,
+): Promise<T> {
+  const path = worldOverlayPath(worldId);
+  try {
+    if (getEditorMode() === 'browser') {
+      const backend = getStorageBackend();
+      if (!(await backend.exists(path))) return {} as T;
+      return JSON.parse(await backend.read(path)) as T;
+    }
+    const res = await fetch(`${BASE}/vgai-file?${new URLSearchParams({ path })}`);
+    if (!res.ok) return {} as T;
+    return JSON.parse(await res.text()) as T;
+  } catch {
+    return {} as T;
+  }
+}
+
+/** Persist a manifest world's overlay (§1.G — project-root `.vgai/overlays/`). */
+export async function saveWorldOverlay(worldId: string, overlay: object): Promise<void> {
+  const path = worldOverlayPath(worldId);
+  const content = JSON.stringify(overlay, null, 2);
+  if (getEditorMode() === 'browser') {
+    await getStorageBackend().write(path, content);
+    return;
+  }
+  const res = await fetch(`${BASE}/vgai-file`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({ path, content }),
+  });
+  if (!res.ok) throw new Error(`saveWorldOverlay '${worldId}': HTTP ${res.status}`);
+}

package/src/authoring/world-pan-state.ts

@@ -0,0 +1,115 @@
+/**
+ * World pan state (spec27 §8 "space-pan" row, D4 rebuild —
+ * docs/unified-world-editor/27-visual-react-editing.md) — a module-level
+ * subscribable singleton (mirrors `eyedropper-session.ts`'s "bare singleton +
+ * own listener set" shape) holding the CURRENT SHARED pan translate `(x, y)`
+ * applied, in LOCKSTEP, to both every design-time world-layer host
+ * (`design-time-layers.ts`'s `createLayerElement`-produced react/pixi layers)
+ * and `WorldSelectionOverlay`'s own outer wrapper.
+ *
+ * SOUNDNESS (why lockstep preserves the "zero-correction" host-relative rect
+ * invariant `WorldSelectionOverlay.tsx`'s own doc comment establishes):
+ * `RectProvider.rect(id)` is computed as `el.getBoundingClientRect()` MINUS
+ * the owning world's own root/host `getBoundingClientRect()`
+ * (`react-world-authoring-adapter.ts`'s `toHostRelative`/`hostRect` — `this
+ * .root` IS the exact layer div `createLayerElement` produces). A CSS
+ * `transform: translate()` applied directly to that host element shifts the
+ * host's OWN rendered rect AND every descendant's rendered rect by the
+ * IDENTICAL `(x, y)` delta — a rigid subtree translation — so the
+ * subtraction is invariant under pan: `rect(id)` returns the SAME
+ * host-relative numbers at any pan offset, unmodified, with no pan-awareness
+ * needed in the adapter, `inspect.ts`'s geometry math, or any of the ~14
+ * overlay chrome consumers. `PickProvider.pick` needs no changes either — it
+ * hit-tests real rendered rects against the real client cursor position,
+ * both of which already reflect the applied transform natively.
+ *
+ * Applying the exact SAME transform to `WorldSelectionOverlay`'s own outer
+ * wrapper (a SIBLING of every world-layer host inside the SAME
+ * `ViewportPanel` containerRef parent — see that file's own mount-site doc
+ * comment) shifts the overlay's local coordinate origin by the identical
+ * `(x, y)` — so drawing a chrome element at `rect(id)`'s (pan-invariant)
+ * host-relative `(x, y)` inside the panned overlay wrapper lands it at the
+ * SAME screen position as the panned live element it describes. This is the
+ * entire "lockstep" contract: every consumer on both sides of the pan reads
+ * ONE shared value (`getWorldPan()`) and applies it through the ONE shared
+ * pure helper (`panTransformValue`) — never two independently-computed
+ * transforms that could drift.
+ */
+
+export interface WorldPan {
+  readonly x: number;
+  readonly y: number;
+}
+
+const ZERO_PAN: WorldPan = { x: 0, y: 0 };
+
+let _pan: WorldPan = ZERO_PAN;
+const listeners = new Set<() => void>();
+
+function notify(): void {
+  for (const l of listeners) l();
+}
+
+/** The current shared pan translate, in CSS px. */
+export function getWorldPan(): WorldPan {
+  return _pan;
+}
+
+/** Set the shared pan translate to an absolute `(x, y)`. */
+export function setWorldPan(x: number, y: number): void {
+  if (_pan.x === x && _pan.y === y) return;
+  _pan = { x, y };
+  notify();
+}
+
+/** Set the shared pan translate by a RELATIVE `(dx, dy)` — a convenience
+ *  wrapper over `setWorldPan` (not used by `WorldSelectionOverlay`'s own
+ *  space-drag, which composes onto a captured drag-start snapshot instead —
+ *  see its own doc comment — but kept here as the natural pure counterpart
+ *  for any future incremental caller, e.g. a nudge-pan keybinding). */
+export function panWorldBy(dx: number, dy: number): void {
+  setWorldPan(_pan.x + dx, _pan.y + dy);
+}
+
+/** Reset pan to `(0, 0)` — called on a world-layer remount (`design-time-
+ *  layers.ts`'s `mountDesignTimeLayers`, invoked on initial edit-mode install
+ *  AND every `'editor:edit-mode-rebuild'`), so switching/reloading the active
+ *  world set never leaves a stale pan offset applied over a DIFFERENT layer
+ *  stack. A no-op (no `notify()`) when already at rest, so a fresh session
+ *  never fires a spurious subscriber tick. */
+export function resetWorldPan(): void {
+  if (_pan.x === 0 && _pan.y === 0) return;
+  _pan = ZERO_PAN;
+  notify();
+}
+
+/** Subscribe to pan changes — both `design-time-layers.ts` (imperative DOM
+ *  style writes) and `WorldSelectionOverlay` (`useSyncExternalStore`) bind
+ *  this so every lockstep mount point re-applies the SAME new value the
+ *  instant it changes. */
+export function subscribeWorldPan(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+/**
+ * The ONE shared CSS `transform` value both lockstep mount points apply —
+ * pure, so a unit test can assert the world-layer host and the overlay
+ * wrapper are handed byte-identical strings for any given pan (the actual
+ * "lockstep" proof). `undefined` at rest `(0, 0)` so neither mount point ever
+ * carries a no-op `transform: translate(0px, 0px)` — keeps every pre-pan
+ * pixel-position snapshot (the full 27x suite, pinned at pan=0) byte-identical
+ * to its pre-this-feature output.
+ */
+export function panTransformValue(pan: WorldPan): string | undefined {
+  if (pan.x === 0 && pan.y === 0) return undefined;
+  return `translate(${pan.x}px, ${pan.y}px)`;
+}
+
+/** Test-only reset (mirrors `eyedropper-session.ts`'s/`world-session-
+ *  state.ts`'s identical helpers) — drops pan + every subscriber so unit
+ *  tests don't leak state across cases. */
+export function _resetWorldPanStateForTest(): void {
+  _pan = ZERO_PAN;
+  listeners.clear();
+}

package/src/authoring/world-session-state.ts

@@ -0,0 +1,102 @@
+/**
+ * World session state (B1, docs/unified-world-editor/26-unified-editor-spec.md
+ * §3 B1 · D9) — a module-level subscribable singleton (same shape as
+ * `./mount-failure-report.ts`: a bare get/set slot, no subscribe of its own —
+ * every caller that mutates it follows up with `store.notifyIngestEdit()`,
+ * which every panel already re-renders off via `useSyncExternalStore(store.subscribe,
+ * …)`) holding THREE session-local, per-worldId toggles that are NEVER
+ * serialized/persisted (D9: "eye = session-local viewport visibility, never
+ * serialized" — generalized here to all three, none of which is an authored
+ * property):
+ *
+ *  - `hidden` — the eye (A2/D9). LIFTED out of `GameHierarchy.tsx`'s former
+ *    local `useState<Set<string>> hiddenWorldIds` (module-private React state
+ *    the design-time layer stack could never see) so `design-time-layers.ts`
+ *    can hide/show a world's actual DOM layer, not just dim its hierarchy row.
+ *  - `interactive` — forwards real pointer events to the layer (for testing
+ *    hover/press states at design time); off by default (`pointer-events:none`
+ *    is the layer's resting state — see `design-time-layers.ts`).
+ *  - `pickLock` — stored here for B4 to consume (layered viewport picking,
+ *    D12): a pick-locked layer is skipped by the topmost-first pick walk.
+ *    B1 only stores/exposes the toggle; nothing reads it yet.
+ *
+ * Keyed by the RAW manifest world id (`CompositeChild.worldId` /
+ * `ResolvedWorldEntry.id`) — the SAME id `design-time-layers.ts` gets from
+ * `composite.childAdapters()`, NOT the composite's synthetic `world:<id>`
+ * group-node id. `GameHierarchy.tsx` (whose rows ARE keyed by the group-node
+ * id) resolves the raw worldId via `compositeGroupBadge`'s `worldId` field
+ * before calling into this module — see that file's row component.
+ *
+ * A process-lifetime singleton (not project-scoped): switching projects
+ * within the same tab does not reset these toggles. That's a deliberate
+ * relaxation of the former per-mount-React-state behavior (which reset on
+ * every `GameHierarchy` remount) — "session-local" here means "this browser
+ * tab's session", matching D9's own framing; nothing depends on a
+ * project-switch reset.
+ */
+
+export interface WorldSessionState {
+  readonly hidden: boolean;
+  readonly interactive: boolean;
+  readonly pickLock: boolean;
+}
+
+const DEFAULT_STATE: WorldSessionState = { hidden: false, interactive: false, pickLock: false };
+
+const _states = new Map<string, WorldSessionState>();
+
+function get(worldId: string): WorldSessionState {
+  return _states.get(worldId) ?? DEFAULT_STATE;
+}
+
+function patch(worldId: string, partial: Partial<WorldSessionState>): void {
+  _states.set(worldId, { ...get(worldId), ...partial });
+}
+
+/** The eye (A2/D9): true while `worldId`'s design-time layer is hidden. */
+export function isWorldHidden(worldId: string): boolean {
+  return get(worldId).hidden;
+}
+
+export function setWorldHidden(worldId: string, hidden: boolean): void {
+  patch(worldId, { hidden });
+}
+
+export function toggleWorldHidden(worldId: string): void {
+  setWorldHidden(worldId, !isWorldHidden(worldId));
+}
+
+/** True while `worldId`'s layer forwards real pointer events (design-time
+ *  hover/press testing) instead of its resting `pointer-events:none`. */
+export function isWorldInteractive(worldId: string): boolean {
+  return get(worldId).interactive;
+}
+
+export function setWorldInteractive(worldId: string, interactive: boolean): void {
+  patch(worldId, { interactive });
+}
+
+export function toggleWorldInteractive(worldId: string): void {
+  setWorldInteractive(worldId, !isWorldInteractive(worldId));
+}
+
+/** B4 will read this to skip a layer in the topmost-first pick walk; B1 only
+ *  stores/exposes the toggle. */
+export function isWorldPickLocked(worldId: string): boolean {
+  return get(worldId).pickLock;
+}
+
+export function setWorldPickLock(worldId: string, pickLock: boolean): void {
+  patch(worldId, { pickLock });
+}
+
+export function toggleWorldPickLock(worldId: string): void {
+  setWorldPickLock(worldId, !isWorldPickLocked(worldId));
+}
+
+/** Test-only: drop every world's session state back to defaults so unit
+ *  tests don't leak toggles across cases (this module is a process-lifetime
+ *  singleton — see the header comment). */
+export function _resetWorldSessionStateForTest(): void {
+  _states.clear();
+}