State machines: asset, tab, State branch and Set state nodes (#51)

A state machine is an asset whose graph holds one `State` node per state
(no ports, name as title), edited in a new "State machine" tab that reuses
the graph canvas: right-click places "State n", snap toggle shared with the
Behavior tab via SnapToggle. `statemachine` is a value kind like texture
(port, literal node, variable, struct field, tagged list item).

Behaviors use it through `State branch` (one exec output per state) and
`Set state` (one exec input per state; the interpreter now hands `run` the
entry port). States live per behavior instance in NodeContext.states, with
no initial state. Ports derive from the inline picker or a wired
`State machine` literal; BehaviorLookup became GraphLookup with
behavior(id) and machine(id).

The Graph tab is labelled "Behavior" (key unchanged). Unit tests
(state-machine, kinds, catalog, ports), e2e step 26 and README added.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

src/editor/graph/GraphCanvas.ts

@@ -17,17 +17,18 @@ import {
   edgesInto,
   edgesOutOf,
   firstPortFor,
+  type Graph,
   type GraphNode,
-  type BehaviorLookup,
+  type GraphLookup,
   type PortSide,
   type PortType,
   portTypeOf,
   resolveDef,
   RUN_BEHAVIOR,
 } from '../../core/graph';
-import type { BehaviorAsset } from '../../core/model/Asset';
-import { behaviorLookup } from '../../core/model/behaviorPrograms';
-import { findAsset } from '../../core/model/Project';
+import type { GraphAsset } from '../../core/model/Asset';
+import { graphLookup } from '../../core/model/graphLookup';
+import { findAsset, findGraphAsset } from '../../core/model/Project';
 import { type Trace, TRACE_FADE } from '../../runtime/systems/BehaviorSystem';
 import { beadsInFlight, launchBead } from './beads';
 import {
@@ -69,8 +70,8 @@ const DRAG_THRESHOLD = 3;
 const LIVE_VALUE_INTERVAL_MS = 100;
 
 /**
- * The node graph of one behavior asset. Which behavior that is comes from the outside (`show`),
- * so the canvas never has an opinion about the selection – the GraphEditor around it does.
+ * The node graph of one behavior or state machine asset. Which one that is comes from the outside
+ * (`show`), so the canvas never has an opinion about the selection – the tab around it does.
  */
 export class GraphCanvas extends Widget {
   private readonly bg = new Graphics();
@@ -123,7 +124,11 @@ export class GraphCanvas extends Widget {
   /** A double-clicked call node; the tab opens the behavior and records the step. */
   onOpenBehavior: (assetId: string) => void = (assetId) => this.state.select({ kind: 'asset', assetId });
 
-  constructor(private readonly state: EditorState) {
+  constructor(
+    private readonly state: EditorState,
+    /** Names the asset kind in the empty state: "No behavior selected …". */
+    private readonly noun = 'behavior',
+  ) {
     super();
     this.canvas.addChild(this.edgeLayer, this.nodeLayer, this.tempEdge);
     this.addChild(this.bg, this.grid, this.canvas, this.band, this.hint, this.clip);
@@ -187,20 +192,19 @@ export class GraphCanvas extends Widget {
     return { w: Math.max(this.minWidth, 200), h: Math.max(this.minHeight, 200) };
   }
 
-  private behaviors(): BehaviorLookup {
-    return behaviorLookup(this.state.project);
+  private behaviors(): GraphLookup {
+    return graphLookup(this.state.project);
   }
 
-  private asset(): BehaviorAsset | null {
-    const asset = this.assetId ? findAsset(this.state.project, this.assetId) : undefined;
-    return asset && asset.type === 'behavior' ? asset : null;
+  private asset(): GraphAsset | null {
+    return (this.assetId && findGraphAsset(this.state.project, this.assetId)) || null;
   }
 
   /** Rebuilds node views from the model (cheap: views are reused by node id). */
   private sync(): void {
     const asset = this.asset();
     if (!asset) {
-      // A behavior that was deleted (or undone away) must not linger as a graph.
+      // An asset that was deleted (or undone away) must not linger as a graph.
       this.assetId = '';
       for (const view of this.views.values()) view.destroy({ children: true });
       this.views.clear();
@@ -208,7 +212,7 @@ export class GraphCanvas extends Widget {
       return;
     }
     const seen = new Set<string>();
-    const lookup = behaviorLookup(this.state.project);
+    const lookup = graphLookup(this.state.project);
     for (const node of asset.graph.nodes) {
       const def = resolveDef(node, asset.graph, lookup);
       if (!def) continue;
@@ -435,7 +439,8 @@ export class GraphCanvas extends Widget {
     const local = this.toLocal(e.global);
     const inside = local.x >= 0 && local.x <= this.w && local.y >= 0 && local.y <= this.h;
     const asset = dragged.kind === 'asset' ? findAsset(this.state.project, dragged.id) : undefined;
-    if (!inside || !this.assetId || asset?.type !== 'behavior') {
+    // Only a behavior graph runs other behaviors; a state machine has nothing to drop in.
+    if (!inside || this.asset()?.type !== 'behavior' || asset?.type !== 'behavior') {
       this.setIncoming(null);
       return;
     }
@@ -631,10 +636,7 @@ export class GraphCanvas extends Widget {
       this.state.select(nodeSelection(this.assetId, [add.node.id]));
   }
 
-  private openLinks(
-    pick: (graph: BehaviorAsset['graph']) => BehaviorAsset['graph']['edges'],
-    at: { x: number; y: number },
-  ): void {
+  private openLinks(pick: (graph: Graph) => Graph['edges'], at: { x: number; y: number }): void {
     const graph = this.asset()?.graph;
     if (graph) openLinkMenu(this.state, this.assetId, pick(graph), at.x, at.y);
   }
@@ -652,7 +654,7 @@ export class GraphCanvas extends Widget {
     const asset = this.asset();
     this.canvas.visible = asset !== null;
     if (!asset) {
-      this.hint.text = 'No behavior selected – pick one above, or add a behavior asset.';
+      this.hint.text = `No ${this.noun} selected – pick one above, or add a ${this.noun} asset.`;
       return;
     }
     const playing = this.state.mode === 'play';

src/editor/graph/GraphEditor.ts

@@ -1,29 +1,24 @@
 import type { Asset, BehaviorAsset } from '../../core/model/Asset';
 import { findAsset, findAssetOf } from '../../core/model/Project';
-import { Checkbox, Label } from '../../ui';
 import { AssetTabEditor } from '../AssetTabEditor';
 import type { EditorState } from '../state';
 import { Breadcrumb } from './Breadcrumb';
 import { GraphCanvas } from './GraphCanvas';
+import { SnapToggle } from './SnapToggle';
 import { backTo, descend, follow, type Trail } from './trail';
 
 /** Room kept for the "N nodes · M links" readout, wide enough for a three-digit graph. */
 const INFO_WIDTH = 150;
 
 export class GraphEditor extends AssetTabEditor<BehaviorAsset, GraphCanvas> {
-  private readonly snapBox = new Checkbox();
+  private readonly snap = new SnapToggle(() => this.canvas);
   readonly breadcrumb = new Breadcrumb();
   private trail: Trail = [];
 
   constructor(state: EditorState) {
     super(state, { noun: 'Behavior', infoWidth: INFO_WIDTH });
-    this.snapBox.onChange = (on) => this.canvas.setSnapping(on);
     this.breadcrumb.onPick = (index) => this.open(this.trail[index]!, backTo(this.trail, index));
-    this.mount(
-      new GraphCanvas(state),
-      [new Label('Snap', { style: 'muted' }), this.snapBox],
-      this.breadcrumb,
-    );
+    this.mount(new GraphCanvas(state), this.snap.widgets, this.breadcrumb);
     this.canvas.onOpenBehavior = (id) => this.open(id, descend(this.trail, this.currentAssetId, id));
     // Play swaps in the runtime copy of the project, and back.
     state.on('mode', () => this.refresh());
@@ -69,6 +64,6 @@ export class GraphEditor extends AssetTabEditor<BehaviorAsset, GraphCanvas> {
   }
 
   protected override syncExtras(asset: BehaviorAsset | null): void {
-    this.snapBox.setEnabled(Boolean(asset));
+    this.snap.setEnabled(Boolean(asset));
   }
 }

src/editor/graph/NodePalette.ts

@@ -2,7 +2,7 @@ import type { NodeCategory, NodeDef } from '../../core/graph';
 import { ListView, Popup, ScrollContainer, TextField, Theme, ui } from '../../ui';
 import type { PaletteEntry } from './paletteEntries';
 
-const CATEGORY_ORDER: NodeCategory[] = ['event', 'flow', 'variable', 'data', 'action'];
+const CATEGORY_ORDER: NodeCategory[] = ['event', 'flow', 'variable', 'data', 'action', 'state'];
 
 /** Searchable list of node types; right-click menu of the graph editor. */
 export class NodePalette extends Popup {

src/editor/graph/NodeView.ts

@@ -49,6 +49,8 @@ export function categoryColor(category: NodeCategory): number {
       return c.categoryVariable;
     case 'action':
       return c.categoryAction;
+    case 'state':
+      return c.categoryState;
   }
 }
 

src/editor/graph/SnapToggle.ts

@@ -0,0 +1,17 @@
+import { Checkbox, Label, type Widget } from '../../ui';
+import type { GraphCanvas } from './GraphCanvas';
+
+/** The "Snap" checkbox every tab on the graph canvas carries in its header. */
+export class SnapToggle {
+  private readonly box = new Checkbox();
+  readonly widgets: readonly Widget[];
+
+  constructor(canvas: () => GraphCanvas) {
+    this.box.onChange = (on) => canvas().setSnapping(on);
+    this.widgets = [new Label('Snap', { style: 'muted' }), this.box];
+  }
+
+  setEnabled(on: boolean): void {
+    this.box.setEnabled(on);
+  }
+}

src/editor/graph/paletteEntries.ts

@@ -3,13 +3,16 @@ import {
   BEHAVIOR_PARAM,
   createEmptyGraph,
   isTerminalType,
+  nextStateName,
   type NodeDef,
   resolveDef,
   RUN_BEHAVIOR,
+  State,
+  STATE_NAME_PARAM,
   terminalNode,
 } from '../../core/graph';
-import type { BehaviorAsset } from '../../core/model/Asset';
-import { behaviorLookup } from '../../core/model/behaviorPrograms';
+import type { GraphAsset } from '../../core/model/Asset';
+import { graphLookup } from '../../core/model/graphLookup';
 import type { PropertyBag } from '../../core/model/Properties';
 import type { Project } from '../../core/model/Project';
 
@@ -25,17 +28,22 @@ export interface PaletteEntry {
 }
 
 /**
- * The node types offerable in `asset`'s graph. Every other behavior appears under its own name
- * instead of behind a generic "Run behavior"; the two terminals drop out once the graph has them.
+ * The node types offerable in `asset`'s graph. A state machine holds states and nothing else, each
+ * new one named by its number. In a behavior, every other behavior appears under its own name
+ * instead of behind a generic "Run behavior", and the two terminals drop out once the graph has them.
  */
-export function paletteEntries(project: Project, asset: BehaviorAsset): PaletteEntry[] {
+export function paletteEntries(project: Project, asset: GraphAsset): PaletteEntry[] {
+  if (asset.type === 'statemachine') {
+    const params = { [STATE_NAME_PARAM]: nextStateName(asset.graph) };
+    return [{ id: State.type, hint: State.category, def: State, params }];
+  }
   const entries: PaletteEntry[] = [];
   for (const def of allNodeDefs()) {
-    if (def.type === RUN_BEHAVIOR) continue;
+    if (def.type === RUN_BEHAVIOR || def.category === 'state') continue;
     if (isTerminalType(def.type) && terminalNode(asset.graph, def.type)) continue;
     entries.push({ id: def.type, hint: def.category, def, params: {} });
   }
-  const lookup = behaviorLookup(project);
+  const lookup = graphLookup(project);
   for (const other of project.assets) {
     // A behavior running itself is an endless loop, so it is not on offer.
     if (other.type !== 'behavior' || other.id === asset.id) continue;