@vgai/editor 0.2.0 → 0.4.0-canary.20260715.0

package/src/hierarchy-drop.ts

@@ -0,0 +1,50 @@
+/**
+ * Cross-world drop validity for the hierarchy shell (spec 29 §3,
+ * `docs/unified-world-editor/29-hierarchy-philosophy.md`): edge semantics
+ * belong to the kind, so `CompositeAuthoringAdapter`'s structure provider
+ * REFUSES cross-world reparents (loud warn + no-op) and cross-world reorder
+ * anchors. A drop the adapter will refuse must never LOOK valid in the panel —
+ * chrome advertising an operation that will be refused is a false claim — so
+ * `GameHierarchy`'s dragover path gates the drop indicator on this predicate
+ * instead of letting the drop fall through to the adapter's refusal.
+ *
+ * Rule zero: roots are resolved by ASKING the composite (`groupNodeId`/
+ * `ownerOf`), never by decoding adapter-minted id strings here.
+ */
+import type { AuthoringAdapter } from '@engine/adapter';
+import { CompositeAuthoringAdapter } from './authoring/composite-authoring-adapter';
+
+/** The world that owns `nodeId` for drop purposes: the owning child's
+ *  `worldId` for an ordinary row, the world itself for its synthetic
+ *  `world:<id>` group row (dropping INTO a world's own group row is
+ *  "become a root of my world" — valid), `null` for an organizational or
+ *  unrecognized id
+ *  no child recognizes. */
+function dropWorldOf(composite: CompositeAuthoringAdapter, nodeId: string): string | null {
+  for (const child of composite.childAdapters()) {
+    if (composite.groupNodeId(child.worldId) === nodeId) return child.worldId;
+  }
+  return composite.ownerOf(nodeId);
+}
+
+/**
+ * True when reparenting/reordering `dragIds` at row `targetId` will be
+ * accepted by the active adapter's structure provider: the adapter is not a
+ * composite (a bare adapter is single-world by construction), or EVERY
+ * dragged id and the target row live in the same world. A mixed-world
+ * multi-select fails as a whole — the alternative is a drop that half-applies
+ * (same-world ids move, foreign ids warn), which is worse than refusing the
+ * affordance outright. Group-row / organizational drag ids fail the same way
+ * (`ownerOf` → null): roots are reordered through their zOrder, not by
+ * dragging one into another's subtree.
+ */
+export function isSameWorldDrop(
+  adapter: AuthoringAdapter,
+  dragIds: string[],
+  targetId: string,
+): boolean {
+  if (!(adapter instanceof CompositeAuthoringAdapter)) return true;
+  const targetWorld = dropWorldOf(adapter, targetId);
+  if (targetWorld === null) return false;
+  return dragIds.every((id) => adapter.ownerOf(id) === targetWorld);
+}

package/src/hierarchy-expansion-state.ts

@@ -0,0 +1,100 @@
+/**
+ * Project-scoped hierarchy expansion preferences.
+ *
+ * Expansion belongs to an authored node's stable adapter id, not to its
+ * current row index. That lets the same preference survive an edit/live
+ * adapter replacement (Play/Stop) and ordinary React remounts. The project
+ * scope prevents common ids such as `game` or `root` leaking between games.
+ *
+ * Only explicit user choices are stored. A node with no entry follows the
+ * hierarchy's current shallow-open default, so changing the projection does
+ * not require a migration of a fully materialized tree state.
+ */
+
+const STORAGE_KEY = 'vgai:hierarchy-expansion:v1';
+
+type ProjectPreferences = Map<string, boolean>;
+
+const preferences = new Map<string, ProjectPreferences>();
+let hydrated = false;
+
+function browserStorage(): Storage | null {
+  try {
+    return typeof window === 'undefined' ? null : window.localStorage;
+  } catch {
+    return null;
+  }
+}
+
+function hydrate(): void {
+  if (hydrated) return;
+  hydrated = true;
+  const storage = browserStorage();
+  if (!storage) return;
+  try {
+    const parsed = JSON.parse(storage.getItem(STORAGE_KEY) ?? '{}') as Record<
+      string,
+      Record<string, boolean>
+    >;
+    for (const [projectId, nodes] of Object.entries(parsed)) {
+      preferences.set(projectId, new Map(Object.entries(nodes)));
+    }
+  } catch {
+    // A corrupt/stale preference must never prevent the editor from opening.
+  }
+}
+
+function persist(): void {
+  const storage = browserStorage();
+  if (!storage) return;
+  try {
+    const serialized: Record<string, Record<string, boolean>> = {};
+    for (const [projectId, nodes] of preferences) {
+      serialized[projectId] = Object.fromEntries(nodes);
+    }
+    storage.setItem(STORAGE_KEY, JSON.stringify(serialized));
+  } catch {
+    // Expansion is convenience state; storage denial/quota is non-fatal.
+  }
+}
+
+export function hierarchyExpansionPreference(
+  projectId: string,
+  nodeId: string,
+): boolean | undefined {
+  hydrate();
+  return preferences.get(projectId)?.get(nodeId);
+}
+
+/** Apply a whole branch/view operation with one storage write. */
+export function setHierarchyExpansionPreferences(
+  projectId: string,
+  entries: Iterable<readonly [nodeId: string, expanded: boolean]>,
+): void {
+  hydrate();
+  let project = preferences.get(projectId);
+  if (!project) {
+    project = new Map();
+    preferences.set(projectId, project);
+  }
+  for (const [nodeId, expanded] of entries) project.set(nodeId, expanded);
+  persist();
+}
+
+/** Return every node in one project to the shallow first-open policy. */
+export function clearHierarchyExpansionPreferences(projectId: string): void {
+  hydrate();
+  preferences.delete(projectId);
+  persist();
+}
+
+/** Test-only reset for this process and its jsdom localStorage. */
+export function _resetHierarchyExpansionPreferencesForTest(): void {
+  preferences.clear();
+  hydrated = true;
+  try {
+    browserStorage()?.removeItem(STORAGE_KEY);
+  } catch {
+    // no-op
+  }
+}

package/src/hierarchy-menu-registry.ts

@@ -64,7 +64,7 @@ export function getHierarchyMenuItems(ctx: HierarchyMenuContext): HierarchyMenuI
   return registrations.filter((r) => r.match(ctx)).flatMap((r) => r.items(ctx));
 }
 
-/** Test-only reset (mirrors `undo-timeline.ts`'s `__resetUndoTimelineForTest`). */
+/** Test-only reset for module-level menu registrations. */
 export function __resetHierarchyMenuRegistryForTest(): void {
   registrations.length = 0;
 }

package/src/hierarchy-projection.ts

@@ -0,0 +1,76 @@
+/**
+ * Project-authored hierarchy projection (D20).
+ *
+ * This is editor metadata, not runtime composition. `vgai.game.json.roots`
+ * declares adapter mounts; `vgai.game.json.authoring.hierarchy` only
+ * chooses how those roots are labelled and grouped in the authoring tree.
+ */
+
+export interface HierarchyProjectionGroup {
+  readonly id: string;
+  readonly label: string;
+  readonly roots: readonly string[];
+}
+
+export interface HierarchyProjection {
+  readonly rootLabels?: Readonly<Record<string, string>>;
+  readonly groups?: readonly HierarchyProjectionGroup[];
+}
+
+function record(value: unknown): Record<string, unknown> | null {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+/**
+ * Leniently read authoring metadata. Invalid entries are omitted so a typo in
+ * an optional projection can never make the game itself unopenable.
+ */
+export function parseHierarchyProjection(value: unknown): HierarchyProjection | undefined {
+  const source = record(value);
+  if (!source) return undefined;
+
+  const labelsSource = record(source['rootLabels']);
+  const labelEntries = labelsSource
+    ? Object.entries(labelsSource).flatMap(([id, label]): Array<[string, string]> => {
+        const normalizedId = id.trim();
+        const normalizedLabel = typeof label === 'string' ? label.trim() : '';
+        return normalizedId && normalizedLabel ? [[normalizedId, normalizedLabel]] : [];
+      })
+    : [];
+  const rootLabels = labelEntries.length > 0 ? Object.fromEntries(labelEntries) : undefined;
+
+  const groupIds = new Set<string>();
+  const groupEntries = Array.isArray(source['groups'])
+    ? source['groups'].flatMap((candidate): HierarchyProjectionGroup[] => {
+        const group = record(candidate);
+        const id = typeof group?.['id'] === 'string' ? group['id'].trim() : '';
+        const label = typeof group?.['label'] === 'string' ? group['label'].trim() : '';
+        const roots = Array.isArray(group?.['roots'])
+          ? group['roots'].flatMap((root): string[] => {
+              const normalized = typeof root === 'string' ? root.trim() : '';
+              return normalized ? [normalized] : [];
+            })
+          : [];
+        if (!id || !label || roots.length === 0 || groupIds.has(id)) return [];
+        groupIds.add(id);
+        return [{ id, label, roots: [...new Set(roots)] }];
+      })
+    : [];
+  const groups = groupEntries.length > 0 ? groupEntries : undefined;
+
+  if (!rootLabels && !groups) return undefined;
+  return {
+    ...(rootLabels ? { rootLabels } : {}),
+    ...(groups ? { groups } : {}),
+  };
+}
+
+/** Read the projection from a raw `vgai.game.json` config object. */
+export function hierarchyProjectionFromProjectConfig(
+  config: unknown,
+): HierarchyProjection | undefined {
+  const authoring = record(record(config)?.['authoring']);
+  return parseHierarchyProjection(authoring?.['hierarchy']);
+}

package/src/history/editor-session.ts

@@ -0,0 +1,21 @@
+import { HistoryCommands } from './history-commands';
+import { HistoryService, type HistoryServiceOptions } from './history-service';
+
+/** Owns project-lifetime editor services; disposed when EditorProvider unmounts. */
+export class EditorSession {
+  readonly history: HistoryService;
+  readonly historyCommands: HistoryCommands;
+
+  constructor(
+    readonly projectIdentity: string,
+    historyOptions: HistoryServiceOptions = {},
+  ) {
+    this.history = new HistoryService(historyOptions);
+    this.historyCommands = new HistoryCommands(this.history);
+  }
+
+  dispose(): void {
+    this.historyCommands.dispose();
+    this.history.dispose();
+  }
+}

package/src/history/history-commands.ts

@@ -0,0 +1,147 @@
+import type { HistoryService } from './history-service';
+
+export interface HistoryCommandSnapshot {
+  readonly version: number;
+  readonly busy: boolean;
+  readonly canUndo: boolean;
+  readonly canRedo: boolean;
+  readonly undoLabel: string | null;
+  readonly redoLabel: string | null;
+}
+
+/** Shell command surface for the one project HistoryService timeline. */
+export class HistoryCommands {
+  private tail: Promise<void> = Promise.resolve();
+  private readonly listeners = new Set<() => void>();
+  private pending = 0;
+  private version = 0;
+  private disposed = false;
+  private readonly idleWaiters = new Set<{
+    unsubscribe: () => void;
+    reject: (error: Error) => void;
+  }>();
+  private readonly unsubscribeHistory: () => void;
+  private snapshot: HistoryCommandSnapshot;
+
+  constructor(private readonly history: HistoryService) {
+    this.snapshot = this.buildSnapshot();
+    this.unsubscribeHistory = history.subscribe(this.notify);
+  }
+
+  subscribe = (listener: () => void): (() => void) => {
+    if (this.disposed) return () => undefined;
+    this.listeners.add(listener);
+    return () => this.listeners.delete(listener);
+  };
+
+  getSnapshot = (): HistoryCommandSnapshot => this.snapshot;
+
+  undo(): Promise<boolean> {
+    return this.enqueue(async () => {
+      await this.waitForServiceIdle();
+      this.assertNotDisposed();
+      return this.history.undo();
+    });
+  }
+
+  redo(): Promise<boolean> {
+    return this.enqueue(async () => {
+      await this.waitForServiceIdle();
+      this.assertNotDisposed();
+      return this.history.redo();
+    });
+  }
+
+  jumpTo(cursor: number): Promise<boolean> {
+    return this.enqueue(async () => {
+      await this.waitForServiceIdle();
+      this.assertNotDisposed();
+      return this.history.jumpTo(cursor);
+    });
+  }
+
+  get canUndo(): boolean {
+    return this.snapshot.canUndo;
+  }
+
+  get canRedo(): boolean {
+    return this.snapshot.canRedo;
+  }
+
+  dispose(): void {
+    if (this.disposed) return;
+    this.disposed = true;
+    this.unsubscribeHistory();
+    const error = new Error('History commands are disposed.');
+    for (const waiter of this.idleWaiters) {
+      waiter.unsubscribe();
+      waiter.reject(error);
+    }
+    this.idleWaiters.clear();
+    this.listeners.clear();
+    this.notify();
+  }
+
+  private enqueue(operation: () => Promise<boolean>): Promise<boolean> {
+    if (this.disposed) return Promise.reject(new Error('History commands are disposed.'));
+    this.pending++;
+    this.notify();
+    const run = () => {
+      if (this.disposed) throw new Error('History commands are disposed.');
+      return operation();
+    };
+    const result = this.tail.then(run, run);
+    this.tail = result.then(
+      () => undefined,
+      () => undefined,
+    );
+    return result.finally(() => {
+      this.pending--;
+      this.notify();
+    });
+  }
+
+  private assertNotDisposed(): void {
+    if (this.disposed) throw new Error('History commands are disposed.');
+  }
+
+  private waitForServiceIdle(): Promise<void> {
+    if (this.disposed) return Promise.reject(new Error('History commands are disposed.'));
+    if (!this.history.getSnapshot().busy) return Promise.resolve();
+    return new Promise((resolve, reject) => {
+      const waiter: {
+        unsubscribe: () => void;
+        reject: (error: Error) => void;
+      } = { unsubscribe: () => undefined, reject };
+      const finish = () => {
+        waiter.unsubscribe();
+        this.idleWaiters.delete(waiter);
+      };
+      waiter.unsubscribe = this.history.subscribe(() => {
+        if (this.history.getSnapshot().busy) return;
+        finish();
+        resolve();
+      });
+      this.idleWaiters.add(waiter);
+    });
+  }
+
+  private notify = (): void => {
+    this.version++;
+    this.snapshot = this.buildSnapshot();
+    for (const listener of this.listeners) listener();
+  };
+
+  private buildSnapshot(): HistoryCommandSnapshot {
+    const current = this.history.getSnapshot();
+    const busy = this.pending > 0 || current.busy;
+    return {
+      version: this.version,
+      busy,
+      canUndo: !this.disposed && !busy && current.canUndo,
+      canRedo: !this.disposed && !busy && current.canRedo,
+      undoLabel: current.undoLabel,
+      redoLabel: current.redoLabel,
+    };
+  }
+}