claude-mcp-workflow 0.1.7 → 0.1.9

package/templates/skills/cleanup/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: cleanup
+description: Clean .claude directory data
+---
+
+## .claude directory cleanup
+
+Run steps in order. **Ask user confirmation before each step.**
+
+### Step 1: Temp data (always safe)
+
+Delete contents of (keep directories themselves):
+- `~/.claude/debug/` — session debug logs
+- `~/.claude/shell-snapshots/` — zsh state snapshots
+- `~/.claude/todos/` — task lists from past sessions
+- `~/.claude/plans/` — plan files from past sessions
+
+Show size before/after.
+
+### Step 2: Project session logs
+
+For each project in `~/.claude/projects/`:
+- **DELETE**: `*.jsonl` files (conversation logs), `UUID/` directories (session caches), `agent-*.jsonl` (subagent logs)
+- **KEEP**: `memory/` directory, `CLAUDE.md` file
+
+⚠️ This breaks `/resume` for old sessions. Warn user.
+
+Show size before/after.
+
+### Step 3: Empty project directories
+
+After step 2, list projects that have no remaining files (no memory/, no CLAUDE.md).
+Offer to remove them — they recreate automatically when Claude Code runs in that project.
+
+### Step 4: Memory audit
+
+For each remaining `memory/MEMORY.md`:
+1. Read its contents
+2. Check each entry against existing skills — is it already covered?
+3. Check if Claude already knows this without any skill
+4. Present table to user:
+
+| Entry | Duplicates? | Verdict |
+|---|---|---|
+| ... | skill X / common knowledge / project-specific | delete / keep |
+
+Only modify after user approval.
+
+### Other cleanable files
+
+Also check and report sizes of:
+- `~/.claude/history.jsonl` — conversation history (can be large)
+- `~/.claude/file-history/` — file change history
+- `~/.claude/paste-cache/` — clipboard cache
+- `~/.claude/tasks/` — task data
+
+These are less critical. Mention sizes, let user decide.

package/templates/skills/coding-skill-selector/SKILL.md

@@ -21,7 +21,7 @@ Load coding skills for files/context in this task.
 
 3. By domain (detect from imports, paths, or task description):
    - YOLO / object detection → `Skill("domain-yolo")`
-   - Pixi.js / pixi.js imports → `Skill("domain-pixi")`
+   - Pixi.js (imports from `pixi.js`, PIXI globals) → `Skill("domain-pixi")`
    - Person re-identification (ReID) → `Skill("domain-reid")`
    - Game dev (physics, precision, camera, sprites) → `Skill("domain-gamedev")`
    - OpenFL / hxcpp native target → `Skill("target-openfl-native")`
@@ -35,6 +35,7 @@ Load coding skills for files/context in this task.
    - Claude Code settings.json / hooks / permissions / plugin config → `Skill("claude-code-config")`
    - Workflow YAML in templates/ or .claude/workflows/ → `Skill("workflow-authoring")`
    - Fetching web docs / external content → `Skill("web-reading")`
+   - Verifying a web/canvas app via Playwright or a browser MCP (screenshots, captures, perf) → `Skill("browser-verify")`
 
 5. If 3+ independent files or parallel work → `Skill("task-delegation")`
 

package/templates/skills/debug-bridge-scaffold/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: debug-bridge-scaffold
+description: Meta-skill for creating debug bridges for new technologies
+---
+
+# Debug Bridge Scaffold
+
+## When to Use
+
+When you need runtime inspection of an application built with a technology that has no existing debug bridge.
+
+## Step 1: Check Existing Solutions First
+
+Before building a custom bridge, check if a standard tool already works:
+
+| Technology | Existing Solution |
+|-----------|-------------------|
+| Web/Electron/browser apps | Playwright MCP, browser DevTools |
+| Native apps with standard UI toolkit | Accessibility API MCP |
+| Any app with visible UI | Computer Use (screenshot + click) |
+| OpenFL/hxcpp | `debug-bridge-openfl` skill (already exists) |
+
+**If an existing solution covers your needs — use it. Don't build a bridge.**
+
+## Step 2: Build a Custom Bridge
+
+If no existing tool works, create an HTTP bridge following this pattern:
+
+### Architecture
+
+```
+[Background Thread] HTTP Server (127.0.0.1:PORT)
+    ↓ accept()
+[Worker Thread] Parse request → dispatch to main thread
+    ↓ runOnMainThread(fn)
+[Main Thread] Execute handler → return result
+    ↑ result via Lock/Mutex
+[Worker Thread] Send HTTP response
+```
+
+### Required Endpoints
+
+| Endpoint | Method | Purpose |
+|----------|--------|---------|
+| `/ping` | GET | Health check |
+| `/screenshot` | GET | Capture visual state → save to /tmp → return path |
+| `/shutdown` | POST | Graceful exit |
+
+### Framework-Specific Endpoints
+
+Add endpoints relevant to the technology:
+- **UI frameworks**: display tree, component inspection, event simulation
+- **Game engines**: scene graph, entity list, physics state
+- **Servers**: request log, connection pool, cache state
+
+### Implementation Checklist
+
+1. HTTP server on background thread (127.0.0.1 only — no external access)
+2. Main-thread dispatch for all UI/rendering operations
+3. JSON envelope: `{"ok": true, "data": ...}` / `{"ok": false, "error": "..."}`
+4. Conditional compilation (only in debug builds)
+5. Graceful shutdown (close socket, flush stdout, exit)
+
+## Step 3: Create a Tech-Specific Skill
+
+After building the bridge, create `~/.claude/skills/debug-bridge-<tech>/SKILL.md` with:
+
+1. Build command with the debug flag
+2. Binary path pattern
+3. All endpoints with parameters and example responses
+4. Technology-specific gotchas (threading, rendering pipeline, etc.)
+
+Register it in `coding-skill-selector` under the appropriate domain.
+
+## Step 4: Create an Interactive Debugger Agent
+
+Create `~/.claude/agents/interactive-<tech>-debugger.md` with pre-loaded skills:
+
+```yaml
+---
+name: interactive-<tech>-debugger
+description: <Tech> debug agent with visual debug bridge — ...
+tools: Read, Glob, Grep, Bash, Skill
+model: sonnet
+skills:
+  - debugging
+  - debug-bridge
+  - debug-bridge-<tech>
+  - <app-specific-interactive-debug-skill if exists>
+---
+```
+
+Body: describe the debug loop for the agent — PID tracking, separate build and run steps, timeout rules.
+
+Then update:
+1. `task-delegation` — add agent to Available Agents table and routing rules
+2. `testing` — reference the new agent for integration verification
+3. `debugging` — reference the new agent in Step 4 (Debug Bridge)

package/templates/skills/domain-gamedev/SKILL.md

@@ -12,19 +12,21 @@ See also: math skill for overflow boundaries (factorial, Fibonacci, float absorp
 | Distance from origin | ULP (precision) | Effect |
 |---------------------|-----------------|--------|
 | 100km | 0.78cm | Fine for most games |
-| 524km (≈2^19m) | 3.1cm → 6.25cm | Unity/Unreal world edge zone |
+| 524km (≈2^19m) | 3.1cm → 6.25cm | Unity world edge zone |
 | 2,097km (2^21m) | 25cm | 5m/s @ 60fps movement ABSORBED — character stops moving |
 | 8,389km (≈2^23m) | 1m | Positions snap to meter grid |
 
 **Absorption formula**: movement absorbed when `velocity * dt < ULP(position) / 2`.
 
+**Unreal gotcha**: Unreal units are CENTIMETERS, not meters — the same ULP boundaries apply per UNIT, so the metric distances above divide by 100 (e.g. 2^21 units ≈ 21km, not 2,097km).
+
 ## Deterministic Physics
 
 **DLL FPU contamination**: Direct3D, printer drivers, sound libraries can silently change FPU control word (precision/rounding mode) without restoring. Assert FPU state after every external call.
 
 **Debug vs release breaks replays**: compiler optimization level alone changes float results even with identical source. All replay participants must use identical binary.
 
-**FMA cross-platform**: PowerPC uses fused multiply-add (one rounding), Intel uses separate mul+add (two roundings) → different results from identical math. Cross-platform determinism requires controlling instruction selection.
+**FMA cross-platform**: fused multiply-add (one rounding) vs separate mul+add (two roundings) → different results from identical math. (The classic PowerPC-has-FMA / Intel-doesn't framing is stale — modern x86 has FMA3 since Haswell and ARM has FMA; today the divergence comes from whether the COMPILER contracts `a*b+c` into FMA, which varies by compiler and flags like `-ffp-contract`.) Cross-platform determinism requires controlling instruction selection.
 
 **x87 vs SSE**: x87 uses 80-bit extended precision internally → double rounding when storing to 64-bit. SSE uses exact 32/64-bit → more predictable. But SSE FTZ/DAZ modes may differ across platforms.
 
@@ -32,7 +34,7 @@ See also: math skill for overflow boundaries (factorial, Fibonacci, float absorp
 
 ## CCD Threshold (verified)
 
-Enable continuous collision detection when: `velocity × dt > object_size`.
+Enable continuous collision detection when: `velocity × dt >= object_size`.
 - 1m object at 60m/s, 60fps: travels 1m/frame → equals object size → CCD needed
 - Below threshold: discrete detection misses contacts (tunneling)
 
@@ -49,7 +51,7 @@ When a state machine waits for an animation-completion event (e.g. xstate `on.AN
 
 ## Parallax Tile Assets: Native Width = Integration Signal
 
-When integrating an artist-authored asset (e.g. `hole_flag.png`) into a row of cyclically-stitched parallax tiles (e.g. `front_1..6.png`), **check native dimensions first**.
+When integrating an artist-authored asset (e.g. `landmark.png`) into a row of cyclically-stitched parallax tiles (e.g. `tile_1..6.png`), **check native dimensions first**.
 
 - If the asset has the **same native width** as the cyclic tiles → it was designed as ONE of the tiles. Insert it into the stitch sequence at a specific anchor position. Don't overlay.
 - If the asset has **different dimensions** → it's a prop sprite meant to sit on top of the tile row (e.g. a character, tree, bush).
@@ -86,7 +88,7 @@ In most 2D engines (Pixi, Phaser, etc.), `sprite.anchor.set(ax, ay)` serves TWO
 
 **Use case**: to rotate a sprite around a specific feature of its PNG (e.g. the left rim of a hazard/foot of a character), put the anchor at that feature's normalized texture coords. Then set `sprite.position` to the world location of that feature and `sprite.rotation` — the feature stays locked in place while the rest swings.
 
-**Gotcha**: anchor and pivot are NOT separate in Pixi's Sprite. If you need them decoupled, wrap the Sprite in a Container and rotate the Container.
+**Gotcha**: in Pixi the Sprite's `anchor` drives BOTH roles — placement point and rotation origin are not independently settable through it (a separate `pivot` property exists on every Container, but changing it shifts where `position` lands too). If you need placement and rotation origin decoupled, wrap the Sprite in a Container and rotate the Container.
 
 ## Heightmap From PNG Alpha — Pre-sample Once
 
@@ -127,7 +129,7 @@ When the follow formula is `cameraY = targetScreenY − worldY × zoom` (standar
 - Ball RISES in world → `worldY` DECREASES → `cameraY` INCREASES.
 - `Math.min(flightTarget, idleCameraY)` reads as "never go ABOVE idle" in human terms, but `cameraY` for a higher ball is NUMERICALLY LARGER than the idle value — so `Math.min` pins the camera to idle and BLOCKS the follow-up. The correct direction is `Math.max` (if clamping against an upper bound on camera Y) or no clamp at all.
 
-**Verify before shipping**: plug in two concrete numbers — ball at rest and ball at peak — and compute `cameraY` for each. The one with higher `worldY` (lower on screen) should yield a MORE NEGATIVE `cameraY` if the pivot is above the horizon pivot, or more positive if below. If the clamp picks the wrong side, the camera becomes useless at exactly the moment it needs to work.
+**Verify before shipping**: plug in two concrete numbers — ball at rest and ball at peak — and compute `cameraY` for each. With `cameraY = targetScreenY − worldY × zoom`, the endpoint with the LARGER `worldY` (ball lower in the world) yields the SMALLER `cameraY`. If the clamp picks the wrong side, the camera becomes useless at exactly the moment it needs to work.
 
 **Rule**: every time you combine `screenAnchor − worldPos × zoom` with a `Math.min`/`Math.max`, write the two endpoints on paper. Don't trust the human-language reading of the clamp.
 
@@ -160,3 +162,51 @@ Sub-pixel for flat terrain, but visible (1+ px sliver) on noticeably tilted band
 | > 40ms | Unacceptable for rhythm/FPS |
 
 Humans react to audio faster than visual → audio lag more noticeable than dropped frames.
+
+## Crash / Multiplier-Game RTP (Aviator / Bustabit style)
+
+**Canonical crash math**: `crashPoint = (1−he)/(1−U)`, `U∈[0,1)`. This gives `P(crashPoint ≥ x) = (1−he)/x` for `x≥1`. EV at any cashout target `x` = `P(survive to x)·x = (1−he)/x · x = 1−he`. RTP = `1−houseEdge`, **strategy-independent** — the only clean way to get that property.
+
+**GOTCHA — forced/consolation payouts break RTP and strategy-independence.**
+Any guaranteed payout on a step the round did NOT crash on (a "soft-loss step saves your accumulated winnings" mechanic, forced cashout on miss, consolation bonus) is EV-positive: it pays value the crash-CDF budget never debited. Effect:
+- Global RTP > target.
+- "Ride longer" becomes the dominant strategy → strategy-independence destroyed.
+
+Only voluntary cashouts and a correctly-priced cap/jackpot are EV-neutral. "Soft-loss that saves X" is fundamentally incompatible with strategy-independent crash RTP without full game-math re-optimization around the save mechanics.
+
+**GOTCHA — flat auto-paid cap inflates AFK strategy EV.**
+A jackpot cap paid regardless of player action gives the never-cash (AFK) strategy `EV = P(cap)·cap`. EV-neutral only if `P(cap) = (1−he)/cap` exactly (the same CDF). Combine with ANY other forced payout and AFK RTP overshoots the target by tens of percent.
+
+**GOTCHA — finite step chain caps reachable multiplier.**
+An N-step chain with per-step multiplier `∈[lo,hi]` tops out at `≈hi^(N−1)`. Crash points above that are structurally unreachable → RTP sags BELOW target for high cashout targets and for never-cash. "Exactly `1−he`, globally strategy-independent" is FALSE for a finite chain; it only holds approximately for reachable targets.
+
+| N steps | per-step max | reachable ceiling |
+|---------|-------------|------------------|
+| 5 | ×3 | ×81 |
+| 7 | ×2.5 | ×244 |
+| 10 | ×2 | ×512 |
+
+**GOTCHA — PRNG stream independence for crashPoint.**
+`crashPoint` must be statistically independent of the per-step multiplier draws. Drawing it as the first output then the curve from subsequent draws of the same stream is fine (good PRNG outputs are uncorrelated). A separate stream keyed by a near-identical seed through a weak hash (e.g. `seed` vs `seed+":crash"` via FNV-1a → mulberry32) can silently correlate and inflate or deflate RTP. Verify empirically with a large Monte Carlo sweep — don't assume independence from the construction.
+
+**GOTCHA — conditional sub-population EV slices carry structural bias.**
+Filtering a Monte Carlo run to "rounds containing event X" and asserting the per-target RTP corridor of the slice ≈ global RTP is wrong whenever X correlates with round length or terminal outcome. Two independent causes:
+(a) *Chain-truncating event*: bonus steps that mostly emit at the crash-branch terminal — the round ends there — so high targets are structurally unreachable. Per-target RTPs of the slice decline monotonically with target; no tolerance widening fixes it.
+(b) *Compensation/dampening gate*: forced-miss rounds replace the event step with a miss variant and never enter the filtered slice — rounds that do enter carry inherited selection bias → the slice mean lands well below the global RTP.
+Pin only the upper bound (no target > 1.10–1.15) to catch +EV regressions, plus a wide mean band (±0.10). Drop per-target corridor, spread, and ride-RTP assertions on any slice with structural correlation between the filter condition and the round's terminal outcome.
+
+**PROCESS GOTCHA — Monte Carlo BEFORE porting or regenerating fixtures.**
+Validate the EV model with a sweep across multiple fixed cashout targets before porting to a second language or regenerating golden fixtures. An analytically "correct" model can hide EV-design bugs (forced payouts, chain ceiling, PRNG correlation) that only a per-target simulation exposes. Porting first = double rework when the math turns out wrong.
+
+**GOTCHA — economic model must not silently override a player-visible physics event.**
+When a deterministic outcome layer (pre-drawn crash point / book-based result) is draped over a physics renderer, scope any economic reclassification to outcomes the player CANNOT SEE. A physical impact the player watches happen (the ball rams an obstacle and bounces) MUST terminate consistently with what was shown — overriding it back to "safe, continue" so the book stays tidy produces a contradiction caught in the first playtest (observed: the ball visibly hit an obstacle yet the multiplier kept climbing). Rule: renderer-derived classification wins for any event the player can see; the economic model may only override outcomes that are visually indistinguishable.
+
+## Virtual-Scroll / Treadmill Takeover — Match Speed at the Handoff Seam
+
+When forward motion transitions from **real translation** (object moves in world-X, camera follows) to a **virtual scroll / treadmill** (object parked at a fixed screen X, background streamed past it to fake motion), the streamed background speed must MATCH the object's prior real forward speed at the seam, then ease down. A speed discontinuity — especially a collapse — reads as the object STOPPING, not as continued motion.
+
+**Concrete case**: a flying ball soared at ~1700 px/s (real X travel, camera following), then a "cruise" phase parked the ball and streamed the sky at a constant 280 px/s — a ~6× speed collapse at the seam. Players read it as "the ball stopped." Fix: start the treadmill at the soar's exit speed (`≈ (end.x − start.x) / duration`, clamped to a sane max), then smoothstep-decelerate to the idle drift speed (280 px/s). The background keeps moving at the prior rate and gently settles — reads as continuous forward flight arriving into a hover.
+
+**Measurement gotcha**: if the engine time-scales animation (e.g. `gsap.globalTimeline.timeScale(speed)` for a `?speed` param), the sampled background px/s is `game-speed × timeScale`. Multiply back by `1/timeScale` before comparing to your intended game-time speed, or a correct value reads as "too slow."
+
+**Secondary motion gotcha**: a vertical overlay (e.g. wind weave) at large amplitude (±70 px) on a now-slow background DOMINATES perception — reads as "bobbing in place." Keep secondary motion small relative to apparent forward speed (±70 → ±26 px fixed it).

package/templates/skills/domain-pixi/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: domain-pixi
-description: Pixi.js v8 masking and graphics gotchas
+description: Pixi.js v8 gotchas — graphics, masking, text, shaders, Spine, capture
 ---
 
 ## Pixi.js v8 Gotchas
@@ -14,7 +14,7 @@ A polygon with ~625 vertices renders fine as a sprite but produces NO clipping a
 
 ### 2. `setMask({ mask, inverse: true })` does not work for Graphics masks
 
-The `StencilMask` object is created (visible on `_maskEffect`) but inverse produces no visible change. Non-inverse normal mask works.
+The `StencilMask` object is created (visible on `_maskEffect`) but inverse produces no visible change. Non-inverse normal mask works. Version qualifier: the `inverse` option only exists since v8.5.0 (earlier v8 ignores it entirely); this failure was observed on v8.6.x — retest on your version before building a workaround.
 
 - Wrong: `container.setMask({ mask: g, inverse: true })` to hide inside-shape content
 - Right: build "world minus holes" via keyhole-bridge manually
@@ -29,12 +29,12 @@ The `StencilMask` object is created (visible on `_maskEffect`) but inverse produ
 
 Outer boundary CW, hole CCW (Y-down screen coords). For a rhombus {top, left, bottom, right} as a hole inside a CW outer rect:
 
-- Wrong CCW order: top → left → right → bottom (skips proper circuit, fills instead of holes)
+- Wrong order: top → left → right → bottom — a self-intersecting bowtie, not a CCW circuit; fills instead of holing
 - Right CCW order: top → left → bottom → right (strict CCW around centroid)
 
 ### 5. Keyhole-bridge: multiple holes in one polygon
 
-`FillStyle` has no `fillRule` field — `evenodd` is not available. Use a zero-width bridge instead:
+`FillStyle` has no `fillRule` field — `evenodd` is not available. v8 does offer `Graphics.cut()` (draw the hole path after the fill, then `.cut()`), but caveat: it attaches the hole only to the LAST drawn shape (its fill+stroke instruction pair), and a hole that is not completely inside that shape "will fail to cut correctly" (per its own doc). For multiple or edge-touching holes use a zero-width bridge instead:
 
 ```ts
 const pts: number[] = [0, 0];
@@ -68,7 +68,7 @@ Adding a Graphics mask as a child of the container it masks makes it inherit the
 
 ### 8. `.fill()` has no `fillRule` option
 
-`FillStyle` fields: `color`, `alpha`, `texture`, `matrix`, `fill`, `visible` — no `fillRule`. TypeScript will error on `.fill({ fillRule: 'evenodd' })`.
+`FillStyle` fields: `color`, `alpha`, `texture`, `matrix`, `fill`, `textureSpace` — no `fillRule`. TypeScript will error on `.fill({ fillRule: 'evenodd' })`. (`textureSpace: 'local' | 'global'`, default `'local'`, controls whether texture coords are relative to each shape's bounds or to world space.)
 
 - Right: use winding-based holes (#4, #5)
 
@@ -108,7 +108,7 @@ When a scene has multiple nested scales (e.g. `sceneRoot.scale = camera_fit`, `l
 
 Pixi v8's federated event system (`eventMode='static'` + `pointertap` etc.) only governs dispatch *within* the Pixi scene graph. The original DOM `pointerevent` continues bubbling to anything attached via `window.addEventListener('pointerdown', ...)` or `canvas.addEventListener(...)` regardless of which Pixi child handled it.
 
-Failure mode: a HUD/UI container is added to `app.stage` (sibling of the world `sceneRoot`) with interactive Graphics for buttons. Clicking a button fires the Pixi `pointertap` AND the global `window` pointerdown listener that was meant to handle "tap on world to fire/cash out" — every panel click double-fires the world action.
+Failure mode: a HUD/UI container is added to `app.stage` (sibling of the world `sceneRoot`) with interactive Graphics for buttons. Clicking a button fires the Pixi `pointertap` AND the global `window` pointerdown listener that was meant to handle "tap on world to trigger the primary action" — every panel click double-fires the world action.
 
 - Wrong: rely on `eventMode='static'` to "consume" the event for window listeners.
 - Wrong: gate via `if (ev.target !== app.canvas) return` — the canvas IS the target for clicks anywhere over its rect, including over panel children.
@@ -135,7 +135,7 @@ When two `roundRect` calls stack to fake a "raised button" effect (e.g. tall pil
 
 ### 15. Firefox clips rightmost glyph of Pixi `Text` — set `TextStyle.padding`
 
-Pixi v8 sizes the offscreen text texture using `measureText`. Firefox's `measureText` reports tighter advance widths than `fillText` actually paints, especially for `bold`/`800`/`900` weights, so the rightmost 1–2 px of the rightmost glyph fall outside the texture and get clipped. Chrome/Safari measure more generously and don't show the bug. User reports it as "in Chrome works, in Firefox last letter is cut" — affects every label simultaneously (BALANCE → BALANC, $100.00 → $100.0, FREE BET → FREE BE).
+Pixi v8 sizes the offscreen text texture using `measureText`. Firefox's `measureText` reports tighter advance widths than `fillText` actually paints, especially for `bold`/`800`/`900` weights, so the rightmost 1–2 px of the rightmost glyph fall outside the texture and get clipped. Chrome/Safari measure more generously and don't show the bug. User reports it as "in Chrome works, in Firefox last letter is cut" — affects every label simultaneously (BALANCE → BALANC, $100.00 → $100.0, TOTAL WIN → TOTAL WI).
 
 - Wrong (clipped in FF):
   ```ts
@@ -161,3 +161,252 @@ Even with `padding` (gotcha #15) keeping FF from clipping, `anchor: 0.5 + sprite
 - GOTCHA: only enable `trim` for centered-anchor texts. With `anchor: 0` (top-left labels), `trim` crops the natural ascender/descender whitespace at the top of the canvas, so the visible ink sits HIGHER than `sprite.y` than the untrimmed equivalent — stacked labels with hardcoded vertical offsets will overlap. Either parametrize the style helper (`labelStyle(size, color, weight, trim = false)`) and opt in only at centered call sites, or split into two separate styles.
 - Verification recipe: clip a 1px-tall strip across the rendered text band, sample bg color from outside the glyphs, find first/last column with significantly-different pixels (Manhattan delta > 100). Compare visible-ink center to bg center. Reading rendered canvas pixels via `python -c "from PIL import Image; ..."` works when Pixi's `preserveDrawingBuffer=false` makes JS-side `drawImage` of the WebGL canvas come back empty.
 
+### 17. Letterboxed canvas: use `app.canvas.clientWidth/Height`, not `container.clientWidth/Height`
+
+`app.renderer.resize(W, H)` sets the canvas CSS size to `W×H` (with `autoDensity: true`; without it the canvas has no CSS size of its own). When the game letterboxes inside a wider container (landscape window), `container.clientWidth > app.canvas.clientWidth`. Overlays laid out using the container dims extend into unrendered space; centering is computed against a wider rect than the canvas occupies.
+
+- Wrong: `bg.rect(0, 0, container.clientWidth, container.clientHeight).fill(color)` — bg overshoots the rendered region; "centered" text drifts toward one side.
+- Right: `bg.rect(0, 0, app.canvas.clientWidth, app.canvas.clientHeight).fill(color)` — matches the rendered region exactly.
+- Symptom: overlay (preloader, modal, HUD) appears off-center on landscape; looks correct in portrait where container and canvas widths match.
+- Note: `app.screen.width/height` gives the logical (renderer) resolution before CSS scaling — use `clientWidth/clientHeight` for layout in CSS pixels.
+
+### 18. `TilingSprite` wrap-samples the whole `TextureSource` — never feed it an atlas sub-frame
+
+Pixi v8 `TilingSprite` repeats the entire backing `TextureSource`, not the `frame` rect of the `Texture` you pass. If the texture is a sub-region of a shared atlas page, every tile wrap boundary bleeds the adjacent atlas content (alpha-bleed rings, packed neighbours), producing periodic seam artifacts across the tiled surface.
+
+- Wrong: pack a gradient strip into a shared atlas, then tile it:
+  ```ts
+  new TilingSprite({ texture: atlas.textures['sky_gradient'], width, height });
+  // → seam every `tileScale * atlas.textures['sky_gradient'].height` px
+  ```
+- Right option 1: keep tiled textures as standalone `TextureSource`s (own PNG, not atlas-packed).
+- Right option 2: if the texture must stay in the atlas and is horizontally uniform (e.g. a 1-px-wide gradient strip), use a clamped `Sprite` instead of tiling:
+  ```ts
+  const src = atlasTex.source;
+  const { x: fx, y: fy, width: fw, height: fh } = atlasTex.textures['sky_gradient'].frame;
+  const cropped = new Texture({ source: src, frame: new Rectangle(fx, fy + cropTop, fw, fh - cropTop) });
+  const sprite = new Sprite(cropped);
+  sprite.width = sceneWidth;
+  sprite.height = fh - cropTop;
+  ```
+  A `Sprite` uses `CLAMP_TO_EDGE` semantics within its frame — no wrap, no seam. Stretching a uniform-column strip horizontally is visually lossless.
+- This is the same underlying constraint as the classic WebGL "repeat requires pow2 or whole texture" rule, restated for v8 atlas usage.
+
+### 19. Custom uniforms on a Mesh shader require UBO (`ubo: true` + std140 block) — plain `uniform float foo;` with `UniformGroup` resource silently never syncs to GPU
+
+Adding a custom uniform to a `Mesh` shader by declaring `uniform float uTime;` at top level (outside any block) and passing `new UniformGroup({ uTime: { value: 0, type: 'f32' } })` as a resource appears correct: the shader compiles, `glProgram._uniformData.uTime` exists (introspected with type `float`), `shader.groups[99].resources[0]` is the UniformGroup, and the generated sync function emits `gl.uniform1f(ud["uTime"].location, v)`. JS-side mutations to `_waveUniforms.uniforms.uTime` advance correctly each frame. But the GPU never sees the value change — the shader behaves as if `uTime` is permanently 0. The fallback bind-group path (group index 99 for resources without a `gpuProgram` layout) generates a sync function that doesn't actually push plain uniforms.
+
+The reliable path is std140 UBO:
+
+- Wrong (compiles, draws, but uniform value never updates):
+  ```glsl
+  uniform float uTime;
+  ```
+  ```ts
+  new UniformGroup({ uTime: { value: 0, type: 'f32' } });
+  new Shader({ glProgram, resources: { waveUniforms } });
+  ```
+- Right (WebGL2 only — requires `#version 300 es`):
+  ```glsl
+  layout(std140) uniform waveUniforms {
+    float uTime;
+  };
+  ```
+  ```ts
+  new UniformGroup(
+    { uTime: { value: 0, type: 'f32' } },
+    { ubo: true },
+  );
+  ```
+  The resource KEY (`waveUniforms`) must match the GLSL block name. The std140 block size is padded to 16 bytes, so the underlying `Float32Array` is length 4 for a single float — write `group.uniforms.uTime = t; group.update();` per frame.
+
+Per-frame update flow that works: bump `_dirtyId` via `group.update()` after writing — `updateUniformGroup` then calls `syncUniformGroup` which writes std140 into `buffer.data`, bumps `buffer._updateID`, and `GlBufferSystem.updateBuffer` re-uploads on the next bind.
+
+Verification trick: read `(window as any).__group.buffer.data[0]` over 500 ms — if it advances but the rendered shader output stays frozen, the binding chain is broken (likely the plain-uniform fallback). If `buffer.data[0]` advances and pixel output also advances → UBO path is working.
+
+### 20. GLSL ES 3.00 fragment shaders need explicit `precision <qual> float;` — `compileHighShaderGl` does NOT inject one
+
+When emitting WebGL2 shaders via `compileHighShaderGl({ template: { vertex: vertexGlTemplate, fragment: fragmentGlTemplate }, bits: [...] })` and prepending `#version 300 es`, the fragment shader fails to link if any custom bit references a float-typed varying or uniform. Symptom: console fills with `WebGL: INVALID_OPERATION: useProgram: program not valid` warnings, the mesh draws silently disappear from the framebuffer (no exception thrown). Vertex stage compiles fine (ES 3.00 supplies an implicit `highp` for vertex floats); only fragment needs the explicit precision.
+
+- Wrong:
+  ```ts
+  const fragment = `#version 300 es\n${compiled.fragment}`;
+  ```
+- Right:
+  ```ts
+  const fragment = `#version 300 es\nprecision highp float;\n${compiled.fragment}`;
+  ```
+
+The standard `localUniformBitGl` / `globalUniformsBitGl` shaders bundled with Pixi escape this because their fragment never reads a float — they only write `outColor = vColor`. Any custom bit doing `mix()`, `smoothstep()`, or reading a `varying vec2 vUV` triggers the precision-missing link error.
+
+### 21. Freezing a Pixi scene for a deterministic screenshot — stop `Ticker.shared`, NOT just the external tween lib
+
+Per-frame motion in a Pixi app often comes from TWO independent drivers: Pixi's own `Ticker.shared` (drives `Spine.autoUpdate` skeletons and any `Ticker.shared.add(...)` per-frame loop) AND a separate tween library (gsap, etc.) driving specific objects. Pausing only ONE freezes only what IT drives. Common failure when capturing a screenshot of a transient overlap/alignment: you pause `gsap.globalTimeline` (which froze the gsap-driven object), take the screenshot a few hundred ms later via your screenshot tool, and the ticker-driven objects have moved on — the exact frame you detected is gone, and the screenshot shows empty space where the detector said a sprite was.
+
+- Wrong (only the gsap-driven object freezes; ticker-driven objects keep moving):
+  ```js
+  window.__gsap.globalTimeline.pause();   // gsap object stops, but ticker-driven sprites move before the screenshot
+  ```
+- Right (freeze BOTH drivers at the detected frame, then screenshot):
+  ```js
+  window.__gsap.globalTimeline.pause();
+  ticker.stop();                          // freezes Spine autoUpdate + every Ticker.shared sim loop
+  ```
+- Reaching `Ticker.shared` when it isn't exposed on `window`: in **spine-pixi-v8** every `Spine` instance with `autoUpdate` on holds the ticker at `spineInstance._ticker` (defaults to `Ticker.shared`; overridable via `options.ticker`) — walk the scene to any Spine and read `._ticker`. (Also reachable via `app.ticker` if you have the Application; the Pixi `Ticker` class itself is usually minified / not global in a prod bundle.)
+- Restore after the screenshot: `ticker.start()` + `gsap.globalTimeline.resume()`.
+- Detect-and-freeze in the SAME `requestAnimationFrame` callback that finds the frame (call `pause()` + `stop()` synchronously inside it), so no extra ticks elapse before the freeze. A poll-from-outside-then-pause loses frames to the round-trip latency.
+
+### 22. Pinpoint an in-clip Spine animation event frame from AttachmentTimeline data — don't eyeball scrubbed screenshots
+
+To find the exact time a prop breaks, an attachment appears/disappears, or a face changes mid-clip, scrubbing the clip and eyeballing screenshots is unreliable: a fast mid-motion pose can look like the event already happened. Concrete miss: a "prop break" was eyeballed at `trackTime ~0.2s` but the prop is still intact then; the real break is `0.933s` — a ~0.7s error that shipped a mistimed banner.
+
+Read the animation's `AttachmentTimeline`s from skeleton data. The keyframe where a slot's attachment name changes (to the broken/cracked variant, or to/from `null`) is the exact event time:
+
+```ts
+const anim = spine.skeleton.data.animations.find(a => a.name === 'break_anim');
+for (const tl of anim.timelines) {
+  if (tl.attachmentNames && tl.frames) {          // AttachmentTimeline
+    const slot = spine.skeleton.data.slots[tl.slotIndex].name;
+    // tl.frames[i] = time (s), tl.attachmentNames[i] = attachment (or null)
+  }
+}
+// e.g. intact `prop_whole` → null AND `shard_1..8` pieces appear, all at t=0.933
+```
+
+Companion: to RENDER a specific frame for a visual check, set `spine.autoUpdate = false`, then:
+
+```ts
+const e = spine.state.setAnimation(0, clip, false);
+e.trackTime = t;
+spine.update(0);
+```
+
+Do NOT call `skeleton.updateWorldTransform()` directly in spine-pixi v8 — it requires a `Physics` argument and throws `physics is undefined`. `spine.update(0)` applies state + transforms correctly.
+
+### 23. A BlurFilter on a fully-transparent sprite still renders its padded region — detach it, don't rely on alpha 0
+
+A `BlurFilter` (or any filter) attached via `sprite.filters = [blur]` forces a filter render pass that composites the filter's padded region **even when the sprite is fully transparent** (`alpha = 0`). The result is a faint soft-edged rectangle lingering on screen at the sprite's position — the blur edge-clamp of the (invisible) content.
+
+- Symptom: sprite is faded to `alpha = 0` (dissolve/burn-out tween) but a faint box persists at its position until something else clears the filter.
+- Wrong: tween `sprite.alpha → 0` and leave `sprite.filters = [blur]` attached, assuming alpha 0 hides everything. The empty filter region keeps compositing.
+- Right: detach the filter when content goes invisible — `sprite.filters = []` in the fade tween's `onComplete` (or whenever alpha hits ~0). An alpha-0 sprite with no filter renders nothing; with a filter it renders the region.
+- Note: a plain alpha-0 sprite (no filter) is correctly skipped by Pixi — only the attached filter forces the stray pass. Verified by toggling `sprite.filters.length` 1→0 at alpha 0: rectangle present with the filter, gone without it.
+
+### 24. Deferred texture upload — a standalone atlas page used only by a LATER clip uploads SYNCHRONOUSLY on its first render, stalling that frame. Pre-warm at boot.
+
+Pixi v8 uploads a `TextureSource` to the GPU lazily, on the FIRST render that binds it (`GlTextureSystem.bind`→`_initSource`→`onSourceUpdate`→`texImage2D`). A boot "warmup render" (`app.render()` once before revealing the scene) only uploads what's VISIBLE in that idle frame. Any texture whose only consumers are clips/states not shown at idle — a separate Spine FX atlas (flame, explosion, bonus), a rarely-used sprite page — is NOT uploaded at boot. It uploads the first time that clip renders: a one-time synchronous `texImage2D` of the WHOLE page on the gameplay frame that first shows it.
+
+- Symptom: a "strong lag SOMETIMES" exactly at a transition (a strike, an ability, a scene change) — "sometimes" = only the FIRST occurrence per page-load, because after that the page is GPU-resident. Invisible on a fast desktop GPU (a ~16 MB upload is a few ms), a clear hitch on mobile (far lower texture-upload bandwidth + driver overhead).
+- A shared atlas page is fine: if the idle scene shows ANY region of `atlas.png`, the whole page uploads at boot, so later clips packed into the SAME page (an action pose, a flag) pay nothing. Only pages with NO region visible at idle defer. (So a Spine action clip on the hero's already-visible atlas = free; the flame's SEPARATE atlas = a deferred stall.)
+- Measure it directly — hook the GL context in an addInitScript BEFORE app boot and timestamp every upload:
+  ```js
+  const og = HTMLCanvasElement.prototype.getContext;
+  HTMLCanvasElement.prototype.getContext = function (t, ...r) {
+    const gl = og.call(this, t, ...r);
+    const proto = Object.getPrototypeOf(gl), o = proto.texImage2D;
+    proto.texImage2D = function (...a) {
+      const w = typeof a[3]==='number'?a[3]:(a[a.length-1]?.width||0);
+      const h = typeof a[4]==='number'?a[4]:(a[a.length-1]?.height||0);
+      if (w*h) window.__up.push({ t: performance.now(), w, h, bytes: w*h*4 });
+      return o.apply(this, a);
+    };
+    return gl;
+  };
+  ```
+  A big single `texImage2D` (e.g. `2018×2044` = 16.5 MB) landing a few ms before the visible transition, present only ONCE in the whole session, is the smoking gun. A page costs `w·h·4` bytes of GPU RAM regardless of the PNG's compressed size (a 2.6 MB PNG → ~16.5 MB upload).
+- Fix: force the upload at boot, behind the preloader, with `renderer.texture.initSource(source)` (idempotent — no-op if already resident). Reach the source of a spine-pixi-v8 atlas via `Assets.get(atlasAlias).pages[i].texture.texture.source` (the `SpineTexture` wrapper holds the Pixi `Texture` at `.texture`, whose `.source` is the `TextureSource`). Call once per standalone FX atlas right after the warmup `app.render()`.
+- This trades a one-time gameplay stall for slightly more load-time work — the correct tradeoff, same intent as the warmup render itself.
+
+### 25. 8-bit gradient banding in additive glows → screen-space additive-noise dither overlay (NOT a post-filter)
+
+A soft radial glow built from stacked ADDITIVE Spine/sprite slots, scaled up several×, shows concentric "Mach-band" rings on some mobile panels (and milder banding on iPhones) even though the source texture is a smooth gradient. Cause: across the falloff the additive contribution drops <1 LSB per screen pixel, so the 8-bit framebuffer holds one value for ~16 px then steps +1 — a ring at every step. Desktop GPUs/panels dither it away; many mobile panels render the raw 8-bit, so the rings show. Confirm by sampling a radial line of the captured frame: a banded glow holds RGB constant for 16–24 px then steps by exactly 1 (`(70,131,194)`→`(70,132,195)`), and ×6-amplifying `(frame − local_sky)` makes the rings pop.
+
+- **The texture is NOT the bug.** Measure the source alpha falloff: if it's a smooth ramp (many levels, no long flat runs), the banding is purely the final 8-bit COMPOSITE. Re-exporting / dithering the source won't help (it's washed out by the upscale + linear filter before the framebuffer quantizes).
+- **A post-process filter on the already-8-bit frame can't reconstruct the gradient, but ≥1-LSB dither STILL breaks the rings** — adding noise then re-quantizing scatters the hard step edge into noise the eye integrates. Sub-LSB dither does nothing (re-rounds to the same value); you need ~1–2 LSB amplitude.
+- **Cheapest robust fix = a screen-space additive `TilingSprite` of noise** over the world, `blendMode:'add'`, tiny `alpha` (~0.012 → contribution `noise(0..255)·alpha` ≈ 0..3 LSB, mean ~1.5). Added to `app.stage` ABOVE the world, BELOW the HUD. Backend-agnostic (works on WebGL AND WebGPU — no custom shader), one cheap quad (vs a full-frame render-target pass for a `Filter`), and it dithers BEFORE the framebuffer re-quantizes. Use `scaleMode:'nearest'`, `tileScale = 1/renderer.resolution` (≈ one noise texel per device pixel), `eventMode:'none'`. Imperceptible at 1× (verify on the real idle scene), bands gone (radial flat-run maxrun drops from ~16–24 px to ~2–3 px).
+- A custom GLSL/WGSL dither `Filter` is the "more correct" symmetric dither but costs: a full-frame render pass, and on a renderer that may pick WebGPU (Pixi v8 default if no `preference` set in `app.init`) you must supply BOTH a glProgram and a gpuProgram. The additive-noise sprite sidesteps all of that.
+- **GOTCHA — generate the noise from a LOCAL seeded PRNG, never `Math.random()`.** Filling a 128×128 RGBA tile is ~49k draws; if the game seeds any sim state (enemy layout, spawn jitter) off the GLOBAL `Math.random` stream, consuming those draws at boot SHIFTS that layout and silently changes gameplay. Use a local `mulberry32` (a fixed seed is ideal — the dither tile only needs to be uncorrelated, not unpredictable). A render-init utility must never consume the sim's RNG.
+
+### 26. A Graphics whose draw is ONLY `g.texture(...)` is UNCLICKABLE — `containsPoint` skips texture instructions; set an explicit `hitArea`
+
+Pixi v8 `GraphicsContext.containsPoint` iterates instructions and does `if (!instruction.action || !path) continue;` — `texture` instructions carry no `path`, so a Graphics that draws nothing but texture quads never hit-tests true. Symptom: `eventMode: 'static'` + `onpointertap` on a texture-only Graphics (e.g. an atlas-frame button) silently never fires; the same handler pattern works elsewhere because those draws include `fill()` shapes. No error, cursor may even change (cursor comes from the events system pre-hit in some paths) — the tap just doesn't land.
+
+- Wrong (renders fine, never clickable):
+  ```ts
+  <Graphics eventMode="static" onpointertap={onTap}
+    draw={(g) => g.texture(frame, 0xffffff, -w/2, -h/2, w, h)} />
+  ```
+- Right — explicit hitArea (local coords of the Graphics):
+  ```ts
+  <Graphics eventMode="static" onpointertap={onTap}
+    hitArea={new Circle(0, 0, w / 2 - pad)}   // or new Rectangle(...)
+    draw={(g) => g.texture(frame, 0xffffff, -w/2, -h/2, w, h)} />
+  ```
+- Related trap: a draw of only thin glyph bars (a `−`/`+` made of 2 small rects) IS hit-testable but the target is a sliver — give it a generous `hitArea` rect too.
+- Rule of thumb: any interactive Graphics should either contain at least one `fill()` shape covering the intended target, or carry an explicit `hitArea`. `hitArea` also short-circuits per-shape testing — cheaper on complex draws.
+
+### 27. `generateTexture` of a TRIMMED Text at resolution≠1 renders shifted when composited into a RenderTexture atlas — bake untrimmed for atlas pages
+
+Baking labels via `renderer.generateTexture({ target: text, resolution: 2 })` where the TextStyle has `trim: true` produces a texture whose CONTENT lands offset (≈ the logical ink height upward) when the baked texture is drawn as a Sprite into another RenderTexture (an atlas page): the recorded frame rect is right, the pixels are not — on retina the atlas shows the label's bottom half at the frame position and garbles every drawn label. At resolution 1 the same pipeline renders perfectly, so the bug ONLY appears on DPR-2 devices — desktop verification with a CDP-forced DPR-1 viewport misses it completely.
+
+- Wrong (garbled on retina): `style.trim = true` → `generateTexture({target, resolution})` → Sprite → atlas page.
+- Right: bake UNTRIMMED with the style's `padding` captured as a border (`generateTexture({ target, frame: new Rectangle(-pad, -pad, w+2pad, h+2pad), resolution })`); the padding is symmetric, so centering the FULL padded box visually centers the text. Subtract `pad` where the label butts another element.
+- Verify by extracting the atlas page itself (`renderer.extract.canvas(new Texture({source: page.source}))`) at BOTH resolutions — comparing only final screenshots hides whether the page or the frame math is at fault.
+- Related: assigning `texture.source.resolution = N` after `Texture.from(canvas)` to "mark" a hi-res raster double-counts in any packer that multiplies `tex.width * source.resolution` — leave source.resolution at 1 and scale at draw time with explicit dw/dh.
+
+### 28. BitmapText silently DROPS local-space FillGradient — DynamicBitmapFont bakes glyphs without textMetrics; layer two solid texts + an alpha-ramp mask instead
+
+A `TextStyle` with `fill: new FillGradient({ textureSpace: 'local', ... })` renders correctly on `Text`, but on `BitmapText` (v8 dynamic bitmap font) the glyphs come out SOLID in (approximately) the LAST stop's colour. Cause: `DynamicBitmapFont._setupContext` calls `getCanvasFillStyle(style._fill, context)` with NO `textMetrics` argument, so the local gradient is built over a 1×1 box — every glyph pixel below y=1 samples the final stop. Same for gradient strokes. No warning is emitted.
+
+- Wrong (compiles, renders solid): per-frame multiplier label as `<BitmapText>` with a vertical `FillGradient` fill/stroke.
+- Switching to `Text` "fixes" the gradient but re-rasterizes + re-uploads the whole string every frame — the exact cost BitmapText was chosen to avoid for per-frame counters.
+- Right (keeps BitmapText, exact vertical gradients for BOTH fill and stroke): draw the string TWICE in solid colours and alpha-mask the top copy:
+  1. Bottom `BitmapText`: fill = gradient END colour, stroke = stroke-gradient END colour (opaque).
+  2. Top `BitmapText` (same text/anchor/pos): fill = gradient START colour, stroke = stroke-gradient START colour.
+  3. Mask the top copy with a static 1×H canvas texture: alpha 1 above the digit ink, linear 1→0 across the ink band, 0 below. Sprite spans the text area; `container.mask = sprite` (alpha mask) — verified working in v8.18.
+- BOTH layers MUST declare a stroke of the SAME `width` — `DynamicBitmapFont` feeds `stroke.width` into the glyph padding and draw offsets (`extraPadding = stroke.width`, `tx/ty ± width/2`), so a stroke-less layer rasterises its glyphs SHIFTED vs a stroked one and its fill paints over the other layer's stroke edge (shows as "the top stroke is eaten"). For a TRANSLUCENT stroke (e.g. black @0.4) that must not double-darken under the mask: keep the visible stroke in the BOTTOM layer and give the TOP layer the same-width stroke with `alpha: 0` — identical metrics, zero paint.
+- Ink-band placement: Poppins-like fonts ≈ ink top at 0.30·fontSize below the line top, ink height ≈ 0.70·fontSize — verify against a live screenshot (measure stroke/fill row extents) rather than font tables.
+- Cost: +1 glyph-quad draw + one small alpha-mask pass while the label shows — no per-frame canvas rasterization.
+
+### 29. pixi-svelte: a late-becoming-true `{#if}` block APPENDS its Pixi node — template order ≠ z-order; background layers must mount UNCONDITIONALLY
+
+pixi-svelte components call `parentContext.addToParent(node)` at mount time. Children that mount TOGETHER land in template order, but a `{#if cond}` block whose condition flips true LATER (data arrives, state changes mid-animation) appends its node to the END of the parent's children — ON TOP of everything already mounted, regardless of where the block sits in the template.
+
+- Symptom: a "background" sprite/Graphics written ABOVE a text/sprite in the template renders OVER it — but only when its data arrives after mount (e.g. an atlas frame that resolves later, a kind flag that flips a frame into the animation). Screenshots taken when the condition was true from the start look correct, hiding the bug.
+- Wrong (flame draws on top of the text whenever `flameTex` resolves after mount):
+  ```svelte
+  {#if flameTex}
+    <Graphics draw={drawFlame} />   <!-- background -->
+  {/if}
+  <BitmapText text={label} ... />
+  ```
+- Right — mount the background node UNCONDITIONALLY (same mount tick as its siblings preserves template order) and guard inside the draw callback; pixi-svelte's Graphics `$effect` runs `graphics.clear()` before every draw, so a null texture just draws nothing:
+  ```svelte
+  <Graphics draw={(g) => { if (flameTex) g.texture(flameTex, ...); }} />
+  <BitmapText text={label} ... />
+  ```
+- Late-mounting is fine for nodes that SHOULD be on top (overlays, masked top layers) — append order is exactly what they need.
+- Verify layering by ZOOMING a screenshot at an actual overlap point (glyph stroke crisp over the background = correct); a row-scan "stroke pixels exist somewhere" check passes in BOTH orders and proves nothing about z.
+
+## Verification & capture
+
+General Playwright/browser-capture traps (stale headless AND headed screenshots,
+persistent MCP browser cache, headless-vs-device GPU perf) live in the
+`browser-verify` skill — load it alongside this one when verifying visually.
+
+### 30. Measuring per-frame motion — sample on the Pixi render ticker, NOT your own `requestAnimationFrame`
+
+To verify/diagnose a per-frame animation artifact (judder, stutter, "moves every other frame"), read the object's position INSIDE a callback added to the actual render ticker (`spineInstance._ticker.add(cb)` — walk the scene for a `Spine` with `_ticker`, see #21), not a separate `requestAnimationFrame` loop you spin up. Your own rAF runs on a DIFFERENT clock than the game's update/render and ALIASES against it: when the game updates at a different effective rate than your sampler, you get bogus duplicate frames — a perfectly regular `0, X, 0, X` per-frame delta that looks like a real every-other-frame stutter but is partly your sampling beat. (Headless Chrome makes this worse: observed `_ticker.FPS` bounced 113→120→151 across runs, and gsap/Pixi can run at mismatched rates so BOTH the tween-driven and ticker-driven motion appeared to update at ~60 while the ticker reported 120.)
+
+- Wrong (aliased — `0,X,0,X` is partly the sampler beat, present even in a smooth build):
+  ```js
+  let prev; const loop = () => { const x = read(); /* delta = prev - x */ prev = x; requestAnimationFrame(loop); };
+  ```
+- Right (synced to what is actually drawn — true per-render-frame delta):
+  ```js
+  let ticker; walkScene(n => { if (n._ticker && n.skeleton) ticker = n._ticker; });
+  const xs = []; const cb = () => xs.push(read()); ticker.add(cb); /* …900ms… */ ticker.remove(cb);
+  // smooth build → every delta ≈ mean (e.g. 4.8–6.1 around 5.4); juddery → 0 / 2×mean alternation (zeroFrac ≈ 0.5)
+  ```
+- Discriminator: compute `zeroFrac` (fraction of frames with ≈0 delta). A render-synced smooth build is `zeroFrac ≈ 0`; a real every-other-frame stutter is `zeroFrac ≈ 0.5`. Your-own-rAF can't tell them apart.
+- Sibling cause to watch for: a fixed-timestep accumulator (`while (acc >= SIM_STEP_MS) step(SIM_STEP_MS)`) on a `>62.5 Hz` display releases a step only every ~N frames → the object visibly moves in quantized bursts. If the camera is static (so the object's own motion is the only thing on screen), this reads as judder. Fix: step with the real (capped) frame `dt` where determinism isn't required.