@vgai/editor 0.2.0 → 0.4.0-canary.20260715.0

package/src/xstate-inspect/xstate-graph.ts

@@ -0,0 +1,265 @@
+/**
+ * E3 (spec §11 E3, docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md) — pure,
+ * UI-free extraction of a renderable node/edge graph from a real XState v5
+ * machine. No separate graph format is persisted anywhere (E3's own AC): this
+ * module reads `machine.root` (a `StateNode`) and its `.states`/`.on`/
+ * `.always`/`.meta` directly, every time it's called — the "graph" is just a
+ * derived view, recomputed from the live machine configuration.
+ *
+ * ## Which xstate v5 accessors this uses, and why
+ *
+ * Confirmed against the installed `xstate@5.32.4` (`node_modules/xstate/dist/
+ * declarations/src/StateNode.d.ts`) and by instrumenting the real
+ * `characterAnimationMachine` (examples/third-person/src/components.ts) at
+ * runtime:
+ *
+ * - `StateNode.states: Record<string, StateNode>` — child state nodes,
+ *   walked recursively for nested/compound machines. Absent (`{}`) on atomic
+ *   leaves.
+ * - `StateNode.id` — the full dotted id (e.g. `"character-animation.idle"`),
+ *   used as this module's node id throughout (stable, globally unique within
+ *   one machine).
+ * - `StateNode.on: TransitionDefinitionMap` — a `Record<eventType,
+ *   TransitionDefinition[]>` of this state's OWN event-triggered transitions
+ *   (does NOT include ancestor/root `on` handlers with no target on this
+ *   node, and does NOT include `always` — confirmed by probing the real
+ *   machine: `idle.on` has only `JUMP`, not the root-level `UPDATE`).
+ * - `StateNode.always: TransitionDefinition[] | undefined` — eventless
+ *   ("always"/guarded-every-microstep) transitions, kept SEPARATE from `.on`
+ *   by xstate itself; each has `eventType: ''`. Rendered as edges labeled
+ *   "always" rather than an event name.
+ * - `TransitionDefinition.target: readonly StateNode[] | undefined` —
+ *   resolved target state node(s) (already-resolved, not a string to
+ *   re-parse); `undefined` for an internal/actionless transition (no target
+ *   state change) — those are skipped as edges (nothing to point an arrow at).
+ * - `TransitionDefinition.guard` — a string (named guard), a `{type, params}`
+ *   object (parameterized named guard), or a plain predicate function
+ *   (`(args, params) => boolean`, the common case for hand-authored
+ *   machines like `characterAnimationMachine`, which uses inline
+ *   `({ context }) => context.speed > 0.1` arrows). `guardLabel` below
+ *   normalizes all three to a short display string.
+ * - `StateNode.meta?: any` — read here only to detect `meta.animation`
+ *   presence; actual parsing/validation is delegated to
+ *   `collectMachineAnimationMeta`/`clipNamesOf` (E1,
+ *   `@engine/animation/xstate-animation-meta`) — this module does not
+ *   duplicate that validation.
+ * - `StateNode.type: 'atomic' | 'compound' | 'parallel' | 'final' |
+ *   'history'` — surfaced per node so the panel can show it (a compound/
+ *   parallel state has children; the graph still renders it as its own node
+ *   PLUS its children as separate nodes with a parent edge implied by
+ *   nesting depth, not a literal drawn edge).
+ *
+ * No `getStateNodes()` call is needed here: that xstate helper resolves the
+ * set of state nodes ACTIVE for one `StateValue` (a snapshot-shaped query).
+ * This module wants the machine's full STATIC configuration (every declared
+ * state, reachable or not, active or not) — a plain recursive walk of
+ * `.states` from `machine.root` is the correct and sufficient tool for that.
+ */
+
+import type {
+  clipNamesOf as ClipNamesOfFn,
+  collectMachineAnimationMeta as CollectMachineAnimationMetaFn,
+  MachineAnimationMetaEntry,
+} from '@engine/animation/xstate-animation-meta';
+import type { AnyStateMachine, AnyStateNode, StateValue } from 'xstate';
+import { getStateNodes } from 'xstate';
+
+export interface XStateGraphNode {
+  /** Full dotted state id, e.g. `"character-animation.locomotion"`. */
+  id: string;
+  /** The relative key, e.g. `"locomotion"`. */
+  key: string;
+  /** Dotted id of the immediate parent state node, or `null` for the root. */
+  parentId: string | null;
+  /** Depth from the root (root = 0), used by the layered layout. */
+  depth: number;
+  type: 'atomic' | 'compound' | 'parallel' | 'final' | 'history';
+  /** True for the machine's single configured initial leaf-path state at each level. */
+  isInitial: boolean;
+  /** Raw `meta` object as authored (e.g. `{ animation: {...} }`), if any. */
+  meta: Record<string, unknown> | undefined;
+  /** Parsed animation meta for this state, if `meta.animation` validated successfully. */
+  animation: MachineAnimationMetaEntry | undefined;
+  /** `clipNamesOf(animation.meta)` when `animation` is present. */
+  clipNames: string[];
+}
+
+export interface XStateGraphEdge {
+  /** Stable synthetic id for React `key` props: `${source}--${eventLabel}--${target}--${index}`. */
+  id: string;
+  source: string;
+  target: string;
+  /** The triggering event name, or `'always'` for eventless transitions. */
+  eventLabel: string;
+  /** `true` for an `always` (eventless) transition. */
+  isEventless: boolean;
+  /** Normalized guard display label, or `undefined` when the transition is unguarded. */
+  guardLabel: string | undefined;
+}
+
+export interface XStateGraph {
+  machineId: string;
+  nodes: XStateGraphNode[];
+  edges: XStateGraphEdge[];
+}
+
+/** True for a plain, non-empty object (guards against `null`/arrays passing `typeof === 'object'`). */
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+/**
+ * Normalize an xstate v5 `TransitionDefinition['guard']` to a short display
+ * label. Handles the three shapes xstate allows (confirmed above):
+ *  - a string → the guard name verbatim (`"someNamedGuard"`).
+ *  - a `{ type, params? }` object → `.type` (a parameterized named guard).
+ *  - a function → its `.name` when xstate/JS gave it a real one (property-
+ *    shorthand functions like `guard: someNamedFn` keep their declared name),
+ *    otherwise (the common inline-arrow case, e.g.
+ *    `({ context }) => context.speed > 0.1`) fall back to a truncated
+ *    `.toString()` of the function body so the condition is still legible
+ *    rather than showing a useless generic "guard" (xstate's own destructured-
+ *    param naming quirk: an arrow assigned to an object property named
+ *    `guard` is named `"guard"` by the JS engine itself, which conveys
+ *    nothing — confirmed by probing the real `characterAnimationMachine`).
+ */
+export function guardLabel(guard: unknown): string | undefined {
+  if (guard == null) return undefined;
+  if (typeof guard === 'string') return guard;
+  if (typeof guard === 'function') {
+    const name = guard.name;
+    if (name && name !== 'guard' && name !== 'anonymous') return name;
+    const src = guard.toString().replace(/\s+/g, ' ').trim();
+    return src.length > 60 ? `${src.slice(0, 57)}...` : src;
+  }
+  if (isPlainObject(guard) && typeof guard['type'] === 'string') {
+    return guard['type'];
+  }
+  return '(guard)';
+}
+
+/** Every dotted-id descendant state node of `node`, depth-first, including `node` itself. */
+function* walkStateNodes(
+  node: AnyStateNode,
+  parentId: string | null,
+  depth: number,
+): Generator<{
+  node: AnyStateNode;
+  parentId: string | null;
+  depth: number;
+}> {
+  yield { node, parentId, depth };
+  for (const child of Object.values(node.states)) {
+    yield* walkStateNodes(child, node.id, depth + 1);
+  }
+}
+
+/** True iff `node` is the configured initial child of its parent (root-relative; always true for the root itself). */
+function isInitialChild(node: AnyStateNode): boolean {
+  const parent = node.parent;
+  if (!parent) return true;
+  if (parent.type !== 'compound') return false; // parallel/atomic parents have no single "initial" child
+  return parent.initial?.target?.some((t) => t.id === node.id) ?? false;
+}
+
+/**
+ * One state node's outgoing edges: its own event-triggered (`on`) transitions
+ * plus its eventless (`always`) transitions — kept as a separate helper from
+ * {@link buildXStateGraph} purely to keep that function's cognitive
+ * complexity low; the logic is unchanged from a single inline loop.
+ */
+function edgesFromNode(node: AnyStateNode, nextEdgeId: () => number): XStateGraphEdge[] {
+  const edges: XStateGraphEdge[] = [];
+  for (const [eventType, defs] of Object.entries(node.on)) {
+    for (const def of defs) {
+      for (const target of def.target ?? []) {
+        edges.push({
+          id: `${node.id}--${eventType}--${target.id}--${nextEdgeId()}`,
+          source: node.id,
+          target: target.id,
+          eventLabel: eventType,
+          isEventless: false,
+          guardLabel: guardLabel(def.guard),
+        });
+      }
+    }
+  }
+  for (const def of node.always ?? []) {
+    for (const target of def.target ?? []) {
+      edges.push({
+        id: `${node.id}--always--${target.id}--${nextEdgeId()}`,
+        source: node.id,
+        target: target.id,
+        eventLabel: 'always',
+        isEventless: true,
+        guardLabel: guardLabel(def.guard),
+      });
+    }
+  }
+  return edges;
+}
+
+/**
+ * Extract a renderable {@link XStateGraph} from a real XState machine.
+ * Accepts `AnyStateMachine` (what `setup(...).createMachine(...)` and
+ * `createMachine(...)` both return) — works for the shipped
+ * `characterAnimationMachine` and any other hand-authored machine.
+ *
+ * `collectMachineAnimationMeta`/`clipNamesOf` are passed in rather than
+ * imported directly so this module (and its tests) never need
+ * `@vgai/engine`'s Zod validation to be duplicated or re-mocked — see the
+ * call sites in `components/xstate-documents.tsx`, which pass the real
+ * functions.
+ */
+export function buildXStateGraph(
+  machine: AnyStateMachine,
+  collectMachineAnimationMeta: typeof CollectMachineAnimationMetaFn,
+  clipNamesOf: typeof ClipNamesOfFn,
+): XStateGraph {
+  const root = machine.root;
+  const animationByStateId = new Map(
+    collectMachineAnimationMeta(root).map((entry) => [entry.stateId, entry]),
+  );
+
+  const nodes: XStateGraphNode[] = [];
+  const edges: XStateGraphEdge[] = [];
+  let edgeSeq = 0;
+  const nextEdgeId = () => edgeSeq++;
+
+  for (const { node, parentId, depth } of walkStateNodes(root, null, 0)) {
+    const animation = animationByStateId.get(node.id);
+    nodes.push({
+      id: node.id,
+      key: node.key,
+      parentId,
+      depth,
+      type: node.type,
+      isInitial: isInitialChild(node),
+      meta: isPlainObject(node.meta) ? node.meta : undefined,
+      animation,
+      clipNames: animation ? clipNamesOf(animation.meta) : [],
+    });
+    edges.push(...edgesFromNode(node, nextEdgeId));
+  }
+
+  return { machineId: root.id, nodes, edges };
+}
+
+/**
+ * The full state ids XState reports as ACTIVE for a given snapshot value —
+ * every ancestor plus the leaf (e.g. a snapshot in `"locomotion"` reports
+ * both `"character-animation"` and `"character-animation.locomotion"`).
+ *
+ * Uses xstate's own `getStateNodes(rootNode, stateValue)` (`xstate` package
+ * root export, confirmed present in the installed v5.32.4 and exercised
+ * directly against a real machine) rather than `snapshot.getMeta()` —
+ * `getMeta()` only returns states that declare a `meta` object at all
+ * (confirmed by probing a real machine: a meta-less compound ancestor is
+ * silently absent from `getMeta()`'s keys even while active), which would
+ * under-highlight the graph for any machine with meta-less parent/compound
+ * states. `getStateNodes` returns the complete active set regardless of
+ * whether a node has `meta`.
+ */
+export function activeStateIdsOf(machine: AnyStateMachine, stateValue: StateValue): string[] {
+  return getStateNodes(machine.root, stateValue).map((n) => n.id);
+}

package/src/xstate-inspect/xstate-layout.ts

@@ -0,0 +1,76 @@
+/**
+ * E3 — a deterministic, dependency-free layered layout for an
+ * {@link XStateGraph}. No graph-layout library exists in this repo (checked:
+ * no reactflow/dagre/elkjs/d3 in `packages/editor/package.json` or the root
+ * manifest) and the spec explicitly says a fancy graph engine is not
+ * required ("a simple deterministic layout is fine — grid/columns by depth").
+ *
+ * Layout rule: one COLUMN per state-tree depth (root=0, its children=1,
+ * grandchildren=2, …) — this both (a) reads naturally for the shallow
+ * machines XState animation binding targets (§5.6's examples are 1-2 levels
+ * deep) and (b) guarantees a parent is always positioned before/left-of its
+ * children, which keeps nesting legible even before any edges are drawn.
+ * Within a column, nodes are stacked top-to-bottom in the machine's own
+ * declaration order (`StateNode.order` is xstate's own deterministic
+ * document-order counter) — so the layout is 100% a pure function of the
+ * machine, not randomized/force-simulated, and is stable across renders
+ * (required for a sane React key/position diff and for tests to assert
+ * exact pixel positions).
+ */
+
+import type { XStateGraph, XStateGraphNode } from './xstate-graph';
+
+export interface LayoutNode {
+  node: XStateGraphNode;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface XStateLayout {
+  nodes: LayoutNode[];
+  positionById: Map<string, LayoutNode>;
+  width: number;
+  height: number;
+}
+
+const COLUMN_WIDTH = 220;
+const COLUMN_GAP = 100;
+const ROW_HEIGHT = 64;
+const ROW_GAP = 24;
+const NODE_WIDTH = 180;
+const MARGIN = 24;
+
+/** Lay out a graph's nodes into depth-based columns, declaration order within each column. */
+export function layoutXStateGraph(graph: XStateGraph): XStateLayout {
+  const byDepth = new Map<number, XStateGraphNode[]>();
+  for (const node of graph.nodes) {
+    const bucket = byDepth.get(node.depth);
+    if (bucket) bucket.push(node);
+    else byDepth.set(node.depth, [node]);
+  }
+
+  const nodes: LayoutNode[] = [];
+  const positionById = new Map<string, LayoutNode>();
+  let maxDepth = 0;
+  let maxRows = 0;
+
+  for (const [depth, column] of byDepth) {
+    maxDepth = Math.max(maxDepth, depth);
+    maxRows = Math.max(maxRows, column.length);
+    const x = MARGIN + depth * (COLUMN_WIDTH + COLUMN_GAP);
+    column.forEach((node, row) => {
+      const y = MARGIN + row * (ROW_HEIGHT + ROW_GAP);
+      const laidOut: LayoutNode = { node, x, y, width: NODE_WIDTH, height: ROW_HEIGHT };
+      nodes.push(laidOut);
+      positionById.set(node.id, laidOut);
+    });
+  }
+
+  const width = MARGIN * 2 + (maxDepth + 1) * COLUMN_WIDTH + maxDepth * COLUMN_GAP;
+  const height =
+    MARGIN * 2 + Math.max(1, maxRows) * ROW_HEIGHT + Math.max(0, maxRows - 1) * ROW_GAP;
+
+  return { nodes, positionById, width, height };
+}

package/src/z-index.ts

@@ -0,0 +1,26 @@
+/**
+ * Canonical z-index scale (editor-style-polish U0,
+ * `roadmaps/editor-style-polish/EDITOR-STYLE-AUDIT.md` §3 "Z-index scale").
+ * Replaces the ungoverned 1..10000 range (4 orders of magnitude, 2 sites
+ * typed as strings) with named tiers. Re-exported from `theme.ts`; kept as
+ * its own module too so a call site that only needs stacking order doesn't
+ * have to import the whole token set.
+ *
+ * `designTimeLayers` is deliberately NOT given a single number here —
+ * `authoring/design-time-layers.ts`'s `BASE_Z_INDEX` is already a real,
+ * scoped constant for that tier and is left as-is per the audit.
+ */
+export const zIndex = {
+  /** Default stacking (no explicit z-index needed). */
+  base: 0,
+  /** World-selection / text-edit / align-toolbar tier (absorbs 20/50/60/70). */
+  overlayLow: 50,
+  /** Dropdown / popover tier (absorbs the flat `100` used almost everywhere). */
+  dropdown: 100,
+  /** Sticky chrome tier (absorbs 200/999/1000, and the stray string `'999'`). */
+  sticky: 1000,
+  /** Toast tier. */
+  toast: 9999,
+  /** Modal tier — already consistent across all dialog components. */
+  modal: 10000,
+} as const;