Implement catwalk layout engine

[williamthorsen]

Goal

Pure function that computes all spatial positions from phase/agent configuration. No Excalibur dependency — just geometry.

Tasks

• Create src/client/visualizations/catwalk/layout/catwalk-layout.ts
• Implement computeCatwalkLayout() function that takes phase/agent configuration and returns:
  • Station X positions (asymmetric content-extent spacing with fixed inter-station gap)
  • Dynamic canvas/platform width computed from layout (not a fixed value)
  • Agent positions (X, Y for each agent within a station)
  • Orchestrator position (X, Y for a given station index)
  • Chute endpoints (top and bottom for each agent position)
  • Gate positions (midpoint between adjacent stations)
  • Rail and ground line endpoints
  • Canvas bounds
• Port the prototype's content-driven layout algorithm (final prototype at commit fe19d60 on branch 162, in demos/catwalk/):
  • Each station has asymmetric extents: left = agent half-width + input artifact overhang; right = agent half-width + output overhang
  • Fixed STATION_GAP (30px) between adjacent stations' content edges
  • PLATFORM_W computed dynamically from total layout
• Support compact layout mode: remove absent stations entirely and recompute positions for visible stations only
• Accept variable agent counts per station (e.g., Review may have 1–4 reviewers depending on the run)
• Unit tests for layout computation

Key algorithm

The prototype uses layoutStations(phaseIndices) which:

1. Computes per-station left extent (agents half-width + ART_W * 1.5 + 11 input overhang)
2. Computes per-station right extent (agents half-width + ART_W / 2 output overhang)
3. Places stations sequentially with STATION_GAP between content edges
4. Returns positions array and computed platformW

Compact mode filters to visible station indices only, then runs the same algorithm.

The agent count per station is not fixed — it comes from the run data. The layout must handle any number of agents at any station.

Acceptance criteria

• Layout is deterministic (same input → same output)
• No Excalibur imports
• Canvas width is computed, not fixed
• Tests cover: single-agent stations, multi-agent stations (Review with 4 agents), single reviewer, absent stations, compact mode

[williamthorsen]

Implementation plan

Plan: Catwalk layout engine

Date: 2026-03-05 09:46 UTC
Scope: Pure geometry module that computes all spatial positions for the catwalk visualization from phase/agent configuration. No Excalibur dependency.

Problem

The catwalk scene (#181) needs a pure function that takes station/agent configuration and returns all spatial positions — station centers, agent circles, orchestrator, chutes, gates, rail, ground line, and bounds. The prototype's layoutStations() in demos/catwalk/scenarios.js (branch origin/162) implements the canonical algorithm using asymmetric content extents; this plan specifies a TypeScript port with a method-based query interface.

File

packages/factory/src/client/visualizations/catwalk/layout/catwalk-layout.ts

Tests:

packages/factory/src/client/visualizations/catwalk/layout/__tests__/catwalk-layout.test.ts

Dependencies

#177 must be completed first. The layout engine imports raw dimension constants from:

packages/factory/src/client/visualizations/catwalk/constants/dimensions.ts

Required exports from #177 (with expected values from the prototype):

Constant	Value	Description
LAYOUT_MARGIN	100	Left/right margin outside layout
STATION_GAP	30	Clear gap between station content edges
CATWALK_Y	100	Y position of catwalk rail
GROUND_Y	340	Y position of ground-floor agents
CHUTE_TOP	148	Top of chute lines (CATWALK_Y + 48)
CHUTE_BOT	320	Bottom of chute lines (GROUND_Y − 20)
AGENT_RADIUS	14	Agent circle radius
ART_W	40	Artifact rectangle width
CANVAS_H	540	Canvas height

If #177 is not yet complete, create these as local constants in the layout file and add a // TODO #177: import from constants/dimensions.ts comment. Move them when #177 lands.

Input type

interface StationLayoutEntry {
  agentCount: number;
  absent?: boolean | undefined;
}

interface CatwalkLayoutConfig {
  stations: readonly StationLayoutEntry[];
  compact?: boolean | undefined;
}

• stations — one entry per phase (always 7 entries matching the phase order: architecture, planning, implementation, review, simplifier, holistic, summary).
• agentCount — the number of agents at each station. The layout must handle any positive integer. A station with no agents uses 1 as minimum for spacing purposes (matching the prototype).
• absent — marks a station as absent. In compact mode, absent stations are excluded from layout computation.
• compact — when true, absent stations are removed from the layout and remaining stations are repositioned contiguously.

Export StationLayoutEntry and CatwalkLayoutConfig from the module.

Output type

interface Position {
  x: number;
  y: number;
}

interface LineEndpoints {
  x1: number;
  x2: number;
  y: number;
}

interface ChuteEndpoints {
  topX: number;
  topY: number;
  botX: number;
  botY: number;
}

interface Bounds {
  minX: number;
  maxX: number;
  minY: number;
  maxY: number;
}

interface CatwalkLayoutResult {
  stationX(index: number): number;
  agentPosition(stationIndex: number, slotIndex: number, agentCount: number): Position;
  orchestratorPosition(stationIndex: number): Position;
  chuteEndpoints(stationIndex: number, slotIndex: number, agentCount: number): ChuteEndpoints;
  gatePosition(leftStation: number, rightStation: number): Position;
  railEndpoints(): LineEndpoints;
  groundEndpoints(): LineEndpoints;
  bounds: Bounds;
  platformWidth: number;
}

Export Position, LineEndpoints, ChuteEndpoints, Bounds, and CatwalkLayoutResult from the module.

The platformWidth property exposes the computed canvas width so the scene can set the world/camera bounds.

Public function

function computeCatwalkLayout(config: CatwalkLayoutConfig): CatwalkLayoutResult

Export as a named export. This is the sole entry point.

Algorithm

Derived constants (computed at module level)

These are layout-engine-specific values derived from imported dimension constants. Define them as const at module scope, not exported.

const AGENT_SPACING = AGENT_RADIUS * 2 + 20;  // 48 — center-to-center distance between adjacent agents
const INPUT_OVERHANG = ART_W * 1.5 + 11;      // 71 — left extent beyond leftmost agent center
const OUTPUT_OVERHANG = ART_W / 2;             // 20 — right extent beyond rightmost agent center
const RAIL_OVERSHOOT = 75;                     // how far rail/ground lines extend past the first visible station
const GROUND_LINE_OFFSET = 42;                 // offset from GROUND_Y to the ground floor line
const ABSENT_X = -200;                         // off-screen X for absent stations

The values 48, 71, 20, 75, 42, and -200 all come directly from the prototype. INPUT_OVERHANG accounts for the input artifact stack plus spacing; OUTPUT_OVERHANG accounts for the output artifact's half-width. RAIL_OVERSHOOT matches the prototype's visibleStationRange().first - 75 rail extent. GROUND_LINE_OFFSET matches the prototype's GROUND_Y + 42 ground line.

Step 1: Resolve visible stations

If compact mode:
  visibleIndices = indices where stations[i].absent is not true
  If visibleIndices is empty → special case (see "Edge cases" below — return early)
Else:
  visibleIndices = all indices [0, 1, ..., stations.length - 1]

Step 2: Compute station positions via layoutStations

This is a direct port of the prototype's layoutStations(phaseIndices). Extract it as a private helper.

function layoutStations(
  stations: readonly StationLayoutEntry[],
  indices: readonly number[],
): { positions: number[]; platformWidth: number }

Algorithm:

Use push() throughout — do not index-assign into result arrays or read from intermediate arrays by index. This avoids number | undefined type errors from noUncheckedIndexedAccess. The established pattern in this codebase (see platform-layout.ts) is to accumulate arrays via push() and carry values forward in local variables.

leftExtents: number[] = []
rightExtents: number[] = []

For each index in indices:
  agentCount = max(stations[index].agentCount, 1)
  agentHalfWidth = (agentCount - 1) * AGENT_SPACING / 2
  Push (agentHalfWidth + INPUT_OVERHANG) onto leftExtents
  Push (agentHalfWidth + OUTPUT_OVERHANG) onto rightExtents

positions: number[] = []
cursor = LAYOUT_MARGIN

For k from 0 to indices.length - 1:
  leftExt = leftExtents[k]  // known non-undefined: k < leftExtents.length
  rightExt = rightExtents[k]
  If k === 0:
    stationX = cursor + leftExt
  Else:
    stationX = Math.round(cursor + STATION_GAP + leftExt)
  Push stationX onto positions
  cursor = stationX + rightExt

platformWidth = cursor + LAYOUT_MARGIN

Return { positions, platformWidth }

The leftExtents[k] and rightExtents[k] reads are safe because k is bounded by the loop over indices, so both arrays have exactly indices.length entries. Use non-null assertions (!) or narrow with a guard if the type checker cannot infer this.

Step 3: Build the station X lookup array

Create a number[] of length stations.length.

If compact mode:
  Initialize all entries to ABSENT_X
  For each (k, originalIndex) in visibleIndices:
    stationPositions[originalIndex] = positions[k]
Else:
  stationPositions = positions (one-to-one mapping)

Step 4: Determine rail/ground extent values

At this point visibleIndices is non-empty (the empty case was handled with an early return in Step 1).

firstVisibleOriginalIndex = visibleIndices[0]  // safe: non-empty
firstVisibleX = stationPositions[firstVisibleOriginalIndex]
lineX1 = firstVisibleX - RAIL_OVERSHOOT
lineX2 = platformWidth - PLATFORM_RIGHT_INSET

Define a constant PLATFORM_RIGHT_INSET = 20 for the right edge value. This matches the prototype's PLATFORM_W - 20 right extent.

Step 5: Compute bounds

bounds = {
  minX: 0,
  maxX: platformWidth,
  minY: 0,
  maxY: CANVAS_H,
}

Step 6: Construct and return the result object

Return an object literal implementing CatwalkLayoutResult with closures over the computed values:

stationX(index)

Return stationPositions[index]

Throw a RangeError if index is out of range.

agentPosition(stationIndex, slotIndex, agentCount)

Port of the prototype's agentX():

cx = stationPositions[stationIndex]
effectiveCount = max(agentCount, 1)
totalWidth = (effectiveCount - 1) * AGENT_SPACING
x = cx - totalWidth / 2 + slotIndex * AGENT_SPACING
y = GROUND_Y

Return { x, y }

Note: agentCount is the total number of agents at this station (not the count from the config — the caller passes it so the scene can override dynamically). slotIndex is zero-based.

orchestratorPosition(stationIndex)

Return { x: stationPositions[stationIndex], y: CATWALK_Y }

chuteEndpoints(stationIndex, slotIndex, agentCount)

The chute drops vertically from below the catwalk to above the ground, aligned with the agent's X position:

agentPos = agentPosition(stationIndex, slotIndex, agentCount)

Return {
  topX: agentPos.x,
  topY: CHUTE_TOP,
  botX: agentPos.x,
  botY: CHUTE_BOT,
}

The chute is a straight vertical line, so topX === botX. The return type uses separate fields to allow future slanted chutes without changing the interface.

gatePosition(leftStation, rightStation)

x = (stationPositions[leftStation] + stationPositions[rightStation]) / 2
y = CATWALK_Y

Return { x, y }

The gate sits on the catwalk midway between two station centers. Typically called with consecutive station indices (gatePosition(i, i + 1)), but accepting arbitrary indices to support compact mode where the "adjacent" visible stations may not be consecutive.

railEndpoints()

Return { x1: lineX1, x2: lineX2, y: CATWALK_Y }

groundEndpoints()

Return { x1: lineX1, x2: lineX2, y: GROUND_Y + GROUND_LINE_OFFSET }

bounds

Return the precomputed bounds object.

platformWidth

Return the computed platformWidth value.

Edge cases

All stations absent + compact mode

When compact is true and every station is absent, visibleIndices is empty. Handle this with an early return at the end of Step 1, before Steps 2–5 run:

• platformWidth = 2 * LAYOUT_MARGIN (empty layout with only margins)
• All stationX values are ABSENT_X
• lineX1 = LAYOUT_MARGIN - RAIL_OVERSHOOT (25)
• lineX2 = platformWidth - PLATFORM_RIGHT_INSET (180)
• bounds = { minX: 0, maxX: platformWidth, minY: 0, maxY: CANVAS_H }

Methods like agentPosition, orchestratorPosition, chuteEndpoints will use ABSENT_X as their X basis since they delegate through stationX.

Single station

The algorithm works unchanged — positions has one entry, platformWidth = LAYOUT_MARGIN + leftExtent + rightExtent + LAYOUT_MARGIN.

Zero agent count

A station with agentCount: 0 is treated as agentCount: 1 for spacing (matching prototype behavior via Math.max(agentCount, 1)). This prevents degenerate zero-width stations.

Test cases

Use describe/it with Vitest. Import computeCatwalkLayout and test through the returned result object.

All assertions must be relational — check structural properties, minimum distances, symmetry, ordering, and expected artifacts. Do not assert concrete pixel values that would need updating every time a constant or formula is refined.

1. Default layout (all 7 stations, standard agent counts)

const config: CatwalkLayoutConfig = {
  stations: [
    { agentCount: 1 },  // architecture
    { agentCount: 1 },  // planning
    { agentCount: 1 },  // implementation
    { agentCount: 4 },  // review
    { agentCount: 1 },  // simplifier
    { agentCount: 1 },  // holistic
    { agentCount: 0 },  // summary (no agents)
  ],
};

Verify:

• stationX(0) equals LAYOUT_MARGIN + INPUT_OVERHANG (asserted by formula, not a hard-coded number)
• Station positions are monotonically increasing: stationX(i + 1) > stationX(i) for all i in 0–5
• platformWidth is positive and equals stationX(6) + OUTPUT_OVERHANG + LAYOUT_MARGIN (relational check)
• Each consecutive pair satisfies: stationX(k + 1) === Math.round(stationX(k) + rightExtentOf(k) + STATION_GAP + leftExtentOf(k + 1)) — verifiable by re-deriving the extents from the agent counts

2. Agent positions within a station

Using the review station (4 agents) from the default layout:

• agentPosition(3, 0, 4) — leftmost agent
• agentPosition(3, 3, 4) — rightmost agent
• Verify agents are spread symmetrically around stationX(3): the midpoint of the leftmost and rightmost agent X values equals stationX(3)
• Verify spacing between consecutive agents equals AGENT_SPACING: agentPosition(3, k + 1, 4).x - agentPosition(3, k, 4).x === AGENT_SPACING for k = 0, 1, 2
• Verify all agents have y === GROUND_Y

3. Single-agent station

• agentPosition(0, 0, 1).x equals stationX(0) (agent is centered on station)
• agentPosition(0, 0, 1).y === GROUND_Y

4. Orchestrator position

• orchestratorPosition(i).x === stationX(i) for all valid i
• orchestratorPosition(i).y === CATWALK_Y for all valid i

5. Chute endpoints

• chuteEndpoints(i, s, n).topY === CHUTE_TOP for all valid chutes
• chuteEndpoints(i, s, n).botY === CHUTE_BOT for all valid chutes
• chuteEndpoints(i, s, n).topX === chuteEndpoints(i, s, n).botX (vertical chute)
• Chute X aligns with agent X: chuteEndpoints(i, s, n).topX === agentPosition(i, s, n).x
• CHUTE_BOT > CHUTE_TOP (chute runs downward)

6. Gate position

• gatePosition(0, 1).x equals (stationX(0) + stationX(1)) / 2 (midpoint)
• gatePosition(0, 1).y === CATWALK_Y

7. Rail and ground endpoints

• railEndpoints().y === CATWALK_Y
• groundEndpoints().y === GROUND_Y + GROUND_LINE_OFFSET
• Both endpoints share the same x1 and x2: railEndpoints().x1 === groundEndpoints().x1 and .x2 === .x2
• x1 === stationX(0) - RAIL_OVERSHOOT
• x2 === platformWidth - PLATFORM_RIGHT_INSET
• x2 > x1 (lines have positive extent)

8. Bounds

• bounds.minX === 0
• bounds.maxX === platformWidth
• bounds.minY === 0
• bounds.maxY === CANVAS_H

9. Compact mode — absent stations removed

const config: CatwalkLayoutConfig = {
  stations: [
    { agentCount: 1, absent: true },   // architecture — absent
    { agentCount: 1, absent: true },   // planning — absent
    { agentCount: 1 },                 // implementation
    { agentCount: 4 },                 // review
    { agentCount: 1 },                 // simplifier
    { agentCount: 1 },                 // holistic
    { agentCount: 0 },                 // summary
  ],
  compact: true,
};

Verify:

• stationX(0) === ABSENT_X (absent station is off-screen)
• stationX(1) === ABSENT_X (absent station is off-screen)
• stationX(2) equals LAYOUT_MARGIN + INPUT_OVERHANG (compact re-indexes; first visible station is placed at margin + left extent)
• Visible station positions are monotonically increasing: stationX(2) < stationX(3) < stationX(4) < stationX(5) < stationX(6)
• platformWidth is less than the equivalent non-compact layout's platformWidth (removing two stations makes the canvas narrower)
• railEndpoints().x1 === stationX(2) - RAIL_OVERSHOOT (rail starts relative to the first visible station)

10. Compact mode — no absent stations

When compact is true but no stations are absent, the result should be identical to non-compact mode: all stationX(i) values and platformWidth are equal.

11. Non-compact mode with absent stations

When compact is false (or omitted) and stations are marked absent, all stations still receive normal positions. The absent flag has no effect on layout. Verify that stationX(0) in non-compact mode with absent: true on station 0 matches stationX(0) in non-compact mode without the flag.

12. All stations absent + compact mode

const config: CatwalkLayoutConfig = {
  stations: Array(7).fill({ agentCount: 1, absent: true }),
  compact: true,
};

Verify:

• platformWidth === 2 * LAYOUT_MARGIN
• All stationX(i) === ABSENT_X for i = 0..6

13. Variable reviewer counts

Test with 1, 2, 3, and 4 agents at the review station (station index 3). Verify:

• platformWidth grows monotonically as agent count increases (wider station → wider canvas)
• All station positions at indices 4–6 shift right as the review station grows (downstream stations are pushed out)
• Agent positions within the review station are symmetric around stationX(3): midpoint of leftmost and rightmost agent X equals stationX(3)
• For 1 agent: agentPosition(3, 0, 1).x === stationX(3)

14. Single station

const config: CatwalkLayoutConfig = {
  stations: [{ agentCount: 1 }],
};

Verify:

• stationX(0) === LAYOUT_MARGIN + INPUT_OVERHANG (relational: first station placed at margin + left extent)
• platformWidth === stationX(0) + OUTPUT_OVERHANG + LAYOUT_MARGIN (relational)
• agentPosition(0, 0, 1).x === stationX(0)

15. Determinism

Call computeCatwalkLayout twice with the same config. Verify results are identical (same positions, same platformWidth).

16. Range errors

• stationX(-1) throws RangeError
• stationX(stations.length) throws RangeError

Risks

• Add shared artifact color constants and catwalk dimension/timing constants #177 dependency: If the constants file doesn't exist when implementation begins, inline the constants temporarily (see "Dependencies" above).
• Prototype drift: The prototype's scenarios.js is the canonical algorithm. If the prototype changes on branch 162 after this plan is written, the implementation should follow the latest prototype.

Non-goals

• No Excalibur imports or rendering logic
• No animation or timing
• No scene config types (CatwalkSceneConfig is Define CatwalkSceneConfig types and implement run-to-catwalk mapper #179)
• No mapper logic (run-to-catwalk.ts is Define CatwalkSceneConfig types and implement run-to-catwalk mapper #179)

Changes from original

Finding	Resolution
X1: noUncheckedIndexedAccess incompatibility in layoutStations pseudocode	Rewrote the layoutStations pseudocode to use push() throughout and carry values in local variables, avoiding index reads on intermediate arrays. Added explicit guidance to use non-null assertions or guards where the type checker cannot infer bounds safety. Noted the established push()-based pattern from platform-layout.ts.
X2: Step 4 formula for lineX1 is contradictory in the all-absent edge case	Added an explicit early-return instruction at the end of Step 1 for the empty visibleIndices case. Clarified in Step 4 that visibleIndices is guaranteed non-empty at that point. The edge case section now states it short-circuits before Steps 2–5.
X3: Dependency path written inconsistently	Updated the constants file path in the "Dependencies" section to include the packages/factory/ prefix, matching the full path format used in the "File" section and the #177 plan.
C1: Test cases use concrete expected values — no guidance on approach	Replaced all hard-coded pixel value assertions in the test cases with relational assertions: symmetry checks, monotonicity checks, formula-based equality (e.g., stationX(0) === LAYOUT_MARGIN + INPUT_OVERHANG expressed as a computed formula check, not a literal number), and structural properties. Added a preamble to the "Test cases" section stating the relational-only rule.