Build Log

Reality Draft — untangling Copilot's PixiJS spiral, swapping in painted art

July 11, 2026

Copilot was debugging a PixiJS asset loader that was never going to fix the real bug; diagnosed three real Pixi lifecycle bugs, then reversed course to SVG <image> elements and wired in the first batch of painted scene art.

Reality DraftBug FixArchitecture ReversalArt Pipeline

real Pixi lifecycle bugs found and fixed

architecture reversed mid-session (Pixi -> SVG <image>)

scene elements swapped to painted art (bridge, cart, stranger, courier, lighthouse, fox)

pixi.js dependency remaining

Timeline

Start

Inherited a stuck Copilot session

PixiOverlay.tsx asset-loading spiral, no crash yet, just wrong visuals

+30m

Root-caused the real bug

PixiOverlay duplicated art HarborStage already drew in SVG; one image path was also just wrong

+1.5h

Rebuilt PixiOverlay properly instead of patching Copilot's version

Async app.init(), PIXI.Assets caching, camera-pan sync, rebuild-fx timeline, umbrella-flight timeline

+2h

Runtime crash: app.ticker undefined

React effect churn from a non-memoized courierPos object opened a race between two cleanup functions

+2.5h

Fixed the crash, then found the real design flaw

Sprites rendered but Pixi had no camera-pan sync — every SVG capability had to be hand re-implemented in Pixi

+2.75h

Anvil: reversed to SVG <image>

Deleted PixiOverlay.tsx and the pixi.js dependency entirely; painted PNGs render as <image> inside the existing camera group

+3.25h

Discovered the actual root cause of the visual bug

Source PNGs had no alpha channel (colorType 2) — checkerboard/solid background was baked into pixels, not real transparency

+4h

Zeb regenerated 4 of the assets with real alpha; 1 (bridge) landed at a different path

Fixed the path, verified with Playwright

+4.5h

Black-box artifact reported, traced to stale browser cache

Playwright render was clean; Zeb confirmed clean after hard reload + fresh room

+5h

Extended painted-art swap to lighthouse (beam on/off) and fox

Dog swapped too but is low-contrast against the night background; courier walk-cycle art still lacks alpha

Committed, session closed

Two known polish items logged for next session

What shipped

Diagnosed and fixed 3 real PixiJS v8 lifecycle bugs Copilot's asset-loader patching never touched: missing async app.init(), a ticker-registration race caused by non-memoized effect dependencies, and no camera-pan sync between the Pixi canvas and the SVG scene's panning coordinate system

Reversed the architecture: deleted PixiOverlay.tsx and the pixi.js dependency; painted PNGs now render as SVG <image> elements inside HarborStage's existing camera group, inheriting pan, z-order, and the existing fxStyle() CSS animation system for free

Found and fixed the actual root cause of the visual bug: all initial art assets had no alpha channel (PNG colorType 2, background baked into pixels as a checkerboard or solid color) rather than real transparency (colorType 6)

Wired stone_bridge, market_cart, stranger_map, and courier (ambient/rebuild mode) to painted art with real alpha

Extended to lighthouse (beam on/off swap driven by the existing beamOn flag) and fox (ambient/rebuild mode + Chapter1Choreography)

Kept dog on painted art in ambient mode but preserved the SVG wolf-recolor fallback (no wolf.png asset exists)

Kept the chapter-1 scripted courier on its existing animated SVG (walk-cycle CSS/SMIL animation) rather than regress it to a static image — new walk-frame assets came back without alpha

“ok, so is there a better implementation for this? maybe we got to this place and should have started somewhere else.”
— Zeb, after the third real Pixi lifecycle bug in a row