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/core/graph/nodes/data/literals.ts

@@ -30,6 +30,11 @@ export const TextureLiteral = literal(
   'texture',
   'A constant picture: a texture, one of its frames or an animation, as a sprite wears it.',
 );
+export const StateMachineLiteral = literal(
+  'StateMachine',
+  'statemachine',
+  'A constant state machine, for a "State branch" or a "Set state" to work on.',
+);
 export const ListLiteral = literal(
   'List',
   'list',

src/core/graph/nodes/flow/RunBehavior.ts

@@ -18,8 +18,8 @@ export const RunBehavior: NodeDef = {
   inputs: [exec()],
   outputs: [exec()],
   params: [{ key: BEHAVIOR_PARAM, label: 'Behavior', kind: 'asset', default: '', assetTypes: ['behavior'] }],
-  derivePorts: ({ node, behaviors }) => {
-    const program = behaviors(textOf(node.params[BEHAVIOR_PARAM] ?? ''));
+  derivePorts: ({ node, lookup }) => {
+    const program = lookup.behavior(textOf(node.params[BEHAVIOR_PARAM] ?? ''));
     return {
       // The graph reads as what it does, not as a row of identical "Run behavior" boxes.
       label: program?.name,

src/core/graph/nodes/flow/SetState.ts

@@ -0,0 +1,23 @@
+import type { NodeDef } from '../../NodeRegistry';
+import { machineOf, machinePort, statePorts } from '../../stateMachine';
+import { asString } from '../../values';
+import { exec } from '../shared';
+
+/** The mirror image of `State branch`: the input the flow arrives through names the new state. */
+export const SetState: NodeDef = {
+  type: 'SetState',
+  label: 'Set state',
+  category: 'action',
+  description:
+    'Puts the machine into the state whose input the flow arrived through, then continues. Each ' +
+    'behavior instance keeps its own states.',
+  inputs: [machinePort()],
+  outputs: [exec()],
+  params: [],
+  derivePorts: (source) => ({ inputs: statePorts(machineOf(source)) }),
+  run: (ctx, inputs, _params, def, entry) => {
+    const machine = asString(inputs.machine);
+    if (machine && def.inputs.some((p) => p.type === 'exec' && p.key === entry)) ctx.states[machine] = entry;
+    return { next: 'exec' };
+  },
+};

src/core/graph/nodes/flow/StateBranch.ts

@@ -0,0 +1,22 @@
+import type { NodeDef } from '../../NodeRegistry';
+import { machineOf, machinePort, statePorts } from '../../stateMachine';
+import { asString } from '../../values';
+import { exec } from '../shared';
+
+/** No state set yet, or a state of another machine: the flow ends here, along no output. */
+export const StateBranch: NodeDef = {
+  type: 'StateBranch',
+  label: 'State branch',
+  category: 'flow',
+  description:
+    'Continues along the output of the state the machine is in. Before "Set state" has run, the ' +
+    'machine is in no state and nothing continues.',
+  inputs: [exec(), machinePort()],
+  outputs: [],
+  params: [],
+  derivePorts: (source) => ({ outputs: statePorts(machineOf(source)) }),
+  run: (ctx, inputs, _params, def) => {
+    const current = ctx.states[asString(inputs.machine)];
+    return def.outputs.some((p) => p.key === current) ? { next: current } : {};
+  },
+};

src/core/graph/nodes/index.ts

@@ -26,7 +26,14 @@ import { IsTouching } from './data/IsTouching';
 import { Join } from './data/Join';
 import { KeyIsDown } from './data/KeyIsDown';
 import { Length } from './data/Length';
-import { BooleanLiteral, ListLiteral, NumberLiteral, StringLiteral, TextureLiteral } from './data/literals';
+import {
+  BooleanLiteral,
+  ListLiteral,
+  NumberLiteral,
+  StateMachineLiteral,
+  StringLiteral,
+  TextureLiteral,
+} from './data/literals';
 import { Max } from './data/Max';
 import { Min } from './data/Min';
 import { Modulo } from './data/Modulo';
@@ -76,6 +83,9 @@ import { Branch } from './flow/Branch';
 import { Repeat } from './flow/Repeat';
 import { RunBehavior } from './flow/RunBehavior';
 import { Sequence } from './flow/Sequence';
+import { SetState } from './flow/SetState';
+import { StateBranch } from './flow/StateBranch';
+import { State } from '../stateMachine';
 import { Variables } from './variable/Variables';
 
 /**
@@ -99,6 +109,8 @@ export const BUILT_IN_NODES: readonly NodeDef[] = [
   Sequence,
   Repeat,
   RunBehavior,
+  StateBranch,
+  SetState,
   BehaviorEnd,
   Variables,
   Self,
@@ -114,6 +126,7 @@ export const BUILT_IN_NODES: readonly NodeDef[] = [
   BooleanLiteral,
   StringLiteral,
   TextureLiteral,
+  StateMachineLiteral,
   Add,
   Subtract,
   Multiply,
@@ -168,3 +181,5 @@ export const BUILT_IN_NODES: readonly NodeDef[] = [
 ];
 
 for (const def of BUILT_IN_NODES) registerNode(def);
+// Registered so a machine's graph loads and draws, but not built in: no behavior graph offers it.
+registerNode(State);