@vgai/editor 0.2.0

package/src/ui-editor/ui-edit-store.ts

@@ -0,0 +1,552 @@
+/**
+ * UIEditStore — the editing state + mutation ops for the UI authoring surface.
+ *
+ * Holds the UI roots (the .vscn `ui` tree, the source of truth — C9), the
+ * selection, a 50-deep undo stack, a clipboard, the live data source for bindings,
+ * and named board states/scenarios (C12). Plain observable store (subscribe/
+ * version) so React binds via useSyncExternalStore. Edits route through here;
+ * each user gesture pushes exactly one undo entry (preview-vs-commit, C6/K4).
+ */
+import type { UIAnimation, UINode, UIRoot } from '@engine/scene/schema';
+import { createDataSource, type UIDataSource } from '@vgai/scene-ui/data-source';
+import { notifyUndoableOp, registerUndoAdapter } from '../authoring/undo-timeline';
+import {
+  cloneWithNewIds,
+  countNodes,
+  deleteNodePath,
+  duplicateNode,
+  ensureIds,
+  findNode,
+  insertNode,
+  moveNode,
+  newId,
+  removeNode,
+  reorderNode,
+  setNodePath,
+  unwrapNode,
+  updateNode,
+  wrapNode,
+} from './node-ops';
+
+const MAX_UNDO = 50;
+
+/** A default node skeleton for a newly-created node of a given kind (palette). */
+export function defaultNodeForKind(kind: UINode['kind']): UINode {
+  const id = newId(kind);
+  const base: UINode = { id, name: capitalize(kind), kind };
+  switch (kind) {
+    case 'text':
+      return { ...base, props: { text: 'Text' } };
+    case 'button':
+      return {
+        ...base,
+        props: { text: 'Button' },
+        style: { backgroundColor: '#4af', color: '#000', borderRadius: 6 },
+      };
+    case 'box':
+      return { ...base, layout: { direction: 'row', gap: 8 }, style: {} };
+    case 'panel':
+      return {
+        ...base,
+        layout: { padding: [8, 8, 8, 8] },
+        style: { backgroundColor: 'rgba(0,0,0,0.5)', borderRadius: 6 },
+      };
+    case 'grid':
+      return { ...base, layout: { columns: 3, gap: 8 } };
+    case 'image':
+      return { ...base, layout: { width: 48, height: 48 }, props: {} };
+    case 'progress':
+      return {
+        ...base,
+        layout: { width: 120, height: 10 },
+        props: { value: 50, max: 100 },
+        style: { backgroundColor: '#4af' },
+      };
+    case 'input':
+      return { ...base, props: { placeholder: 'Input' } };
+    case 'toggle':
+      return { ...base, props: { text: 'Toggle', checked: false } };
+    case 'slider':
+      return { ...base, props: { value: 50, min: 0, max: 100 } };
+    default:
+      return base;
+  }
+}
+
+function capitalize(s: string): string {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+/**
+ * The minimal schema-valid empty canvas root (design/24-scene-ui.md D10):
+ * `UIRootSchema` requires only `kind:'canvas'` plus the shared node fields
+ * (schema/ui.ts) — `space`/`scaling`/`theme` are all optional. Seeds a
+ * ui-less scene in PROJECT mode (a registry is present) instead of the demo
+ * fixture `COMPLEX_UI_ROOTS` — an author's own project should never land the
+ * demo tree, only an empty stage to build on.
+ */
+export function defaultCanvasRoot(): UIRoot {
+  return { id: newId('canvas'), kind: 'canvas', name: 'Canvas', space: 'screen', children: [] };
+}
+
+export interface UIEditStoreOptions {
+  /** Initial live data source state for bindings (game state). */
+  data?: Record<string, unknown>;
+  /** Called after a committed edit so the host can persist to .vscn (C9). */
+  onCommit?: (roots: UIRoot[]) => void;
+}
+
+export class UIEditStore {
+  private _roots: UIRoot[];
+  private _selection: string[] = [];
+  private _undo: string[] = [];
+  private _redo: string[] = [];
+  private _clipboard: UINode | null = null;
+  private _version = 0;
+  private _listeners = new Set<() => void>();
+  private _interactive: string | null = null; // snapshot taken at gesture start
+  private _states = new Map<string, Record<string, unknown>>();
+  private _sourceOid: string | null = null;
+  private _locale = 'en';
+  private _previewResolution: { width: number; height: number } | null = null;
+  private _onCommit: ((roots: UIRoot[]) => void) | undefined;
+
+  readonly data: UIDataSource;
+
+  constructor(roots: UIRoot[], opts: UIEditStoreOptions = {}) {
+    this._roots = ensureIds(roots);
+    this.data = createDataSource(opts.data ?? {});
+    this._onCommit = opts.onCommit;
+    // T3.2 slice 2: this store IS the undo/redo target the editor-global timeline
+    // dispatches to for entries it records below (`pushUndo`/`endEdit`). C3's
+    // `edit-mode-authoring.ts` (`exitEditModeAuthoring`) unregisters it on
+    // teardown for the unified editor's scene-UI child; the standalone
+    // harness (harness.tsx) never tears down, so it stays registered for the
+    // page's lifetime — harmless, mirrors `EditorStore`.
+    registerUndoAdapter(this);
+  }
+
+  // --- subscription ---
+  subscribe = (l: () => void): (() => void) => {
+    this._listeners.add(l);
+    return () => this._listeners.delete(l);
+  };
+  getVersion = (): number => this._version;
+  private notify(): void {
+    this._version += 1;
+    for (const l of this._listeners) l();
+  }
+
+  // --- reads ---
+  get roots(): UIRoot[] {
+    return this._roots;
+  }
+  get selection(): string[] {
+    return this._selection;
+  }
+  get primary(): string | null {
+    return this._selection[this._selection.length - 1] ?? null;
+  }
+  get locale(): string {
+    return this._locale;
+  }
+  get previewResolution(): { width: number; height: number } | null {
+    return this._previewResolution;
+  }
+  get clipboardHasContent(): boolean {
+    return this._clipboard !== null;
+  }
+  get canUndo(): boolean {
+    return this._undo.length > 0;
+  }
+  get canRedo(): boolean {
+    return this._redo.length > 0;
+  }
+  /**
+   * True while an interactive gesture (drag/resize) is live — between
+   * `beginEdit()` and `endEdit()`, `_roots` holds uncommitted preview state.
+   * The viewport layer's content-sync (`scene-ui-layer.ts`) reads this to
+   * avoid reloading the committed document over an in-flight gesture, which
+   * would revert the drag and wipe selection/local-undo mid-motion.
+   */
+  get inGesture(): boolean {
+    return this._interactive != null;
+  }
+  stateNames(): string[] {
+    return [...this._states.keys()];
+  }
+  nodeCount(): number {
+    return countNodes(this._roots);
+  }
+  find(id: string) {
+    return findNode(this._roots, id);
+  }
+
+  // --- selection ---
+  select(ids: string[]): void {
+    this._selection = ids;
+    this.notify();
+  }
+  selectOne(id: string | null, additive = false): void {
+    if (id == null) this._selection = [];
+    else if (additive)
+      this._selection = this._selection.includes(id)
+        ? this._selection.filter((s) => s !== id)
+        : [...this._selection, id];
+    else this._selection = [id];
+    if (!additive) this._sourceOid = null; // a node selection clears any source selection
+    this.notify();
+  }
+
+  /** The selected component-internal source element (an OID), for live source edits (C7). */
+  get sourceOid(): string | null {
+    return this._sourceOid;
+  }
+  setSourceSelection(oid: string | null): void {
+    this._sourceOid = oid;
+    this.notify();
+  }
+
+  // --- undo plumbing ---
+  private snapshot(): string {
+    return JSON.stringify(this._roots);
+  }
+  private pushUndo(): void {
+    this._undo.push(this.snapshot());
+    if (this._undo.length > MAX_UNDO) this._undo.shift();
+    this._redo = [];
+    notifyUndoableOp(this); // T3.2 slice 2 — tag this op on the global timeline
+  }
+  private commit(next: UIRoot[]): void {
+    this.pushUndo();
+    this._roots = next;
+    this._onCommit?.(this._roots);
+    this.notify();
+  }
+
+  undo(): boolean {
+    // `false` tells the undo timeline "couldn't act — put the entry back"
+    // (see UndoAdapter in ../authoring/undo-timeline.ts).
+    const prev = this._undo.pop();
+    if (prev == null) return false;
+    this._redo.push(this.snapshot());
+    this._roots = JSON.parse(prev);
+    this._onCommit?.(this._roots);
+    this.notify();
+    return true;
+  }
+  redo(): boolean {
+    const next = this._redo.pop();
+    if (next == null) return false;
+    this._undo.push(this.snapshot());
+    this._roots = JSON.parse(next);
+    this._onCommit?.(this._roots);
+    this.notify();
+    return true;
+  }
+
+  // --- editing (each is one undo step) ---
+  setProp(id: string, path: string, value: unknown): void {
+    this.commit(setNodePath(this._roots, id, path, value));
+  }
+  /** Multi-select shared-property edit (K9). One undo step for all targets. */
+  setPropMulti(ids: string[], path: string, value: unknown): void {
+    let next = this._roots;
+    for (const id of ids) next = setNodePath(next, id, path, value);
+    this.commit(next);
+  }
+  deleteProp(id: string, path: string): void {
+    this.commit(deleteNodePath(this._roots, id, path));
+  }
+
+  /** Apply multiple path->value patches to each id in ONE undo step (e.g. anchor presets). */
+  setMany(ids: string[], patches: Record<string, unknown>): void {
+    let next = this._roots;
+    for (const id of ids) {
+      for (const [path, value] of Object.entries(patches))
+        next = setNodePath(next, id, path, value);
+    }
+    this.commit(next);
+  }
+
+  addNode(parentId: string, kind: UINode['kind'], index?: number): string {
+    const node = defaultNodeForKind(kind);
+    this.commit(insertNode(this._roots, parentId, node, index));
+    const id = node.id as string;
+    this.selectOne(id);
+    return id;
+  }
+  addNodeValue(parentId: string, node: UINode, index?: number): string {
+    const withIds = cloneWithNewIds(node);
+    this.commit(insertNode(this._roots, parentId, withIds, index));
+    return withIds.id as string;
+  }
+  remove(id: string): void {
+    this.commit(removeNode(this._roots, id));
+    this._selection = this._selection.filter((s) => s !== id);
+  }
+  /** D4.R2 (spec27 §6 D4 reopen) — remove every id in ONE undo step (one
+   *  `commit`), the `StructureProvider.removeMany` backing for
+   *  `UIAuthoringAdapter`. `removeSelected` (below) is now just this called
+   *  with the current selection. */
+  removeMany(ids: readonly string[]): void {
+    if (ids.length === 0) return;
+    let next = this._roots;
+    for (const id of ids) next = removeNode(next, id);
+    this.commit(next);
+    const removed = new Set(ids);
+    this._selection = this._selection.filter((s) => !removed.has(s));
+  }
+  removeSelected(): void {
+    this.removeMany(this._selection);
+  }
+  duplicate(id: string): string | null {
+    const res = duplicateNode(this._roots, id);
+    if (res.newId) {
+      this.commit(res.roots);
+      this.selectOne(res.newId);
+    }
+    return res.newId;
+  }
+  reparent(id: string, newParentId: string, index?: number): void {
+    this.commit(moveNode(this._roots, id, newParentId, index));
+  }
+  reorder(id: string, newIndex: number): void {
+    this.commit(reorderNode(this._roots, id, newIndex));
+  }
+  /** Wrap a node in a new container (C8). Returns the wrapper id. */
+  wrap(id: string, kind: UINode['kind'] = 'box'): string | null {
+    const res = wrapNode(this._roots, id, kind);
+    if (res.wrapperId) {
+      this.commit(res.roots);
+      this.selectOne(res.wrapperId);
+    }
+    return res.wrapperId;
+  }
+  /** Unwrap a container, splicing its children into the parent (C8). */
+  unwrap(id: string): void {
+    this.commit(unwrapNode(this._roots, id));
+  }
+  /** Inline text edit (C8) — set a node's text prop. */
+  editText(id: string, text: string): void {
+    this.commit(setNodePath(this._roots, id, 'props.text', text));
+  }
+
+  // --- keyframe / timeline animation (S1) ---
+
+  /** Map a node's animation clip immutably and commit (one undo step). */
+  private updateClip(id: string, animIndex: number, fn: (clip: UIAnimation) => UIAnimation): void {
+    this.commit(
+      updateNode(this._roots, id, (node) => {
+        const anims = [...(node.animations ?? [])];
+        const clip = anims[animIndex];
+        if (!clip) return node;
+        anims[animIndex] = fn(clip);
+        return { ...node, animations: anims };
+      }),
+    );
+  }
+
+  /** Add a (default) animation clip to a node. Returns its index. */
+  addAnimation(id: string, clip?: UIAnimation): number {
+    const loc = findNode(this._roots, id);
+    if (!loc) return -1;
+    const count = loc.node.animations?.length ?? 0;
+    const next: UIAnimation = clip ?? {
+      name: `clip${count + 1}`,
+      duration: 1,
+      loop: false,
+      tracks: [],
+    };
+    this.commit(
+      updateNode(this._roots, id, (node) => ({
+        ...node,
+        animations: [...(node.animations ?? []), next],
+      })),
+    );
+    return count;
+  }
+  removeAnimation(id: string, animIndex: number): void {
+    this.commit(
+      updateNode(this._roots, id, (node) => {
+        const anims = (node.animations ?? []).filter((_, i) => i !== animIndex);
+        return { ...node, animations: anims };
+      }),
+    );
+  }
+  setAnimationField(
+    id: string,
+    animIndex: number,
+    field: 'name' | 'duration' | 'loop' | 'autoplay',
+    value: unknown,
+  ): void {
+    this.updateClip(id, animIndex, (c) => ({ ...c, [field]: value }));
+  }
+  addTrack(
+    id: string,
+    animIndex: number,
+    property: UIAnimation['tracks'][number]['property'],
+  ): void {
+    this.updateClip(id, animIndex, (c) =>
+      c.tracks.some((t) => t.property === property)
+        ? c
+        : { ...c, tracks: [...c.tracks, { property, keyframes: [] }] },
+    );
+  }
+  removeTrack(id: string, animIndex: number, trackIndex: number): void {
+    this.updateClip(id, animIndex, (c) => ({
+      ...c,
+      tracks: c.tracks.filter((_, i) => i !== trackIndex),
+    }));
+  }
+  /** Upsert a keyframe on a track at `time` (record mode + manual add), keeping order. */
+  setKeyframe(
+    id: string,
+    animIndex: number,
+    trackIndex: number,
+    time: number,
+    value: number | string,
+    easing?: UIAnimation['tracks'][number]['keyframes'][number]['easing'],
+  ): void {
+    this.updateClip(id, animIndex, (c) => {
+      const tracks = [...c.tracks];
+      const track = tracks[trackIndex];
+      if (!track) return c;
+      const kfs = track.keyframes.filter((k) => Math.abs(k.time - time) > 1e-4);
+      kfs.push({ time, value, ...(easing ? { easing } : {}) });
+      kfs.sort((a, b) => a.time - b.time);
+      tracks[trackIndex] = { ...track, keyframes: kfs };
+      return { ...c, tracks };
+    });
+  }
+  removeKeyframe(id: string, animIndex: number, trackIndex: number, kfIndex: number): void {
+    this.updateClip(id, animIndex, (c) => {
+      const tracks = [...c.tracks];
+      const track = tracks[trackIndex];
+      if (!track) return c;
+      tracks[trackIndex] = { ...track, keyframes: track.keyframes.filter((_, i) => i !== kfIndex) };
+      return { ...c, tracks };
+    });
+  }
+  setKeyframeEasing(
+    id: string,
+    animIndex: number,
+    trackIndex: number,
+    kfIndex: number,
+    easing: UIAnimation['tracks'][number]['keyframes'][number]['easing'],
+  ): void {
+    this.updateClip(id, animIndex, (c) => {
+      const tracks = [...c.tracks];
+      const track = tracks[trackIndex];
+      if (!track) return c;
+      const kfs = track.keyframes.map((k, i) => (i === kfIndex ? { ...k, easing } : k));
+      tracks[trackIndex] = { ...track, keyframes: kfs };
+      return { ...c, tracks };
+    });
+  }
+
+  // --- clipboard (K8) ---
+  copy(id?: string): void {
+    const target = id ?? this.primary;
+    if (!target) return;
+    const loc = findNode(this._roots, target);
+    if (loc) this._clipboard = JSON.parse(JSON.stringify(loc.node));
+  }
+  cut(id?: string): void {
+    const target = id ?? this.primary;
+    if (!target) return;
+    this.copy(target);
+    this.remove(target);
+  }
+  paste(targetParentId?: string): string | null {
+    if (!this._clipboard) return null;
+    const parentId = targetParentId ?? this.primary ?? this._roots[0]?.id;
+    if (!parentId) return null;
+    // paste INTO the selected container, or as sibling if selection is a leaf
+    const loc = findNode(this._roots, parentId);
+    const intoId =
+      loc && (loc.node.children || isContainer(loc.node))
+        ? parentId
+        : (loc?.parent?.id ?? this._roots[0]?.id);
+    if (!intoId) return null;
+    return this.addNodeValue(intoId, this._clipboard);
+  }
+
+  // --- live preview vs commit (C6/K4) ---
+  /** Begin an interactive gesture (drag): snapshot once for a single undo step. */
+  beginEdit(): void {
+    this._interactive = this.snapshot();
+  }
+  /** Live property set during a gesture — NO undo push, NO persist callback. */
+  previewSetProp(id: string, path: string, value: unknown): void {
+    this._roots = setNodePath(this._roots, id, path, value);
+    this.notify();
+  }
+  previewSetPropMulti(ids: string[], path: string, value: unknown): void {
+    let next = this._roots;
+    for (const id of ids) next = setNodePath(next, id, path, value);
+    this._roots = next;
+    this.notify();
+  }
+  /** End the gesture: push the pre-gesture snapshot as the single undo step. */
+  endEdit(): void {
+    if (this._interactive == null) return;
+    this._undo.push(this._interactive);
+    if (this._undo.length > MAX_UNDO) this._undo.shift();
+    this._redo = [];
+    notifyUndoableOp(this); // T3.2 slice 2 — tag this op on the global timeline
+    this._interactive = null;
+    this._onCommit?.(this._roots);
+    this.notify();
+  }
+
+  // --- board states / in-realm scenarios (C12) ---
+  defineState(name: string, data: Record<string, unknown>): void {
+    this._states.set(name, data);
+  }
+  loadState(name: string): void {
+    const s = this._states.get(name);
+    if (!s) return;
+    for (const k of Object.keys(s)) this.data.set(k, s[k]);
+    this.notify();
+  }
+
+  // --- responsive preview (I3) + locale (G5) ---
+  setPreviewResolution(res: { width: number; height: number } | null): void {
+    this._previewResolution = res;
+    this.notify();
+  }
+  setLocale(locale: string): void {
+    this._locale = locale;
+    this.notify();
+  }
+
+  /** Serialize the UI tree for persistence into a SceneFile.ui (C9). */
+  serialize(): UIRoot[] {
+    return JSON.parse(JSON.stringify(this._roots));
+  }
+  /** Replace the whole tree (e.g. external load). Clears undo. */
+  load(roots: UIRoot[]): void {
+    this._roots = ensureIds(roots);
+    this._undo = [];
+    this._redo = [];
+    this._selection = [];
+    this.notify();
+  }
+}
+
+function isContainer(node: UINode): boolean {
+  return [
+    'canvas',
+    'box',
+    'grid',
+    'stack',
+    'scroll',
+    'panel',
+    'center',
+    'wrap',
+    'aspect',
+    'sizebox',
+    'tab',
+  ].includes(node.kind);
+}

package/src/ui-editor/ui-prefab.ts

@@ -0,0 +1,95 @@
+/**
+ * UI prefab reuse (H1-H4): instantiate a saved UI subtree with fresh ids, apply
+ * per-instance overrides (H2), expose named props/slots (H3), and resolve NESTED
+ * prefab references with cycle protection (H4). Pure functions — unit tested.
+ */
+import type { UINode, UIPrefabFile } from '@engine/scene/schema';
+import { cloneWithNewIds } from './node-ops';
+
+/** Per-instance overrides for a prefab instance (H2). */
+export interface UIPrefabOverrides {
+  props?: Record<string, unknown>;
+  style?: Record<string, unknown>;
+  /** Content injected into named slots (H3): slotName → nodes. */
+  slots?: Record<string, UINode[]>;
+}
+
+/** A registry resolving a prefab name/path → its file (for nested reuse, H4). */
+export type UIPrefabRegistry = Record<string, UIPrefabFile>;
+
+const MAX_DEPTH = 32;
+
+/**
+ * Instantiate a prefab into a UINode tree: fresh ids, overrides merged onto the
+ * root (H2), nested `component` references to other prefabs resolved recursively
+ * (H4), and slot content injected (H3). Throws on a cyclic prefab reference.
+ */
+export function instantiateUIPrefab(
+  prefab: UIPrefabFile,
+  overrides: UIPrefabOverrides = {},
+  registry: UIPrefabRegistry = {},
+  _stack: string[] = [],
+): UINode {
+  if (_stack.includes(prefab.name)) {
+    throw new Error(`cyclic UI prefab reference: ${[..._stack, prefab.name].join(' -> ')}`);
+  }
+  if (_stack.length > MAX_DEPTH) throw new Error('UI prefab nesting too deep');
+
+  const root = cloneWithNewIds(prefab.root);
+  const resolved = resolveNested(root, registry, [..._stack, prefab.name]);
+  return mergeUIPrefabInstance(resolved, overrides, prefab);
+}
+
+/** Apply per-instance overrides to a prefab root, gated by exposedProps/slots (H2/H3). */
+export function mergeUIPrefabInstance(
+  node: UINode,
+  overrides: UIPrefabOverrides,
+  prefab?: UIPrefabFile,
+): UINode {
+  const next: UINode = { ...node };
+  if (overrides.props) {
+    const allowed = prefab?.exposedProps;
+    const incoming = allowed ? pick(overrides.props, allowed) : overrides.props;
+    next.props = { ...next.props, ...incoming } as UINode['props'];
+  }
+  if (overrides.style) {
+    next.style = { ...next.style, ...overrides.style } as UINode['style'];
+  }
+  if (overrides.slots) {
+    next.children = injectSlots(next.children ?? [], overrides.slots);
+  }
+  return next;
+}
+
+/** Replace `component` nodes that reference a prefab in the registry with its instance (H4). */
+function resolveNested(node: UINode, registry: UIPrefabRegistry, stack: string[]): UINode {
+  if (node.kind === 'component' && node.component && registry[node.component]) {
+    const ov: UIPrefabOverrides = node.props
+      ? { props: node.props as Record<string, unknown> }
+      : {};
+    return instantiateUIPrefab(registry[node.component] as UIPrefabFile, ov, registry, stack);
+  }
+  if (!node.children) return node;
+  return { ...node, children: node.children.map((c) => resolveNested(c, registry, stack)) };
+}
+
+/** Inject slot content where a child is a slot marker (kind 'component' named '$slot:name'). */
+function injectSlots(children: UINode[], slots: Record<string, UINode[]>): UINode[] {
+  const out: UINode[] = [];
+  for (const c of children) {
+    const slotName =
+      c.kind === 'component' && c.component?.startsWith('$slot:') ? c.component.slice(6) : null;
+    if (slotName && slots[slotName]) {
+      out.push(...slots[slotName].map(cloneWithNewIds));
+    } else {
+      out.push(c.children ? { ...c, children: injectSlots(c.children, slots) } : c);
+    }
+  }
+  return out;
+}
+
+function pick(obj: Record<string, unknown>, keys: string[]): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const k of keys) if (k in obj) out[k] = obj[k];
+  return out;
+}