@vgai/editor 0.2.0 → 0.4.0-canary.20260715.0

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

@@ -1,552 +0,0 @@
-/**
- * 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

@@ -1,95 +0,0 @@
-/**
- * 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;
-}

package/template/project.json

@@ -1,9 +0,0 @@
-{
-  "name": "My Game",
-  "resolution": {
-    "width": 1280,
-    "height": 720
-  },
-  "defaultScene": "scenes/default.vscn.json",
-  "appId": "com.example.mygame"
-}