@volter/editor-game 0.5.65 → 0.5.67

package/src/xstate/character-animation-machine.fixture.ts

@@ -1,74 +0,0 @@
-/**
- * E3/E4 demo + test fixture — mirrors `characterAnimationMachine`
- * (`examples/third-person/src/components.ts`) EXACTLY (same states, events,
- * guards, `meta.animation`). Not a re-export: that machine is a module-
- * private `const` in the example game (never exported), and
- * `examples/third-person` is outside `packages/editor`'s tsconfig `include`
- * (no path alias reaches it — confirmed: `packages/editor/tsconfig*.json`
- * only maps the runtime packages), so the editor package cannot
- * import it directly without either widening the example's public surface or
- * adding a new cross-package path alias — both bigger changes than this lean
- * inspector unit warrants. A representative fixture machine is
- * spec-sanctioned for exactly this case ("import it or a representative
- * fixture machine").
- *
- * Keep this in sync with `examples/third-person/src/components.ts` by hand if
- * that machine's shape ever changes — there is no structural coupling
- * enforcing it (a comment-only contract, same as any other fixture mirroring
- * real game code).
- */
-
-import { assign, setup as xstateSetup } from 'xstate';
-
-export const characterAnimationMachine = xstateSetup({
-  types: {
-    context: {} as { speed: number; grounded: boolean },
-    events: {} as { type: 'UPDATE'; speed: number; grounded: boolean } | { type: 'JUMP' },
-  },
-}).createMachine({
-  id: 'character-animation',
-  initial: 'idle',
-  context: { speed: 0, grounded: true },
-  on: {
-    UPDATE: {
-      actions: assign({
-        speed: ({ event }) => event.speed,
-        grounded: ({ event }) => event.grounded,
-      }),
-    },
-  },
-  states: {
-    idle: {
-      meta: { animation: { clip: 'idle', loop: true, crossfade: { duration: 0.2 } } },
-      on: { JUMP: 'airborne' },
-      always: { guard: ({ context }) => context.speed > 0.1, target: 'locomotion' },
-    },
-    locomotion: {
-      meta: {
-        animation: {
-          blendTree: {
-            type: '1D',
-            parameter: 'speed',
-            children: [
-              { clip: 'walk', threshold: 1 },
-              { clip: 'run', threshold: 5 },
-            ],
-          },
-          crossfade: { duration: 0.2 },
-        },
-      },
-      on: { JUMP: 'airborne' },
-      always: { guard: ({ context }) => context.speed <= 0.1, target: 'idle' },
-    },
-    airborne: {
-      meta: { animation: { clip: 'jump', loop: false, crossfade: { duration: 0.1 } } },
-      always: [
-        {
-          guard: ({ context }) => context.grounded && context.speed > 0.1,
-          target: 'locomotion',
-        },
-        { guard: ({ context }) => context.grounded, target: 'idle' },
-      ],
-    },
-  },
-});

package/src/xstate/live-behaviors.ts

@@ -1,106 +0,0 @@
-/**
- * XState BEHAVIOR — the live debugger's reads over the editor's HIERARCHY
- * DOOR (`editorHost().hierarchy`), and the one subject the Behavior document
- * draws. The graph is a derived live debugger over a real actor; it is never
- * an animation view or a second persisted machine.
- *
- * NO fabricated hierarchy rows, NO demo machine anywhere: the shipped
- * `character-animation-machine.fixture.ts` is a TEST/story fixture only
- * (`packages/editor/test/xstate-fixture-ban.test.ts` pins that), and every
- * open path here requires an actual live actor — with none, nothing renders
- * and nothing can be opened. The starter template has no XState machine, so a
- * template session shows no XState UI at all.
- *
- * `Open Source` (§4.3 mentions it MAY exist): deliberately NOT built —
- * neither XState nor the inspection carries machine→source-file identity, and
- * fabricating one (e.g. grepping for the machine id) would violate §4.3's
- * "no ids decoded for magic words". When the engine grows a real
- * machine→module provenance, the section is where it lands.
- *
- * Editing stays a code change: the graph view is inspect-only.
- *
- * THE DOCUMENT IS ONE. A contributed `workspace.document` is registered under
- * its own contribution id, so the editor holds exactly one Behavior tab and
- * this module holds WHICH live actor it shows. Before the move into this
- * package the host opened a document per node (`behavior:xstate:<nodeId>`);
- * a package reaches the center through the contribution point, which has no
- * per-subject form, and one Behavior surface that follows the actor you asked
- * for is the honest shape of that point.
- */
-
-import { editorHost } from '@volter/editor-sdk/host';
-import type { XStateBehaviorInspection } from '@volter/threejs-runtime/behavior/xstate-inspection';
-import { getUserData } from '@volter/threejs-runtime/ecs/user-data';
-
-/** This package's `xstate-behavior.document.tsx`, by the id the host derives
- *  from its filename (the workspace tab is `tool:` + this). */
-export const BEHAVIOR_DOCUMENT_ID = 'xstate-behavior.document';
-
-/** The node's explicitly registered live behavior, through the door. */
-export function liveBehaviorFor(nodeId: string): XStateBehaviorInspection | undefined {
-  const object = editorHost().hierarchy.object(nodeId);
-  return object ? getUserData(object, '_xstateBehavior') : undefined;
-}
-
-export interface LiveBehaviorEntry {
-  readonly nodeId: string;
-  readonly machineId: string;
-  readonly label: string;
-}
-
-/** Every explicitly registered live behavior actor, one row per actor. */
-export function listLiveBehaviors(): LiveBehaviorEntry[] {
-  const seen = new Set<XStateBehaviorInspection>();
-  const out: LiveBehaviorEntry[] = [];
-  for (const [nodeId, object] of editorHost().hierarchy.objects()) {
-    const behavior = getUserData(object, '_xstateBehavior');
-    if (!behavior || seen.has(behavior)) continue;
-    seen.add(behavior);
-    out.push({ nodeId, machineId: behavior.machine.id, label: object.name || nodeId });
-  }
-  return out;
-}
-
-// --- The document's subject -------------------------------------------------
-
-let subjectNodeId: string | null = null;
-let subjectVersion = 0;
-const subjectListeners = new Set<() => void>();
-
-export function subscribeBehaviorSubject(listener: () => void): () => void {
-  subjectListeners.add(listener);
-  return () => {
-    subjectListeners.delete(listener);
-  };
-}
-
-export function behaviorSubjectVersion(): number {
-  return subjectVersion;
-}
-
-/** The node whose actor the Behavior document draws, or null before any open. */
-export function behaviorSubject(): string | null {
-  return subjectNodeId;
-}
-
-/**
- * Open the Behavior document on one live actor. False — and nothing opens —
- * when that node carries no live behavior, or when the document contribution
- * is not registered (a build without this package).
- */
-export function openBehaviorDocument(nodeId: string): boolean {
-  if (!liveBehaviorFor(nodeId)) return false;
-  if (subjectNodeId !== nodeId) {
-    subjectNodeId = nodeId;
-    subjectVersion++;
-    for (const listener of subjectListeners) listener();
-  }
-  return editorHost().workspace.openContributedDocument(BEHAVIOR_DOCUMENT_ID);
-}
-
-/** Open the first truthful live behavior, if one exists — what the Debug menu
- *  item and the standing palette action do. */
-export function openFirstBehaviorDocument(): boolean {
-  const first = listLiveBehaviors()[0];
-  return first ? openBehaviorDocument(first.nodeId) : false;
-}

package/src/xstate/use-live-actor-state.ts

@@ -1,44 +0,0 @@
-/**
- * E3 ("Current state and active transition are highlighted during
- * preview/play") — subscribes to a live XState actor and returns the full
- * set of currently-active state ids, updating on every transition.
- *
- * Returns `null` (not `[]`) when no actor is provided, or the actor hasn't
- * emitted a snapshot yet — callers should treat `null` as "fall back to the
- * static `currentStateId` prop", and `[]` as "the actor genuinely reports no
- * active animation-relevant states" (shouldn't normally happen for a running
- * actor, but is a real distinct value from "no live actor at all").
- */
-
-import type { InspectableXStateActor } from '@volter/threejs-runtime/behavior/xstate-inspection';
-import { useEffect, useState } from 'react';
-import type { AnyStateMachine, StateValue } from 'xstate';
-import { activeStateIdsOf } from './xstate-graph';
-
-// The actor is the engine binding's own minimal shape, not XState's
-// `AnyActorRef` — see `XStateAnimationActor`'s note. It keeps `value` as
-// `unknown`, so interpreting it as a `StateValue` is this inspector's job and
-// happens in exactly the two places below.
-export function useLiveActorState(
-  machine: AnyStateMachine,
-  actor: InspectableXStateActor | undefined,
-): string[] | null {
-  const [activeIds, setActiveIds] = useState<string[] | null>(null);
-
-  useEffect(() => {
-    if (!actor) {
-      setActiveIds(null);
-      return;
-    }
-    // Seed from whatever snapshot the actor already has (it may have started
-    // and transitioned before this component mounted), then follow every
-    // subsequent transition.
-    setActiveIds(activeStateIdsOf(machine, actor.getSnapshot().value as StateValue));
-    const subscription = actor.subscribe((snapshot) => {
-      setActiveIds(activeStateIdsOf(machine, snapshot.value as StateValue));
-    });
-    return () => subscription.unsubscribe();
-  }, [machine, actor]);
-
-  return activeIds;
-}

package/src/xstate/xstate-graph.ts

@@ -1,235 +0,0 @@
-/**
- * E3 (spec §11 E3) — 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` 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.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 { 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;
-}
-
-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[];
-}
-
-function isPlainObject(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
-/**
- * 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.
- *
- * Animation metadata is intentionally absent: this graph represents behavior
- * statechart structure only. Animation playback has its own native-runtime
- * projection in the Animation workspace.
- */
-export function buildXStateGraph(machine: AnyStateMachine): XStateGraph {
-  const root = machine.root;
-
-  const nodes: XStateGraphNode[] = [];
-  const edges: XStateGraphEdge[] = [];
-  let edgeSeq = 0;
-  const nextEdgeId = () => edgeSeq++;
-
-  for (const { node, parentId, depth } of walkStateNodes(root, null, 0)) {
-    nodes.push({
-      id: node.id,
-      key: node.key,
-      parentId,
-      depth,
-      type: node.type,
-      isInitial: isInitialChild(node),
-    });
-    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/xstate-layout.ts

@@ -1,76 +0,0 @@
-/**
- * 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
- * behavior machines (§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 };
-}