Standalone HTML/Canvas prototype for catwalk factory visualization

[williamthorsen]

Problem

The catwalk factory visualization design (#161) introduces significant spatial and movement changes: a two-level layout, vertical artifact chutes, and a shuttle cycle for the review-fix loop. Before committing 2-4 days of implementation effort in the Excalibur-based Factory app, we need a cheap way to validate that the movement patterns, spatial arrangement, and state transitions feel right.

The design being validated

The factory visualizes an orchestrated software development run as a 2D scene. The orchestrator dispatches work to specialized subagents, collects their output, and carries artifacts between phases. The key design elements:

Two-level spatial layout

  CATWALK ═══════╤═══════════╤═══════════╤═══════════════════════════╤══════════╤══════════╤═══════
                 │chute      │chute      │chute  chute chute chute   │chute     │chute     │chute
  ───────────────┼───────────┼───────────┼──┬──────┬──────┬──────┬───┼──────────┼──────────┼───────
  GROUND:    [Architect] [Planner]   [Coder] │[core]│[code]│[silnt]│[test] [Simplifier] [Holistic] [Summary]
                                          └──────┴──────┴──────┘
                                            REVIEW STATION (4 agents)

• Catwalk (upper level): The orchestrator walks here exclusively. It never descends to the ground floor. This visually reinforces its role as dispatcher/supervisor, not a worker.
• Ground floor (lower level): Workstations arranged left-to-right in phase order. Each station has one or more subagent slots.
• Vertical chutes: Dashed vertical lines connecting the catwalk to each ground station. Artifacts visibly travel down (dispatch) and up (collection) through these chutes.
• Gates: Vertical barriers between stations. Red = closed, green = open. A gate opens when the orchestrator is ready to proceed to the next phase.
• Skipped phases: Rendered as dim/dark stations — present but inactive, so the viewer sees the full possible pipeline.

Seven phases (stations)

The prototype should show these phases left-to-right, matching the orchestrate skill's default pipeline:

Station	Phase	Agent(s)	Color
0	Architecture	1 architect	blue
1	Planning	1 planner	green
2	Implementation	1 coder	yellow/amber
3	Parallel review	4 reviewers: core, code, silent-failure, test	red
4	Code simplifier	1 simplifier	magenta
5	Holistic review	1 holistic reviewer	cyan
6	Summary	(orchestrator produces this on the catwalk)	white

Agent visual identity

• Orchestrator: Distinct from ground agents. Amber/gold circle or rectangle, labeled "ORCH". Only appears on the catwalk.
• Ground agents: Colored circles matching their station color, labeled with a short name (e.g., "arch", "plan", "coder", "core", "code", "silnt", "test", "simp", "holi").
• Working state: Agent pulses or has a visible activity indicator (spinning, bouncing, or color change).
• Resting state: Agent is static and slightly dimmed.
• Idle state: Agent is fully dimmed.

Artifact types and colors

Artifacts are rendered as small labeled rectangles:

Artifact	Label	Color	Produced by	Consumed by
Architecture doc	arch	blue (#a5d8ff)	Architect	Planner, Coder
Orchestration plan	plan	green (#b2f2bb)	Planner	Coder
Code / change summary	code	yellow (#fff3bf)	Coder	Reviewers
Review findings	review	red (#ffc9c9)	Each reviewer	Orchestrator
Consolidated review	fixes	orange (#ffe8cc)	Orchestrator	Coder
Simplified code review	clean	magenta (#f3d9fa)	Simplifier	Coder
Holistic review	holi	cyan (#c3fae8)	Holistic reviewer	Coder
Run summary	summary	white (#f8f9fa)	Orchestrator	(persisted)

Three-beat cycle (every phase)

Every phase follows the same three-step pattern:

1. Dispatch: Orchestrator stops above the station on the catwalk. An artifact (instructions/input) descends through the chute to the agent(s) below. For parallel dispatch (review phase), one copy descends per reviewer simultaneously.
2. Work: Agent(s) show "working" state. A new artifact progressively materializes at the station (e.g., fades in or grows). This is the "fabrication" moment.
3. Collect: The finished artifact ascends through the chute to the orchestrator on the catwalk. The orchestrator picks it up (shown as an indicator above its sprite). Gate to next station opens. Orchestrator walks along catwalk to the next station.

Review-fix shuttle cycle

The review phase (station 3) extends the three-beat cycle with iteration:

Iteration 1:

1. Orchestrator drops [code] to all 4 reviewers simultaneously (parallel dispatch — 4 chutes activate at once)
2. All 4 reviewers show "working" state simultaneously
3. Reviews ascend asynchronously as each reviewer finishes (they may finish at different times)
4. Orchestrator collects all 4 reviews. A progress indicator shows collection progress (e.g., "2/4")
5. Consolidation: Orchestrator produces a [fixes] artifact on the catwalk itself (brief "working" animation — the one time it fabricates something)
6. Orchestrator walks backward along the catwalk to the coder station (station 2)
7. Orchestrator drops [fixes] to the coder
8. Coder shows "working" state, produces [code v2] (stacks visually on top of [code v1] at the station)
9. [code v2] ascends to orchestrator
10. Orchestrator walks forward along the catwalk back to review station (station 3)

Iteration 2 (selective re-review):

1. Orchestrator drops [code v2] to only 2 of the 4 reviewers (e.g., core and code). The other 2 (silent-failure and test) remain "resting" — they don't reactivate.
2. The 2 active reviewers show "working", produce reviews, reviews ascend
3. Orchestrator collects, determines criticality is below threshold

Convergence:

• Round counter near the review station shows "Round 1/3" during iteration 1, "Round 2/3" during iteration 2
• After convergence, the gate to station 4 opens
• Brief celebration beat (agents pulse or change state) before orchestrator proceeds forward

Station records (artifact persistence)

After an artifact is produced and collected, a copy remains at the station as a "station record." These persist for the rest of the demo. Superseded versions stack vertically:

• Code station after iteration 1: [code v1]
• Code station after iteration 2: [code v2] on top of [code v1] (v1 is dimmed/faded)

State transitions

From	To	Trigger	Visual
Initialization	Phase execution	Demo starts	Stations appear, orchestrator appears on catwalk above station 0
Phase execution	Next phase	Collect complete	Gate opens, orchestrator walks to next station
Phase execution	Review-fix loop	Enter review phase	Multiple chutes activate, round counter appears
Review-fix loop	Review-fix loop	Fix delivered	Orchestrator shuttles back to coder, then returns
Review-fix loop	Next phase	Convergence	Gate opens, orchestrator proceeds forward
Last phase	Completed	Summary produced	All gates open, all agents celebrate (pulse/glow)

Proposed solution

A single HTML file using the Canvas 2D API with requestAnimationFrame for animation. No dependencies, no build step — open directly in a browser.

Code structure

The code must be modular — clearly separated concerns so a reader can understand the structure without tracing through a monolith. Organize as clearly labeled sections or IIFEs:

1. Constants — Canvas dimensions, colors, spacing, timing values
2. Layout — Position calculations for catwalk Y, ground Y, station X positions, chute start/end coordinates, agent slots within stations
3. Entities — Data structures and factory functions for stations, agents, artifacts, the orchestrator, gates, and the round counter
4. Rendering — One draw function per entity type: drawStation(), drawAgent(), drawCatwalk(), drawChute(), drawArtifact(), drawGate(), drawRoundCounter(), drawOrchestrator()
5. Animation — Tweening/interpolation utilities for smooth movement: lerp(), moveTo() (horizontal walk), descend() / ascend() (vertical chute travel), fadeIn() (artifact materialization)
6. Sequence — The scripted demo sequence that drives the orchestrator through all 7 phases including the full review-fix shuttle cycle. This should read as a high-level choreography (e.g., "dispatch to architect → wait for work → collect → walk to planner → ...") rather than low-level animation code.
7. Main loop — requestAnimationFrame loop that calls update and render

Optional playback controls

If feasible within the time budget, add simple controls:

• Play / Pause button
• Speed slider (1x, 2x, 4x)
• Step forward button (advance one beat at a time)

These aid validation by letting the viewer pause and inspect specific states.

Acceptance criteria

• Opens in a browser with no server, build step, or dependencies
• Shows two-level layout: catwalk (amber/gold) above, ground-floor stations (colored) below, with dashed vertical chute lines connecting them
• Seven stations visible left-to-right matching the phase table above, each with its labeled agent(s)
• Review station (station 3) has 4 agents side by side
• Orchestrator walks on the catwalk only, stops above each station
• Three-beat cycle visible at each phase: artifact descends → agent works → artifact ascends
• Artifacts rendered as small labeled colored rectangles matching the artifact table above
• Parallel dispatch at the review station: 4 artifacts descend simultaneously through 4 chutes
• Review-fix shuttle: orchestrator walks backward to coder station carrying [fixes], coder produces [code v2] stacked on [code v1], orchestrator walks forward carrying [code v2]
• Selective re-review: on iteration 2, only 2 of 4 reviewers reactivate (the other 2 remain dimmed/resting)
• Round counter visible during review iterations showing "Round N/3"
• Convergence: gate between review and simplifier opens, orchestrator proceeds forward
• Gates between stations: red (closed) before orchestrator arrives, green (open) after phase completes
• Station records: artifact copies persist at stations after collection, with stacking for superseded versions
• Run completion: all gates open, agents show a celebration state (pulse, glow, or color shift)
• Code is modular: constants, layout, entities, rendering, animation, sequence, and main loop are clearly separated sections, each independently readable