@codyswann/lisa 2.178.6 → 2.179.0

package/plugins/src/phaser/rules/phaser.md

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

package/plugins/src/phaser/skills/phaser-accessibility/SKILL.md

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

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