@codyswann/lisa 2.178.6 → 2.179.0

package/plugins/lisa-phaser-agy/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>

package/plugins/lisa-phaser-agy/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-agy/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-agy/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>