@vgai/editor 0.2.0

package/src/ui-editor/palette.tsx

@@ -0,0 +1,114 @@
+/**
+ * UIPalette — the widget palette (K1). Click (or drag) a widget to add it under
+ * the selected container (or the first root). Containers vs controls grouped.
+ */
+import type { UINode } from '@engine/scene/schema';
+import { findNode } from './node-ops';
+import { useUIStore } from './react-store';
+import type { UIEditStore } from './ui-edit-store';
+
+const CONTAINERS: UINode['kind'][] = [
+  'box',
+  'grid',
+  'stack',
+  'scroll',
+  'panel',
+  'center',
+  'wrap',
+  'aspect',
+  'tab',
+];
+const CONTROLS: UINode['kind'][] = [
+  'text',
+  'richtext',
+  'button',
+  'image',
+  'input',
+  'toggle',
+  'slider',
+  'dropdown',
+  'progress',
+];
+
+export function UIPalette({ store }: { store: UIEditStore }): React.ReactNode {
+  useUIStore(store);
+
+  const add = (kind: UINode['kind']): void => {
+    // Add under the selected node if it's a container, else its parent, else first root.
+    const sel = store.primary;
+    let parentId = store.roots[0]?.id as string | undefined;
+    if (sel) {
+      const loc = findNode(store.roots, sel);
+      if (loc) parentId = isContainer(loc.node) ? sel : (loc.parent?.id ?? parentId);
+    }
+    if (parentId) store.addNode(parentId, kind);
+  };
+
+  return (
+    <div data-testid="ui-palette" style={wrap}>
+      <Group title="Containers" kinds={CONTAINERS} onAdd={add} />
+      <Group title="Controls" kinds={CONTROLS} onAdd={add} />
+    </div>
+  );
+}
+
+function Group({
+  title,
+  kinds,
+  onAdd,
+}: {
+  title: string;
+  kinds: UINode['kind'][];
+  onAdd: (k: UINode['kind']) => void;
+}): React.ReactNode {
+  return (
+    <div style={{ marginBottom: 8 }}>
+      <div
+        style={{
+          fontSize: 10,
+          textTransform: 'uppercase',
+          color: '#888',
+          margin: '4px 0',
+          letterSpacing: 0.5,
+        }}
+      >
+        {title}
+      </div>
+      <div style={{ display: 'flex', flexWrap: 'wrap', gap: 4 }}>
+        {kinds.map((k) => (
+          <button
+            key={k}
+            data-testid={`palette-${k}`}
+            draggable
+            onDragStart={(e) => e.dataTransfer.setData('text/ui-kind', k)}
+            onClick={() => onAdd(k)}
+            style={btn}
+          >
+            {k}
+          </button>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+function isContainer(node: UINode): boolean {
+  return CONTAINERS.includes(node.kind) || node.kind === 'canvas';
+}
+
+const wrap: React.CSSProperties = {
+  background: '#161616',
+  padding: 8,
+  color: '#ddd',
+  fontFamily: 'monospace',
+};
+const btn: React.CSSProperties = {
+  background: '#262626',
+  color: '#ccc',
+  border: '1px solid #3a3a3a',
+  borderRadius: 3,
+  padding: '3px 7px',
+  fontSize: 11,
+  cursor: 'pointer',
+  fontFamily: 'monospace',
+};

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

@@ -0,0 +1,78 @@
+import { useSyncExternalStore } from 'react';
+import type { UIEditStore } from './ui-edit-store';
+
+/** Bind a React component to the UIEditStore (re-renders on version bump). */
+export function useUIStore(store: UIEditStore): number {
+  return useSyncExternalStore(store.subscribe, store.getVersion, store.getVersion);
+}
+
+/** Resolve a node's on-screen rect (relative to the stage) by its data-ui-id. */
+export function nodeRect(stage: HTMLElement, id: string): DOMRect | null {
+  const el = stage.querySelector(`[data-ui-id="${cssEscape(id)}"]`);
+  if (!el) return null;
+  const r = el.getBoundingClientRect();
+  const s = stage.getBoundingClientRect();
+  return new DOMRect(r.left - s.left, r.top - s.top, r.width, r.height);
+}
+
+/**
+ * The data-ui-id of the most-specific UI element under a client point (in-realm
+ * hit-test, C3). Geometric test over the live `data-ui-id` rects — robust to the
+ * runtime's `pointer-events:none` wrappers (which `elementFromPoint` would skip)
+ * and to the overlay sitting on top. Picks the smallest-area element containing
+ * the point (the deepest/most specific node), tie-broken by DOM order (topmost).
+ *
+ * `isLocked` (D4.R1) — an optional per-id predicate: an id it reports `true`
+ * for is treated exactly as if no element there claimed the point (it is
+ * SKIPPED, not returned as `null` outright), so the hit-test naturally falls
+ * through to whatever unlocked element is behind/around it — the same
+ * "skip and keep walking" semantics `viewport-raycast.ts`'s first-party
+ * raycast already uses for a locked `SceneEntity`. Absent ⇒ unchanged
+ * behavior (every existing call site).
+ */
+export function hitTest(
+  stage: HTMLElement,
+  clientX: number,
+  clientY: number,
+  isLocked?: (id: string) => boolean,
+): string | null {
+  return hitTestAttr(stage, clientX, clientY, 'data-ui-id', isLocked);
+}
+
+/** Generic geometric hit-test for the smallest element carrying `attr` at a
+ *  point. `isLocked` — see {@link hitTest}'s doc comment; same skip-and-keep-
+ *  walking semantics, generalized to any attribute. */
+export function hitTestAttr(
+  stage: HTMLElement,
+  clientX: number,
+  clientY: number,
+  attr: string,
+  isLocked?: (id: string) => boolean,
+): string | null {
+  const els = Array.from(stage.querySelectorAll<HTMLElement>(`[${attr}]`));
+  let bestId: string | null = null;
+  let bestArea = Number.POSITIVE_INFINITY;
+  let bestOrder = -1;
+  for (let order = 0; order < els.length; order++) {
+    const el = els[order] as HTMLElement;
+    const id = el.getAttribute(attr);
+    if (!id) continue;
+    if (isLocked?.(id)) continue;
+    const r = el.getBoundingClientRect();
+    if (clientX < r.left || clientX > r.right || clientY < r.top || clientY > r.bottom) continue;
+    const area = r.width * r.height;
+    // smallest-area (deepest) wins; ties broken by later DOM order (topmost)
+    if (area < bestArea || (area === bestArea && order > bestOrder)) {
+      bestId = id;
+      bestArea = area;
+      bestOrder = order;
+    }
+  }
+  return bestId;
+}
+
+function cssEscape(s: string): string {
+  // CSS.escape if available, else a minimal fallback for our id charset (#,/, etc.)
+  if (typeof CSS !== 'undefined' && CSS.escape) return CSS.escape(s);
+  return s.replace(/["\\#/]/g, '\\$&');
+}

package/src/ui-editor/timeline-panel.tsx

@@ -0,0 +1,443 @@
+/**
+ * UITimeline — the keyframe/dope-sheet editor (S1). For the selected node it shows
+ * its animation clips as tracks (one row per animated property) with keyframe
+ * diamonds on a time ruler, a draggable playhead (scrub), play/pause/loop, record
+ * mode (set a value → keyframe at the playhead), add/remove track + keyframe, and
+ * per-keyframe easing. Edits route through the store (one undo each, C6/K4) and the
+ * shared UIAnimationController drives the live stage preview.
+ */
+
+import type { UIAnimatableProperty } from '@engine/scene/schema';
+import type { UIAnimationController } from '@vgai/scene-ui/animation';
+import { useState } from 'react';
+import { findNode } from './node-ops';
+import { useUIStore } from './react-store';
+import type { UIEditStore } from './ui-edit-store';
+
+const PROPERTIES: UIAnimatableProperty[] = [
+  'opacity',
+  'translateX',
+  'translateY',
+  'rotate',
+  'scale',
+  'backgroundColor',
+  'color',
+  'width',
+  'height',
+];
+const EASINGS = ['linear', 'ease-in', 'ease-out', 'ease-in-out', 'step'] as const;
+const RULER_W = 460;
+
+function defaultValueFor(p: UIAnimatableProperty): number | string {
+  if (p === 'opacity' || p === 'scale') return 1;
+  if (p === 'backgroundColor' || p === 'color') return '#4af';
+  return 0;
+}
+
+export function UITimeline({
+  store,
+  anim,
+}: {
+  store: UIEditStore;
+  anim: UIAnimationController;
+}): React.ReactNode {
+  useUIStore(store);
+  const [clipIndex, setClipIndex] = useState(0);
+  const [playhead, setPlayhead] = useState(0);
+  const [record, setRecord] = useState(false);
+  const [sel, setSel] = useState<{ track: number; kf: number } | null>(null);
+  const [newProp, setNewProp] = useState<UIAnimatableProperty>('opacity');
+  const [recordVal, setRecordVal] = useState('1');
+
+  const nodeId = store.primary;
+  const node = nodeId ? findNode(store.roots, nodeId)?.node : null;
+  const clips = node?.animations ?? [];
+  const clip = clips[clipIndex];
+
+  if (!node) return <Bar>Select a UI node to author animation (S1).</Bar>;
+
+  const scrub = (t: number): void => {
+    const clamped = Math.max(0, Math.min(t, clip?.duration ?? 1));
+    setPlayhead(clamped);
+    if (clip && nodeId) anim.scrubTo(nodeId, clip, clamped);
+  };
+  const xToTime = (clientX: number, rulerLeft: number): number =>
+    ((clientX - rulerLeft) / RULER_W) * (clip?.duration ?? 1);
+
+  return (
+    <div data-testid="ui-timeline" style={panel}>
+      {/* toolbar */}
+      <div style={{ ...row, gap: 6, marginBottom: 4 }}>
+        <strong style={{ color: '#6cf' }}>Timeline</strong>
+        <select
+          data-testid="tl-clip"
+          value={clipIndex}
+          onChange={(e) => setClipIndex(Number(e.target.value))}
+          style={input}
+        >
+          {clips.map((c, i) => (
+            <option key={i} value={i}>
+              {c.name}
+            </option>
+          ))}
+          {clips.length === 0 && <option>— none —</option>}
+        </select>
+        <Btn
+          testid="tl-add-clip"
+          onClick={() => {
+            const i = store.addAnimation(nodeId as string);
+            setClipIndex(i);
+          }}
+        >
+          + clip
+        </Btn>
+        {clip && (
+          <>
+            <Btn
+              testid="tl-play"
+              onClick={() => {
+                if (nodeId) anim.play(nodeId, clip);
+              }}
+            >
+              ▶ play
+            </Btn>
+            <Btn
+              testid="tl-pause"
+              onClick={() => {
+                if (nodeId) {
+                  anim.scrubTo(nodeId, clip, anim.timeFor(nodeId));
+                  setPlayhead(anim.timeFor(nodeId));
+                }
+              }}
+            >
+              ⏸
+            </Btn>
+            <label style={lbl}>
+              <input
+                data-testid="tl-loop"
+                type="checkbox"
+                checked={!!clip.loop}
+                onChange={(e) =>
+                  store.setAnimationField(nodeId as string, clipIndex, 'loop', e.target.checked)
+                }
+              />
+              loop
+            </label>
+            <label style={lbl}>
+              dur
+              <input
+                data-testid="tl-duration"
+                type="number"
+                step={0.1}
+                value={clip.duration}
+                onChange={(e) =>
+                  store.setAnimationField(
+                    nodeId as string,
+                    clipIndex,
+                    'duration',
+                    Number(e.target.value),
+                  )
+                }
+                style={{ ...input, width: 48 }}
+              />
+            </label>
+            <Btn testid="tl-record" onClick={() => setRecord((r) => !r)} active={record}>
+              {record ? '● REC' : 'record'}
+            </Btn>
+          </>
+        )}
+      </div>
+
+      {clip && (
+        <>
+          {/* add-track + record value */}
+          <div style={{ ...row, gap: 6, marginBottom: 4 }}>
+            <select
+              data-testid="tl-prop"
+              value={newProp}
+              onChange={(e) => setNewProp(e.target.value as UIAnimatableProperty)}
+              style={input}
+            >
+              {PROPERTIES.map((p) => (
+                <option key={p} value={p}>
+                  {p}
+                </option>
+              ))}
+            </select>
+            <Btn
+              testid="tl-add-track"
+              onClick={() => store.addTrack(nodeId as string, clipIndex, newProp)}
+            >
+              + track
+            </Btn>
+            {record && (
+              <>
+                <span style={{ color: '#fa6', fontSize: 11 }}>value@{playhead.toFixed(2)}s</span>
+                <input
+                  data-testid="tl-record-val"
+                  value={recordVal}
+                  onChange={(e) => setRecordVal(e.target.value)}
+                  style={{ ...input, width: 70 }}
+                />
+                <Btn
+                  testid="tl-key"
+                  onClick={() => {
+                    const ti = clip.tracks.findIndex((t) => t.property === newProp);
+                    if (ti >= 0)
+                      store.setKeyframe(
+                        nodeId as string,
+                        clipIndex,
+                        ti,
+                        playhead,
+                        coerce(recordVal),
+                      );
+                  }}
+                >
+                  ◆ key
+                </Btn>
+              </>
+            )}
+          </div>
+
+          {/* ruler + playhead */}
+          <div
+            data-testid="tl-ruler"
+            style={{
+              position: 'relative',
+              height: 18,
+              width: RULER_W,
+              marginLeft: 88,
+              background: '#0d0d0d',
+              borderRadius: 3,
+              cursor: 'pointer',
+            }}
+            onMouseDown={(e) => {
+              const left = e.currentTarget.getBoundingClientRect().left;
+              scrub(xToTime(e.clientX, left));
+            }}
+          >
+            <div
+              data-testid="tl-playhead"
+              style={{
+                position: 'absolute',
+                left: (playhead / (clip.duration || 1)) * RULER_W,
+                top: 0,
+                bottom: -200,
+                width: 1,
+                background: '#f44',
+              }}
+            />
+            {[0.25, 0.5, 0.75].map((f) => (
+              <div
+                key={f}
+                style={{
+                  position: 'absolute',
+                  left: f * RULER_W,
+                  top: 0,
+                  bottom: 0,
+                  width: 1,
+                  background: '#222',
+                }}
+              />
+            ))}
+            <span style={{ position: 'absolute', right: 2, top: 2, color: '#666', fontSize: 9 }}>
+              {clip.duration}s
+            </span>
+          </div>
+
+          {/* tracks */}
+          {clip.tracks.map((track, ti) => (
+            <div
+              key={track.property}
+              data-testid={`tl-track-${track.property}`}
+              style={{ ...row, height: 22 }}
+            >
+              <span style={{ width: 80, color: '#aaa', fontSize: 10, overflow: 'hidden' }}>
+                {track.property}
+              </span>
+              <button
+                style={miniBtn}
+                title="remove track"
+                onClick={() => store.removeTrack(nodeId as string, clipIndex, ti)}
+              >
+                ×
+              </button>
+              <div
+                style={{
+                  position: 'relative',
+                  height: 18,
+                  width: RULER_W,
+                  background: '#161616',
+                  borderRadius: 3,
+                }}
+                onDoubleClick={(e) => {
+                  const left = e.currentTarget.getBoundingClientRect().left;
+                  store.setKeyframe(
+                    nodeId as string,
+                    clipIndex,
+                    ti,
+                    xToTime(e.clientX, left),
+                    defaultValueFor(track.property),
+                  );
+                }}
+              >
+                {track.keyframes.map((kf, ki) => {
+                  const x = (kf.time / (clip.duration || 1)) * RULER_W;
+                  const isSel = sel?.track === ti && sel?.kf === ki;
+                  return (
+                    <div
+                      key={ki}
+                      data-testid={`tl-kf-${track.property}-${ki}`}
+                      onClick={(e) => {
+                        e.stopPropagation();
+                        setSel({ track: ti, kf: ki });
+                      }}
+                      title={`${kf.time.toFixed(2)}s = ${kf.value}`}
+                      style={{
+                        position: 'absolute',
+                        left: x - 5,
+                        top: 3,
+                        width: 10,
+                        height: 10,
+                        background: isSel ? '#fc4' : '#4af',
+                        transform: 'rotate(45deg)',
+                        cursor: 'pointer',
+                        border: isSel ? '1px solid #fff' : 'none',
+                      }}
+                    />
+                  );
+                })}
+              </div>
+            </div>
+          ))}
+
+          {/* selected keyframe editor */}
+          {sel && clip.tracks[sel.track]?.keyframes[sel.kf] && (
+            <div style={{ ...row, gap: 6, marginTop: 4, color: '#ccc', fontSize: 11 }}>
+              <span>keyframe</span>
+              <span style={{ color: '#888' }}>
+                {clip.tracks[sel.track]?.keyframes[sel.kf]?.time.toFixed(2)}s
+              </span>
+              <span>val</span>
+              <input
+                data-testid="tl-kf-value"
+                value={String(clip.tracks[sel.track]?.keyframes[sel.kf]?.value ?? '')}
+                onChange={(e) => {
+                  const t = clip.tracks[sel.track]?.keyframes[sel.kf]?.time ?? 0;
+                  store.setKeyframe(
+                    nodeId as string,
+                    clipIndex,
+                    sel.track,
+                    t,
+                    coerce(e.target.value),
+                  );
+                }}
+                style={{ ...input, width: 70 }}
+              />
+              <select
+                data-testid="tl-kf-easing"
+                value={clip.tracks[sel.track]?.keyframes[sel.kf]?.easing ?? 'linear'}
+                onChange={(e) =>
+                  store.setKeyframeEasing(
+                    nodeId as string,
+                    clipIndex,
+                    sel.track,
+                    sel.kf,
+                    e.target.value as (typeof EASINGS)[number],
+                  )
+                }
+                style={input}
+              >
+                {EASINGS.map((es) => (
+                  <option key={es} value={es}>
+                    {es}
+                  </option>
+                ))}
+              </select>
+              <Btn
+                testid="tl-kf-delete"
+                onClick={() => {
+                  store.removeKeyframe(nodeId as string, clipIndex, sel.track, sel.kf);
+                  setSel(null);
+                }}
+              >
+                delete key
+              </Btn>
+            </div>
+          )}
+        </>
+      )}
+    </div>
+  );
+}
+
+function coerce(s: string): number | string {
+  if (s !== '' && !Number.isNaN(Number(s))) return Number(s);
+  return s;
+}
+
+function Bar({ children }: { children: React.ReactNode }): React.ReactNode {
+  return <div style={{ ...panel, color: '#777' }}>{children}</div>;
+}
+function Btn({
+  children,
+  onClick,
+  testid,
+  active,
+}: {
+  children: React.ReactNode;
+  onClick: () => void;
+  testid?: string;
+  active?: boolean;
+}): React.ReactNode {
+  return (
+    <button
+      data-testid={testid}
+      onClick={onClick}
+      style={{
+        ...miniBtn,
+        background: active ? '#5a2' : '#262626',
+        color: active ? '#fff' : '#ccc',
+      }}
+    >
+      {children}
+    </button>
+  );
+}
+
+const panel: React.CSSProperties = {
+  padding: 8,
+  background: '#121212',
+  borderTop: '1px solid #2a2a2a',
+  color: '#ddd',
+  fontFamily: 'monospace',
+  fontSize: 12,
+  minHeight: 120,
+};
+const row: React.CSSProperties = { display: 'flex', alignItems: 'center', gap: 4 };
+const input: React.CSSProperties = {
+  background: '#0d0d0d',
+  color: '#ddd',
+  border: '1px solid #333',
+  borderRadius: 3,
+  padding: '2px 4px',
+  fontSize: 11,
+  fontFamily: 'monospace',
+};
+const miniBtn: React.CSSProperties = {
+  background: '#262626',
+  color: '#ccc',
+  border: '1px solid #3a3a3a',
+  borderRadius: 3,
+  padding: '2px 7px',
+  fontSize: 11,
+  cursor: 'pointer',
+  fontFamily: 'monospace',
+};
+const lbl: React.CSSProperties = {
+  display: 'flex',
+  alignItems: 'center',
+  gap: 3,
+  fontSize: 11,
+  color: '#999',
+};