Replace geometric placeholders with tileset rendering

[williamthorsen]

Problem

The Excalibur OfficeScene renders agents as colored circles, artifacts as colored rectangles, and zones as tinted rectangles. The data pipeline is fully built (mapper, differ, transition planner, position resolver) but the rendering layer uses geometric placeholders. The static prototypes from #307 demonstrate that the LimeZu tilesets produce a warm, readable office visualization. This issue replaces placeholders with actual tileset sprites.

Relevant considerations

• Asset source: LimeZu Modern Office Revamped v1.2 (furniture spritesheet, 16×53 tiles) and Modern Interiors (room builder sheets, character idle sprites). Licensed for distribution. Assets should be copied into the repo at office/sprites/assets/ (~300KB total).
• Established pattern: The catwalk visualization demonstrates the sprite loading approach: Vite asset imports → ImageSource → SpriteSheet → Sprite, with a singleton cache in a dedicated loader module.
• Existing pipeline: CanonicalRunStatus → mapRunToLogicalScene() → LogicalSceneState → mapLogicalToOffice() → OfficeSceneConfig → diffOfficeConfigs() → OfficeDiff. This pipeline stays unchanged — only the rendering calls change.
• Furniture from spritesheet regions: The v8 prototype demonstrated that multi-tile composites (orchestrator desk 5×4, coder desk 2×2, rear-facing monitors 1×2) must be extracted as regions from the full spritesheet, not just the 64×96 singles.
• Character directions: Direction 3 (up/facing wall) for desk workers at wall-mounted displays. Direction 0 (down/facing camera) for the orchestrator and reviewers who stand behind their desks.
• Design skill: .agents/skills/office-visual-design/SKILL.md encodes palette, tile coordinates, wall construction, composition principles, and quality rubric.

Proposed solution

1. Copy tileset assets into office/sprites/assets/ — room builder sheets (floors, walls, shadows), the full office furniture spritesheet, 12 furniture singles, and 7 character idle sprites.
2. Create sprite loader (office-sprite-loader.ts) following the catwalk singleton cache pattern. Loads all sheets and singles via ImageSource with pixel filtering.
3. Create sprite definitions (sprite-definitions.ts) with tile source coordinates, furniture manifest (position + spritesheet region for each item), and character-to-role mapping.
4. Create OfficeCanvas.tsx React wrapper matching CatwalkCanvas.tsx — hosts the Excalibur engine and bridges React state to OfficeScene via updateStatus(status).
5. Rewrite OfficeScene.ts rendering layer — draw tiled background (floors, walls, shadows, doorways) on a single Canvas actor, place furniture sprites from the manifest, render characters from idle sprite sheets. Keep the existing data pipeline unchanged.
6. Register office in the visualization registry.

Acceptance criteria

• Tiled floor, wall, and shadow rendering from LimeZu tile sheets (cream floors, gray transition strip, two-row north walls with doorway gaps, floor shadows)
• Furniture sprites placed at workstation positions matching the v8 prototype layout — including multi-tile spritesheet regions (orchestrator desk, coder desk, rear-facing reviewer monitors)
• Character idle sprites replace colored circles (Alex=architect, Amelia=planner, Dan=coder, Bob/Ash/Rob=reviewers, Adam=orchestrator)
• OfficeCanvas.tsx registered in registry.ts, accessible via ?vis=office
• Scene updates correctly when run state changes (agents appear/disappear at assigned slots)
• Existing adapter pipeline tests continue to pass (pnpm --filter factory test)
• No type errors (pnpm --filter factory typecheck)

Out of scope

• Animation and transitions (Animate transitions and bring the office to life #311)
• Thought bubbles, HUD overlays (Animate transitions and bring the office to life #311)
• Walk cycles and character animation states (Animate transitions and bring the office to life #311)
• Artifact sprites (keep colored rectangles for now)
• Spritesheet region support in the drag editor (Create reusable sprite placement editor for tileset prototypes #312)
• Display slots (wall-mounted displays are static furniture in the sprite manifest, not slot-based entities)

Depends on

• Implement office visualization with React canvas and animation #307 (zone definition updates, design skills) — merged

Guided by

.agents/skills/office-visual-design/SKILL.md

[williamthorsen]

Prototyping round: visual design

Before implementing #310, run a competing-prototypes round to converge on visual quality. Each agent produces a self-contained HTML prototype using the established build-*.cjs pattern.

Instructions for the session

Read issue #310 and its parent #307. Read the visual design skill at .agents/skills/office-visual-design/SKILL.md. Read the current refined prototype build script at ~/repos/vaults/code-artifacts/projects/codeassembly/tickets/307/build-canvas-refined.cjs — this is the baseline to improve upon.

Dispatch 3 agents in parallel, each with a different lens (see below). Every agent receives:

1. The full office-visual-design skill content
2. The build-canvas-refined.cjs source as the starting point
3. The tileset base path: ~/Library/Mobile Documents/com~apple~CloudDocs/Resources/Tilesets/
4. The layout constants: prep (cols 1-11, rows 0-11), workshop (cols 13-35, rows 0-11), transition strip (row 12), info panel placeholder (cols 1-17, rows 13-21), governor's office (cols 19-35, rows 13-21)
5. Access to the tile picker at ~/repos/vaults/code-artifacts/projects/codeassembly/tickets/293/tile-picker.html for browsing available tiles
6. Instruction to explore the tileset directories (4_Modern_Office_singles/32x32/ has 152+ furniture PNGs, 2_Characters/Old/Single_Characters_Legacy/32x32/ has 20+ characters) and make deliberate choices rather than reusing the baseline's selections

Each agent must:

• Output a build script (build-vis-{lens}.cjs) and run it to produce vis-{lens}.html
• Output to ~/repos/vaults/code-artifacts/projects/codeassembly/tickets/307/
• Write a brief rationale (10-15 lines in a comment at the top of the build script) explaining their choices
• Use only idle standing sprites (32x64), direction 0 (facing camera) for all agents except those at wall-mounted displays (direction 3)
• Include thought bubbles and agent labels as HTML overlays
• Keep the layout grid identical — the spatial structure is settled; only the visual treatment varies

Lenses

Lens A: Furniture curator. Your job is to find the right furniture. Browse every PNG in 4_Modern_Office_singles/32x32/ and 1_Interiors/32x32/. The baseline picked items hastily — you should find better desks, monitors, chairs, shelves, and room accessories. Evaluate each piece for how it reads at 32px scale and whether it tells a story about the room's purpose. Prep should feel analytical (boards, planning tools). Workshop should feel productive (multiple screens, work surfaces). Governor's office should feel like a command center (dashboards, delivery surface, status displays). Aim for 15-20 distinct furniture items across the three rooms.

Lens B: Atmosphere and texture. Your job is to make the rooms feel inhabited. Explore different floor tile variants (the baseline uses a single cream tile everywhere — are there better options? carpet vs hardwood vs tile per room?). Try different wall tile rows from the sheet. Add floor details (rugs, mats, cable runs if available). Vary the visual weight between rooms — prep should feel quieter than the busy workshop. Use subtle differences in floor or wall treatment to give each room its own character without breaking the unified palette.

Lens C: Composition and negative space. Your job is to make the layout feel natural. The baseline places furniture in a mechanical grid pattern. Rearrange items within each room for better visual rhythm: cluster workstations into natural groupings, leave breathing room for the orchestrator's walking paths, create visual landmarks that help the eye navigate. Consider asymmetry — real offices aren't symmetric. Place decorative items (plants, bookshelves) to soften edges and fill dead corners without cluttering work areas. The viewer should feel like they're looking at a place someone designed, not a tile editor output.

[williamthorsen]

Implementation plan (v2 — refined)

Context

The office visualization (packages/factory/src/client/visualizations/office/) has a fully built data pipeline (mapper, differ, transition planner, position resolver) but renders everything as colored circles and rectangles. Issue #310 replaces these with LimeZu tileset sprites — tiled floors/walls, furniture, and character idle sprites — so the office looks like the prototypes in tickets/307/.

The catwalk visualization establishes the pattern: Vite asset imports → ImageSource → SpriteSheet → Animation, all in a self-contained sprite loader module. For the office loader, character idle sheets require SpriteSheet.getSprite(col, row) (a synchronous Sprite extractor) rather than Animation.fromSpriteSheetCoordinates, since the office uses static directional poses rather than animated states.

Files to create

1. Tileset assets — office/sprites/assets/

Copy these PNGs into packages/factory/src/client/visualizations/office/sprites/assets/.

Tileset base path: /Users/william/Library/Mobile Documents/com~apple~CloudDocs/Resources/Tilesets/

Room builder sheets — from moderninteriors-win/1_Interiors/32x32/Room_Bulder_subfiles_32x32/:

• Room_Builder_Floors_32x32.png (71KB)
• Room_Builder_Walls_32x32.png (46KB)
• Room_Builder_Floor_Shadows_32x32.png (3KB)

Office furniture sheet — from Modern_Office_Revamped_v1.2/2_Modern_Office_Black_Shadow/:

• Modern_Office_Black_Shadow_32x32.png (110KB) — full 16×53 tile sheet with all furniture including multi-tile composites

Furniture singles (64×96 each) — from Modern_Office_Revamped_v1.2/4_Modern_Office_singles/32x32/:

• Modern_Office_Singles_32x32_100.png → key plant100
• Modern_Office_Singles_32x32_113.png → key certificate113
• Modern_Office_Singles_32x32_114.png → key certificate114
• Modern_Office_Singles_32x32_116.png → key diploma116
• Modern_Office_Singles_32x32_141.png → key deskLamp141
• Modern_Office_Singles_32x32_171.png → key chartBoard171
• Modern_Office_Singles_32x32_172.png → key analysisBoard172
• Modern_Office_Singles_32x32_175.png → key dashboard175
• Modern_Office_Singles_32x32_183.png → key workshopDesk183
• Modern_Office_Singles_32x32_186.png → key prepDesk186
• Modern_Office_Singles_32x32_205.png → key modernShelf205
• Modern_Office_Singles_32x32_206.png → key execShelf206

Character idle sprites — from moderninteriors-win/2_Characters/Old/Single_Characters_Legacy/32x32/:

• Adam_idle_32x32.png (orchestrator)
• Alex_idle_32x32.png (architect)
• Amelia_idle_32x32.png (planner)
• Bob_idle_32x32.png (code reviewer)
• Ash_idle_32x32.png (silent failure reviewer)
• Dan_idle_32x32.png (coder)
• Rob_idle_32x32.png (test reviewer)

Total: 23 files, ~430KB.

2. office/sprites/sprite-sheet-urls.ts

Vite asset imports for all PNGs. Pattern: import floorsUrl from './assets/Room_Builder_Floors_32x32.png'.

Export a typed record mapping asset keys to URLs.

3. office/sprites/sprite-definitions.ts

Constants for tile coordinates and furniture placement:

• Tile source coordinates: floor cream (96,0), floor gray (288,0), wall upper (32,256), wall baseboard (32,288), shadow (0,0) on the shadow sheet
• Character frame layout: 4 columns (down=0, left=1, right=2, up=3), single idle row; frame size 32×64. Extract with spriteSheet.getSprite(direction, 0).
• Furniture manifest: static array of FurnitureItem entries for each zone's decoration. Each entry has label, position: { tx, ty } (in tile units, may be fractional), and either:
  • asset: a key into the single-file image map (64×96 furniture singles drawn with Sprite.from(imageSource))
  • region: { sheet: 'officeSheet', sx, sy, sw, sh } for multi-tile composites extracted from the full office sheet

The furniture manifest content, derived from the v8 prototype (tickets/307/visual-design/build-vis-composition.cjs):

// ── Prep area: wall ──
{ label: 'Analysis board',   asset: 'analysisBoard172',  tx: 3.56, ty: -1.06 },
{ label: 'Certificate 1',    asset: 'certificate113',    tx: 7.47, ty: -1.03 },
{ label: 'Diploma',          asset: 'diploma116',        tx: 8.47, ty: -1.03 },
// ── Prep area: furniture ──
{ label: 'Desk (architect)', asset: 'prepDesk186',       tx: 2,    ty: 4 },
{ label: 'Lamp (architect)', asset: 'deskLamp141',       tx: 2,    ty: 3.53 },
{ label: 'Desk (planner)',   asset: 'prepDesk186',       tx: 5,    ty: 5 },
{ label: 'Lamp (planner)',   asset: 'deskLamp141',       tx: 5,    ty: 4.59 },
{ label: 'Plant (prep NW)',  asset: 'plant100',          tx: 1,    ty: 1 },
{ label: 'Plant (prep S)',   asset: 'plant100',          tx: 10.81, ty: 8.44 },
// ── Workshop: coder ──
{ label: 'Desk (coder)',     region: { sheet: 'officeSheet', sx: 32,  sy: 1120, sw: 64,  sh: 64  }, tx: 17.00, ty: 7.00 },
{ label: 'Monitors (coder)', region: { sheet: 'officeSheet', sx: 416, sy: 384,  sw: 96,  sh: 32  }, tx: 16.50, ty: 6.50 },
{ label: 'Keyboard (coder)', region: { sheet: 'officeSheet', sx: 448, sy: 448,  sw: 32,  sh: 32  }, tx: 17.50, ty: 7.50 },
{ label: 'Shelf (workshop)', asset: 'modernShelf205',    tx: 16.78, ty: 0.88 },
// ── Workshop: reviewers ──
{ label: 'Desk (Bob)',       asset: 'workshopDesk183',   tx: 27,   ty: 4 },
{ label: 'Monitor (Bob)',    region: { sheet: 'officeSheet', sx: 448, sy: 320,  sw: 32,  sh: 64  }, tx: 27.03, ty: 4.25 },
{ label: 'Desk (Ash)',       asset: 'workshopDesk183',   tx: 30.00, ty: 5.00 },
{ label: 'Monitor (Ash)',    region: { sheet: 'officeSheet', sx: 448, sy: 320,  sw: 32,  sh: 64  }, tx: 30.00, ty: 5.25 },
{ label: 'Desk (Rob)',       asset: 'workshopDesk183',   tx: 33.00, ty: 4.00 },
{ label: 'Monitor (Rob)',    region: { sheet: 'officeSheet', sx: 448, sy: 320,  sw: 32,  sh: 64  }, tx: 33.00, ty: 4.31 },
// ── Workshop: decor ──
{ label: 'Dashboard',        asset: 'dashboard175',      tx: 13.34, ty: 1.19 },
{ label: 'Plant (workshop NW)', asset: 'plant100',       tx: 15.59, ty: 1.16 },
{ label: 'Plant (workshop S)',  asset: 'plant100',       tx: 19.06, ty: 0.97 },
{ label: 'Certificate 2',    asset: 'certificate114',    tx: 23.56, ty: 12.09 },
{ label: 'Chart board',      asset: 'chartBoard171',     tx: 29.28, ty: 11.91 },
// ── Governor's office ──
{ label: 'Orchestrator desk', region: { sheet: 'officeSheet', sx: 320, sy: 0,   sw: 160, sh: 128 }, tx: 20.13, ty: 16.53 },
{ label: 'Exec shelf',        asset: 'execShelf206',     tx: 32.69, ty: 13.22 },
{ label: 'Plant (governor)',  asset: 'plant100',         tx: 34,   ty: 13 },

The singles used: plant100, certificate113, certificate114, diploma116, deskLamp141, chartBoard171, analysisBoard172, dashboard175, workshopDesk183, prepDesk186, modernShelf205, execShelf206.

• Character-to-role mapping: architecture→Alex, planning→Amelia, implementation→Dan, reviewer pool→[Bob, Ash, Rob], orchestrator→Adam

4. office/sprites/office-sprite-loader.ts

Follow the catwalk singleton cache pattern. Build sheets and extract sprites synchronously before the await, so callers can use sprites immediately after invoking the function without waiting for image data.

export async function loadOfficeSprites(): Promise<void>
export function getFloorSheet(): SpriteSheet
export function getWallSheet(): SpriteSheet
export function getShadowSheet(): SpriteSheet
export function getOfficeSheet(): SpriteSheet
export function getCharacterSprite(name: CharacterName, direction: number): Sprite
export function getSingleSprite(key: SingleAssetKey): Sprite
export function clearOfficeSpriteCache(): void  // for tests

Implementation notes:

• Create ImageSource for each sheet and furniture single with ImageFiltering.Pixel
• Build SpriteSheet.fromImageSource() synchronously with the appropriate grid dimensions:
  • Floor/wall/shadow sheets: 32×32 tiles
  • Character idle sheets: 32 wide × 64 tall per frame, 4 columns × 1 row
• For character sprites, call spriteSheet.getSprite(direction, 0) to extract a single directional Sprite
• For furniture singles (64×96 PNGs), use Sprite.from(imageSource) — each file is one sprite
• For spritesheet regions (multi-tile composites), use Excalibur's Canvas graphic to draw the region from the loaded ImageSource. Create a Canvas with the region's pixel dimensions, draw via ctx.drawImage(officeSheet.image, sx, sy, sw, sh, 0, 0, sw, sh), and assign the Canvas graphic to the furniture actor. This avoids SpriteSheet grid assumptions and handles arbitrary-sized regions cleanly
• Await all source.load() calls concurrently with Promise.all
• Reset cache on load failure so a subsequent call can retry

5. components/OfficeCanvas.tsx

React wrapper — near-identical to CatwalkCanvas.tsx and FactoryFloorCanvas.tsx:

• Implement VisualizationProps interface (status: CanonicalRunStatus) — the same contract as the other canvas components
• Create Engine with CANVAS_WIDTH_PX × CANVAS_HEIGHT_PX, DisplayMode.FitContainer
• Instantiate OfficeScene, add to engine, go to scene
• On status prop change: call scene.updateStatus(status) — passing CanonicalRunStatus directly to the scene, matching the established pattern
• Uses existing useContainerResize hook and canvas.css

Files to modify

6. office/scene/OfficeScene.ts — major rewrite

Replace the entire rendering layer. The data pipeline (updateState → mapLogicalToOffice → diffOfficeConfigs) stays unchanged.

Add updateStatus(status: CanonicalRunStatus) adapter method:

/** Accept raw CanonicalRunStatus from the canvas component, matching the catwalk/factory-floor interface. */
updateStatus(status: CanonicalRunStatus): void {
  this.updateState(mapRunToLogicalScene(status));
}

This keeps OfficeScene conformant with the canvas component pattern: the canvas calls updateStatus(status) with a CanonicalRunStatus, and the scene handles the mapping internally.

Z-ordering: Use explicit Excalibur z values on all actors to ensure correct layering regardless of insertion order:

• z: 0 — background canvas actor (floors, walls, shadows)
• z: 1 — furniture actors (desks, monitors, boards, shelves, plants)
• z: 2 — character actors (agents, orchestrator)
• z: 3 — artifact actors (colored rectangles)

Position mapping: Furniture tx/ty values are fractional tile coordinates. Convert to pixel position: x = tx * TILE_SIZE, y = ty * TILE_SIZE (where TILE_SIZE = 32). Excalibur actor positions use the actor's center by default — adjust anchor to top-left (vec(0, 0)) for tile-aligned placement.

onInitialize():

1. Call loadOfficeSprites() (async, but the scene can start rendering after the cache is populated synchronously)
2. Draw tiled background using an Excalibur Canvas graphic on a single background actor (z: 0):
   • Cream floor tiles for each room area
   • Gray tiles for transition strip and doorway openings
   • Two-row north walls (upper + baseboard) with doorway gaps
   • Floor shadows below north walls
   • Side walls as solid fills
   • Prep-workshop boundary wall
   • Info panel zone placeholder
3. Place static furniture actors (z: 1) from the manifest (desks, monitors, boards, plants, shelves)
4. Position camera

updateState():

• Same pipeline as current: map → diff → apply
• placeAgent(): replace Circle with character Sprite from getCharacterSprite(name, direction). Direction 3 (up/facing wall) for desk workers, direction 0 (down/facing camera) for orchestrator and behind-desk reviewers.
• placeOrchestrator(): replace magenta Circle with Adam sprite, direction 0
• placeArtifact(): keep as colored Rectangle for now (artifact sprites are a stretch goal, not core Replace geometric placeholders with tileset rendering #310)

7. office/__tests__/office-scene.test.ts — update for rewrite

The existing tests count actors based on the geometric zone rendering (9 actors for 3 zones × 3 actors each). After the rewrite, onInitialize produces:

• 1 background canvas actor (replaces 9 zone geometry actors)
• N furniture actors from the manifest (26 items from the v8 manifest above)

The test mock must be updated to include the new Excalibur API surface used by the rewritten scene:

• Add Canvas class mock (used for the background actor's graphic)
• Add ImageSource, SpriteSheet, Sprite mocks (used by loadOfficeSprites)
• Mock loadOfficeSprites from ../sprites/office-sprite-loader.js so tests don't attempt real image loads
• Update actor-count assertions to reflect the new structure: 1 background + 26 furniture actors = 27 on initialize; downstream counts adjust accordingly

The catwalk-sprite-loader.test.ts demonstrates the required mock pattern for ImageSource, SpriteSheet, and Animation — use it as the reference for the office loader mock.

8. visualizations/registry.ts — add entry

import { OfficeCanvas } from '../components/OfficeCanvas.js';
// ...
office: OfficeCanvas,

Out of scope

• Animation/transitions (Animate transitions and bring the office to life #311 — the transition planner is wired but not executed)
• Thought bubbles and HUD (Animate transitions and bring the office to life #311)
• Walk cycles and character animation states (Animate transitions and bring the office to life #311)
• Artifact sprites (keep colored rectangles for now)
• Spritesheet region support in the drag editor (Create reusable sprite placement editor for tileset prototypes #312)
• Display slots (SlotType, ZoneDefinition, zone-definitions.ts — not needed for Replace geometric placeholders with tileset rendering #310 or Animate transitions and bring the office to life #311; wall-mounted displays are static furniture in the sprite manifest)

Verification

1. pnpm --filter factory typecheck — no type errors
2. pnpm --filter factory test — all tests pass, including the updated office-scene.test.ts
3. pnpm --filter factory dev — start dev server, navigate to ?vis=office, confirm:
   • Tiled floor and wall background renders correctly
   • Furniture sprites visible at workstation positions
   • Character sprites appear at agent positions (not colored circles)
   • Orchestrator is Adam facing camera in governor's office
   • Scene updates when run state changes (agents appear/disappear)

[williamthorsen]

Insight: Sprite loader synchronous cache population strategy

The office sprite loader's doLoad() function populates the module-level cache object synchronously before its first await (the Promise.all for image loads). This allows OfficeScene.onInitialize() to call getter functions like getFloorSheet() and getCharacterSprite() immediately after a fire-and-forget loadOfficeSprites() call — without awaiting the result.

This works because JavaScript guarantees the synchronous portion of an async function completes before the caller resumes. The ImageSource, SpriteSheet, and Sprite objects are lazy wrappers that render correctly once image data loads asynchronously in the background.

This pattern was validated during the holistic review and matches the catwalk visualization's loadAllCatwalkSprites approach. Worth preserving as a deliberate design decision if the loader is ever refactored.