@vgai/editor 0.2.0 → 0.4.0-canary.20260715.0

package/src/authoring/world2d-authoring-adapter.ts

@@ -14,6 +14,7 @@
 import type {
   AuthoringAdapter,
   AuthoringCapabilities,
+  AuthoringProvenance,
   EditorNode,
   HierarchyProvider,
   InspectorProvider,
@@ -32,7 +33,21 @@ import {
 import type { PhysicsAdapter2D } from '@engine/world2d/system-adapters-2d';
 import type { Container } from 'pixi.js';
 import type { EditorStore } from '../editor-store';
-import { notifyUndoableOp, registerUndoAdapter } from './undo-timeline';
+import { JsonHistoryResource } from '../history/json-history-resource';
+
+interface World2DHistoryState {
+  overlay: Overlay2D;
+  nodes: Record<
+    string,
+    {
+      label: string;
+      alpha: number;
+      visible: boolean;
+      tint?: number;
+      transform?: Transform2DValue;
+    }
+  >;
+}
 
 function numToHex(n: number): string {
   return `#${(n & 0xffffff).toString(16).padStart(6, '0')}`;
@@ -64,11 +79,22 @@ export interface World2DAuthoringOptions {
 
 export class World2DAuthoringAdapter implements AuthoringAdapter {
   readonly capabilities: AuthoringCapabilities;
+
+  // Every construction site today persists through the 2D overlay
+  // (`saveWorldOverlay`) — including first-party pixi roots: the live tree
+  // is projected directly and never written back as source.
+  readonly provenance: AuthoringProvenance = {
+    source: 'foreign',
+    label: 'overlay',
+    detail:
+      'Live 2D (PixiJS) tree projected directly — edits persist to an editor overlay, never to the game source.',
+  };
   private readonly a2d: AuthoringAdapter2D;
   private readonly persistFn: ((overlay: Overlay2D) => Promise<void>) | undefined;
   /** Human-readable overlay destination (design §2) — see {@link World2DAuthoringOptions.destination}. */
   private readonly destination: string;
   private listeners = new Set<() => void>();
+  private readonly historyResource: JsonHistoryResource<World2DHistoryState> | null;
 
   constructor(
     root: Container,
@@ -93,14 +119,23 @@ export class World2DAuthoringAdapter implements AuthoringAdapter {
       reparent: false,
       persist: !!this.persistFn, // runtime-only unless a persist callback is wired
     };
-    // v4 architecture-review §7.1-13 (was T3.2 slice 2 for the structural twin,
-    // `IngestAuthoringAdapter`, only): this adapter IS the undo/redo target the
-    // editor-global timeline dispatches to for entries it records below
-    // (`pushUndo`). The caller (`play-mode.ts`'s `exitMultiWorldAuthoring`,
-    // `ingest-mode.ts`'s `exitIngestMode2D`) unregisters it on teardown — see
-    // those call sites' comments for why an unregistered-but-still-recorded
-    // entry is dropped (with a warn) rather than undone against a torn-down tree.
-    registerUndoAdapter(this);
+    const history = store.projectHistory;
+    this.historyResource = history
+      ? new JsonHistoryResource({
+          history,
+          kind: opts.persist ? 'overlay' : 'session-state',
+          scope: opts.persist ? 'project' : 'session',
+          ...(opts.persist
+            ? { location: (opts.destination ?? '.vgai/overlays/world2d.json').replace(/^\//, '') }
+            : { sessionId: `world2d-${crypto.randomUUID()}` }),
+          displayName: opts.destination ?? 'World 2D edits',
+          capture: () => this.captureHistoryState(),
+          restore: async (state) => {
+            this.restoreHistoryState(state);
+            if (this.persistFn) await this.persistFn(this.a2d.serializeOverlay());
+          },
+        })
+      : null;
   }
 
   refresh(): { count: number; sprites: number } {
@@ -161,6 +196,7 @@ export class World2DAuthoringAdapter implements AuthoringAdapter {
     return {
       id: n.id,
       label: n.label,
+      role: 'entity',
       kind: n.kind,
       parentId: n.parentId,
       childIds: n.childIds,
@@ -196,9 +232,10 @@ export class World2DAuthoringAdapter implements AuthoringAdapter {
     // exact same primitives `setTransform`/`getTransform` already use (no lossy
     // angle<->quaternion re-derivation on the undo path).
     beginEdit: (id) => {
+      this.historyResource?.assertCanMutate();
       const disp = this.a2d.displayObject(id);
       if (disp && this.physics.ownerOf(disp) === 'physics') this.physics.freeze(disp);
-      this.editStartTransform = this.a2d.getTransform(id) ?? undefined;
+      this.editStartState = this.captureHistoryState();
     },
     apply: (id, t) => {
       const pos: [number, number] = [t.position[0], t.position[1]];
@@ -211,23 +248,18 @@ export class World2DAuthoringAdapter implements AuthoringAdapter {
     endEdit: (id) => {
       const disp = this.a2d.displayObject(id);
       if (disp && this.physics.ownerOf(disp) === 'physics') this.physics.unfreeze(disp);
-      const prev = this.editStartTransform;
-      this.editStartTransform = undefined;
-      if (!prev) return;
-      const next = this.a2d.getTransform(id);
-      if (!next) return;
-      this.pushUndo({
-        undo: () => this.writeTransform(id, prev),
-        redo: () => this.writeTransform(id, next),
-      });
+      this.recordHistory(
+        `Transform ${this.a2d.node(id)?.label ?? '2D Object'}`,
+        this.editStartState,
+      );
+      this.editStartState = undefined;
     },
   };
 
   /** Write a 2D transform to the live tree (+ physics body, if owned) + the
-   *  overlay (via `AuthoringAdapter2D.setTransform`) — no undo push; shared by
-   *  `transforms.apply` (live-drag, no push) and the undo/redo thunks
-   *  `endEdit` records (which DO push, exactly once, on commit). */
+   * overlay. The gesture's complete before/after state is journaled at endEdit. */
   private writeTransform(id: string, t: Transform2DValue): void {
+    this.historyResource?.assertCanMutate();
     const disp = this.a2d.displayObject(id);
     if (disp && this.physics.ownerOf(disp) === 'physics') {
       this.physics.commit(disp, t.position, t.rotation);
@@ -255,12 +287,10 @@ export class World2DAuthoringAdapter implements AuthoringAdapter {
       return disp[path];
     },
     set: (id, path, value) => {
-      const prev = this.inspector.get(id, path); // snapshot for undo
+      this.historyResource?.assertCanMutate();
+      const before = this.captureHistoryState();
       this.writeProp(id, path, value);
-      this.pushUndo({
-        undo: () => this.writeProp(id, path, prev),
-        redo: () => this.writeProp(id, path, value),
-      });
+      this.recordHistory(`Set ${this.a2d.node(id)?.label ?? '2D Object'} ${path}`, before);
     },
   };
 
@@ -269,45 +299,72 @@ export class World2DAuthoringAdapter implements AuthoringAdapter {
   private writeProp(id: string, path: string, value: unknown): void {
     const disp = this.a2d.displayObject(id) as (Container & Record<string, unknown>) | null;
     if (!disp) return;
-    if (path === 'name') disp.label = value as string;
+    if (path === 'name') this.a2d.set(id, 'label', value as string);
     else if (path === 'tint') this.a2d.set(id, 'tint', hexToNum(value as string));
     else if (path === 'visible') this.a2d.set(id, 'visible', value as boolean);
+    else if (path === 'alpha') this.a2d.set(id, 'alpha', value as number);
     else disp[path] = value;
     this.notify();
   }
 
   // --- Overlay-backed undo/redo (v4 §7.1-13 — the world2d port of
   // IngestAuthoringAdapter's "Overlay-backed undo/redo" section). ---
-  private readonly undoStack: Array<{ undo: () => void; redo: () => void }> = [];
-  private readonly redoStack: Array<{ undo: () => void; redo: () => void }> = [];
-  private editStartTransform: Transform2DValue | undefined;
+  private editStartState: World2DHistoryState | undefined;
 
-  private pushUndo(entry: { undo: () => void; redo: () => void }): void {
-    this.undoStack.push(entry);
-    this.redoStack.length = 0;
-    notifyUndoableOp(this); // tag this op on the global timeline
+  private recordHistory(label: string, before: World2DHistoryState | undefined): void {
+    if (this.historyResource && before) {
+      void this.historyResource.record(label, before, this.captureHistoryState()).catch(() => {});
+      return;
+    }
+  }
+
+  subscribe(listener: () => void): () => void {
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
   }
 
-  undo(): boolean {
-    // `false` tells the undo timeline "couldn't act — put the entry back" (see
-    // `UndoAdapter` in `./undo-timeline.ts`).
-    const e = this.undoStack.pop();
-    if (!e) return false;
-    e.undo();
-    this.redoStack.push(e);
-    return true;
+  dispose(): void {
+    this.historyResource?.dispose();
+    this.listeners.clear();
   }
 
-  redo(): boolean {
-    const e = this.redoStack.pop();
-    if (!e) return false;
-    e.redo();
-    this.undoStack.push(e);
-    return true;
+  private captureHistoryState(): World2DHistoryState {
+    const nodes: World2DHistoryState['nodes'] = {};
+    const visit = (id: string): void => {
+      const node = this.a2d.node(id);
+      const display = this.a2d.displayObject(id) as (Container & { tint?: number }) | null;
+      if (!node || !display) return;
+      let transform: Transform2DValue | null = null;
+      try {
+        transform = this.a2d.getTransform(id);
+      } catch {
+        // A custom adapter may expose inspectable container-like nodes without
+        // Pixi transform observables. Their non-transform fields remain journaled.
+      }
+      nodes[id] = {
+        label: display.label ?? '',
+        alpha: display.alpha,
+        visible: display.visible,
+        ...('tint' in display ? { tint: display.tint } : {}),
+        ...(transform ? { transform } : {}),
+      };
+      for (const childId of node.childIds) visit(childId);
+    };
+    for (const root of this.a2d.roots()) visit(root.id);
+    return { overlay: structuredClone(this.a2d.serializeOverlay()), nodes };
   }
 
-  subscribe(listener: () => void): () => void {
-    this.listeners.add(listener);
-    return () => this.listeners.delete(listener);
+  private restoreHistoryState(state: World2DHistoryState): void {
+    for (const [id, value] of Object.entries(state.nodes)) {
+      const display = this.a2d.displayObject(id) as (Container & { tint?: number }) | null;
+      if (!display) continue;
+      display.label = value.label;
+      display.alpha = value.alpha;
+      display.visible = value.visible;
+      if (value.tint !== undefined && 'tint' in display) display.tint = value.tint;
+      if (value.transform) this.a2d.setTransform(id, value.transform);
+    }
+    this.a2d.replaceOverlay(state.overlay);
+    this.notify();
   }
 }

package/src/availability-tick.ts

@@ -0,0 +1,56 @@
+/**
+ * W5 (workspace-shell W5-candidates, recorded by the W4 reviewer in
+ * docs/workspace-shell/W0-INVENTORY.md §7): ONE shared 250ms availability
+ * tick replacing the three independent `setInterval(…, 250)` pollers that
+ * W4 left behind (utility availability, the play-only State Watch gate, and
+ * ConnectionStatus's networking-adapter poll).
+ *
+ * These gates all watch the SAME kind of out-of-band signal — a live play
+ * session's adapters appearing/disappearing without any store/registry
+ * notification — so they don't need three timers, three wakeups, and three
+ * interleaved re-render schedules; they need one heartbeat. The interval is
+ * refcounted: it starts with the first subscriber and stops with the last,
+ * so an idle editor (none of the three consumers mounted) runs no timer at
+ * all — strictly better than the three always-on intervals it replaces.
+ *
+ * `useSyncExternalStore`-shaped on purpose: consumers subscribe + read the
+ * monotonic version, then derive their own predicate (`getActiveDebug()`,
+ * `getActiveNetworking()`, utility availability) per render.
+ */
+
+import { useSyncExternalStore } from 'react';
+
+const TICK_MS = 250;
+
+let _version = 0;
+let _intervalId: ReturnType<typeof setInterval> | null = null;
+const _listeners = new Set<() => void>();
+
+function onTick(): void {
+  _version++;
+  for (const fn of _listeners) fn();
+}
+
+/** Subscribe to the shared 250ms tick. Starts the timer on first subscriber,
+ *  stops it with the last. Returns unsubscribe. */
+export function subscribeAvailabilityTick(fn: () => void): () => void {
+  _listeners.add(fn);
+  if (_intervalId === null) _intervalId = setInterval(onTick, TICK_MS);
+  return () => {
+    _listeners.delete(fn);
+    if (_listeners.size === 0 && _intervalId !== null) {
+      clearInterval(_intervalId);
+      _intervalId = null;
+    }
+  };
+}
+
+/** Monotonic tick counter — the `getSnapshot` for `useSyncExternalStore`. */
+export function availabilityTickVersion(): number {
+  return _version;
+}
+
+/** Re-render the calling component on every shared availability tick. */
+export function useAvailabilityTick(): void {
+  useSyncExternalStore(subscribeAvailabilityTick, availabilityTickVersion);
+}

package/src/browser-play-entry.ts

@@ -1,6 +1,8 @@
 /**
- * Browser play entry — a STATIC, dynamic-import-free version of the template's
- * `src/scripts/main.ts` for the static/browser editor build.
+ * Browser play compatibility entry — a STATIC, dynamic-import-free generic
+ * scene loader for the hosted editor build. The standalone scaffold no longer
+ * owns scene loading in setup code; this path remains for pre-bundled examples
+ * and browser-only projects that have no live manifest-module resolver.
  *
  * The static host has no dev server, so play mode can't `import('/@fs/.../main.ts')`.
  * Instead this file is pre-bundled (see `scripts/bundle-project-scripts.mjs`) into a
@@ -32,9 +34,7 @@ import { setAssetPrefix } from '@engine/loader';
 import type { EditorPreview, GameCleanup, GameContext } from '@engine/runtime/types';
 import { loadScene, loadSceneFromData } from '@engine/scene/scene-loader';
 import { applyScenePostProcessing } from '@engine/setup/setup-renderer';
-// The generic fallback's component registry is still the template's (soon-to-be
-// minimal) `src/scripts/registry.ts` — unrelated to example dispatch, and this
-// migration wave does not touch the template layout (a later wave does).
+// The generic compatibility fallback uses the template component registry.
 import { componentRegistry, gameComponents } from '../template/src/scripts/registry';
 import { SETUP_BY_EXAMPLE_ID } from './generated/setup-by-example.generated';
 

package/src/browser-project-scripts.ts

@@ -56,6 +56,7 @@ const BUNDLE_RUNTIME_MODULE_LOADERS: Record<string, () => Promise<unknown>> = {
   '@engine/audio': () => import('@engine/audio'),
   '@engine/data/data-asset': () => import('@engine/data/data-asset'),
   '@engine/ecs/game-component': () => import('@engine/ecs/game-component'),
+  '@engine/react/game-state': () => import('@engine/react/game-state'),
   '@engine/scene/scene-loader': () => import('@engine/scene/scene-loader'),
   '@engine/scene/scene-query': () => import('@engine/scene/scene-query'),
   '@engine/scene/user-data': () => import('@engine/scene/user-data'),

package/src/build-identity.ts

@@ -0,0 +1,15 @@
+import enginePackage from '../../engine/package.json';
+import { GAME_MANIFEST_VERSION } from '../../engine/src/manifest/schema';
+import editorPackage from '../package.json';
+import type { EditorServerCompatibility } from './editor-compatibility';
+
+/** Build-time package identity shared by browser-only editor surfaces. */
+export const BUNDLED_EDITOR_VERSION = editorPackage.version;
+export const BUNDLED_ENGINE_VERSION = enginePackage.version;
+export const BUNDLED_EDITOR_COMPATIBILITY: EditorServerCompatibility = {
+  apiVersion: 1,
+  engineVersion: BUNDLED_ENGINE_VERSION,
+  manifestVersion: GAME_MANIFEST_VERSION,
+  startedAt: 'browser-build',
+  source: { state: 'current' },
+};