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>

tests/core/graph.test.ts

@@ -72,8 +72,10 @@ describe('node registry', () => {
       const keys = [...def.inputs, ...def.outputs].map((p) => p.key);
       expect(new Set(def.inputs.map((p) => p.key)).size).toBe(def.inputs.length);
       expect(new Set(def.outputs.map((p) => p.key)).size).toBe(def.outputs.length);
-      // An event is seeded by the runtime, a state is a name in a machine: neither runs.
-      if (def.category === 'event' || def.category === 'state') expect(def.inputs).toHaveLength(0);
+      // An event is seeded by the runtime, so nothing flows into it.
+      if (def.category === 'event') expect(def.inputs).toHaveLength(0);
+      // A state is a name in a machine; its ports only anchor transitions, so it never runs.
+      else if (def.category === 'state') expect(def.run).toBeUndefined();
       // A shader node is compiled to GLSL and a particle node to a function: neither is ever run.
       else if (def.category === 'shader' || def.category === 'particles') expect('emit' in def).toBe(true);
       else expect(def.run).toBeTypeOf('function');

tests/core/node-catalog.test.ts

@@ -8,6 +8,7 @@ import { BUILT_IN_NODES } from '../../src/core/graph/nodes';
 import {
   createEmptyGraph,
   type DeclaredPort,
+  type GraphLookup,
   NO_LOOKUP,
   type NodeContext,
   resolveDef,
@@ -38,10 +39,19 @@ interface Case {
   repeat?: RunResult['repeat'] | null;
   /** Expected nested-behavior call; `null` asserts the node calls nothing. */
   call?: RunResult['call'] | null;
+  /** The project around the graph – for a node whose step is written in another asset. */
+  lookup?: GraphLookup;
   /** Assertions on what the node did to the context or to the handles it was given. */
   after?(ctx: FakeContext): void;
 }
 
+/** A lookup holding one machine "m" with the given transitions – what `State transition` reads. */
+const machineLookup = (transitions: { from: string; to: string; name?: string }[]): GraphLookup => ({
+  ...NO_LOOKUP,
+  machine: (id) =>
+    id === 'm' ? { name: 'M', states: [], transitions: transitions.map((t) => ({ name: '', ...t })) } : null,
+});
+
 const run = (type: string, c: Case): { result: RunResult; ctx: FakeContext } => {
   const ctx = fakeContext(c.context);
   const node = { id: 'n', type, x: 0, y: 0, params: c.params ?? {}, ports: c.ports };
@@ -52,7 +62,8 @@ const run = (type: string, c: Case): { result: RunResult; ctx: FakeContext } =>
     inputs: [...execPorts(c.derivedInputs), ...registered.inputs],
     outputs: [...registered.outputs, ...execPorts(c.derivedOutputs)],
   };
-  return { result: def.run!(ctx, c.inputs ?? {}, c.params ?? {}, def, c.entry ?? 'exec'), ctx };
+  const lookup = c.lookup ?? NO_LOOKUP;
+  return { result: def.run!(ctx, c.inputs ?? {}, c.params ?? {}, def, c.entry ?? 'exec', lookup), ctx };
 };
 
 const at = (name: string, x: number, y: number) => ({ ...fakeEntity(name), x, y });
@@ -140,6 +151,76 @@ const CASES: Record<string, Case[]> = {
       after: (ctx) => expect(ctx.states).toEqual({}),
     },
   ],
+  StateTransition: [
+    {
+      name: 'follows the transition of the asked-for name out of the current state',
+      inputs: { machine: 'm' },
+      params: { transition: 'alarm' },
+      context: { states: { m: 's1' } },
+      lookup: machineLookup([{ from: 's1', to: 's2', name: 'alarm' }]),
+      next: 'exec',
+      after: (ctx) => expect(ctx.states).toEqual({ m: 's2' }),
+    },
+    {
+      // The point of naming transitions: one node works from every state that has that name.
+      name: 'picks the same name out of whichever state the machine is in',
+      inputs: { machine: 'm' },
+      params: { transition: 'alarm' },
+      context: { states: { m: 'searching' } },
+      lookup: machineLookup([
+        { from: 'patrolling', to: 'chasing', name: 'alarm' },
+        { from: 'chasing', to: 'searching', name: 'lost' },
+        { from: 'searching', to: 'chasing', name: 'alarm' },
+      ]),
+      next: 'exec',
+      after: (ctx) => expect(ctx.states).toEqual({ m: 'chasing' }),
+    },
+    {
+      name: 'a name the current state does not carry moves nothing',
+      inputs: { machine: 'm' },
+      params: { transition: 'lost' },
+      context: { states: { m: 's1' } },
+      lookup: machineLookup([{ from: 's1', to: 's2', name: 'alarm' }]),
+      next: 'exec',
+      after: (ctx) => expect(ctx.states).toEqual({ m: 's1' }),
+    },
+    {
+      name: 'two of the name out of one state is no move: the graph never picked between them',
+      inputs: { machine: 'm' },
+      params: { transition: 'alarm' },
+      context: { states: { m: 's1' } },
+      lookup: machineLookup([
+        { from: 's1', to: 's2', name: 'alarm' },
+        { from: 's1', to: 's3', name: 'alarm' },
+      ]),
+      next: 'exec',
+      after: (ctx) => expect(ctx.states).toEqual({ m: 's1' }),
+    },
+    {
+      // An unnamed transition is a name too, so a machine nobody named still steps.
+      name: 'with no name asked for, follows the one unnamed transition',
+      inputs: { machine: 'm' },
+      context: { states: { m: 's1' } },
+      lookup: machineLookup([{ from: 's1', to: 's2' }]),
+      next: 'exec',
+      after: (ctx) => expect(ctx.states).toEqual({ m: 's2' }),
+    },
+    {
+      name: 'a state with nothing drawn out of it stays put',
+      inputs: { machine: 'm' },
+      context: { states: { m: 's2' } },
+      lookup: machineLookup([{ from: 's1', to: 's2' }]),
+      next: 'exec',
+      after: (ctx) => expect(ctx.states).toEqual({ m: 's2' }),
+    },
+    {
+      name: 'in no state yet there is nothing to move from',
+      inputs: { machine: 'm' },
+      lookup: machineLookup([{ from: 's1', to: 's2' }]),
+      next: 'exec',
+      after: (ctx) => expect(ctx.states).toEqual({}),
+    },
+  ],
   Repeat: [
     {
       name: 'asks for as many body rounds as it was given, then continues at done',

tests/core/state-machine.test.ts

@@ -5,7 +5,13 @@
  */
 import { describe, expect, it } from 'vitest';
 import { CreateAssetCommand } from '../../src/core/commands/assetCommands';
-import { AddNodeCommand, ConnectCommand, SetNodeParamCommand } from '../../src/core/commands/graphCommands';
+import {
+  AddNodeCommand,
+  ConnectCommand,
+  NameTransitionCommand,
+  RemoveNodeCommand,
+  SetNodeParamCommand,
+} from '../../src/core/commands/graphCommands';
 import { AddVariableCommand } from '../../src/core/commands/variableCommands';
 import {
   BEHAVIOR_PARAM,
@@ -15,8 +21,13 @@ import {
   nextStateName,
   resolveDef,
   STATE,
+  STATE_IN,
   STATE_NAME_PARAM,
+  STATE_OUT,
   statesOf,
+  transitionNames,
+  transitionsOf,
+  transitionTo,
 } from '../../src/core/graph';
 import { BUILT_IN_NODES } from '../../src/core/graph/nodes';
 import type { StateMachineAsset } from '../../src/core/model/Asset';
@@ -289,3 +300,122 @@ describe('a running state machine', () => {
     ).toThrow('Port not found');
   });
 });
+
+describe('transitions between states', () => {
+  /** Draws a transition the way the canvas does: out of one state's `out`, into the other's `in`. */
+  const connect = (f: ProjectFixture, machineId: string, from: string, to: string) =>
+    f.stack.execute(
+      new ConnectCommand(machineId, { node: from, port: STATE_OUT }, { node: to, port: STATE_IN }),
+    );
+
+  it('hangs on the two exec ports every state carries', () => {
+    const f = makeProject();
+    const machine = makeMachine(f);
+    const node = machine.asset().graph.nodes[0]!;
+    const def = resolveDef(node, machine.asset().graph, graphLookup(f.project))!;
+    expect(def.inputs.map((p) => p.key)).toEqual([STATE_IN]);
+    expect(def.outputs.map((p) => p.key)).toEqual([STATE_OUT]);
+    // Without a port there is no anchor to draw, drag or right-click an edge on.
+    expect(def.inputs[0]?.type).toBe('exec');
+    expect(def.outputs[0]?.type).toBe('exec');
+  });
+
+  it('is an ordinary edge, so drawing, undo and a save round trip come for free', () => {
+    const f = makeProject();
+    const machine = makeMachine(f);
+    const [open, closed] = machine.ids as [string, string];
+    connect(f, machine.id, open, closed);
+    expect(transitionsOf(machine.asset().graph)).toEqual([{ from: open, to: closed, name: '' }]);
+
+    const loaded = findAssetOf(roundTrip(f.project), machine.id, 'statemachine')!;
+    expect(transitionsOf(loaded.graph)).toEqual([{ from: open, to: closed, name: '' }]);
+
+    f.stack.undo();
+    expect(transitionsOf(machine.asset().graph)).toEqual([]);
+  });
+
+  it('goes away with the state it hangs on, because both live in the one graph', () => {
+    const f = makeProject();
+    const machine = makeMachine(f);
+    const [open, closed] = machine.ids as [string, string];
+    connect(f, machine.id, open, closed);
+    f.stack.execute(new RemoveNodeCommand(machine.id, closed));
+    expect(transitionsOf(machine.asset().graph)).toEqual([]);
+    f.stack.undo();
+    expect(transitionsOf(machine.asset().graph)).toEqual([{ from: open, to: closed, name: '' }]);
+  });
+
+  it('is what the lookup hands a running graph', () => {
+    const f = makeProject();
+    const machine = makeMachine(f);
+    const [open, closed] = machine.ids as [string, string];
+    connect(f, machine.id, open, closed);
+    expect(graphLookup(f.project).machine(machine.id)?.transitions).toEqual([
+      { from: open, to: closed, name: '' },
+    ]);
+  });
+
+  it('moves the machine one step when a behavior runs State transition', () => {
+    const f = makeProject();
+    const machine = makeMachine(f);
+    const [open, closed] = machine.ids as [string, string];
+    connect(f, machine.id, open, closed);
+    const behavior = makeBehavior(f, 'B');
+    const edit = graphEditor(f, behavior);
+    const start = edit.addNode('OnStart');
+    const set = edit.addNode('SetState', { [MACHINE_PORT]: machine.id });
+    const next = edit.addNode('StateTransition', { [MACHINE_PORT]: machine.id });
+    edit.wire([
+      [start, 'exec', set, open],
+      [set, 'exec', next, 'exec'],
+    ]);
+    const ctx = fakeContext();
+    new GraphInterpreter(behavior.graph, graphLookup(f.project)).fire('OnStart', ctx);
+    expect(ctx.states).toEqual({ [machine.id]: closed });
+  });
+
+  it('carries the name it was given through a save, and undo takes it back', () => {
+    const f = makeProject();
+    const machine = makeMachine(f);
+    const [open, closed] = machine.ids as [string, string];
+    connect(f, machine.id, open, closed);
+    const edge = machine.asset().graph.edges[0]!;
+    f.stack.execute(new NameTransitionCommand(machine.id, edge.id, '  alarm  '));
+    // Trimmed on the way in, so a stray space never makes a second name that looks the same.
+    expect(transitionsOf(machine.asset().graph)).toEqual([{ from: open, to: closed, name: 'alarm' }]);
+
+    const loaded = findAssetOf(roundTrip(f.project), machine.id, 'statemachine')!;
+    expect(transitionsOf(loaded.graph)).toEqual([{ from: open, to: closed, name: 'alarm' }]);
+
+    f.stack.undo();
+    expect(transitionsOf(machine.asset().graph)).toEqual([{ from: open, to: closed, name: '' }]);
+  });
+
+  it('clears a name back to unnamed rather than keeping an empty one', () => {
+    const f = makeProject();
+    const machine = makeMachine(f);
+    const [open, closed] = machine.ids as [string, string];
+    connect(f, machine.id, open, closed);
+    const edge = machine.asset().graph.edges[0]!;
+    f.stack.execute(new NameTransitionCommand(machine.id, edge.id, 'alarm'));
+    f.stack.execute(new NameTransitionCommand(machine.id, edge.id, '   '));
+    expect(edge.label).toBeUndefined();
+    expect(transitionsOf(machine.asset().graph)).toEqual([{ from: open, to: closed, name: '' }]);
+  });
+
+  it('reads the same name out of whichever state the machine is in', () => {
+    const machine = {
+      name: 'Guard',
+      states: [],
+      transitions: [
+        { from: 'patrolling', to: 'chasing', name: 'alarm' },
+        { from: 'searching', to: 'chasing', name: 'alarm' },
+        { from: 'chasing', to: 'searching', name: 'lost' },
+      ],
+    };
+    expect(transitionTo(machine, 'patrolling', 'alarm')).toBe('chasing');
+    expect(transitionTo(machine, 'searching', 'alarm')).toBe('chasing');
+    expect(transitionTo(machine, 'chasing', 'alarm')).toBe('');
+    expect(transitionNames(machine)).toEqual(['alarm', 'lost']);
+  });
+});

tests/editor/transitions.test.ts

@@ -0,0 +1,129 @@
+/**
+ * The straight arrow between two states. It runs border to border because a diagonal line into a
+ * port passes under the target node and hides its own arrowhead there – the failure that made this
+ * geometry necessary, and the one these checks hold shut.
+ */
+import { describe, expect, it } from 'vitest';
+import {
+  ARROW,
+  arrowCorners,
+  arrowShaft,
+  BORDER_GAP,
+  boxExit,
+  centreOf,
+  direction,
+  PARALLEL_SEP,
+  transitionEnds,
+  transitionOffsets,
+  transitionPreview,
+} from '../../src/editor/graph/transitions';
+
+/** Two states side by side, 100 x 40 each, 200 apart on x. */
+const left = { x: 0, y: 0, w: 100, h: 40 };
+const right = { x: 300, y: 0, w: 100, h: 40 };
+/** Directly below the first, which is where a pin-to-pin line would cut through a node. */
+const below = { x: 0, y: 200, w: 100, h: 40 };
+
+describe('transition geometry', () => {
+  it('leaves a box on the side the ray points at', () => {
+    expect(boxExit(left, { x: 1, y: 0 })).toEqual({ x: 100, y: 20 });
+    expect(boxExit(left, { x: -1, y: 0 })).toEqual({ x: 0, y: 20 });
+    expect(boxExit(left, { x: 0, y: 1 })).toEqual({ x: 50, y: 40 });
+    expect(boxExit(left, { x: 0, y: -1 })).toEqual({ x: 50, y: 0 });
+  });
+
+  it('runs border to border, so neither end sits inside a node', () => {
+    const ends = transitionEnds(left, right)!;
+    expect(ends.start).toEqual({ x: 100 + BORDER_GAP, y: 20 });
+    expect(ends.end).toEqual({ x: 300 - BORDER_GAP, y: 20 });
+  });
+
+  it('leaves through the bottom and the top when one state sits under the other', () => {
+    const ends = transitionEnds(left, below)!;
+    // The whole point: straight down, out of the lower border and into the upper one – never
+    // across the body of either node.
+    expect(ends.start).toEqual({ x: 50, y: 40 + BORDER_GAP });
+    expect(ends.end).toEqual({ x: 50, y: 200 - BORDER_GAP });
+  });
+
+  it('keeps both ends clear of the borders they leave', () => {
+    const ends = transitionEnds(left, right)!;
+    expect(ends.start.x).toBeGreaterThan(left.x + left.w);
+    expect(ends.end.x).toBeLessThan(right.x);
+  });
+
+  it('pushes a there-and-back pair to opposite sides of the line', () => {
+    const offsets = transitionOffsets([
+      { id: 'there', from: 'a', to: 'b' },
+      { id: 'back', from: 'b', to: 'a' },
+    ]);
+    const there = offsets.get('there')!;
+    const back = offsets.get('back')!;
+    // Same sign in each arrow's own frame, which is opposite sides on screen, since the normal
+    // turns with the direction.
+    expect(there).toBe(back);
+    expect(Math.abs(there)).toBe(PARALLEL_SEP / 2);
+
+    const a = transitionEnds(left, right, there)!;
+    const b = transitionEnds(right, left, back)!;
+    expect(a.start.y).not.toBe(b.end.y);
+    expect(Math.abs(a.start.y - b.end.y)).toBeCloseTo(PARALLEL_SEP);
+  });
+
+  it('leaves a lone transition on the line between the centres', () => {
+    const offsets = transitionOffsets([{ id: 'only', from: 'a', to: 'b' }]);
+    expect(offsets.get('only')).toBe(0);
+    expect(transitionEnds(left, right, 0)).toEqual(transitionEnds(left, right));
+  });
+
+  it('fans three between the same pair evenly around the centre line', () => {
+    const offsets = transitionOffsets([
+      { id: 'one', from: 'a', to: 'b' },
+      { id: 'two', from: 'a', to: 'b' },
+      { id: 'three', from: 'a', to: 'b' },
+    ]);
+    expect([...offsets.values()]).toEqual([-PARALLEL_SEP, 0, PARALLEL_SEP]);
+  });
+
+  it('keeps transitions between different pairs on their own centre lines', () => {
+    const offsets = transitionOffsets([
+      { id: 'ab', from: 'a', to: 'b' },
+      { id: 'cd', from: 'c', to: 'd' },
+    ]);
+    expect(offsets.get('ab')).toBe(0);
+    expect(offsets.get('cd')).toBe(0);
+  });
+
+  it('has no ends when the two boxes share a centre', () => {
+    expect(transitionEnds(left, { ...left })).toBeNull();
+    expect(direction({ x: 5, y: 5 }, { x: 5, y: 5 })).toBeNull();
+  });
+
+  it('stops the line one arrowhead short of the tip', () => {
+    const shaft = arrowShaft({ x: 0, y: 0 }, { x: 100, y: 0 });
+    expect(shaft).toEqual({ x: 100 - ARROW, y: 0 });
+  });
+
+  it('points the head at the target, across the line', () => {
+    const [tip, a, b] = arrowCorners({ x: 0, y: 0 }, { x: 100, y: 0 })!;
+    expect(tip).toEqual({ x: 100, y: 0 });
+    // Both base corners sit at the shaft's end, one on each side of the line.
+    expect(a.x).toBeCloseTo(100 - ARROW);
+    expect(b.x).toBeCloseTo(100 - ARROW);
+    expect(Math.sign(a.y)).toBe(-Math.sign(b.y));
+    expect(Math.abs(a.y)).toBeCloseTo(Math.abs(b.y));
+  });
+
+  it('previews from the source border to the pointer until it finds a state', () => {
+    const loose = transitionPreview(left, null, { x: 300, y: 20 });
+    expect(loose.start).toEqual({ x: 100 + BORDER_GAP, y: 20 });
+    expect(loose.end).toEqual({ x: 300, y: 20 });
+
+    const snapped = transitionPreview(left, right, { x: 280, y: 20 });
+    expect(snapped).toEqual(transitionEnds(left, right));
+  });
+
+  it('centres a box where both halves meet', () => {
+    expect(centreOf(left)).toEqual({ x: 50, y: 20 });
+  });
+});

tests/helpers.ts

@@ -9,7 +9,9 @@ import {
   type DeclaredPort,
   ENTITY_HANDLE,
   type EntityHandle,
+  type GraphLookup,
   type GraphNode,
+  NO_LOOKUP,
   type NodeContext,
   type PointerState,
   type Value,
@@ -216,9 +218,10 @@ export function runDef(
   inputs: Record<string, Value>,
   params: PropertyBag = {},
   entry = 'exec',
+  lookup: GraphLookup = NO_LOOKUP,
 ): RunResult {
   const def = requireNodeDef(type);
-  return def.run!(ctx, inputs, params, def, entry);
+  return def.run!(ctx, inputs, params, def, entry, lookup);
 }
 
 /** Runs one node definition in isolation and returns its data outputs. */