Wiring & Filters Guide

Patch Bay concept: TouchDesigner-style connection graph between signal sources, signal types, choreographies, and outputs (theme/shader).

Wire Zones:

Zone	Description
signal	Signal source endpoints
signal-type	Signal type channels (task_dispatch, tool_call, etc.)
choreographer	Choreography definitions
theme	Theme output slots
shader	Shader uniform endpoints

Three wire layers:

1. signal -> signal-type: "this source feeds this channel"
2. signal-type -> choreographer: "this channel triggers this choreography"
3. choreographer -> theme/shader: "this choreography outputs to theme/shader"

WireConnection structure:

interface WireConnection {
  id: string;
  fromZone: "signal" | "signal-type" | "choreographer";
  fromId: string;
  toZone: "signal-type" | "choreographer" | "theme" | "shader";
  toId: string;
  mapping?: { fn: string; args: number[] };
  filters?: SignalFilterConfig[];
}

Implicit combinators (no special config needed):

• Merge = multiple wires to the same choreography -- all signal types trigger it
• Split = when filters on parallel wires to different choreos -- conditional routing
• Map = map filter on a wire -- payload transformation

Signal Filters (wire-level processing):

5 filter types can be composed into a chain on each wire:

Filter	Purpose	Stateful
throttle	Rate-limit by time interval (intervalMs)	Yes (lastPass)
sample	Pass every Nth signal (every)	Yes (count)
delta	Pass when numeric value at path changes by threshold	Yes (lastValue)
when	Conditional pass via when-clause evaluation	No
map	Transform payload fields (from -> to). Always passes.	No

FilterChain: evaluates filters in sequence, short-circuits on first drop. Shallow-copies payload before mutation.

Synthetic types for filtered dispatch: When a choreography has filtered wires, it's registered under __f:<choreoId> instead of its original signal type. The run-mode controller evaluates filter chains per-wire and dispatches the synthetic type when filters pass. Unfiltered choreographies keep normal behavior.

Effective types resolution:

• If signal-type->choreographer wires exist -- those are authoritative
• If no wires -- fallback to choreography's on field

---

Auto-Wiring

When importing a scene ZIP or when a signal source connects, the scene-builder automatically creates signal -> signal-type wires for all (connected source x active signal type) pairs that don't already exist.

This solves the portability problem: when Pierre imports a scene created by Yan, the choreographies are immediately wired to Pierre's connected sources without manual re-wiring.

Two entry points:

• autoWireConnectedSources() -- one-shot, called after ZIP import. Iterates all connected sources and all signal types used by choreographies, creates missing wires.
• initAutoWire() -- reactive, called at workspace init. Subscribes to signal source state changes and auto-wires sources that transition into "connected". Tracks previous status per source to avoid firing on unrelated state updates.

What counts as an "active signal type":

1. Signal types used as fromId in signal-type -> choreographer wires
2. The on field of each choreography definition (fallback when no wires exist)

Key files:

• tools/scene-builder/src/state/auto-wire.ts -- auto-wire logic
• tools/scene-builder/src/state/wiring-state.ts -- wire store + mutations
• tools/scene-builder/src/state/wiring-queries.ts -- derived lookups
• tools/scene-builder/src/run-mode/signal-filters.ts -- filter engine
• tools/scene-builder/src/run-mode/when-matcher.ts -- when-clause evaluator