@codyswann/lisa 2.178.6 → 2.179.0

package/plugins/lisa-phaser-agy/skills/phaser-testing/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: phaser-testing
-description: This skill should be used when writing or designing tests for a Phaser 4 game — unit-testing pure game logic with Vitest, keeping logic Phaser-free so it tests without a browser, the Phaser.HEADLESS renderer for logic-only boots, asset-manifest coverage tests, and Playwright smoke tests that prove the game actually boots and renders. Use it when adding tests, setting up CI verification, or deciding what is testable at which level. Pairs with phaser-project-structure, phaser-assets, and phaser-physics.
+description: This skill should be used when writing or designing tests for a Phaser 4 game — unit-testing pure game logic with Vitest, keeping logic Phaser-free so it tests without a browser, the Phaser.HEADLESS renderer for logic-only boots, asset-manifest coverage tests, and the CI runtime gates (boot smoke, allocation/perf budget, leak gate, determinism gate, deterministic Playwright visual regression, bundle-size budget) that verify scenes and entities that are excluded from unit coverage. Use it when adding tests, setting up CI verification, or deciding what is testable at which level. Pairs with phaser-project-structure, phaser-assets, and phaser-services.
 ---
 
 # Phaser 4 Testing
@@ -13,10 +13,17 @@ pyramid, bottom-up:
 1. **Vitest unit tests** over `src/logic/**` — the bulk of coverage.
 2. **Manifest/contract tests** — cheap structural checks (asset packs, scene
    keys, anim definitions).
-3. **Playwright smoke test** — the game boots in a real browser, renders past
-   the Preloader, no console errors.
-
-There is no official Phaser testing harness — this layering IS the strategy.
+3. **Headless integration** (sparingly) — `Phaser.HEADLESS` for things that
+   genuinely need the engine loop.
+4. **Playwright smoke** — the game boots in a real browser, renders past the
+   Preloader, no console errors.
+5. **CI runtime gates** — scenes/entities are excluded from unit coverage and
+   instead verified by deterministic runtime gates: boot smoke, allocation/perf
+   budget, leak gate, determinism gate, visual regression, bundle-size budget.
+
+There is no official Phaser testing harness — this layering IS the strategy. The
+dividing line: pure logic is unit-tested; everything that needs the engine is a
+runtime gate, never a brittle unit test that mocks the world.
 
 ## Layer 1: pure logic under Vitest (the rule that makes it possible)
 
@@ -85,15 +92,101 @@ Convention: scenes set `window.__sceneReady = key` in `create()` (dev/test
 builds) so tests await real readiness instead of sleeping. Run against
 `bun run dev` (or `vite preview` in CI).
 
+## Layer 5: CI runtime gates (how scenes get verified)
+
+Scenes and entities are deliberately **excluded from unit coverage** — mocking
+the engine to "unit test" a scene tests the mock. Instead, CI runs a set of
+deterministic gates against a real (or headless) game. Each gate fails the build
+on regression; together they are the contract that the engine-coupled layer
+keeps working.
+
+**Boot smoke** — the Playwright test above, hardened: page error listener, wait
+for `__sceneReady`, assert zero console errors. This is the floor.
+
+**Allocation / perf budget** — run the game for N frames and assert the frame
+budget and heap growth. Per-frame allocation is what the `no-allocation-in-update`
+and `no-create-in-update` lint rules forbid statically; this gate catches what
+slips through dynamically.
+
+```ts
+test("steady-state frames stay within budget", async ({ page }) => {
+  await page.goto("/"); await bootTo(page, "Game");
+  const stats = await page.evaluate(async () => {
+    const g = (window as any).__game as Phaser.Game;
+    const frames: number[] = []; let last = performance.now();
+    for (let i = 0; i < 600; i++) { await new Promise(r => g.events.once("postrender", r)); const n = performance.now(); frames.push(n - last); last = n; }
+    return { p95: frames.sort((a,b)=>a-b)[Math.floor(frames.length*0.95)], heap: (performance as any).memory?.usedJSHeapSize };
+  });
+  expect(stats.p95).toBeLessThan(20); // ~50fps floor on CI hardware
+});
+```
+
+**Leak gate** — start and stop a scene N times and assert that texture count,
+event-listener count, active tweens, and timers all return to baseline. This is
+the runtime enforcement of the `require-shutdown-cleanup` rule and the
+on/off-discipline in [[phaser-services]].
+
+```ts
+test("scene start/stop leaves no leaks", async ({ page }) => {
+  await page.goto("/"); await bootTo(page, "MainMenu");
+  const before = await page.evaluate(() => (window as any).__game.textures.getTextureKeys().length);
+  for (let i = 0; i < 20; i++) await page.evaluate(async () => {
+    const g = (window as any).__game as Phaser.Game; g.scene.start("Game");
+    await new Promise(r => setTimeout(r, 50)); g.scene.stop("Game");
+    await new Promise(r => setTimeout(r, 50));
+  });
+  const after = await page.evaluate(() => (window as any).__game.textures.getTextureKeys().length);
+  expect(after).toBeLessThanOrEqual(before); // no per-cycle texture growth
+});
+```
+
+**Determinism gate** — boot twice with the same seed, drive the same inputs, and
+assert an identical state hash. Logic exposes a serializable snapshot; the gate
+hashes it. Same seed → same hash, always. This is the runtime backstop for the
+no-`Math.random()`/`Date.now()`/`performance.now()` rules ([[phaser-services]]).
+
+```ts
+const run = (seed: number) => page.evaluate(s => (window as any).__sim(s, REPLAY), seed);
+expect(hash(await run(1234))).toBe(hash(await run(1234)));
+```
+
+**Deterministic visual regression** — `toHaveScreenshot` under **software GL**
+(`--use-gl=swiftshader`), a **frozen frame** (pause the loop / step a fixed
+number of ticks at a fixed delta), and **masked dynamic regions** (timers,
+particles). Without all three, screenshots flake. Pin Playwright's browser and
+OS in CI so the baseline is stable.
+
+```ts
+await page.evaluate(() => { const g=(window as any).__game; g.loop.sleep(); g.step(0,16.6); });
+await expect(page).toHaveScreenshot("game.png", { mask: [page.locator("#timer")], maxDiffPixelRatio: 0.01 });
+```
+
+**Bundle-size budget** — assert the built bundle stays under a byte budget so a
+stray dependency or an un-split `phaser` chunk fails the PR. Wire it to the prod
+build's `manualChunks` split ([[phaser-build-deploy]]).
+
+```jsonc
+// size-limit / custom check after `bun run build`
+[{ "path": "dist/assets/index-*.js", "limit": "60 kB" },
+ { "path": "dist/assets/phaser-*.js", "limit": "400 kB" }]
+```
+
 ## Project conventions
 
-- `bun run test` = Vitest (layers 1–2, coverage-gated). Playwright smoke runs as
-  its own script/CI job against a built preview.
+- `bun run test` = Vitest (layers 1–2, coverage-gated **over `src/logic/**`
+  only** — scenes/entities are out of scope here). The layer-5 gates run as their
+  own CI jobs against a built `vite preview` (and a headless boot for the
+  determinism gate).
+- Build pins are part of the contract: `phaser ^4.2.0`, Vite, TypeScript 6.
 - Tests never assert on private scene fields; they assert on logic outputs
-  (layer 1) or observable behavior (layer 4).
+  (layer 1), observable behavior (layer 4), or the runtime invariants the gates
+  measure (layer 5).
 
 ## Verification
 
 The testing setup itself is verified when `bun run test` passes with coverage
-over `src/logic/**`, and the Playwright smoke fails when you deliberately break
-boot (rename a pack file) — a smoke test that can't fail is decoration.
+over `src/logic/**`, the Playwright smoke fails when you deliberately break boot
+(rename a pack file), and each layer-5 gate fails on its targeted regression —
+leak gate when a listener loses its `.off()`, determinism gate when a
+`Math.random()` sneaks in, visual gate when the frame changes. A gate that
+can't fail is decoration.

package/plugins/lisa-phaser-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-phaser",
-  "version": "2.178.6",
+  "version": "2.179.0",
   "description": "Phaser 4 game-development rules for TypeScript projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-phaser-copilot/rules/phaser.md

@@ -1,59 +1,126 @@
 # Phaser 4 Project Rules
 
-This is a **Phaser 4** (v4.1+ "Salusa") TypeScript game project. Phaser 4 is the
-only supported target — never introduce Phaser 3 idioms. The lint config enforces
-the bans below; do not disable those rules, fix the code.
-
-## Phaser 4 Only — Banned v3 Idioms
-
-- **No pipelines.** `setPipeline` / `setPostPipeline` / `resetPipeline` are gone.
-  Custom rendering is a **RenderNode** (registered via `render.renderNodes` in the
-  game config); post-processing is a **Filter** (`gameObject.filters` /
-  `camera.filters`). See the `phaser-rendering` skill.
-- **No preFX/postFX.** The v3 FX controllers were replaced by the unified Filter
-  system. `BitmapMask` → `Mask` filter.
-- **No `setTintFill`/`tintFill`.** Use `setTint()` + `setTintMode(Phaser.TintModes.FILL)`.
-- **No `Phaser.Geom.Point`** (removed — use `Phaser.Math.Vector2`) and **no
-  `Phaser.Struct.Set/Map`** (removed — use native `Set`/`Map`).
-- **No raw WebGL calls.** External GL work goes through the `Extern` game object.
-- **No `setPipeline('Light2D')`.** Lighting is `gameObject.setLighting(true)`.
+This is a **Phaser 4** (v4.2+, npm `phaser@^4.2.0`) TypeScript game project built
+on the official `template-vite-ts` layout (Vite + TypeScript 6). Phaser 4 is the
+only supported target — never introduce Phaser 3 idioms. These decisions are
+**locked** and most are **lint-enforced**; do not disable a rule, fix the code.
+
+## Locked architecture decisions
+
+1. **Thin scenes over a pure-logic core.** Scenes and GameObjects are thin
+   adapters that wire pure logic to the engine. All game rules live in
+   `src/logic/**` as plain TypeScript with **zero `phaser` imports** (data in,
+   data out). This is what makes the game unit-testable. ECS (bitECS / Miniplex)
+   is an opt-in option, not the default — reach for it only at high entity
+   counts. See `phaser-project-structure` and `phaser-testing`.
+2. **Canvas-only, framework-agnostic UI.** UI is plain TS + DOM/canvas (the
+   `template-vite-ts` baseline). A React/Vue EventBus bridge is documented only
+   as an upgrade path — it is not the default and is not added unless required.
+3. **Arcade physics by default; Matter is opt-in.** Matter is heavier and does
+   not interop with Arcade. Switching is a one-line config swap. See
+   `phaser-physics`.
+4. **Determinism.** No `Math.random()`, `Date.now()`, or `performance.now()` in
+   game code. Use the seeded `Phaser.Math.RandomDataGenerator` (`Phaser.Math.RND`
+   or a local instance seeded from one place) so replays and tests reproduce.
+5. **State and events.** Global state goes through a **typed wrapper over the
+   registry**; cross-cutting events go through a **single dedicated
+   EventsCenter** (`new Phaser.Events.EventEmitter()`) — **never reuse
+   `game.events`**. Every external `.on()` (`this.input` / `scale` / `time` /
+   `window` / the custom bus) must have a matching `.off()` in the scene's
+   `shutdown`. See `phaser-services`.
+6. **Performance.** Pool transient objects via `Group`s; make **no allocations
+   and create no objects/tweens/timers inside `update()`**; atlas everything; use
+   `BitmapText` for high-churn text; use `SpriteGPULayer` / `TilemapGPULayer` for
+   mass rendering. See `phaser-gameobjects`.
+7. **Baked-in asset pipeline.** Raw art in `assets/src` is packed at build time
+   (free-tex-packer-core atlases, audiosprite, BMFont) into `public/assets`, and
+   a codegen step emits typed keys to `src/assets.ts` so a missing or renamed key
+   is a **compile error**. No raw string asset / scene / event keys anywhere.
+   See `phaser-asset-pipeline`.
+8. **PWA on by default** via `vite-plugin-pwa` (`registerType: "autoUpdate"`,
+   `globPatterns` extended to cover game assets). See `phaser-build-deploy`.
+9. **Cross-cutting services are scaffolded** in `src/services/**`: SoundService
+   (mobile audio unlock on first gesture), InputService (semantic actions, not
+   raw keys), SaveService (typed `localStorage` with a schema `VERSION` +
+   migration chain — never raw `localStorage`), a typed i18n string catalog (no
+   hardcoded user-facing strings), accessibility (prefers-reduced-motion,
+   pause-on-blur, keyboard-navigable menus, screen-reader live region), and a
+   vendor-neutral telemetry/analytics abstraction. In-game errors are wired to
+   the observability sink. See `phaser-services`, `phaser-i18n`,
+   `phaser-accessibility`.
+10. **Testing is a pyramid.** Pure logic is unit-tested with Vitest;
+    scenes/entities are excluded from unit coverage and verified by **runtime
+    gates** in CI (boot smoke, allocation/perf budget, leak gate, determinism
+    gate, deterministic visual regression, bundle-size budget). See
+    `phaser-testing`. Build pins: `phaser ^4.2.0`, Vite, TypeScript 6.
+
+## Enforced lint rules (prose must match machine enforcement)
+
+The lint config enforces the rules below. Each exists because the prose above
+relies on it — keep them in sync.
+
+**`no-restricted-imports`**
+
+- Importing `phaser` anywhere under `src/logic/**` is banned. The logic core
+  stays engine-free so Vitest runs it without a browser.
+
+**`no-restricted-syntax`** bans:
+
+- Removed v3 idioms: `setPipeline` / `setPostPipeline` / `resetPipeline`,
+  `setTintFill`, `preFX` / `postFX`, `Phaser.Geom.Point`, `Phaser.Struct`,
+  `BitmapMask`, `Mesh`, `Plane`, `Camera3D`. Use the v4 replacements
+  (RenderNodes, Filters, `Phaser.Math.Vector2`, native `Set`/`Map`, GPU layers).
+- `Math.random()` / `Date.now()` / `performance.now()` in `src` game code — use
+  the seeded RND and the scene clock (`this.time.now`).
+- Reusing `game.events` for app messaging — use the dedicated EventsCenter.
+- `debug: true` inside a physics/game config object literal — debug stays off in
+  committed code (toggle locally, never commit it on).
+
+**Direct-`localStorage` ban**
+
+- Direct `localStorage` access outside `src/services/**` is banned. Persist
+  through SaveService (versioned + migrated).
+
+**Custom `eslint-plugin-phaser` rules**
+
+- `no-create-in-update` — no `this.add.*`, `tweens.add`, `time.addEvent`,
+  `physics.add.*`, or `new Phaser.*` inside an `update()` method. Create in
+  `create()`; in the loop, reuse and pool.
+- `no-allocation-in-update` — no object/array literals, closures, or
+  `.map`/`.filter`/`.reduce` chains inside `update()`. Hoist scratch objects.
+- `require-shutdown-cleanup` — a `Scene` that registers persistent external
+  listeners must define a `shutdown` handler that removes them.
 
 ## Architecture
 
 - **One scene class per file** under `src/scenes/`, named after the scene key.
   The scene flow is `Boot → Preloader → MainMenu → Game` (plus overlays). Boot
   loads only what the Preloader needs; the Preloader loads everything else.
-- **Pure game logic lives outside scenes** in `src/logic/` (or `src/core/`) with
-  **no `phaser` imports** — plain TypeScript functions and classes that take and
-  return data. Scenes are thin orchestrators that wire logic to GameObjects.
-  This is what makes the game unit-testable; see the `phaser-testing` skill.
-- **Asset keys are typed constants** in `src/assets.ts` — never inline magic
-  strings for texture/audio/animation keys. Load via asset-pack manifests
-  (`this.load.pack`), not ad-hoc `load.image` lists scattered across scenes.
-
-## Determinism
-
-- **No `Math.random()` in game code.** Use the scene-seeded
-  `Phaser.Math.RandomDataGenerator` (`Phaser.Math.RND` or a local instance with
-  an explicit seed) so replays and tests are reproducible.
-- Arcade physics keeps its v4 default `fixedStep: true`. Do not switch physics to
-  variable step to "fix" a tunneling bug — fix the body/velocity configuration.
+- **Pure game logic lives in `src/logic/**`** with no `phaser` imports — plain
+  TypeScript that takes and returns data. Scenes/entities are thin orchestrators
+  that wire that logic to GameObjects. See `phaser-testing`.
+- **Keys are typed constants** generated into `src/assets.ts` — never inline
+  magic strings for texture/audio/animation/scene/event keys. Load via asset-pack
+  manifests (`this.load.pack`), not ad-hoc `load.image` lists.
 
 ## Performance
 
-- **No allocations in `update()`.** No `new`, array literals, closures, or
-  `.filter/.map` chains in per-frame paths — hoist scratch objects, reuse vectors.
+- **No allocations in `update()`** and **no object/tween/timer creation in
+  `update()`** (both lint-enforced) — hoist scratch objects, reuse vectors.
 - **Pool, don't churn.** Bullets, enemies, particles, and pickups come from
-  `Group` pools (`get`/`killAndHide`), never `new`/`destroy` per spawn.
-- **Mass rendering uses the GPU layers.** Large static/animated sprite fields →
-  `SpriteGPULayer`; large tile maps → `TilemapGPULayer`. Texture atlases (PCT
-  where possible) over loose images — see the `phaser-assets` skill.
-- Target WebGL; the Canvas renderer is deprecated in v4 and only acceptable as an
-  explicit, documented fallback decision.
+  `Group` pools (`get` / `killAndHide`), never `new` / `destroy` per spawn.
+- **Mass rendering uses the GPU layers.** Large sprite fields → `SpriteGPULayer`;
+  large tile maps → `TilemapGPULayer`. Atlas everything (see
+  `phaser-asset-pipeline`); `BitmapText` for high-churn text.
+- Target WebGL; the Canvas renderer is deprecated in v4 and acceptable only as an
+  explicit, documented fallback.
 
 ## Verification
 
-Before reporting any change complete: run `bun run typecheck`, `bun run test`,
-and `bun run build`. For changes that affect rendering or input, verify in the
-real browser — `bun run dev` plus a Playwright check (the game boots, the canvas
-renders, no console errors). A green typecheck alone is not proof a game works.
+Before reporting any change complete: run `bun run typecheck`, `bun run lint`,
+`bun run test`, and `bun run build`. For changes that affect rendering or input,
+verify in the real browser — `bun run dev` plus a Playwright check (the game
+boots, the canvas renders, no console errors). CI additionally runs the runtime
+gates (`phaser-testing`). A green typecheck alone is not proof a game works.
+</content>
+</invoke>

package/plugins/lisa-phaser-copilot/skills/phaser-accessibility/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: phaser-accessibility
+description: This skill should be used when making a Phaser 4 game accessible — honoring prefers-reduced-motion, pausing on window/tab blur, keyboard navigation and visible focus for menus, colorblind-safe palettes, and a screen-reader live region that announces game state through the DOM. Use it when building menus, settings, HUD, or any player-facing UI, or when an accessibility requirement comes up. Pairs with phaser-services, phaser-i18n, and phaser-scenes.
+---
+
+# Phaser 4 Accessibility
+
+## Overview
+
+The canvas is opaque to assistive tech, so accessibility is something you build
+in, not get for free. Five pillars carry most of the value: respect
+`prefers-reduced-motion`, pause when the window loses focus, make menus fully
+keyboard-navigable with visible focus, use colorblind-safe palettes, and mirror
+game state into a DOM **live region** for screen readers. These wire through the
+shared services ([[phaser-services]]) and use translated strings ([[phaser-i18n]]).
+
+## prefers-reduced-motion
+
+Read the media query once and gate non-essential motion (screen shake, parallax,
+big tweens, particle bursts) behind it. Reduced motion means "convey the same
+information with less movement", not "remove feedback".
+
+```ts
+// src/services/a11y.ts
+export const reduceMotion = window.matchMedia("(prefers-reduced-motion: reduce)").matches;
+
+// in a scene
+if (!reduceMotion) this.cameras.main.shake(120, 0.004);
+this.tweens.add({ targets: panel, alpha: 1, duration: reduceMotion ? 0 : 250 });
+```
+
+Expose it as a togglable setting too (some players want it on regardless of OS),
+stored via SaveService ([[phaser-services]]).
+
+## Pause on blur
+
+A game that keeps running while the tab is hidden drains battery, desyncs audio,
+and is hostile to players who switch away. Phaser already exposes blur/focus
+events — pause the loop and audio, resume on focus.
+
+```ts
+this.game.events.on(Phaser.Core.Events.BLUR, () => { this.scene.pause(); this.sound.pauseAll(); });
+this.game.events.on(Phaser.Core.Events.FOCUS, () => { this.scene.resume(); this.sound.resumeAll(); });
+```
+
+Set `Phaser.Types.Core.GameConfig.autoFocus` and `disableContextMenu` as needed.
+(These are listeners — remove them in `shutdown` per the on/off discipline in
+[[phaser-services]].) For competitive/timed play, pausing on blur is also the
+fair behavior.
+
+## Keyboard navigation and visible focus
+
+Every menu must be operable without a pointer: arrow keys / Tab move focus, Enter
+or Space activates, Escape backs out. Keep a focus index over a typed list of
+items and render an unmistakable focus indicator (outline/scale, not color alone).
+
+```ts
+private items: MenuItem[] = [];
+private focus = 0;
+
+private move(delta: number) {
+  this.items[this.focus].setFocused(false);
+  this.focus = Phaser.Math.Wrap(this.focus + delta, 0, this.items.length);
+  this.items[this.focus].setFocused(true);          // visible outline + announce
+  this.announce(this.items[this.focus].label);
+}
+create() {
+  this.input.keyboard!.on("keydown-DOWN", () => this.move(1));
+  this.input.keyboard!.on("keydown-UP",   () => this.move(-1));
+  this.input.keyboard!.on("keydown-ENTER",() => this.items[this.focus].activate());
+}
+```
+
+Use the semantic InputService actions ([[phaser-services]]) so the same bindings
+serve gamepad and touch. Never rely on hover-only affordances.
+
+## Colorblind-safe palettes
+
+Never encode meaning in hue alone — pair every color cue with a shape, icon,
+label, or pattern (red enemy *and* a spike icon; green/red status *and* a check/x).
+Choose palettes that stay distinguishable across deuteranopia/protanopia
+/tritanopia, and offer a colorblind palette option in settings.
+
+```ts
+// src/logic/palette.ts — pure, testable, no phaser import
+export const palettes = {
+  default: { ally: 0x2e7d32, enemy: 0xc62828, neutral: 0xf9a825 },
+  deuter:  { ally: 0x0072b2, enemy: 0xd55e00, neutral: 0xf0e442 }, // Okabe–Ito, CB-safe
+} as const;
+```
+
+Keep palette selection in `src/logic/**` so contrast/choice logic is unit-tested,
+and store the player's choice via SaveService.
+
+## Screen-reader live region
+
+Mirror important state changes into an ARIA live region in the DOM (outside the
+canvas) so screen readers announce them. One polite region for status, one
+assertive for urgent events.
+
+```html
+<!-- index.html, alongside the game container -->
+<div id="sr-status" aria-live="polite"   class="sr-only"></div>
+<div id="sr-alert"  aria-live="assertive" class="sr-only"></div>
+```
+
+```ts
+// src/services/a11y.ts
+const status = document.getElementById("sr-status")!;
+export function announce(msg: string, urgent = false) {
+  const el = urgent ? document.getElementById("sr-alert")! : status;
+  el.textContent = ""; el.textContent = msg; // clear+set so identical repeats re-announce
+}
+```
+
+Announce menu focus, score milestones, level changes, and game-over. Messages
+come from the i18n catalog ([[phaser-i18n]]) — never hardcoded — and `.sr-only`
+keeps the region visually hidden but readable by AT.
+
+## Project conventions
+
+- A11y plumbing lives in `src/services/a11y.ts`; palette/choice logic lives in
+  `src/logic/**` (unit-tested).
+- Accessibility settings (reduced motion, colorblind palette) persist via
+  SaveService and apply on boot ([[phaser-services]]).
+- All announced/visible text comes from the i18n catalog ([[phaser-i18n]]).
+
+## Verification
+
+Verified by manual passes that double as runtime checks: tab through every menu
+with the pointer unplugged and confirm visible focus + activation; set the OS to
+reduce-motion and confirm shake/parallax stop while feedback remains; blur the
+tab and confirm the game pauses and audio stops; and run a screen reader (VoiceOver
+/NVDA) to confirm the live region announces menu focus and game state.
+</content>

package/plugins/lisa-phaser-copilot/skills/phaser-asset-pipeline/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: phaser-asset-pipeline
+description: This skill should be used when setting up or changing the build-time asset pipeline of a Phaser 4 game — packing raw art in assets/src into public/assets (free-tex-packer-core texture atlases, audiosprite audio sprites, BMFont bitmap fonts) and the codegen step that emits typed keys to src/assets.ts so a missing or renamed key is a compile error. Use it when adding source art, wiring packing into the build, regenerating typed keys, or eliminating raw string asset keys. Pairs with phaser-assets, phaser-build-deploy, and phaser-services.
+---
+
+# Phaser 4 Asset Pipeline
+
+## Overview
+
+Runtime assets are **generated, not hand-placed**. Raw source art lives in
+`assets/src/**` (PNGs, audio, font sources); a build step packs it into
+`public/assets/**` (atlases, audio sprites, bitmap fonts) and **codegens typed
+key constants into `src/assets.ts`**. The payoff: a missing or renamed asset is a
+**compile error**, not a green square or silent-missing audio at runtime. No raw
+string asset / scene / event keys anywhere — they all come from the generated
+module ([[phaser-assets]] covers loading those keys at runtime).
+
+## Layout
+
+| Path | Role |
+| --- | --- |
+| `assets/src/sprites/**` | Raw individual PNGs — the art source of truth |
+| `assets/src/audio/**` | Raw audio clips (wav/ogg sources) |
+| `assets/src/fonts/**` | Font sources for BMFont generation |
+| `public/assets/**` | **Generated** packed output (atlases, audiosprites, fonts, `pack.json`) — git-ignored or committed as a build artifact |
+| `src/assets.ts` | **Generated** typed key constants — never edited by hand |
+| `scripts/pack-assets.mjs` | The pipeline driver (runs the three packers + codegen) |
+
+## Step 1: texture atlases with free-tex-packer-core
+
+`free-tex-packer-core` packs many PNGs into atlas pages plus a JSON manifest, in
+a Node script (no GUI, runs in CI):
+
+```js
+// scripts/pack-assets.mjs (excerpt)
+import { packAsync } from "free-tex-packer-core";
+import { glob } from "glob";
+import { readFile, writeFile } from "node:fs/promises";
+
+const images = await Promise.all(
+  (await glob("assets/src/sprites/**/*.png")).map(async p => ({
+    path: p.replace("assets/src/sprites/", ""), contents: await readFile(p),
+  })));
+
+const files = await packAsync(images, {
+  textureName: "game", width: 2048, height: 2048,
+  padding: 2, allowRotation: false, allowTrim: true,
+  exporter: "JsonHash", removeFileExtension: true,
+});
+for (const f of files) await writeFile(`public/assets/atlases/${f.name}`, f.buffer ?? f.content);
+```
+
+The frame names in the manifest become the atlas frame keys you reference as
+generated constants. Atlas everything that renders together — loose images break
+sprite batching ([[phaser-assets]]).
+
+## Step 2: audio sprites with audiosprite
+
+`audiosprite` concatenates short SFX into one file (in multiple codecs) plus a
+JSON map of `{ start, end }` per clip — one request, one decode, instead of dozens:
+
+```jsonc
+// package.json script
+"pack:audio": "audiosprite --output public/assets/audio/sfx --export ogg,m4a --format howler2 assets/src/audio/*.wav"
+```
+
+Provide at least two codecs (`ogg` + `m4a`) so every browser can play one. Load
+with `this.load.audioSprite(Audio.Sfx, "audio/sfx.json")` and play by sprite key.
+
+## Step 3: bitmap fonts with BMFont
+
+`BitmapText` is the performant choice for high-churn text (scores, timers) —
+[[phaser-assets]] / [[phaser-i18n]]. Generate the `.fnt` (XML/JSON) + PNG page
+from a font source with a BMFont tool (`msdf-bmfont-xml` or the `bmfont` CLI) in
+the same script:
+
+```jsonc
+"pack:font": "msdf-bmfont -o public/assets/fonts/ui --font-size 42 --texture-size 1024 1024 assets/src/fonts/ui.ttf"
+```
+
+Load with `this.load.bitmapFont(Font.UI, "fonts/ui.png", "fonts/ui.fnt")`.
+
+## Step 4: codegen typed keys into `src/assets.ts`
+
+After packing, walk the generated manifests and emit `as const` key maps. This is
+the step that turns runtime failures into compile failures:
+
+```js
+// scripts/pack-assets.mjs (codegen excerpt)
+const atlas = JSON.parse(await readFile("public/assets/atlases/game.json", "utf8"));
+const frames = Object.keys(atlas.frames); // raw keys, e.g. "player/idle"
+const sfx = Object.keys(JSON.parse(await readFile("public/assets/audio/sfx.json","utf8")).spritemap);
+
+const out = `// AUTO-GENERATED by scripts/pack-assets.mjs — do not edit.
+export const Tex = { GameAtlas: "game" } as const;
+export const Frame = { ${frames.map(k => `${toIdent(k)}: "${k}"`).join(", ")} } as const;
+export const Audio = { Sfx: "sfx" } as const;
+export const Sfx = { ${sfx.map(s => `${toIdent(s)}: "${s}"`).join(", ")} } as const;
+export const Font = { UI: "ui" } as const;
+export const SceneKeys = { Boot:"Boot", Preloader:"Preloader", MainMenu:"MainMenu", Game:"Game" } as const;
+export const GameEvent = { ScoreChanged:"score-changed", EnemyDied:"enemy-died" } as const;
+`;
+await writeFile("src/assets.ts", out);
+```
+
+Scenes import `Tex`, `Frame`, `Sfx`, `Font`, `SceneKeys`, `GameEvent` — never an
+inline string. Rename art, re-run the pipeline, and every now-stale reference
+fails `bun run typecheck` immediately. (Scene/event keys are kept in the same
+generated module so they share the no-raw-string discipline; edit them via the
+codegen template, not by hand.)
+
+## Step 5: wire into the build
+
+The pipeline runs before dev and before build so generated output is never stale:
+
+```jsonc
+// package.json
+"scripts": {
+  "assets": "node scripts/pack-assets.mjs",
+  "predev":   "bun run assets",
+  "prebuild": "bun run assets",
+  "dev":   "vite",
+  "build": "vite build"
+}
+```
+
+For fast iteration, a `--watch` mode on the pack script re-packs changed source
+art. In CI the pack step runs once before `vite build`; the build then hashes the
+generated files for immutable caching ([[phaser-build-deploy]]).
+
+## Project conventions
+
+- `assets/src/**` is the source of truth; `public/assets/**` and `src/assets.ts`
+  are generated — treat them as build output (re-runnable, not hand-edited).
+- One atlas per render group, one audiosprite per SFX set, BMFont for hot text.
+- A contract test asserts every constant in `src/assets.ts` resolves to an entry
+  in the generated `pack.json`/manifests ([[phaser-testing]]).
+- The generated `src/assets.ts` is the single source of asset/scene/event keys —
+  the no-raw-string-keys rule depends on it existing.
+
+## Verification
+
+The pipeline is verified by deleting a source PNG and re-running `bun run assets`:
+the corresponding generated constant disappears and `bun run typecheck` fails at
+every use site (proving keys are compile-checked). Then boot the game and confirm
+the atlas/audiosprite/font load with no `FILE_LOAD_ERROR` and render/play
+correctly.
+</content>