@codyswann/lisa 2.195.4 → 2.195.7

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

@@ -0,0 +1,222 @@
+---
+name: phaser-asset-pipeline
+description: "setting up or changing the…"
+---
+
+# Phaser 4 Asset Pipeline
+
+## Where the raw art comes from (read this first)
+
+This skill **packs** raw art; it does not conjure it. The inputs under
+`assets/src/**` are **real, licensed source art you sourced first** — they do not
+magically pre-exist, and they are not procedural `generateTexture` rectangles.
+Before you can pack anything, use **[[phaser-asset-sourcing]]**: it covers where
+game art comes from (curated CC0 packs like Kenney and Ninja Adventure → deriving
+CC0 art → asking the human), the strict CC0-or-equivalent license gate with
+`assets/LICENSES.md` evidence, provenance via a committed ingest script, and why
+`generateTexture` placeholders are tracked art debt rather than a finished state.
+The rule of thumb: **source → `assets/src` → pack (this skill) → typed keys.**
+
+## Overview
+
+The pipeline turns committed source art into runtime form — it is a build step,
+not a substitute for having art. 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 (the
+official `loading-assets` skill covers loading those keys at runtime).
+
+## Layout
+
+| Path | Role |
+| --- | --- |
+| `assets/src/sprites/**` | Raw individual PNGs — the art source of truth (sourced per [[phaser-asset-sourcing]]) |
+| `assets/src/audio/**` | Raw audio clips (wav/ogg sources) |
+| `assets/src/fonts/**` | Font sources for BMFont generation |
+| `assets/LICENSES.md` | License evidence per source pack (CC0 quote + evidence URL) — see [[phaser-asset-sourcing]] |
+| `scripts/ingest-assets.mjs` | The provenance record — how each frame was carved from its source pack into `assets/src` (re-runnable) |
+| `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: 4096, height: 4096,
+  packer: "MaxRectsPacker", packerMethod: "Smart", // see gotcha below
+  padding: 2, extrude: 1,                            // 1px extrude kills bleeding at integer scales
+  allowRotation: false, allowTrim: false,            // pixel-art-safe (see below)
+  detectIdentical: true,
+  exporter: "JsonHash", removeFileExtension: true, prependFolderName: 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 (the official `loading-assets` skill). Full-screen backdrops and
+parallax layers are the exception: copy them verbatim into `public/assets/images`
+and `load.image` them — they would bloat an atlas. Even this exception keeps the
+no-raw-string promise: the codegen step emits one generated constant per copied
+image (the `Img` record below), and the loader derives the file path from the
+key in exactly one place — a call site never spells out a path string.
+
+**Packer gotcha (verified in the reference implementation):** use
+`packer: "MaxRectsPacker"` with `packerMethod: "Smart"`. The other packer methods
+produce degenerate single-row *strip* atlases that waste enormous texture space
+and can blow past the max texture size. **For pixel art**, set `allowTrim: false`
+and `allowRotation: false`: trimming makes animation frames different sizes so
+anchors swim between frames, and rotation makes Phaser frame-flipping non-trivial.
+Add `extrude: 1` to stop edge bleeding when the game renders at integer scales.
+Keep inputs **sorted** and emit **no timestamps** so the packed output is
+deterministic and can be committed + `git diff --exit-code`-checked in CI.
+
+## 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) —
+the official `loading-assets` skill / [[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 images = (await readdir("public/assets/images", { recursive: true }))
+  .filter(f => f.endsWith(".png")).sort(); // standalone backdrops/parallax layers
+
+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 Img = { ${images.map(p => `${toIdent(p)}: "img-${p.replace(/\.png$/u, "")}"`).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`, `Img`, `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.)
+
+**Animation keys are the one deliberately hand-authored layer.** Codegen cannot
+know how frames group into cycles, so animation keys live in a hand-written
+`as const` record (e.g. `AnimKeys` / `FxAnims`) whose frame sequences are built
+from the generated `Frame` constants — and the contract test below proves every
+frame those definitions reference exists in the committed atlases. The typed-key
+guarantee is therefore: **generated** constants for textures, frames, images,
+audio, and fonts; **hand-authored typed constants + contract-test coverage** for
+animation keys. Nothing is a raw inline string either way.
+
+## 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 frame name the game *derives by convention*
+  (e.g. `battlerWalkFrame(ref, dir, n)`, FX-strip frame lists, per-speaker
+  portrait keys) resolves to a real entry in the committed atlas JSON under
+  `public/assets`. The other constants in `src/assets.ts` (`SceneKeys`,
+  `GameEvent`, `Font`, `Audio`, standalone `Img` entries) are plain generated
+  literals already enforced by TypeScript at every use site, so they don't need
+  a runtime check — only names built at runtime from a pattern can go stale
+  silently without one. This keeps that narrower guarantee honest: a renamed or
+  missing frame fails a headless Vitest assertion instead of rendering a silent
+  black square. The test reads the packed JSON directly — zero Phaser
+  ([[phaser-testing]]):
+
+  ```ts
+  const frames = new Set(Object.keys(
+    JSON.parse(readFileSync("public/assets/atlases/battlers.json", "utf8")).frames));
+  for (const ref of BATTLER_REFS)
+    for (const dir of DIRS) {
+      expect(frames).toContain(battlerIdleFrame(ref, dir));
+      expect(frames).toContain(battlerAttackFrame(ref, dir));
+      for (let n = 0; n < WALK_FRAME_COUNT; n++)
+        expect(frames).toContain(battlerWalkFrame(ref, dir, n));
+    }
+  // ...and one loop per remaining derived family (FX-strip frame lists,
+  // per-speaker portrait keys, …) — the test is only done when EVERY name the
+  // game can derive at runtime has been asserted against the committed atlas.
+  ```
+
+- Ship a `--check` mode on the pack script: it re-packs into a temp staging area
+  and exits non-zero if any committed output under `public/assets` — atlases,
+  standalone images, audio, fonts alike — or `src/assets.ts` is stale, so CI
+  proves the committed artifacts (and every generated key they back) are current.
+- 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/.codex-plugin/skills/phaser-asset-pipeline/agents/openai.yaml

@@ -0,0 +1,4 @@
+display_name: "Phaser Asset Pipeline"
+short_description: "setting up or changing the…"
+default_prompt:
+  - "Use $phaser-asset-pipeline: setting up or changing the…."

package/plugins/lisa-phaser/.codex-plugin/skills/phaser-asset-sourcing/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: phaser-asset-sourcing
+description: "a Phaser 4 game needs actual…"
+---
+
+# Phaser 4 Asset Sourcing
+
+## Why this skill exists
+
+The `phaser-asset-pipeline` skill is **packing-only**: it assumes raw art already
+sits in `assets/src` and turns it into atlases + typed keys. It never says where
+that art comes from. Left to fill the gap, agents reach for the path of least
+resistance — `this.add.graphics().generateTexture(...)` white rectangles — and
+ship a wireframe that *typechecks and boots* but looks like programmer art.
+
+**Procedural placeholders are art debt, not an art strategy.** A shipped game
+needs real, licensed, cohesive assets. This skill is the missing step: how to
+**get** the art before you pack it. Read it *before* `phaser-asset-pipeline`.
+
+## The sourcing decision, in priority order
+
+Work top-down. Only fall to the next tier when the one above genuinely can't
+serve the need.
+
+### 1. Curated CC0 sources (default — reach here first)
+
+Real, cohesive, commercially-usable art exists for free under CC0. These are the
+recommended starting points; all are CC0 or CC0-equivalent (verify per pack —
+see the license gate below):
+
+- **[Kenney.nl](https://kenney.nl/assets)** — hundreds of packs (top-down,
+  platformer, UI, tiles, isometric, audio), **all CC0**. The single best
+  first stop for cohesive, atlas-friendly art.
+- **Pixel-boy & AAA — [Ninja Adventure Asset Pack](https://pixel-boy.itch.io/ninja-adventure-asset-pack)**
+  — a full CC0 JRPG kit: characters with directional idle/walk/attack strips,
+  monsters, tilesets, UI, portraits, FX, and music. Ideal for top-down /
+  RPG-shaped games (this is what the reference implementation uses).
+- **ansimuz (Luis Zuno) — [CC0 packs](https://ansimuz.itch.io/)** — parallax
+  backdrops, environments, effects. Check each pack's license: the base packs
+  are typically CC0; some have paid add-ons that are **not**.
+- **[OpenGameArt.org](https://opengameart.org/)**, **filtered to CC0**
+  (`CC0` in the license facet). Great breadth; licenses are per-submission, so
+  you MUST verify each asset individually — OGA also hosts CC-BY, CC-BY-SA, and
+  GPL art that the license gate rejects.
+- **[itch.io](https://itch.io/game-assets/assets-cc0)** game assets filtered to
+  the CC0 license.
+
+Prefer one or two packs with a shared visual language over a magpie mix — a
+single Kenney pack reads more cohesive than ten sources stitched together (the
+art-director persona will flag the mismatch otherwise).
+
+### 2. Deriving / editing CC0 art (allowed freely)
+
+CC0 waives all rights, so you may recolor, crop, re-slice, retag, upscale
+(nearest-neighbor for pixel art), and recombine freely. This is usually how a
+pack becomes *this game's* assets: slice a sprite sheet into per-frame PNGs,
+rename frames to your content refs, restitch strips. Record exactly how in the
+ingest script (below) so the derivation is reproducible.
+
+### 3. Ask the human (bespoke quality, paid tools, commissioning)
+
+When the art bible demands a bespoke look no CC0 pack delivers — a signature
+character, a specific illustrated style, licensed audio — **stop and ask the
+human**. Do not silently downgrade to placeholders and do not buy/commission on
+your own. Surface the decision:
+
+> "The art direction calls for `<X>`. No CC0 source covers it. Options: (a) adapt
+> the closest CC0 pack `<Y>` and accept the style delta, (b) you provide/approve
+> a paid pack or commission, (c) ship a tracked `generateTexture` placeholder
+> against issue `#NNN` until real art lands. Which?"
+
+Paid assets, CC-BY with attribution, or any non-CC0 license are allowed **only
+with explicit human approval**, recorded in `assets/LICENSES.md` with the terms.
+
+## Hard rules
+
+### License gate — CC0 or equivalent only
+
+- **Accept**: CC0 1.0, public domain dedication, or an explicit "use freely in
+  commercial games, no attribution required" grant equivalent to CC0.
+- **Reject** (unless the human explicitly approves and the terms are recorded):
+  CC-BY (attribution burden), CC-BY-SA / GPL (copyleft — forces your project's
+  license), CC-NC (no commercial), "free for personal use", and anything
+  unlicensed or license-unknown.
+- For **every** pack, record in `assets/LICENSES.md`: the pack name, author,
+  source URL, the exact license, a **verbatim license quote**, and the
+  **evidence URL** where that quote lives (the itch page, the in-pack
+  `LICENSE.txt`, the OGA submission). "It looked free" is not evidence.
+
+```md
+| Pack | Author | Source | License | Evidence |
+|------|--------|--------|---------|----------|
+| Ninja Adventure – Asset Pack | Pixel-boy & AAA | https://pixel-boy.itch.io/ninja-adventure-asset-pack | CC0 1.0 | In-pack `LICENSE.txt` (full CC0 text); itch page "Creative Commons Zero v1.0 Universal" |
+```
+
+### Provenance — the source must be reproducible
+
+The packs themselves are often large and need not be committed, but **how you
+got from a pack to `assets/src` must be**. Two acceptable patterns:
+
+- **Committed ingest script** (`scripts/ingest-assets.mjs`) that records, per
+  frame, which pack / file / cell it came from and re-slices deterministically.
+  Re-running it against a fresh download reproduces `assets/src` byte-for-byte.
+  This is the provenance record — it documents the source layout (e.g. "Ninja
+  Adventure character `Idle.png` is 64×16 = 4 direction cells; `Walk.png` is
+  64×64 = 4 direction columns × 4 walk rows") and doubles as the derivation log.
+- **Committed raw sources** under `assets/src` directly, when the art is small,
+  hand-authored, or already per-frame.
+
+Either way: `assets/LICENSES.md` + a reproducible path from source to
+`assets/src`. Adding art from a **new** source requires both, every time.
+
+### Procedural `generateTexture` placeholders are TRACKED ART DEBT
+
+A scene MAY ship `generateTexture` / `graphics`-drawn placeholder art **only**
+when it is tracked by a linked art-debt issue. It is never the finished state,
+and it is never described as a best practice. In particular:
+
+- **Never** write comments like "zero binary assets, zero licensing risk" as if
+  placeholders were the goal. They are a temporary stand-in, and that framing is
+  exactly what produced wireframe games.
+- Keep a visible ledger of the debt (e.g. a `LEGACY_GENERATED_TEXTURE_KEYS` map
+  in the pack script, or a checklist in the issue) and delete each entry the
+  moment the real asset lands.
+- The art-director persona treats a placeholder-only scene as a **blocking**
+  finding (see its review checklist).
+
+### Characters get real animation
+
+Static single-frame sprites are a placeholder smell. A character/creature ships
+at minimum an **idle** and a **walk** cycle; most CC0 character packs already
+provide directional idle/walk/attack strips, so there is no excuse to ship a
+frozen frame. Name frames so the pipeline and the official **`animations`**
+skill can build the animation from them (e.g. `<ref>/walk-<dir>-<n>`), and drive
+them with `anims.create` / `anims.play`, not a static texture. The asset-pipeline
+skill covers frame naming; the official `animations` skill covers playback.
+
+## Verification
+
+- Every entry in `assets/LICENSES.md` is CC0-or-equivalent (or human-approved
+  with terms recorded) and carries a verbatim quote + evidence URL.
+- `assets/src` is reproducible from a committed ingest script or is itself
+  committed raw source.
+- No scene ships `generateTexture` placeholder art without a linked art-debt
+  issue; the debt ledger matches reality.
+- Characters render with a playing idle/walk animation, not a static frame —
+  confirm in the **real browser** (the art-director persona reviews rendered
+  screenshots, not code).
+
+Once the art exists in `assets/src`, hand off to **`phaser-asset-pipeline`** to
+pack it and codegen the typed keys.

package/plugins/lisa-phaser/.codex-plugin/skills/phaser-asset-sourcing/agents/openai.yaml

@@ -0,0 +1,4 @@
+display_name: "Phaser Asset Sourcing"
+short_description: "a Phaser 4 game needs actual…"
+default_prompt:
+  - "Use $phaser-asset-sourcing: a Phaser 4 game needs actual…."

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

@@ -0,0 +1,153 @@
+---
+name: phaser-build-deploy
+description: "configuring the production…"
+---
+
+# 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: {
+        // Vite 8's rolldown bundler requires the FUNCTION form (the object form
+        // `{ phaser: ["phaser"] }` throws "manualChunks is not a function").
+        manualChunks: id =>
+          id.includes("node_modules/phaser") ? "phaser" : undefined,
+        entryFileNames: "assets/[name]-[hash].js",      // content hash on everything
+        chunkFileNames: "assets/[name]-[hash].js",
+        assetFileNames: "assets/[name]-[hash][extname]",
+      },
+    },
+  },
+});
+```
+
+The `manualChunks` function 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. Use the **function** form — Vite 8 ships the rolldown bundler,
+which requires it (the classic object form throws `manualChunks is not a
+function`). 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/.codex-plugin/skills/phaser-build-deploy/agents/openai.yaml

@@ -0,0 +1,4 @@
+display_name: "Phaser Build Deploy"
+short_description: "configuring the production…"
+default_prompt:
+  - "Use $phaser-build-deploy: configuring the production…."

package/plugins/lisa-phaser/.codex-plugin/skills/phaser-i18n/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: phaser-i18n
+description: "localizing a Phaser 4 game — a…"
+---
+
+# 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" (the official `game-object-components` skill)
+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/.codex-plugin/skills/phaser-i18n/agents/openai.yaml

@@ -0,0 +1,4 @@
+display_name: "Phaser I18n"
+short_description: "localizing a Phaser 4 game — a…"
+default_prompt:
+  - "Use $phaser-i18n: localizing a Phaser 4 game — a…."