@vgai/editor 0.2.0

package/src/ui-editor/node-ops.ts

@@ -0,0 +1,266 @@
+/**
+ * Pure, immutable tree operations on the UI scene-graph (M3/M4 backbone).
+ *
+ * All ops return NEW trees (structural sharing where cheap) so the editing store
+ * can snapshot for undo and React can diff. Nodes are addressed by stable id;
+ * `ensureIds` guarantees every node has one on load. These functions are pure and
+ * unit-tested in isolation (no React, no DOM).
+ */
+import type { UINode, UIRoot } from '@engine/scene/schema';
+
+let _idCounter = 0;
+/** Deterministic-ish unique id for a new/unidentified node. */
+export function newId(prefix = 'ui'): string {
+  _idCounter += 1;
+  return `${prefix}_${_idCounter.toString(36)}_${(globalThis.performance?.now?.() ?? 0).toString(36).replace('.', '')}`;
+}
+
+/** Assign ids to every node missing one (immutably). Run on load. */
+export function ensureIds(roots: UIRoot[]): UIRoot[] {
+  const visit = <T extends UINode>(node: T): T => {
+    const id = node.id ?? newId(node.kind);
+    const children = node.children?.map(visit);
+    return { ...node, id, ...(children ? { children } : {}) } as T;
+  };
+  return roots.map(visit);
+}
+
+export interface NodeLocation {
+  node: UINode;
+  /** Parent node, or null if `node` is a root. */
+  parent: UINode | null;
+  /** Index within the parent's children (or within roots if a root). */
+  index: number;
+  /** True if `node` is a top-level UI root. */
+  isRoot: boolean;
+}
+
+/** Find a node and its location by id. */
+export function findNode(roots: UIRoot[], id: string): NodeLocation | null {
+  for (let i = 0; i < roots.length; i++) {
+    const r = roots[i] as UIRoot;
+    if (r.id === id) return { node: r, parent: null, index: i, isRoot: true };
+    const found = findInChildren(r, id);
+    if (found) return found;
+  }
+  return null;
+}
+
+function findInChildren(parent: UINode, id: string): NodeLocation | null {
+  const kids = parent.children ?? [];
+  for (let i = 0; i < kids.length; i++) {
+    const c = kids[i] as UINode;
+    if (c.id === id) return { node: c, parent, index: i, isRoot: false };
+    const deeper = findInChildren(c, id);
+    if (deeper) return deeper;
+  }
+  return null;
+}
+
+/** Map a single node (by id) through `updater`, returning a new tree. */
+export function updateNode(
+  roots: UIRoot[],
+  id: string,
+  updater: (node: UINode) => UINode,
+): UIRoot[] {
+  const visit = (node: UINode): UINode => {
+    if (node.id === id) return updater(node);
+    if (!node.children) return node;
+    let changed = false;
+    const children = node.children.map((c) => {
+      const n = visit(c);
+      if (n !== c) changed = true;
+      return n;
+    });
+    return changed ? { ...node, children } : node;
+  };
+  return roots.map((r) => visit(r) as UIRoot);
+}
+
+/** Immutably set a dotted path (e.g. "layout.gap", "props.text", "style.color") on a node. */
+export function setNodePath(roots: UIRoot[], id: string, path: string, value: unknown): UIRoot[] {
+  return updateNode(roots, id, (node) => deepSet(node, path.split('.'), value) as UINode);
+}
+
+/** Immutably delete a dotted path on a node (used to clear overrides / unbind). */
+export function deleteNodePath(roots: UIRoot[], id: string, path: string): UIRoot[] {
+  return updateNode(roots, id, (node) => deepDelete(node, path.split('.')) as UINode);
+}
+
+function deepSet(obj: unknown, keys: string[], value: unknown): unknown {
+  const [head, ...rest] = keys;
+  const base: Record<string, unknown> =
+    obj && typeof obj === 'object' ? { ...(obj as Record<string, unknown>) } : {};
+  if (rest.length === 0) {
+    base[head as string] = value;
+  } else {
+    base[head as string] = deepSet(base[head as string], rest, value);
+  }
+  return base;
+}
+
+function deepDelete(obj: unknown, keys: string[]): unknown {
+  if (!obj || typeof obj !== 'object') return obj;
+  const [head, ...rest] = keys;
+  const base = { ...(obj as Record<string, unknown>) };
+  if (rest.length === 0) {
+    delete base[head as string];
+  } else {
+    base[head as string] = deepDelete(base[head as string], rest);
+  }
+  return base;
+}
+
+/** Read a dotted path from a node. */
+export function getNodePath(node: UINode, path: string): unknown {
+  let cur: unknown = node;
+  for (const k of path.split('.')) {
+    if (cur == null || typeof cur !== 'object') return undefined;
+    cur = (cur as Record<string, unknown>)[k];
+  }
+  return cur;
+}
+
+/** Insert `child` under `parentId` at `index` (default: append). */
+export function insertNode(
+  roots: UIRoot[],
+  parentId: string,
+  child: UINode,
+  index?: number,
+): UIRoot[] {
+  return updateNode(roots, parentId, (parent) => {
+    const kids = [...(parent.children ?? [])];
+    const at = index == null ? kids.length : Math.max(0, Math.min(index, kids.length));
+    kids.splice(at, 0, child);
+    return { ...parent, children: kids };
+  });
+}
+
+/** Remove a node (and its subtree) by id. Roots can be removed too. */
+export function removeNode(roots: UIRoot[], id: string): UIRoot[] {
+  const next = roots.filter((r) => r.id !== id);
+  if (next.length !== roots.length) return next;
+  const strip = (node: UINode): UINode => {
+    if (!node.children) return node;
+    const children = node.children.filter((c) => c.id !== id).map(strip);
+    return { ...node, children };
+  };
+  return roots.map((r) => strip(r) as UIRoot);
+}
+
+/** Deep-clone a node, assigning fresh ids throughout (for duplicate/paste). */
+export function cloneWithNewIds(node: UINode): UINode {
+  const children = node.children?.map(cloneWithNewIds);
+  return { ...node, id: newId(node.kind), ...(children ? { children } : {}) };
+}
+
+/** Duplicate a node as a sibling immediately after itself. Returns [tree, newId]. */
+export function duplicateNode(
+  roots: UIRoot[],
+  id: string,
+): { roots: UIRoot[]; newId: string | null } {
+  const loc = findNode(roots, id);
+  if (!loc) return { roots, newId: null };
+  const copy = cloneWithNewIds(loc.node);
+  if (loc.isRoot) {
+    const next = [...roots];
+    next.splice(loc.index + 1, 0, copy as UIRoot);
+    return { roots: next, newId: copy.id ?? null };
+  }
+  if (!loc.parent?.id) return { roots, newId: null };
+  return { roots: insertNode(roots, loc.parent.id, copy, loc.index + 1), newId: copy.id ?? null };
+}
+
+/** Move a node under a new parent at an index (reparent). Guards against cycles. */
+export function moveNode(
+  roots: UIRoot[],
+  id: string,
+  newParentId: string,
+  index?: number,
+): UIRoot[] {
+  if (id === newParentId) return roots;
+  const loc = findNode(roots, id);
+  if (!loc || loc.isRoot) return roots; // roots aren't reparentable
+  // target parent must exist, else detach+insert would silently drop the node
+  if (!findNode(roots, newParentId)) return roots;
+  // cycle guard: can't move a node into its own descendant
+  if (isDescendant(loc.node, newParentId)) return roots;
+  const detached = removeNode(roots, id);
+  return insertNode(detached, newParentId, loc.node, index);
+}
+
+function isDescendant(node: UINode, id: string): boolean {
+  for (const c of node.children ?? []) {
+    if (c.id === id || isDescendant(c, id)) return true;
+  }
+  return false;
+}
+
+/** Reorder a node within its current parent to a new index. */
+export function reorderNode(roots: UIRoot[], id: string, newIndex: number): UIRoot[] {
+  const loc = findNode(roots, id);
+  if (!loc || loc.isRoot || !loc.parent?.id) return roots;
+  return updateNode(roots, loc.parent.id, (parent) => {
+    const kids = [...(parent.children ?? [])];
+    const from = kids.findIndex((c) => c.id === id);
+    if (from < 0) return parent;
+    const [moved] = kids.splice(from, 1);
+    kids.splice(Math.max(0, Math.min(newIndex, kids.length)), 0, moved as UINode);
+    return { ...parent, children: kids };
+  });
+}
+
+/** Wrap a node in a new container of `kind` (the node becomes the container's child). */
+export function wrapNode(
+  roots: UIRoot[],
+  id: string,
+  kind: UINode['kind'] = 'box',
+): { roots: UIRoot[]; wrapperId: string | null } {
+  const loc = findNode(roots, id);
+  if (!loc || loc.isRoot) return { roots, wrapperId: null };
+  const wrapper: UINode = {
+    id: newId(kind),
+    name: `${capitalize(kind)}Wrap`,
+    kind,
+    children: [loc.node],
+  };
+  // replace the node in place with the wrapper containing it
+  const next = updateNode(roots, id, () => wrapper);
+  return { roots: next, wrapperId: wrapper.id ?? null };
+}
+
+/** Unwrap a container: replace it with its children in its parent (inverse of wrap). */
+export function unwrapNode(roots: UIRoot[], id: string): UIRoot[] {
+  const loc = findNode(roots, id);
+  if (!loc || loc.isRoot || !loc.parent?.id) return roots;
+  const children = loc.node.children ?? [];
+  return updateNode(roots, loc.parent.id, (parent) => {
+    const kids = [...(parent.children ?? [])];
+    const at = kids.findIndex((c) => c.id === id);
+    if (at < 0) return parent;
+    kids.splice(at, 1, ...children);
+    return { ...parent, children: kids };
+  });
+}
+
+function capitalize(s: string): string {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+/** Walk every node depth-first (roots first), calling `fn(node, parent)`. */
+export function walk(roots: UIRoot[], fn: (node: UINode, parent: UINode | null) => void): void {
+  const visit = (node: UINode, parent: UINode | null): void => {
+    fn(node, parent);
+    for (const c of node.children ?? []) visit(c, node);
+  };
+  for (const r of roots) visit(r, null);
+}
+
+/** Total node count (for perf budget / stats). */
+export function countNodes(roots: UIRoot[]): number {
+  let n = 0;
+  walk(roots, () => {
+    n += 1;
+  });
+  return n;
+}

package/src/ui-editor/overlay.tsx

@@ -0,0 +1,380 @@
+/**
+ * SelectionOverlay — the visual-edit selection overlay applied in-realm (C5/C10).
+ *
+ * A transparent layer over the rendered UI. Hover highlights, click selects
+ * (shift = multi), drag on empty space marquee-selects, drag on the body moves an
+ * absolute node, the SE handle resizes, and measurement guides show spacing
+ * between the hovered and selected nodes. Hit-testing uses document.elementFromPoint
+ * against the live DOM `data-ui-id` tags (no iframe, no postMessage — in-realm).
+ */
+import { type RefObject, useEffect, useRef, useState } from 'react';
+import { getElementsInRect, type MarqueeCandidate } from '../ui-source/inspect';
+import { findNode, getNodePath } from './node-ops';
+import { hitTest, hitTestAttr, nodeRect, useUIStore } from './react-store';
+import type { UIEditStore } from './ui-edit-store';
+
+interface Props {
+  store: UIEditStore;
+  stageRef: RefObject<HTMLDivElement | null>;
+}
+
+interface Rect {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+
+const ACCENT = '#0d99ff';
+const GRID = 8; // snap grid (K3)
+
+export function SelectionOverlay({ store, stageRef }: Props): React.ReactNode {
+  useUIStore(store);
+  const overlayRef = useRef<HTMLDivElement>(null);
+  const [hoverId, setHoverId] = useState<string | null>(null);
+  const [marquee, setMarquee] = useState<Rect | null>(null);
+  const drag = useRef<null | {
+    mode: 'move' | 'resize' | 'marquee';
+    id?: string;
+    startX: number;
+    startY: number;
+    orig: Rect;
+    startOffset?: { left: number; top: number; right: number; bottom: number } | null;
+  }>(null);
+
+  // Force one re-render after mount so refs populate for rect computation.
+  const [, setMounted] = useState(0);
+  useEffect(() => setMounted(1), []);
+
+  // Read refs LIVE (not a render-time snapshot) so handlers see the mounted nodes.
+  const rectOf = (id: string): Rect | null => {
+    const stage = stageRef.current;
+    if (!stage) return null;
+    const r = nodeRect(stage, id);
+    return r ? { x: r.x, y: r.y, w: r.width, h: r.height } : null;
+  };
+
+  useEffect(() => {
+    function onUp(): void {
+      if (drag.current && drag.current.mode !== 'marquee') store.endEdit();
+      if (drag.current?.mode === 'marquee' && marquee) commitMarquee(marquee);
+      drag.current = null;
+      setMarquee(null);
+    }
+    window.addEventListener('mouseup', onUp);
+    return () => window.removeEventListener('mouseup', onUp);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [marquee]);
+
+  function commitMarquee(m: Rect): void {
+    const stage = stageRef.current;
+    if (!stage) return;
+    const ids: string[] = [];
+    const els = stage.querySelectorAll('[data-ui-id]');
+    const s = stage.getBoundingClientRect();
+    els.forEach((el) => {
+      const r = el.getBoundingClientRect();
+      const x = r.left - s.left;
+      const y = r.top - s.top;
+      if (x >= m.x && y >= m.y && x + r.width <= m.x + m.w && y + r.height <= m.y + m.h) {
+        const id = (el as HTMLElement).dataset['uiId'];
+        if (id && !id.includes('/')) ids.push(id); // prefer top-level-ish nodes
+      }
+    });
+    if (ids.length) store.select(ids);
+    // Cap 8 (React visual-edit parity): a marquee over component-internal (data-oid)
+    // elements also surfaces the DEEPEST source element (getElementsInRect) for the
+    // source-edit path — so a rubber-band selects into a component's JSX, not just UI nodes.
+    const oidEls = Array.from(stage.querySelectorAll<HTMLElement>('[data-oid]'));
+    const candidates: MarqueeCandidate[] = oidEls.map((el) => {
+      const rr = el.getBoundingClientRect();
+      return {
+        oid: el.getAttribute('data-oid') ?? '',
+        rect: { x: rr.left - s.left, y: rr.top - s.top, width: rr.width, height: rr.height },
+        descendantOids: Array.from(el.querySelectorAll<HTMLElement>('[data-oid]')).map(
+          (d) => d.getAttribute('data-oid') ?? '',
+        ),
+      };
+    });
+    const inRect = getElementsInRect({ x: m.x, y: m.y, width: m.w, height: m.h }, candidates);
+    if (inRect[0]) store.setSourceSelection(inRect[0].oid);
+  }
+
+  function onMouseMove(e: React.MouseEvent): void {
+    const stage = stageRef.current;
+    if (!stage) return;
+    if (drag.current) {
+      const dx = e.clientX - drag.current.startX;
+      const dy = e.clientY - drag.current.startY;
+      if (drag.current.mode === 'marquee') {
+        const x0 = drag.current.orig.x;
+        const y0 = drag.current.orig.y;
+        setMarquee({
+          x: Math.min(x0, x0 + dx),
+          y: Math.min(y0, y0 + dy),
+          w: Math.abs(dx),
+          h: Math.abs(dy),
+        });
+        return;
+      }
+      const id = drag.current.id;
+      if (!id) return;
+      const loc = findNode(store.roots, id);
+      if (!loc) return;
+      // K3: snap to an 8px grid unless Alt is held (free move).
+      const snap = (v: number): number => (e.altKey ? Math.round(v) : Math.round(v / GRID) * GRID);
+      if (drag.current.mode === 'move') {
+        // Move an absolute-positioned node by adjusting its offsets.
+        const o = drag.current.startOffset;
+        if (o) {
+          store.previewSetProp(id, 'layout.offset', {
+            left: snap(o.left + dx),
+            top: snap(o.top + dy),
+            right: snap(o.right + dx),
+            bottom: snap(o.bottom + dy),
+          });
+        }
+      } else if (drag.current.mode === 'resize') {
+        const w = Math.max(8, snap(drag.current.orig.w + dx));
+        const h = Math.max(8, snap(drag.current.orig.h + dy));
+        store.previewSetProp(id, 'layout.width', w);
+        store.previewSetProp(id, 'layout.height', h);
+      }
+      return;
+    }
+    const id = hitTest(stage, e.clientX, e.clientY);
+    setHoverId(id);
+  }
+
+  function onMouseDown(e: React.MouseEvent): void {
+    const stage = stageRef.current;
+    if (!stage) return;
+    const id = hitTest(stage, e.clientX, e.clientY);
+    if (!id) {
+      // start marquee
+      const s = stage.getBoundingClientRect();
+      drag.current = {
+        mode: 'marquee',
+        startX: e.clientX,
+        startY: e.clientY,
+        orig: { x: e.clientX - s.left, y: e.clientY - s.top, w: 0, h: 0 },
+      };
+      return;
+    }
+    store.selectOne(id, e.shiftKey);
+    // If a component-internal element (data-oid, stamped by the OID Vite plugin) is
+    // under the point, also select it for the LIVE source-edit path (C7).
+    const oid = hitTestAttr(stage, e.clientX, e.clientY, 'data-oid');
+    store.setSourceSelection(oid ?? null);
+    const loc = findNode(store.roots, id);
+    const r = rectOf(id);
+    if (loc && r && loc.node.layout?.position === 'absolute') {
+      const o =
+        (getNodePath(loc.node, 'layout.offset') as
+          | { left: number; top: number; right: number; bottom: number }
+          | undefined) ?? null;
+      store.beginEdit();
+      drag.current = {
+        mode: 'move',
+        id,
+        startX: e.clientX,
+        startY: e.clientY,
+        orig: r,
+        startOffset: o,
+      };
+    }
+  }
+
+  // Cap 3 (React visual-edit parity): double-click a component-internal (data-oid) element
+  // to edit its text — surfaces the source element so the SourceEditPanel's text field
+  // (which commits to the JSX source via /__ui-source/text) targets it.
+  function onDoubleClick(e: React.MouseEvent): void {
+    const stage = stageRef.current;
+    if (!stage) return;
+    const oid = hitTestAttr(stage, e.clientX, e.clientY, 'data-oid');
+    if (oid) store.setSourceSelection(oid);
+  }
+
+  function startResize(e: React.MouseEvent, id: string): void {
+    e.stopPropagation();
+    const r = rectOf(id);
+    if (!r) return;
+    store.beginEdit();
+    drag.current = { mode: 'resize', id, startX: e.clientX, startY: e.clientY, orig: r };
+  }
+
+  const selection = store.selection;
+  const hoverRect = hoverId && !selection.includes(hoverId) ? rectOf(hoverId) : null;
+
+  return (
+    <div
+      ref={overlayRef}
+      data-ui-overlay
+      onMouseMove={onMouseMove}
+      onMouseDown={onMouseDown}
+      onDoubleClick={onDoubleClick}
+      style={{
+        position: 'absolute',
+        inset: 0,
+        zIndex: 10,
+        cursor: drag.current?.mode === 'move' ? 'grabbing' : 'default',
+      }}
+    >
+      {hoverRect && <Box rect={hoverRect} color={ACCENT} />}
+      {(() => {
+        const oid = store.sourceOid;
+        const stage = stageRef.current;
+        if (!oid || !stage) return null;
+        const el = stage.querySelector(`[data-oid="${oid}"]`);
+        if (!el) return null;
+        const r = el.getBoundingClientRect();
+        const s = stage.getBoundingClientRect();
+        return (
+          <Box
+            rect={{ x: r.left - s.left, y: r.top - s.top, w: r.width, h: r.height }}
+            color="#f80"
+            solid
+            label={`source · ${oid}`}
+          />
+        );
+      })()}
+      {selection.map((id) => {
+        const r = rectOf(id);
+        if (!r) return null;
+        return (
+          <div key={id}>
+            <Box rect={r} color={ACCENT} solid label={labelFor(store, id)} />
+            <Handle rect={r} onMouseDown={(e) => startResize(e, id)} />
+          </div>
+        );
+      })}
+      {/* measurement guide between primary selection and hover (C10) */}
+      {hoverRect && selection.length === 1 && rectOf(selection[0] as string) && (
+        <Measure a={rectOf(selection[0] as string) as Rect} b={hoverRect} />
+      )}
+      {marquee && (
+        <div
+          style={{
+            position: 'absolute',
+            left: marquee.x,
+            top: marquee.y,
+            width: marquee.w,
+            height: marquee.h,
+            border: `1px solid ${ACCENT}`,
+            background: 'rgba(13,153,255,0.1)',
+            pointerEvents: 'none',
+          }}
+        />
+      )}
+    </div>
+  );
+}
+
+function labelFor(store: UIEditStore, id: string): string {
+  const loc = findNode(store.roots, id);
+  return loc ? `${loc.node.name} · ${loc.node.kind}` : id;
+}
+
+function Box({
+  rect,
+  color,
+  solid,
+  label,
+}: {
+  rect: Rect;
+  color: string;
+  solid?: boolean;
+  label?: string;
+}): React.ReactNode {
+  return (
+    <div
+      style={{
+        position: 'absolute',
+        left: rect.x,
+        top: rect.y,
+        width: rect.w,
+        height: rect.h,
+        border: `${solid ? 2 : 1}px solid ${color}`,
+        boxSizing: 'border-box',
+        pointerEvents: 'none',
+      }}
+    >
+      {label && (
+        <div
+          style={{
+            position: 'absolute',
+            top: -18,
+            left: 0,
+            background: color,
+            color: '#fff',
+            fontSize: 10,
+            padding: '1px 4px',
+            whiteSpace: 'nowrap',
+            fontFamily: 'monospace',
+          }}
+        >
+          {label}
+        </div>
+      )}
+    </div>
+  );
+}
+
+function Handle({
+  rect,
+  onMouseDown,
+}: {
+  rect: Rect;
+  onMouseDown: (e: React.MouseEvent) => void;
+}): React.ReactNode {
+  return (
+    <div
+      data-ui-handle="se"
+      onMouseDown={onMouseDown}
+      style={{
+        position: 'absolute',
+        left: rect.x + rect.w - 5,
+        top: rect.y + rect.h - 5,
+        width: 10,
+        height: 10,
+        background: '#fff',
+        border: `1px solid ${ACCENT}`,
+        cursor: 'nwse-resize',
+        pointerEvents: 'auto',
+      }}
+    />
+  );
+}
+
+function Measure({ a, b }: { a: Rect; b: Rect }): React.ReactNode {
+  // horizontal gap between the two rects (simple spacing indicator, C10)
+  const gap = Math.round(Math.max(0, b.x - (a.x + a.w)));
+  if (gap <= 0) return null;
+  const y = a.y + a.h / 2;
+  return (
+    <div
+      style={{
+        position: 'absolute',
+        left: a.x + a.w,
+        top: y,
+        width: gap,
+        height: 0,
+        borderTop: '1px dashed #f0f',
+        pointerEvents: 'none',
+      }}
+    >
+      <span
+        style={{
+          position: 'absolute',
+          left: gap / 2 - 8,
+          top: -14,
+          color: '#f0f',
+          fontSize: 10,
+          fontFamily: 'monospace',
+        }}
+      >
+        {gap}px
+      </span>
+    </div>
+  );
+}