A transition carries a name, so a state needs no visible port (#52)

A state keeps its `in`/`out` exec pins in the model and the editor never draws
them. That is the whole trick: connecting, undo, deleting a state and saving all
keep working untouched, because `normalizeGraph` filters nodes and never edges,
and no edge ever checks its port key against a NodeDef. Only two places change --
`NodeView.redraw` stops drawing the row, and `portAt` refuses to hand one out, so
an invisible pin cannot be grabbed either.

Transitions are drawn by right-clicking a state, `Make transition`, then clicking
the target. The armed mode takes the same shape as a live drag, so the existing
preview draws it with no second code path, and it dies with Escape, a click on
empty canvas or a switch to another asset.

Removing the pins removed the only handle a transition had: edges have no
hit-test anywhere, and the pin right-click was the sole route to Disconnect.
The inspector's TRANSITIONS OUT / TRANSITIONS IN lists are therefore not a
convenience, they are the delete path.

`GraphEdge` gained an optional `label`, which `normalizeGraph` has to pass
through explicitly or a saved name is dropped on load. `State transition`
replaces `Next state`: it takes the machine on an input port and the name from a
picker, and resolves against the *current* state. Names are deliberately not
unique across a machine -- two states may both have an `alarm` -- so a node named
`alarm` moves whichever state has one, and an empty name follows the single
unnamed edge.

The geometry moved to a Pixi-free `transitions.ts`: a gap to the box border, and
a fan that puts a pair of opposite edges beside each other instead of on top of
each other. Keeping it as plain maths is what let a screenshot bug become a unit
test -- an earlier pin-to-pin line ran under the target node and took its
arrowhead with it, because `nodeLayer` sits above `edgeLayer`.

One limit stands and is not fixed here: `ConnectCommand` rejects a second edge
between the same two states ("Already connected"), because every transition
hangs off the same two ports. With names, `A --alarm--> B` beside
`A --seen--> B` is a sensible pair, so this is worth its own issue.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

src/core/graph/Graph.ts

@@ -53,6 +53,8 @@ export interface GraphEdge {
   to: PortRef;
   /** Drawn as a stub at each end instead of a curve across the graph. Purely visual. */
   folded?: boolean;
+  /** What a transition between two states is called – the name `State transition` asks for. */
+  label?: string;
 }
 
 export interface Graph {

src/core/graph/GraphInterpreter.ts

@@ -105,7 +105,7 @@ export class GraphInterpreter {
     const def = this.def(node);
     if (!def?.run) return;
     const inputs = this.collectInputs(node, ctx);
-    const result = def.run(ctx, inputs, node.params, def, entry);
+    const result = def.run(ctx, inputs, node.params, def, entry, this.lookup);
     const returned = result.call ? this.call(result.call, ctx, depth) : {};
     const produced = { ...result.outputs, ...returned };
     if (!def.read) this.frame.outputCache.set(node.id, produced);
@@ -197,7 +197,8 @@ export class GraphInterpreter {
       throw new Error('Behavior graph exceeded the step limit (data cycle?)');
     // Mark before evaluating so a data cycle reads null instead of recursing forever.
     this.frame.dataCache.set(nodeId, {});
-    const outputs = def.run(ctx, this.collectInputs(source, ctx), source.params, def, '').outputs ?? {};
+    const outputs =
+      def.run(ctx, this.collectInputs(source, ctx), source.params, def, '', this.lookup).outputs ?? {};
     this.frame.dataCache.set(nodeId, outputs);
     this.trace?.onNode(nodeId);
     this.record(nodeId, outputs);

src/core/graph/NodeRegistry.ts

@@ -91,6 +91,12 @@ export interface NodeDef {
   declaresPorts?: 'inputs' | 'outputs' | 'both';
   /** How a declared port becomes a port; without it, named after its key and typed by its kind. */
   declaredPort?(port: DeclaredPort, node: GraphNode): PortDef;
+  /**
+   * Edges between two such nodes are transitions: drawn as a straight arrow instead of the usual
+   * curve, and hung on ports that are never shown. A transition graph is read as directed steps
+   * between whole states, not as signal flowing left to right into a particular socket.
+   */
+  transitionEdges?: true;
   /**
    * Ports this node computes beyond the fixed and the declared ones – how many outputs a Sequence
    * offers, which values the behavior a call node names takes. `resolveDef` applies it.
@@ -105,7 +111,8 @@ export interface NodeDef {
   /**
    * Event nodes have no `run` – the interpreter seeds their outputs. `def` is resolved for the node at
    * hand, the only way a node with derived ports knows how many it has. `entry` is the exec input
-   * the pulse arrived through – what a node with one exec input per meaning reads.
+   * the pulse arrived through – what a node with one exec input per meaning reads. `lookup` is the
+   * project around the graph, for a node whose step is written in another asset.
    */
   run?(
     ctx: NodeContext,
@@ -113,6 +120,7 @@ export interface NodeDef {
     params: PropertyBag,
     def: NodeDef,
     entry: string,
+    lookup: GraphLookup,
   ): RunResult;
 }
 

src/core/graph/lookup.ts

@@ -14,9 +14,20 @@ export interface MachineState {
   name: string;
 }
 
+/**
+ * An allowed move between two states, both named by state node id, under the name `State
+ * transition` asks for. The name is empty until someone gives the transition one.
+ */
+export interface MachineTransition {
+  from: string;
+  to: string;
+  name: string;
+}
+
 export interface StateMachine {
   name: string;
   states: MachineState[];
+  transitions: MachineTransition[];
 }
 
 /**

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

@@ -0,0 +1,28 @@
+import { textOf } from '../../../model/Properties';
+import { flatDef } from '../../../properties/PropertySchema';
+import type { NodeDef } from '../../NodeRegistry';
+import { machinePort, STATE_TRANSITION, TRANSITION_PARAM, transitionTo } from '../../stateMachine';
+import { asString } from '../../values';
+import { exec } from '../shared';
+
+/** What the transitions drawn in the machine are for at runtime: one step along a named arrow. */
+export const StateTransition: NodeDef = {
+  type: STATE_TRANSITION,
+  label: 'State transition',
+  category: 'action',
+  description:
+    "Takes the transition of this name out of the machine's current state, then continues. " +
+    'Nothing happens when that state has no transition of the name.',
+  inputs: [exec(), machinePort()],
+  outputs: [exec()],
+  params: [flatDef(TRANSITION_PARAM, 'text', { label: 'Transition', value: '' })],
+  run: (ctx, inputs, params, _def, _entry, lookup) => {
+    const id = asString(inputs.machine);
+    const current = ctx.states[id] ?? '';
+    const machine = current ? lookup.machine(id) : null;
+    const name = textOf(params[TRANSITION_PARAM] ?? '');
+    const target = machine ? transitionTo(machine, current, name) : '';
+    if (target) ctx.states[id] = target;
+    return { next: 'exec' };
+  },
+};

src/core/graph/nodes/index.ts

@@ -89,6 +89,7 @@ import { RunBehavior } from './flow/RunBehavior';
 import { Sequence } from './flow/Sequence';
 import { SetState } from './flow/SetState';
 import { StateBranch } from './flow/StateBranch';
+import { StateTransition } from './flow/StateTransition';
 import { PARTICLE_NODES } from '../../particles/nodes';
 import { SHADER_NODES } from '../../shader/nodes';
 import { State } from '../stateMachine';
@@ -120,6 +121,7 @@ export const BUILT_IN_NODES: readonly NodeDef[] = [
   RunBehavior,
   StateBranch,
   SetState,
+  StateTransition,
   BehaviorEnd,
   Variables,
   Self,

src/core/graph/stateMachine.ts

@@ -1,27 +1,36 @@
 import { textOf } from '../model/Properties';
 import { flatDef } from '../properties/PropertySchema';
 import { edgesInto, type Graph, type GraphNode } from './Graph';
-import type { MachineState, StateMachine } from './lookup';
+import type { MachineState, MachineTransition, StateMachine } from './lookup';
 import type { NodeDef, PortDef, PortSource } from './NodeRegistry';
 
 export const STATE = 'State';
 export const STATE_MACHINE = 'StateMachine';
+export const STATE_TRANSITION = 'StateTransition';
 export const STATE_NAME_PARAM = 'name';
 /** The input naming the machine on `State branch` and `Set state`. */
 export const MACHINE_PORT = 'machine';
+/** The setting naming the transition on `State transition`. */
+export const TRANSITION_PARAM = 'transition';
+/** The two ports a transition hangs on. A port is the only anchor an edge has – without one it
+ *  cannot be drawn, selected or undone – so a state carries these, and the editor never draws
+ *  them: a transition joins whole states, not sockets. */
+export const STATE_IN = 'in';
+export const STATE_OUT = 'out';
 
 /**
- * One state of a state machine: a node with no ports whose name is its title. Its graph is the
- * machine asset's, never a behavior's – the palette leaves the `state` category out.
+ * One state of a state machine: a node whose name is its title. Its graph is the machine asset's,
+ * never a behavior's – the palette leaves the `state` category out.
  */
 export const State: NodeDef = {
   type: STATE,
   label: 'State',
   category: 'state',
   description: 'One state of a state machine.',
-  inputs: [],
-  outputs: [],
+  inputs: [{ key: STATE_IN, label: '', type: 'exec' }],
+  outputs: [{ key: STATE_OUT, label: '', type: 'exec' }],
   params: [flatDef(STATE_NAME_PARAM, 'text', { label: 'Name', value: 'State' })],
+  transitionEdges: true,
   derivePorts: ({ node }) => ({ label: stateName(node) }),
 };
 
@@ -38,6 +47,31 @@ export function statesOf(graph: Graph): MachineState[] {
   return graph.nodes.filter(isStateNode).map((node) => ({ id: node.id, name: stateName(node) }));
 }
 
+/** The transitions of a machine's graph: every edge between two states, in edge order. */
+export function transitionsOf(graph: Graph): MachineTransition[] {
+  const states = new Set(graph.nodes.filter(isStateNode).map((n) => n.id));
+  return graph.edges
+    .filter((e) => states.has(e.from.node) && states.has(e.to.node))
+    .map((e) => ({ from: e.from.node, to: e.to.node, name: e.label ?? '' }));
+}
+
+/**
+ * Where `State transition` moves from `current`: along the transition of that name leaving it. The
+ * name is matched against the current state alone, so one node asking for "alarm" moves every state
+ * that has an "alarm". Nothing happens when the state has no such transition, or two of the name –
+ * with nothing drawn to pick between them, choosing either would be a guess the graph never made.
+ */
+export function transitionTo(machine: StateMachine, current: string, name: string): string {
+  const out = machine.transitions.filter((t) => t.from === current && t.name === name);
+  const targets = [...new Set(out.map((t) => t.to))];
+  return targets.length === 1 ? targets[0]! : '';
+}
+
+/** The names a machine's transitions carry, deduped and in edge order – what a node may ask for. */
+export function transitionNames(machine: StateMachine | null): string[] {
+  return [...new Set((machine?.transitions ?? []).map((t) => t.name).filter((name) => name))];
+}
+
 /** What a state placed from the palette is called: "State 3" for the third. */
 export function nextStateName(graph: Graph): string {
   return `${State.label} ${statesOf(graph).length + 1}`;