Create sprite-loading infrastructure with placeholder assets for catwalk

[williamthorsen]

Description

The catwalk visualization currently renders agents as Excalibur geometric primitives: Circle + Text for station agents, Rectangle + Text for the orchestrator. This ticket builds the sprite loading infrastructure and placeholder assets needed to transition to pixel art sprites, as designed in the parent epic #222.

The placeholder assets (simple colored-rectangle SVGs with frame-number labels) serve as a build-bridge — all code is fully functional and testable before AI-generated pixel art arrives. Swapping in real art later is a single file replacement per sprite sheet.

Current state

• StationAgentActor renders a Circle (radius 14px) with role color + text label overlay
• OrchestratorActor renders a Rectangle (~35×25px) in gold with "ORCH" text
• Background is #111111 (near-black)
• No sprite loading infrastructure exists in the catwalk visualization
• The FactoryScene (separate visualization, being discarded) has a working sprite system in packages/factory/src/client/game/sprites/ that proves the pattern

Proposed solution

2 new sprite sheets loaded via Vite static imports:

Sheet	File	Visual	Purpose
Subagent	catwalk/sprites/assets/subagent.svg	Neutral metallic (placeholder: steel gray #888899 rectangles)	Shared across all non-orchestrator roles
Orchestrator	catwalk/sprites/assets/orchestrator.svg	Distinct silhouette (placeholder: gold-tinted #CCAA44 rectangles)	Unique mobile agent

Both sheets follow the existing sprite-definitions.ts frame layout (already used by FactoryScene):

• Grid: 4 columns × 3 rows, 32×32px per frame (128×96 total)
• Frame layout: Row 0 = idle (0-1), walking (2), resting-1 (3); Row 1 = working (0-2), resting-2 (3); Row 2 = celebrating (0-1), concerned (2), resting-3 (3)
• Transparent backgrounds

Role differentiation: A colored Rectangle accent bar (4px tall) beneath each subagent sprite, using the existing ROLE_TYPE_COLORS palette per role type.

New modules:

• catwalk/sprites/sprite-sheet-urls.ts — maps CatwalkSpriteType ('subagent' | 'orchestrator') → Vite static asset URL
• catwalk/sprites/catwalk-sprite-loader.ts — loads sprite sheets, creates cached Excalibur Animation objects per animation state. Exports loadAllCatwalkSprites() (async init) and getAnimation(spriteType, state) (cached lookup)

Modified actors:

• StationAgentActor — replaces Circle + Text with Animation + accent bar GraphicsGroup. updateConfig() switches animation state + opacity.
• OrchestratorActor — replaces Rectangle + Text with Animation. working: true → working animation, false → idle.
• CatwalkScene — calls loadAllCatwalkSprites() in onInitialize(), background changes from #111111 to midnight blue #1a1a2e

Reused unchanged:

• sprite-definitions.ts (frame coordinates, animation durations/strategies — shared contract between code and art)
• catwalk-differ.ts, run-to-catwalk.ts, layout logic
• ArtifactActor, ChuteActor, GateActor (remain geometric primitives)

Key files to reference

File	Relevance
packages/factory/src/client/game/sprites/sprite-definitions.ts	Frame coordinates and animation config — reused as-is
packages/factory/src/client/game/sprites/agent-sprite-loader.ts	Reference implementation for the loader pattern (FactoryScene version)
packages/factory/src/client/visualizations/catwalk/actors/StationAgentActor.ts	Currently 69 lines — replace Circle+Text with sprite
packages/factory/src/client/visualizations/catwalk/actors/OrchestratorActor.ts	Currently 50 lines — replace Rectangle+Text with sprite
packages/factory/src/client/visualizations/catwalk/scene/CatwalkScene.ts	Scene init + background color
packages/factory/src/client/visualizations/catwalk/constants/dimensions.ts	AGENT_RADIUS=14 needs to become 16 for 32×32 sprites
packages/factory/src/client/visualizations/catwalk/actors/__tests__/actors.test.ts	Existing actor tests — mock pattern with vi.mock('excalibur')
packages/factory/src/client/visualizations/catwalk/scene/__tests__/CatwalkScene.test.ts	Scene tests — mocks actors module

Quality gates

Run from repo root:

• pnpm typecheck
• pnpm lint
• pnpm test
• Visual smoke test: cd packages/factory && pnpm dev → open catwalk visualization

Acceptance criteria

Must have

• 2 placeholder sprite sheets in catwalk/sprites/assets/ (128×96 SVGs, 4×3 grid of 32×32 frames, transparent backgrounds)
• sprite-sheet-urls.ts maps sprite types to Vite static asset URLs
• catwalk-sprite-loader.ts loads sheets, creates cached Animation objects per state, exports loadAllCatwalkSprites() and getAnimation()
• StationAgentActor renders sprite animation + colored accent bar (not Circle + Text)
• OrchestratorActor renders sprite animation (not Rectangle + Text)
• CatwalkScene background is #1a1a2e (midnight blue) and calls sprite loader on init
• AGENT_RADIUS and ORCH_RADIUS updated to 16 (half of 32×32 sprite)
• All existing tests pass (pnpm typecheck && pnpm lint && pnpm test)

Should have

• Accent bar uses ROLE_TYPE_COLORS[roleType] per agent
• Loader is idempotent (second loadAllCatwalkSprites() call is a no-op)
• getAnimation() throws if called before loading

Nice to have

• One-shot generator script (packages/factory/scripts/generate-placeholder-pngs.ts) for regenerating placeholders

Parent epic

#222 — Pixel art upgrade for catwalk visualization

[williamthorsen]

Implementation plan

Catwalk sprite infrastructure implementation plan

Goal: Replace catwalk geometric primitives with pixel art sprites loaded from PNG sprite sheets.

Architecture: Create a sprite loading module that loads 2 PNG sprite sheets (subagent + orchestrator) via Vite static imports, produces cached Excalibur Animation objects per state, and is consumed by refactored StationAgentActor and OrchestratorActor classes. Placeholder SVGs are generated as a build-bridge until real AI art arrives.

Tech Stack: Excalibur.js 0.32.0, Vite static imports, TypeScript, Vitest

---

Task 1: Generate placeholder sprite sheets

Generate 2 placeholder SVG files so downstream tasks have real loadable assets. These are temporary — they'll be replaced with AI-generated pixel art later.

Files:

• Create: packages/factory/src/client/visualizations/catwalk/sprites/assets/subagent.svg
• Create: packages/factory/src/client/visualizations/catwalk/sprites/assets/orchestrator.svg
• Create: packages/factory/scripts/generate-placeholder-pngs.ts (one-shot script, can be deleted after use)

Step 1: Write a Node script that generates placeholder SVGs

// packages/factory/scripts/generate-placeholder-pngs.ts
import { writeFileSync, mkdirSync } from 'node:fs';
import { join } from 'node:path';

// Simple colored-rectangle sprite sheets as placeholders.
// Each is 128x96 (4 cols × 3 rows of 32×32 frames).
// Subagent: steel gray (#888899). Orchestrator: gold-tinted (#CCAA44).

const SPRITE_SIZE = 32;
const COLS = 4;
const ROWS = 3;
const WIDTH = SPRITE_SIZE * COLS;
const HEIGHT = SPRITE_SIZE * ROWS;

function generatePlaceholderSvg(color: string, label: string): string {
  const frames: string[] = [];
  for (let row = 0; row < ROWS; row++) {
    for (let col = 0; col < COLS; col++) {
      const x = col * SPRITE_SIZE;
      const y = row * SPRITE_SIZE;
      const frameNum = row * COLS + col;
      frames.push(
        `<rect x="${x + 2}" y="${y + 2}" width="${SPRITE_SIZE - 4}" height="${SPRITE_SIZE - 4}" rx="4" fill="${color}" opacity="0.8" />`,
        `<text x="${x + SPRITE_SIZE / 2}" y="${y + SPRITE_SIZE / 2 + 3}" text-anchor="middle" font-size="8" font-family="monospace" fill="white">${label}${frameNum}</text>`,
      );
    }
  }
  return `<svg xmlns="http://www.w3.org/2000/svg" width="${WIDTH}" height="${HEIGHT}">${frames.join('')}</svg>`;
}

const outDir = join(import.meta.dirname, '../src/client/visualizations/catwalk/sprites/assets');
mkdirSync(outDir, { recursive: true });

writeFileSync(join(outDir, 'subagent.svg'), generatePlaceholderSvg('#888899', 'S'));
writeFileSync(join(outDir, 'orchestrator.svg'), generatePlaceholderSvg('#CCAA44', 'O'));

console.log('Placeholder sprite sheets written to', outDir);

Step 2: Run the script

cd packages/factory && npx tsx scripts/generate-placeholder-pngs.ts

Step 3: Verify, then commit

---

Task 2: Create sprite sheet URL module

Map sprite types to Vite static asset imports.

Files:

• Create: packages/factory/src/client/visualizations/catwalk/sprites/sprite-sheet-urls.ts
• Test: packages/factory/src/client/visualizations/catwalk/sprites/__tests__/sprite-sheet-urls.test.ts

Step 1: Write the failing test

import { describe, expect, it } from 'vitest';
import { SPRITE_SHEET_URLS } from '../sprite-sheet-urls.js';

describe('SPRITE_SHEET_URLS', () => {
  it('exports a subagent URL string', () => {
    expect(typeof SPRITE_SHEET_URLS.subagent).toBe('string');
    expect(SPRITE_SHEET_URLS.subagent.length).toBeGreaterThan(0);
  });

  it('exports an orchestrator URL string', () => {
    expect(typeof SPRITE_SHEET_URLS.orchestrator).toBe('string');
    expect(SPRITE_SHEET_URLS.orchestrator.length).toBeGreaterThan(0);
  });
});

Step 2: Run test — expected FAIL (module not found)

Step 3: Write the implementation

import subagentUrl from './assets/subagent.svg';
import orchestratorUrl from './assets/orchestrator.svg';

export type CatwalkSpriteType = 'subagent' | 'orchestrator';

export const SPRITE_SHEET_URLS: Record<CatwalkSpriteType, string> = {
  subagent: subagentUrl,
  orchestrator: orchestratorUrl,
};

Step 4: Run test — expected PASS. Commit.

---

Task 3: Create catwalk sprite loader

Build the sprite loading and caching module that converts sprite sheets into Excalibur Animation objects. This reuses sprite-definitions.ts (at packages/factory/src/client/game/sprites/sprite-definitions.ts) for frame coordinates and animation timing — the same contract used by the FactoryScene.

Files:

• Create: packages/factory/src/client/visualizations/catwalk/sprites/catwalk-sprite-loader.ts
• Test: packages/factory/src/client/visualizations/catwalk/sprites/__tests__/catwalk-sprite-loader.test.ts

Step 1: Write the failing tests

Mock Excalibur (same pattern as actors/__tests__/actors.test.ts). Key behaviors to test:

• loadAllCatwalkSprites() loads 2 image sources (subagent + orchestrator)
• Loading is idempotent (second call is no-op)
• getAnimation(spriteType, state) returns an Animation for all 6 states × 2 sprite types
• getAnimation() returns cached instances on repeat calls
• getAnimation() throws if called before loading

import { beforeEach, describe, expect, it, vi } from 'vitest';
import type { AgentAnimationState } from '../../types.js';

const mockImageSourceLoad = vi.fn().mockResolvedValue(undefined);

vi.mock('excalibur', () => {
  const MockImageFiltering = { Pixel: 'pixel' };
  class MockImageSource {
    url: string;
    constructor(url: string, _bustCache?: boolean, _filtering?: unknown) { this.url = url; }
    load = mockImageSourceLoad;
  }
  class MockSpriteSheet {
    static fromImageSource(_opts: unknown) { return new MockSpriteSheet(); }
  }
  class MockAnimation {
    static fromSpriteSheetCoordinates(_opts: unknown) { return new MockAnimation(); }
  }
  return { ImageFiltering: MockImageFiltering, ImageSource: MockImageSource, SpriteSheet: MockSpriteSheet, Animation: MockAnimation };
});

vi.mock('../sprite-sheet-urls.js', () => ({
  SPRITE_SHEET_URLS: { subagent: '/assets/subagent.svg', orchestrator: '/assets/orchestrator.svg' },
}));

const { getAnimation, loadAllCatwalkSprites, clearCatwalkSpriteCache } = await import('../catwalk-sprite-loader.js');

describe('catwalk-sprite-loader', () => {
  beforeEach(() => { clearCatwalkSpriteCache(); mockImageSourceLoad.mockClear(); });

  describe('loadAllCatwalkSprites', () => {
    it('loads image sources for both sprite types', async () => {
      await loadAllCatwalkSprites();
      expect(mockImageSourceLoad).toHaveBeenCalledTimes(2);
    });

    it('is idempotent', async () => {
      await loadAllCatwalkSprites();
      await loadAllCatwalkSprites();
      expect(mockImageSourceLoad).toHaveBeenCalledTimes(2);
    });
  });

  describe('getAnimation', () => {
    it('returns cached instances', async () => {
      await loadAllCatwalkSprites();
      expect(getAnimation('subagent', 'idle')).toBe(getAnimation('subagent', 'idle'));
    });

    it('throws if not loaded', () => {
      expect(() => getAnimation('subagent', 'idle')).toThrow();
    });

    const ALL_STATES: AgentAnimationState[] = ['idle', 'walking', 'working', 'celebrating', 'concerned', 'resting'];
    for (const state of ALL_STATES) {
      it(`returns animation for subagent ${state}`, async () => {
        await loadAllCatwalkSprites();
        expect(getAnimation('subagent', state)).toBeDefined();
      });
    }
  });
});

Step 2: Run test — expected FAIL

Step 3: Write the implementation

The loader imports frame coordinates and timing from sprite-definitions.ts, creates ImageSource → SpriteSheet → Animation per sprite type + state, and caches everything. Reference packages/factory/src/client/game/sprites/agent-sprite-loader.ts for the pattern.

Key exports:

• loadAllCatwalkSprites(): Promise<void> — async init, call once in scene
• getAnimation(spriteType: CatwalkSpriteType, state: AgentAnimationState): Animation — cached lookup
• clearCatwalkSpriteCache(): void — for tests

import { Animation, ImageFiltering, ImageSource, SpriteSheet } from 'excalibur';
import {
  CELEBRATING_DURATION, CELEBRATING_FRAME_COORDINATES, CELEBRATING_STRATEGY,
  CONCERNED_DURATION, CONCERNED_FRAME_COORDINATES, CONCERNED_STRATEGY,
  GRID_COLUMNS, GRID_ROWS,
  IDLE_DURATION, IDLE_FRAME_COORDINATES, IDLE_STRATEGY,
  RESTING_DURATION, RESTING_FRAME_COORDINATES, RESTING_STRATEGY,
  SPRITE_SIZE,
  WALKING_DURATION, WALKING_FRAME_COORDINATES, WALKING_STRATEGY,
  WORKING_DURATION, WORKING_FRAME_COORDINATES, WORKING_STRATEGY,
} from '../../../../game/sprites/sprite-definitions.js';
import type { AgentAnimationState } from '../types.js';
import { type CatwalkSpriteType, SPRITE_SHEET_URLS } from './sprite-sheet-urls.js';

const imageSourceCache = new Map<CatwalkSpriteType, ImageSource>();
const spriteSheetCache = new Map<CatwalkSpriteType, SpriteSheet>();
const animationCache = new Map<string, Animation>();
let loaded = false;

function cacheKey(spriteType: CatwalkSpriteType, state: AgentAnimationState): string {
  return `${spriteType}:${state}`;
}

function createSpriteSheet(spriteType: CatwalkSpriteType): SpriteSheet {
  const cached = spriteSheetCache.get(spriteType);
  if (cached) return cached;

  const url = SPRITE_SHEET_URLS[spriteType];
  const imageSource = new ImageSource(url, false, ImageFiltering.Pixel);
  imageSourceCache.set(spriteType, imageSource);

  const spriteSheet = SpriteSheet.fromImageSource({
    image: imageSource,
    grid: { rows: GRID_ROWS, columns: GRID_COLUMNS, spriteWidth: SPRITE_SIZE, spriteHeight: SPRITE_SIZE },
  });
  spriteSheetCache.set(spriteType, spriteSheet);
  return spriteSheet;
}

const STATE_CONFIG: Record<AgentAnimationState, {
  coordinates: ReadonlyArray<{ x: number; y: number }>; duration: number; strategy: unknown;
}> = {
  idle: { coordinates: IDLE_FRAME_COORDINATES, duration: IDLE_DURATION, strategy: IDLE_STRATEGY },
  walking: { coordinates: WALKING_FRAME_COORDINATES, duration: WALKING_DURATION, strategy: WALKING_STRATEGY },
  working: { coordinates: WORKING_FRAME_COORDINATES, duration: WORKING_DURATION, strategy: WORKING_STRATEGY },
  celebrating: { coordinates: CELEBRATING_FRAME_COORDINATES, duration: CELEBRATING_DURATION, strategy: CELEBRATING_STRATEGY },
  concerned: { coordinates: CONCERNED_FRAME_COORDINATES, duration: CONCERNED_DURATION, strategy: CONCERNED_STRATEGY },
  resting: { coordinates: RESTING_FRAME_COORDINATES, duration: RESTING_DURATION, strategy: RESTING_STRATEGY },
};

function createAnimation(spriteType: CatwalkSpriteType, state: AgentAnimationState): Animation {
  const key = cacheKey(spriteType, state);
  const cached = animationCache.get(key);
  if (cached) return cached;

  const spriteSheet = createSpriteSheet(spriteType);
  const config = STATE_CONFIG[state];
  const animation = Animation.fromSpriteSheetCoordinates({
    spriteSheet, frameCoordinates: [...config.coordinates],
    durationPerFrame: config.duration, strategy: config.strategy,
  });
  animationCache.set(key, animation);
  return animation;
}

export function getAnimation(spriteType: CatwalkSpriteType, state: AgentAnimationState): Animation {
  if (!loaded) throw new Error('Catwalk sprites not loaded. Call loadAllCatwalkSprites() first.');
  return createAnimation(spriteType, state);
}

export async function loadAllCatwalkSprites(): Promise<void> {
  if (loaded) return;
  const spriteTypes: CatwalkSpriteType[] = ['subagent', 'orchestrator'];
  const states: AgentAnimationState[] = ['idle', 'walking', 'working', 'celebrating', 'concerned', 'resting'];
  for (const spriteType of spriteTypes) {
    for (const state of states) { createAnimation(spriteType, state); }
  }
  await Promise.all([...imageSourceCache.values()].map((source) => source.load()));
  loaded = true;
}

export function clearCatwalkSpriteCache(): void {
  imageSourceCache.clear(); spriteSheetCache.clear(); animationCache.clear(); loaded = false;
}

Step 4: Run test — expected PASS. Run full suite. Commit.

---

Task 4: Refactor StationAgentActor to use sprites

Replace the Circle + Text GraphicsGroup with a sprite Animation + colored accent bar.

Files:

• Modify: packages/factory/src/client/visualizations/catwalk/actors/StationAgentActor.ts
• Modify: packages/factory/src/client/visualizations/catwalk/actors/__tests__/actors.test.ts

Step 1: Add sprite loader mock to actors.test.ts

Add near the top (after excalibur mock):

const mockAnimation = { clone: () => mockAnimation };
vi.mock('../../sprites/catwalk-sprite-loader.js', () => ({
  getAnimation: () => mockAnimation,
}));

Step 2: Update StationAgentActor tests

Key behavioral changes: updateConfig() now calls graphics.use() (to switch animation). Opacity behavior is preserved.

describe('StationAgentActor', () => {
  beforeEach(() => { mockGraphicsUse.mockClear(); });

  it('calls graphics.use() on construction', () => {
    new StationAgentActor({ id: 'a', role: 'arch', color: '#5555FF', state: 'idle' }, vec(0, 0));
    expect(mockGraphicsUse).toHaveBeenCalled();
  });

  it('sets opacity to 0.3 for idle state', () => {
    const actor = new StationAgentActor({ id: 'a', role: 'arch', color: '#5555FF', state: 'idle' }, vec(0, 0));
    expect(actor.graphics.opacity).toBe(0.3);
  });

  it('updateConfig calls graphics.use() to switch animation', () => {
    const actor = new StationAgentActor({ id: 'a', role: 'arch', color: '#5555FF', state: 'idle' }, vec(0, 0));
    mockGraphicsUse.mockClear();
    actor.updateConfig({ id: 'a', role: 'arch', color: '#5555FF', state: 'working' });
    expect(mockGraphicsUse).toHaveBeenCalled();
  });

  it('updateConfig updates opacity by state', () => {
    const actor = new StationAgentActor({ id: 'a', role: 'arch', color: '#5555FF', state: 'idle' }, vec(0, 0));
    expect(actor.graphics.opacity).toBe(0.3);
    actor.updateConfig({ id: 'a', role: 'arch', color: '#5555FF', state: 'working' });
    expect(actor.graphics.opacity).toBe(1);
    actor.updateConfig({ id: 'a', role: 'arch', color: '#5555FF', state: 'resting' });
    expect(actor.graphics.opacity).toBe(0.6);
  });
});

Step 3: Run test — expected FAIL (StationAgentActor still uses Circle)

Step 4: Rewrite StationAgentActor

import { Actor, Color, GraphicsGroup, Rectangle, vec, type Vector } from 'excalibur';
import { SPRITE_SIZE } from '../../../../game/sprites/sprite-definitions.js';
import { getAnimation } from '../sprites/catwalk-sprite-loader.js';
import type { AgentAnimationState } from '../types.js';

const ACCENT_BAR_HEIGHT = 4;
const ACCENT_BAR_WIDTH = SPRITE_SIZE - 4;

export interface StationAgentActorConfig {
  id: string; role: string; color: string; state: AgentAnimationState;
}

function opacityForState(state: AgentAnimationState): number {
  switch (state) {
    case 'idle': return 0.3;
    case 'resting': return 0.6;
    case 'working': case 'walking': case 'celebrating': case 'concerned': return 1;
    default: { const _exhaustive: never = state; return _exhaustive; }
  }
}

export class StationAgentActor extends Actor {
  private currentState: AgentAnimationState;

  constructor(config: StationAgentActorConfig, position: Vector) {
    super({ pos: position });
    this.currentState = config.state;
    this.applyGraphics(config);
  }

  updateConfig(config: StationAgentActorConfig): void {
    this.currentState = config.state;
    this.applyGraphics(config);
  }

  private applyGraphics(config: StationAgentActorConfig): void {
    const animation = getAnimation('subagent', config.state);
    const accentBar = new Rectangle({
      width: ACCENT_BAR_WIDTH, height: ACCENT_BAR_HEIGHT, color: Color.fromHex(config.color),
    });
    const group = new GraphicsGroup({
      useAnchor: false,
      members: [
        { graphic: animation, offset: vec(0, 0) },
        { graphic: accentBar, offset: vec(2, SPRITE_SIZE) },
      ],
    });
    this.graphics.use(group);
    this.graphics.opacity = opacityForState(config.state);
  }
}

Step 5: Run test — expected PASS. Commit.

---

Task 5: Refactor OrchestratorActor to use sprites

Replace the Rectangle + Text with a sprite Animation.

Files:

• Modify: packages/factory/src/client/visualizations/catwalk/actors/OrchestratorActor.ts
• Modify: packages/factory/src/client/visualizations/catwalk/actors/__tests__/actors.test.ts

Step 1: Update OrchestratorActor tests

working: true → working animation; false → idle. updateConfig() now calls graphics.use().

describe('OrchestratorActor', () => {
  beforeEach(() => { mockGraphicsUse.mockClear(); });

  it('calls graphics.use() on construction', () => {
    new OrchestratorActor({ working: true }, vec(0, 0));
    expect(mockGraphicsUse).toHaveBeenCalled();
  });

  it('sets opacity to 1.0 when working', () => {
    const actor = new OrchestratorActor({ working: true }, vec(0, 0));
    expect(actor.graphics.opacity).toBe(1);
  });

  it('sets opacity to 0.8 when idle', () => {
    const actor = new OrchestratorActor({ working: false }, vec(0, 0));
    expect(actor.graphics.opacity).toBe(0.8);
  });

  it('updateConfig calls graphics.use()', () => {
    const actor = new OrchestratorActor({ working: true }, vec(0, 0));
    mockGraphicsUse.mockClear();
    actor.updateConfig({ working: false });
    expect(mockGraphicsUse).toHaveBeenCalled();
  });

  it('updateConfig toggles opacity', () => {
    const actor = new OrchestratorActor({ working: true }, vec(0, 0));
    expect(actor.graphics.opacity).toBe(1);
    actor.updateConfig({ working: false });
    expect(actor.graphics.opacity).toBe(0.8);
  });
});

Step 2: Run test — expected FAIL

Step 3: Rewrite OrchestratorActor

import { Actor, type Vector } from 'excalibur';
import { getAnimation } from '../sprites/catwalk-sprite-loader.js';

export interface OrchestratorActorConfig { working: boolean; }

export class OrchestratorActor extends Actor {
  constructor(config: OrchestratorActorConfig, position: Vector) {
    super({ pos: position });
    this.applyGraphics(config);
  }

  updateConfig(config: OrchestratorActorConfig): void {
    this.applyGraphics(config);
  }

  private applyGraphics(config: OrchestratorActorConfig): void {
    const state = config.working ? 'working' : 'idle';
    const animation = getAnimation('orchestrator', state);
    this.graphics.use(animation);
    this.graphics.opacity = config.working ? 1 : 0.8;
  }
}

Step 4: Run test — expected PASS. Commit.

---

Task 6: Update CatwalkScene background and sprite loading

Files:

• Modify: packages/factory/src/client/visualizations/catwalk/scene/CatwalkScene.ts (lines 36-41)
• Modify: packages/factory/src/client/visualizations/catwalk/scene/__tests__/CatwalkScene.test.ts

Step 1: Add sprite loader mock to CatwalkScene.test.ts

vi.mock('../../sprites/catwalk-sprite-loader.js', () => ({
  loadAllCatwalkSprites: vi.fn().mockResolvedValue(undefined),
}));

Step 2: Update background color test

it('sets the background color to midnight blue', () => {
  const status = createMockRunStatus();
  const scene = new CatwalkScene(status);
  expect(scene.backgroundColor).toEqual(expect.objectContaining({ hex: '#1a1a2e' }));
});

Step 3: Run test — expected FAIL (still #111111)

Step 4: Update CatwalkScene

Two changes:

1. Constructor: this.backgroundColor = Color.fromHex('#1a1a2e');
2. onInitialize(): Add void loadAllCatwalkSprites(); before this.buildScene();
3. Add import: import { loadAllCatwalkSprites } from '../sprites/catwalk-sprite-loader.js';

Step 5: Run test — expected PASS. Commit.

---

Task 7: Update dimensions constants

Files:

• Modify: packages/factory/src/client/visualizations/catwalk/constants/dimensions.ts
• Modify: packages/factory/src/client/visualizations/catwalk/constants/__tests__/dimensions.test.ts

Changes:

• AGENT_RADIUS: 14 → 16 (half of 32×32 sprite)
• ORCH_RADIUS: already 16, confirm unchanged

Run the full catwalk test suite after the change — fix any tests that assert exact pixel positions derived from AGENT_RADIUS.

Commit.

---

Task 8: Full integration verification

Step 1: pnpm typecheck (repo root) — no errors

Step 2: pnpm lint (repo root) — no errors

Step 3: pnpm test (repo root) — all pass

Step 4: Visual smoke test

cd packages/factory && pnpm dev

Open catwalk visualization. Verify:

• Background is midnight blue (not black)
• Agents render as placeholder sprites (colored rectangles with frame numbers)
• Orchestrator is a distinct placeholder sprite
• Accent bars appear beneath agents in role colors
• Scene layout is correct (stations, chutes, gates, artifacts)

[williamthorsen]

Insight from orchestrated run 20260307-212824Z:

Architecture validation catches test regressions that external plans miss — changing AGENT_RADIUS from 14→16 makes it equal to ORCH_RADIUS (also 16), which broke an expect(ORCH_RADIUS).toBeGreaterThan(AGENT_RADIUS) assertion in dimensions.test.ts. The external plan didn't trace this through. Running the architecture phase even when an external plan exists proved valuable here.