@codyswann/lisa 2.178.6 → 2.179.0

package/plugins/lisa-phaser-copilot/skills/phaser-build-deploy/SKILL.md

@@ -0,0 +1,148 @@
+---
+name: phaser-build-deploy
+description: This skill should be used when configuring the production build or deploying a Phaser 4 game — the Vite prod config (manualChunks to split the phaser vendor chunk, terser two-pass minification), content-hashed assets with immutable caching, the base path per host, vite-plugin-pwa (autoUpdate + globPatterns covering game assets), a bundle-size budget, and static hosting. Use it when setting up the build, fixing caching/base-path issues, adding the PWA, or enforcing bundle size. Pairs with phaser-asset-pipeline, phaser-project-structure, and phaser-testing.
+---
+
+# Phaser 4 Build and Deploy
+
+## Overview
+
+The game ships as static files built by **Vite** (with TypeScript 6, `phaser`
+pinned `^4.2.0`). A good prod build does four things: split the large `phaser`
+vendor chunk so app code can change without re-downloading the engine, minify
+hard, content-hash everything for immutable caching, and register a PWA service
+worker that precaches game assets. A bundle-size budget keeps the result honest.
+The asset pipeline ([[phaser-asset-pipeline]]) runs first; this skill packages
+its output.
+
+## Vite production config
+
+```ts
+// vite.config.ts
+import { defineConfig } from "vite";
+import { VitePWA } from "vite-plugin-pwa";
+
+export default defineConfig({
+  base: process.env.BASE_PATH ?? "/",   // "/" for root domains, "/repo/" for project pages
+  build: {
+    target: "es2022",
+    assetsInlineLimit: 0,               // never inline game assets — keep them cacheable files
+    minify: "terser",
+    terserOptions: { compress: { passes: 2, drop_console: true }, format: { comments: false } },
+    rollupOptions: {
+      output: {
+        manualChunks: { phaser: ["phaser"] },          // engine in its own long-lived chunk
+        entryFileNames: "assets/[name]-[hash].js",      // content hash on everything
+        chunkFileNames: "assets/[name]-[hash].js",
+        assetFileNames: "assets/[name]-[hash][extname]",
+      },
+    },
+  },
+});
+```
+
+`manualChunks: { phaser: ["phaser"] }` is the single highest-value line: Phaser is
+hundreds of KB and rarely changes, so isolating it means a gameplay tweak only
+busts the small app chunk. Two-pass terser squeezes meaningfully more than one.
+
+## Asset hashing and immutable caching
+
+Every emitted file carries a content hash, so it can be cached forever and a
+change produces a new filename (cache-busted automatically):
+
+```
+/assets/index-3f2a.js        Cache-Control: public, max-age=31536000, immutable
+/assets/phaser-9b1c.js       Cache-Control: public, max-age=31536000, immutable
+/index.html                  Cache-Control: no-cache   (must revalidate to pick up new hashes)
+```
+
+`index.html` is the only file served `no-cache` — it points at the hashed assets,
+so revalidating it is enough to roll the whole app forward. Game assets under
+`public/assets/**` ([[phaser-asset-pipeline]]) are hashed by the PWA precache
+manifest below even though Vite copies them verbatim.
+
+## Base path per host
+
+`base` must match where the game is served:
+
+- Root domain / custom domain → `base: "/"`.
+- GitHub Pages project site → `base: "/<repo>/"`.
+- Subpath behind a reverse proxy → that subpath.
+
+A wrong `base` is the classic "works on `bun run dev`, blank canvas on deploy"
+bug — assets 404 because the URLs are absolute to the wrong root. Drive it from an
+env var so the same build config serves every host.
+
+## PWA: vite-plugin-pwa (on by default)
+
+The PWA is on by default: install-to-home-screen, offline play, and auto-update.
+`registerType: "autoUpdate"` ships new versions without a manual prompt; the
+critical part is extending `globPatterns` to precache **game assets** (atlases,
+audio sprites, fonts) — the Workbox default only catches JS/CSS/HTML and would
+leave a "installed but can't load its art offline" game.
+
+```ts
+VitePWA({
+  registerType: "autoUpdate",
+  includeAssets: ["favicon.svg"],
+  workbox: {
+    globPatterns: ["**/*.{js,css,html,png,jpg,svg,webp,woff2,json,fnt,mp3,m4a,ogg}"],
+    // critically include packed game assets:
+    globDirectory: "dist",
+    additionalManifestEntries: [],     // or widen globPatterns to assets/**/*.{png,json,fnt,ogg,m4a}
+    maximumFileSizeToCacheInBytes: 8 * 1024 * 1024, // raise above default 2MB for atlas pages
+  },
+  manifest: { name: "Game", short_name: "Game", display: "fullscreen", orientation: "landscape",
+              background_color: "#000000", theme_color: "#000000", icons: [/* 192/512 */] },
+})
+```
+
+Set `maximumFileSizeToCacheInBytes` above the default 2 MB or large atlas pages
+silently fall out of the precache.
+
+## Bundle-size budget
+
+A byte budget, checked after `bun run build`, fails the PR when a stray dependency
+or an un-split engine chunk bloats the download. This is the same budget the
+bundle-size gate in [[phaser-testing]] enforces in CI.
+
+```jsonc
+// size-limit config (or a custom post-build check)
+[
+  { "name": "app",    "path": "dist/assets/index-*.js",  "limit": "60 kB" },
+  { "name": "phaser", "path": "dist/assets/phaser-*.js", "limit": "400 kB" }
+]
+```
+
+Separate budgets per chunk catch the right regressions: app growth from your code
+vs. an accidental second copy of a big dependency landing in the phaser chunk.
+
+## Static deploy
+
+Output is plain static files in `dist/` — host on any static CDN (GitHub Pages,
+Netlify, Cloudflare Pages, S3+CloudFront). Requirements: serve over HTTPS (PWA +
+Web Audio expect a secure context), set the cache headers above (immutable for
+hashed assets, no-cache for `index.html`), and for client-routed builds add an
+SPA fallback to `index.html`. Build with the host's base path:
+
+```bash
+BASE_PATH=/my-game/ bun run build   # then publish dist/
+```
+
+## Project conventions
+
+- Run the asset pipeline before the build (`prebuild`) so `public/assets/**` and
+  `src/assets.ts` are current ([[phaser-asset-pipeline]]).
+- `phaser` is always its own manualChunk; never let it merge into the app chunk.
+- `base` comes from an env var, never hardcoded to one host.
+- The bundle-size budget is committed and CI-gated ([[phaser-testing]]).
+- Build pins: `phaser ^4.2.0`, Vite, TypeScript 6.
+
+## Verification
+
+Verified by `bun run build` succeeding under the size budget, then `bun run
+preview` (served at the deploy `base`) booting the game with no 404s and no
+console errors. Confirm the PWA registers (Application → Service Workers), load
+once online then go offline and reload to confirm assets are precached, and
+confirm a redeploy auto-updates clients without a manual cache clear.
+</content>

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

@@ -0,0 +1,122 @@
+---
+name: phaser-i18n
+description: This skill should be used when localizing a Phaser 4 game — a typed string catalog so no user-facing text is hardcoded, runtime locale switching that re-renders open text, interpolation/pluralization, and the BitmapText vs Text trade-offs (glyph coverage, RTL, CJK) localization forces. Use it when adding any player-facing string, building a language selector, or fixing missing-glyph/hardcoded-text issues. Pairs with phaser-services, phaser-accessibility, and phaser-asset-pipeline.
+---
+
+# Phaser 4 Internationalization
+
+## Overview
+
+No user-facing string is hardcoded in a scene. All player-visible text comes from
+a **typed string catalog** keyed by typed constants, so a missing or misspelled
+key is a compile error and every string has a home for translation. The catalog
+is a small typed wrapper (no heavy dependency required); locale switching
+re-renders any open text. Announced strings ([[phaser-accessibility]]) and
+service messages ([[phaser-services]]) draw from the same catalog.
+
+## The typed catalog
+
+One module owns the locales and the lookup. The key type is derived from the
+default locale so every locale must cover the same keys:
+
+```ts
+// src/i18n/catalog.ts
+const en = {
+  "menu.play": "Play",
+  "menu.settings": "Settings",
+  "hud.score": "Score: {score}",
+  "result.cleared": "Level {level} cleared!",
+  "lives": "{n} life|{n} lives",     // singular|plural
+} as const;
+
+const es: Record<keyof typeof en, string> = {
+  "menu.play": "Jugar", "menu.settings": "Ajustes",
+  "hud.score": "Puntos: {score}", "result.cleared": "¡Nivel {level} superado!",
+  "lives": "{n} vida|{n} vidas",
+};
+
+export type StringKey = keyof typeof en;
+const locales = { en, es } as const;
+export type Locale = keyof typeof locales;
+```
+
+## The `t()` function: interpolation + pluralization
+
+```ts
+// src/i18n/i18n.ts
+let current: Locale = "en";
+export function setLocale(l: Locale) { current = l; EventCenter.emit(GameEvent.LocaleChanged); }
+export function getLocale() { return current; }
+
+export function t(key: StringKey, params?: Record<string, string | number>): string {
+  let s = (locales[current][key] ?? locales.en[key]) as string;   // fall back to en, never crash
+  if (s.includes("|") && params && "n" in params)                 // pick plural form
+    s = (Number(params.n) === 1 ? s.split("|")[0] : s.split("|")[1]);
+  return s.replace(/\{(\w+)\}/g, (_, k) => String(params?.[k] ?? `{${k}}`));
+}
+```
+
+Usage is always `t(...)` with a typed key — never a raw string in a scene:
+
+```ts
+this.add.bitmapText(x, y, Font.UI, t("hud.score", { score: 0 }));
+this.announce(t("result.cleared", { level }));  // [[phaser-accessibility]] live region
+```
+
+The plural/interpolation rules are pure functions — put them in `src/logic/**`
+so Vitest covers them ([[phaser-testing]]).
+
+## Locale switching at runtime
+
+Changing language must update text that is already on screen. Emit a
+`LocaleChanged` event on the EventsCenter ([[phaser-services]]); each scene with
+visible text subscribes and re-applies `t()` to its labels, then removes the
+listener in `shutdown` (the on/off discipline).
+
+```ts
+create() {
+  const refresh = () => this.scoreText.setText(t("hud.score", { score: this.score }));
+  EventCenter.on(GameEvent.LocaleChanged, refresh);
+  this.events.once(Phaser.Scenes.Events.SHUTDOWN, () => EventCenter.off(GameEvent.LocaleChanged, refresh));
+}
+```
+
+Persist the chosen locale via SaveService and apply it on boot; default from
+`navigator.language` when there is no saved choice.
+
+## BitmapText vs Text — the localization trade-off
+
+The performance advice "use BitmapText for hot text" ([[phaser-gameobjects]])
+collides with i18n: a bitmap font only contains the glyphs it was generated with.
+
+- **BitmapText** — fastest, but the BMFont must include every glyph the locale
+  needs. Fine for digits/Latin HUD; generate per-script font pages
+  ([[phaser-asset-pipeline]]) if you ship CJK/Cyrillic/etc. via BitmapText.
+- **Text** (canvas) — renders any glyph the loaded web font supports, handles
+  diacritics and combining marks, and is the safe choice for arbitrary
+  translated body text and user-generated content. Cost is rasterization per
+  change, so it is for static/low-churn strings.
+
+Rule of thumb: BitmapText for high-churn numeric/short HUD with a covered glyph
+set; Text for translated prose and any locale whose script the bitmap font does
+not include. For RTL locales (Arabic/Hebrew), use canvas `Text` with
+`rtl: true`/right alignment and lay out mirrored — BitmapText does not shape RTL.
+
+## Project conventions
+
+- Every player-facing string is a `t(StringKey, …)` call — no inline literals in
+  scenes/entities (this mirrors the no-raw-string-keys discipline).
+- The default locale defines the key type; other locales must satisfy it
+  (compile error on a missing key).
+- Interpolation/plural logic lives in `src/logic/**`; the catalog and `t()` live
+  in `src/i18n/**`.
+- Locale persists via SaveService and is announced through the live region for
+  screen-reader users ([[phaser-accessibility]]).
+
+## Verification
+
+Verified by switching locale at runtime and confirming on-screen text updates
+live (no reload), a missing key fails `bun run typecheck`, and pluralization unit
+tests pass for n=0/1/many. For non-Latin locales, confirm glyphs render (no tofu
+boxes) — that is the signal you need a per-script BMFont page or canvas Text.
+</content>

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

@@ -0,0 +1,208 @@
+---
+name: phaser-services
+description: This skill should be used when wiring cross-cutting services and shared state in a Phaser 4 game — the typed registry wrapper for global state, a single dedicated EventsCenter bus (never game.events), the .on()/.off() listener discipline enforced in scene shutdown, SoundService (mobile audio unlock on first gesture), InputService (semantic actions instead of raw keys), and SaveService (versioned localStorage with a migration chain). Use it when adding global state, an event bus, audio/input/save plumbing, or fixing listener leaks and lost saves. Pairs with phaser-scenes, phaser-testing, and phaser-i18n.
+---
+
+# Phaser 4 Services and Shared State
+
+## Overview
+
+Cross-cutting concerns — global state, app events, sound, input, save — live in
+`src/services/**` as thin, typed singletons, **not** scattered through scenes.
+Two rules anchor everything: state flows through a typed registry wrapper, and
+app messaging flows through **one dedicated EventsCenter** that is never
+`game.events`. Direct `localStorage` access outside `src/services/**` is
+lint-banned — persistence goes through SaveService.
+
+## Global state: a typed wrapper over the registry
+
+`this.registry` is a game-wide key/value `DataManager` shared across scenes. Raw
+access is stringly-typed and untestable, so wrap it once:
+
+```ts
+// src/services/state.ts
+interface GameState { coins: number; level: number; muted: boolean; seed: number; }
+const DEFAULTS: GameState = { coins: 0, level: 1, muted: false, seed: 0 };
+
+export class GameStore {
+  constructor(private reg: Phaser.Data.DataManager) {
+    for (const k in DEFAULTS) if (!reg.has(k)) reg.set(k, (DEFAULTS as any)[k]);
+  }
+  get<K extends keyof GameState>(k: K): GameState[K] { return this.reg.get(k); }
+  set<K extends keyof GameState>(k: K, v: GameState[K]) { this.reg.set(k, v); }
+  onChange<K extends keyof GameState>(k: K, fn: (v: GameState[K]) => void) {
+    const h = (_p: unknown, key: string, v: GameState[K]) => { if (key === k) fn(v); };
+    this.reg.events.on(Phaser.Data.Events.CHANGE_DATA, h);
+    return () => this.reg.events.off(Phaser.Data.Events.CHANGE_DATA, h); // caller .off()s in shutdown
+  }
+}
+```
+
+Construct it once (in Boot) and read it via the registry. Keys are typed by
+`GameState`, so a typo is a compile error. The registry holds *small* shared
+state (settings, run seed, currency) — not GameObjects and not per-frame data.
+
+## The EventsCenter bus (never `game.events`)
+
+App-level messaging ("enemy-died", "score-changed", "level-cleared") uses a
+single dedicated emitter. Reusing `game.events` (the engine's own bus) is
+lint-banned — it mixes your events with engine lifecycle events and is
+impossible to fully tear down.
+
+```ts
+// src/services/event-center.ts
+export const EventCenter = new Phaser.Events.EventEmitter();
+
+// typed key constants come from src/assets.ts (generated) — no raw strings
+import { GameEvent } from "../assets";
+EventCenter.emit(GameEvent.ScoreChanged, score);
+```
+
+## Listener discipline: every `.on()` has a matching `.off()`
+
+This is the leak rule the `require-shutdown-cleanup` lint rule and the testing
+leak gate ([[phaser-testing]]) enforce. **Any** external listener — `EventCenter`,
+`this.input`, `this.scale`, `this.time`, `window`, the registry — must be removed
+in the scene's `shutdown`. Listeners on the scene's own display objects die with
+the scene; external ones do not, and they fire again (doubled) after a restart.
+
+```ts
+export class Game extends Phaser.Scene {
+  private cleanups: Array<() => void> = [];
+
+  create() {
+    const onResize = (s: Phaser.Structs.Size) => this.layout(s.width, s.height);
+    this.scale.on(Phaser.Scale.Events.RESIZE, onResize);
+    this.cleanups.push(() => this.scale.off(Phaser.Scale.Events.RESIZE, onResize));
+
+    const onScore = (n: number) => this.hud.setScore(n);
+    EventCenter.on(GameEvent.ScoreChanged, onScore);
+    this.cleanups.push(() => EventCenter.off(GameEvent.ScoreChanged, onScore));
+
+    this.events.once(Phaser.Scenes.Events.SHUTDOWN, this.shutdown, this);
+  }
+
+  shutdown() { this.cleanups.forEach(fn => fn()); this.cleanups.length = 0; }
+}
+```
+
+Keeping the matching `.off()` next to each `.on()` (a `cleanups` array, or named
+handler methods you remove in `shutdown`) is the pattern that survives the leak
+gate. Prefer `.once()` where a listener should fire only once.
+
+## SoundService — audio unlock on first gesture
+
+Web Audio starts **suspended** until a user gesture; sound played before then is
+silently dropped ("works on my machine, silent on the phone"). Centralize the
+unlock and all playback:
+
+```ts
+// src/services/sound-service.ts
+export class SoundService {
+  private unlocked = false;
+  constructor(private sound: Phaser.Sound.BaseSoundManager, private store: GameStore) {}
+
+  attachUnlock(scene: Phaser.Scene) {
+    if (this.unlocked) return;
+    scene.input.once(Phaser.Input.Events.POINTER_DOWN, () => this.resume());
+    // Phaser also fires its own unlock; resume() is idempotent
+    this.sound.once(Phaser.Sound.Events.UNLOCKED, () => this.resume());
+  }
+  private resume() { if ((this.sound as any).context?.state === "suspended") (this.sound as any).context.resume(); this.unlocked = true; }
+  play(key: string, cfg?: Phaser.Types.Sound.SoundConfig) { if (!this.store.get("muted")) this.sound.play(key, cfg); }
+}
+```
+
+Scenes call `soundService.play(Sfx.Jump)` — never `this.sound.play("jump")`.
+Sound keys are generated constants ([[phaser-asset-pipeline]]).
+
+## InputService — semantic actions, not raw keys
+
+Scenes should ask "is *jump* down?", not "is the spacebar down?". A semantic
+layer makes rebinding, gamepads, and touch swap in without touching game code,
+and keeps replays deterministic (record actions, not hardware).
+
+```ts
+// src/services/input-service.ts
+export type Action = "left" | "right" | "jump" | "fire" | "pause";
+
+export class InputService {
+  private down = new Set<Action>();
+  private bindings: Record<number, Action> = {};
+  constructor(kb: Phaser.Input.Keyboard.KeyboardPlugin) {
+    this.bindings[Phaser.Input.Keyboard.KeyCodes.LEFT] = "left";
+    this.bindings[Phaser.Input.Keyboard.KeyCodes.SPACE] = "jump";
+    kb.on("keydown", (e: KeyboardEvent) => { const a = this.bindings[e.keyCode]; if (a) this.down.add(a); });
+    kb.on("keyup",   (e: KeyboardEvent) => { const a = this.bindings[e.keyCode]; if (a) this.down.delete(a); });
+  }
+  isDown(a: Action) { return this.down.has(a); }
+  snapshot(): readonly Action[] { return [...this.down]; } // for replay capture
+}
+```
+
+`update()` reads `input.isDown("jump")` and forwards the action set to pure logic
+in `src/logic/**`. (Register/remove the keyboard listeners with the same on/off
+discipline above.)
+
+## SaveService — versioned localStorage with a migration chain
+
+Raw `localStorage` outside `src/services/**` is lint-banned. Saves carry a schema
+`VERSION`; on load, unknown-but-older saves run forward through a migration chain,
+so an old player's data is never silently lost or crash-loaded.
+
+```ts
+// src/services/save-service.ts
+const KEY = "save:v"; const VERSION = 3;
+interface SaveV3 { version: 3; coins: number; unlocked: string[]; settings: { muted: boolean } }
+
+const migrations: Record<number, (s: any) => any> = {
+  1: s => ({ ...s, unlocked: [], version: 2 }),                 // v1 -> v2
+  2: s => ({ ...s, settings: { muted: false }, version: 3 }),  // v2 -> v3
+};
+
+export class SaveService {
+  load(): SaveV3 {
+    const raw = localStorage.getItem(KEY);                 // only legal localStorage access lives here
+    if (!raw) return this.fresh();
+    try {
+      let s = JSON.parse(raw);
+      while (s.version < VERSION) s = migrations[s.version](s);
+      return s as SaveV3;
+    } catch { return this.fresh(); }                       // corrupt save -> fresh, never crash
+  }
+  save(s: SaveV3) { localStorage.setItem(KEY, JSON.stringify({ ...s, version: VERSION })); }
+  private fresh(): SaveV3 { return { version: VERSION, coins: 0, unlocked: [], settings: { muted: false } }; }
+}
+```
+
+Bump `VERSION` and add the `n -> n+1` migration whenever the shape changes; never
+mutate the read path to "just handle" an old shape inline.
+
+## Errors and telemetry
+
+A vendor-neutral telemetry/analytics abstraction (`src/services/telemetry.ts`)
+exposes `track(event, props)` and `captureError(err, ctx)` behind a stable
+interface so the concrete sink (PostHog, Sentry, none) swaps without touching
+game code. Wire Phaser's error surfaces to it — `window.onerror`, the loader's
+`FILE_LOAD_ERROR`, and `try/catch` around scene transitions all route to
+`captureError`. Strings shown to players come from the i18n catalog
+([[phaser-i18n]]), never hardcoded.
+
+## Project conventions
+
+- Services live in `src/services/**`; that directory is the **only** place raw
+  `localStorage` is permitted.
+- One EventsCenter instance, exported once; never `game.events` for app events.
+- Every external `.on()` is paired with an `.off()` removed in `shutdown` (lint:
+  `require-shutdown-cleanup`; verified by the leak gate in [[phaser-testing]]).
+- Service logic that is pure (migrations, action mapping, mute gating) belongs in
+  or beside `src/logic/**` so Vitest covers it.
+
+## Verification
+
+Services are verified by the runtime gates: the leak gate ([[phaser-testing]])
+proves listeners are removed (start/stop a scene N times, counts return to
+baseline); a SaveService unit test feeds each old version through the migration
+chain and asserts the current shape; and on a real phone, the first tap unlocks
+audio (sound plays) — confirm before committing.
+</content>

package/plugins/lisa-phaser-copilot/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-cursor/.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"