Catwalk milestone 3: Chute animations, carried artifacts, code badge

[williamthorsen]

Catwalk milestone 3: Chute animations, carried artifacts, code badge

Problem

Artifacts appear at stations via instant fade-in, with no visual connection between producing and consuming stations. The orchestrator moves between stations but carries nothing — there's no visual representation of artifact delivery, fix shuttles, or iteration state.

Context

Milestones 1–2 established the actor system (sprite sheets, animated state transitions, diff-driven updates) and layout engine. The types already include carriedArtifacts: CarriedArtifactConfig[] and codeBadge on OrchestratorConfig, currently unused. CHUTE_DURATION (600ms) is defined. The existing applyDiff() fires all animations simultaneously — M3 requires sequenced choreography.

Solution

Implement a five-step artifact delivery animation using a promise-based choreography queue:

1. Produce — artifact fades in at producing station (existing behavior)
2. Ascend — FlyingArtifactActor rises up the origin chute (600ms)
3. Pick up — orchestrator shows carried artifact badge, begins walking
4. Walk — orchestrator slides to destination station (distance-based)
5. Descend + land — FlyingArtifactActor drops down destination chute (600ms), then auto-removes

This pattern is symmetric: forward delivery (coder → review) and fix shuttle (review → coder) use identical mechanics with reversed direction.

New components:

• FlyingArtifactActor — temporary actor with ascend()/descend() returning Promises
• OrchestratorActor extensions — setCarriedArtifacts() and setCodeBadge() rendering children that travel with the orchestrator
• ChuteChoreographer — promise-based sequencer that chains animation steps from a diff

Code badge: Shows iteration count (v2, v3) below the orchestrator sprite when implementation has been re-entered (iteration > 1). Derived from artifact iteration data in CanonicalRunStatus.

Differ extensions: Add carriedChanged and codeBadgeChanged to OrchestratorDiff.

Acceptance criteria

• Artifacts visually ascend the origin station's chute when the orchestrator picks them up
• Orchestrator displays carried artifacts as trailing badges while walking
• Artifacts visually descend the destination station's chute on delivery
• FlyingArtifactActors are temporary — auto-removed after animation completes
• Fix shuttle: orchestrator walks leftward from review to coder, carrying fix artifacts
• Code badge appears below orchestrator showing iteration count when iteration > 1
• Animation steps are sequenced (ascend → pick up → walk → descend), not simultaneous
• Existing diff-driven updates (gates, agent states) continue to work alongside choreography
• All new actors and choreographer logic have unit tests

[williamthorsen]

Insight: Descend station design tension

During the M3 review cycle, the Phase 4 core reviewer and Phase 4b holistic reviewer gave contradictory recommendations about which station the descend animation should target:

• Core reviewer (Phase 4): Descend should use the origin station to match where addArtifact places the permanent artifact (at artifact.stationIndex, which is the producing station).
• Holistic reviewer (Phase 4b): Descend should use the destination station per the ticket spec: "Artifacts visually descend the destination station's chute on delivery."

Resolved by applying the authority hierarchy: ticket spec wins. The descend animation now targets the destination station. The visual discontinuity (artifact descends at destination but permanent artifact renders at origin) is a known limitation of the artifact placement model — the mapper determines stationIndex based on the producing station, and changing that would require wider mapper changes.

This tension may resurface if the catwalk evolves to show artifact ownership at consuming stations.