/VERSION.md`:
@@ -714,3 +751,160 @@ Use GDScript conventions for `.gd` files and C# conventions for `.cs` files. Mix
| Native extension / plugin files (.gdextension, C++) | godot-gdextension-specialist |
| General architecture review | godot-specialist |
```
+
+---
+
+## Appendix B — HTML5 / Web Configuration
+
+All HTML5-specific variants for language-dependent configuration. Referenced from Sections 4 and 5 — only relevant when HTML5 is the chosen engine. Use the subsection matching the language chosen in Section 4.
+
+> **Note on engine family naming**: For HTML5 projects, the `Engine` field reads "HTML5 (PixiJS [version])" rather than a single product name. The "engine" here is the combined runtime: browser + PixiJS framework + build tooling. Engine-reference docs live at `docs/engine-reference/html5/`.
+
+---
+
+### B1. CLAUDE.md Technology Stack Templates
+
+**TypeScript (recommended):**
+```markdown
+- **Engine**: HTML5 / PixiJS [version] (e.g., 8.16.0)
+- **Language**: TypeScript [version] (e.g., 5.x)
+- **Build System**: Vite [version] (e.g., 7.3 LTS or 8.0)
+- **Test Framework**: Vitest (unit) + Playwright [version] (e2e / browser)
+- **Asset Pipeline**: TexturePacker (spritesheets) + custom Vite asset handling + KTX2/Basis (texture compression, optional)
+- **Target Runtime**: Modern evergreen browsers, iOS Safari 16+, Android Chrome 110+
+- **Deployment**: itch.io / GitHub Pages / Cloudflare Pages / Capacitor-wrapped native (optional)
+```
+
+**Vanilla JavaScript:**
+```markdown
+- **Engine**: HTML5 / PixiJS [version]
+- **Language**: JavaScript (ES2022+, no TypeScript)
+- **Build System**: Vite [version]
+- **Test Framework**: Vitest (unit) + Playwright (e2e / browser)
+- **Asset Pipeline**: TexturePacker + custom Vite asset handling
+- **Target Runtime**: Modern evergreen browsers, iOS Safari 16+, Android Chrome 110+
+- **Deployment**: itch.io / GitHub Pages / Cloudflare Pages
+```
+
+> **Guardrail**: For TypeScript projects, the Language field must say "TypeScript" — not "TypeScript and JavaScript". A TypeScript project can have a few `.js` files at the edges (configs, scripts), but the language identity is TypeScript. Mixed-language is the Vanilla JS template's territory and should not bleed into TS projects.
+
+---
+
+### B2. Naming Conventions
+
+**TypeScript:**
+- Classes: PascalCase (e.g., `PlayerController`)
+- Variables/functions: camelCase (e.g., `moveSpeed`, `getCurrentScore()`)
+- Constants (module-level): UPPER_SNAKE_CASE (e.g., `MAX_HEALTH`, `DEFAULT_SPEED`)
+- Interfaces / Types: PascalCase, no `I` prefix (e.g., `PlayerState`, not `IPlayerState`)
+- Generics: single capital letter (`T`, `K`, `V`) or PascalCase (`TItem`)
+- Enums: PascalCase for enum + PascalCase for values (e.g., `GameState.MainMenu`)
+- Files: kebab-case for modules (e.g., `player-controller.ts`); PascalCase for classes-as-files (e.g., `PlayerController.ts`) — pick one convention per project
+- Component / scene files: PascalCase (e.g., `MainMenuScene.ts`)
+- Test files: `*.test.ts` (Vitest) or `*.spec.ts` (Playwright)
+
+**Vanilla JavaScript:**
+Same as TypeScript except no type-only naming (no Interfaces / Generics rules). Use JSDoc comments for type hints if desired.
+
+> **Pick one file naming convention upfront**: kebab-case is more idiomatic in modern Node/Vite ecosystems; PascalCase is more idiomatic in Java/C# backgrounds. Both work — consistency matters more than choice.
+
+---
+
+### B3. Engine Specialists Routing
+
+**TypeScript:**
+```markdown
+## Engine Specialists
+- **Primary**: html5-specialist
+- **Framework Specialist**: pixijs-specialist (PixiJS 8.x — scene graph, Assets, Filters, Ticker, ParticleContainer, Federated events; also owns TypeScript code quality for PixiJS-adjacent code)
+- **Shader Specialist**: webgl-shader-specialist (custom GLSL filters, WebGL2/WebGPU dual-target shaders)
+- **Build Specialist**: web-build-specialist (Vite, bundle optimization, asset pipeline, PWA, CI/CD)
+- **E2E Test Specialist**: playwright-e2e-specialist (browser e2e, mobile device emulation, viewport/touch simulation, screenshot regression)
+- **Routing Notes**: Invoke primary for browser API decisions (Workers, Storage, fetch), platform architecture (PWA vs SPA vs Capacitor wrap), and overall web game architecture. Invoke PixiJS specialist for any `.ts` file working with the PixiJS API — also for general TypeScript code quality in the game codebase (TypeScript and PixiJS are inseparable in v8). Invoke shader specialist for custom GLSL / WGSL authoring. Invoke build specialist for `vite.config.ts`, bundling, asset optimization. Invoke E2E specialist for `tests/e2e/*.spec.ts`. Unit tests (Vitest) default to the gameplay programmer or PixiJS specialist depending on what's being tested.
+
+### File Extension Routing
+
+| File Extension / Type | Specialist to Spawn |
+|-----------------------|---------------------|
+| Game code (.ts, .tsx files using PixiJS) | pixijs-specialist |
+| Platform / browser API code (.ts files, no Pixi) | html5-specialist |
+| Custom shader files (.glsl, .wgsl, .vert, .frag, .vs, .fs) | webgl-shader-specialist |
+| Build config (vite.config.ts, tsconfig.json, package.json scripts) | web-build-specialist |
+| E2E test files (tests/e2e/**/*.spec.ts) | playwright-e2e-specialist |
+| Unit test files (tests/unit/**/*.test.ts) | pixijs-specialist or gameplay-programmer |
+| HTML entry (index.html) | html5-specialist |
+| PWA manifest (public/manifest.json) | web-build-specialist |
+| CI / workflow files (.github/workflows/*.yml) | web-build-specialist |
+| Stylesheets (.css — minimal in canvas-based games) | html5-specialist |
+| General architecture review | html5-specialist |
+```
+
+**Vanilla JavaScript:**
+```markdown
+## Engine Specialists
+- **Primary**: html5-specialist
+- **Framework Specialist**: pixijs-specialist (PixiJS 8.x — also handles JS code quality; flag opportunities to introduce TypeScript at module boundaries)
+- **Shader Specialist**: webgl-shader-specialist (custom GLSL filters)
+- **Build Specialist**: web-build-specialist (Vite, bundle optimization, asset pipeline)
+- **E2E Test Specialist**: playwright-e2e-specialist (browser e2e)
+- **Routing Notes**: Same routing as TypeScript variant, with `.js` instead of `.ts`. Without static typing, the PixiJS specialist must work harder on runtime contracts and JSDoc — recommend incremental TypeScript adoption when the project crosses ~5000 lines.
+
+### File Extension Routing
+
+| File Extension / Type | Specialist to Spawn |
+|-----------------------|---------------------|
+| Game code (.js, .mjs files using PixiJS) | pixijs-specialist |
+| Platform / browser API code (.js files, no Pixi) | html5-specialist |
+| Custom shader files (.glsl, .wgsl, .vert, .frag, .vs, .fs) | webgl-shader-specialist |
+| Build config (vite.config.js, package.json scripts) | web-build-specialist |
+| E2E test files (tests/e2e/**/*.spec.js) | playwright-e2e-specialist |
+| Unit test files (tests/unit/**/*.test.js) | pixijs-specialist or gameplay-programmer |
+| HTML entry (index.html) | html5-specialist |
+| PWA manifest (public/manifest.json) | web-build-specialist |
+| General architecture review | html5-specialist |
+```
+
+---
+
+### B4. Performance Budgets (HTML5 Defaults)
+
+When the user opts into default budgets in Section 5, use these for HTML5:
+
+```markdown
+## Performance Budgets
+- **Target Framerate**: 60fps (mobile baseline: iPhone X / Galaxy S10 class)
+- **Acceptable Degraded**: 30fps locked
+- **Frame Budget**: 16.6ms at 60fps; 33.3ms at 30fps
+- **Initial Bundle (JS + CSS, gzipped)**: <500 KB
+- **First Playable Assets**: <500 KB additional
+- **Total Time-to-Playable (4G)**: <3 seconds
+- **Memory Ceiling**: 256 MB (mobile web; aggressive)
+- **Draw Calls**: <100 per frame (PixiJS auto-batches — atlas everything)
+- **Texture Memory**: <128 MB (use KTX2 compression for projects >5 MB art)
+```
+
+These come from `docs/engine-reference/html5/modules/build.md` and `current-best-practices.md`. Adjust based on target devices.
+
+---
+
+### B5. Forbidden Patterns (HTML5 Defaults)
+
+For HTML5 projects, suggest these forbidden patterns out of the box (with user confirmation):
+
+```markdown
+## Forbidden Patterns
+- `any` type in TypeScript (except at validated external boundaries with comment)
+- `Texture.from(url)` without prior `await Assets.load(url)` — silently returns blank
+- `new Application({ ... })` (v7 constructor pattern) — v8 requires `await app.init({ ... })`
+- `interactive: true` (v7 pattern) — v8 uses `eventMode: 'static' | 'dynamic'`
+- `.beginFill().drawRect().endFill()` (v7 Graphics) — v8 uses `.rect().fill()`
+- jQuery / lodash in new code — modern JS covers utility needs
+- `setTimeout` for game timing — use `Ticker` with `deltaMS`
+- Inlining binary assets in JS bundle (use Vite's asset URLs, not base64)
+- Synchronous XHR / blocking the main thread
+- DOM manipulation inside game loop (batch via Pixi `Container` instead)
+```
+
+---
+
+End of Appendix B.
diff --git a/README.md b/README.md
index c08cec9c45..01db1fd72c 100644
--- a/README.md
+++ b/README.md
@@ -3,13 +3,13 @@
Turn a single Claude Code session into a full game development studio.
- 49 agents. 73 skills. One coordinated AI team.
+ 54 agents. 73 skills. One coordinated AI team.
- 
+ 
@@ -24,7 +24,7 @@
Building a game solo with AI is powerful — but a single chat session has no structure. No one stops you from hardcoding magic numbers, skipping design docs, or writing spaghetti code. There's no QA pass, no design review, no one asking "does this actually fit the game's vision?"
-**Claude Code Game Studios** solves this by giving your AI session the structure of a real studio. Instead of one general-purpose assistant, you get 49 specialized agents organized into a studio hierarchy — directors who guard the vision, department leads who own their domains, and specialists who do the hands-on work. Each agent has defined responsibilities, escalation paths, and quality gates.
+**Claude Code Game Studios** solves this by giving your AI session the structure of a real studio. Instead of one general-purpose assistant, you get 54 specialized agents organized into a studio hierarchy — directors who guard the vision, department leads who own their domains, and specialists who do the hands-on work. Each agent has defined responsibilities, escalation paths, and quality gates.
The result: you still make every decision, but now you have a team that asks the right questions, catches mistakes early, and keeps your project organized from first brainstorm to launch.
@@ -52,7 +52,7 @@ The result: you still make every decision, but now you have a team that asks the
| Category | Count | Description |
|----------|-------|-------------|
-| **Agents** | 49 | Specialized subagents across design, programming, art, audio, narrative, QA, and production |
+| **Agents** | 54 | Specialized subagents across design, programming, art, audio, narrative, QA, and production |
| **Skills** | 73 | Slash commands for every workflow phase (`/start`, `/design-system`, `/create-epics`, `/create-stories`, `/dev-story`, `/story-done`, etc.) |
| **Hooks** | 12 | Automated validation on commits, pushes, asset changes, session lifecycle, agent audit trail, and gap detection |
| **Rules** | 11 | Path-scoped coding standards enforced when editing gameplay, engine, AI, UI, network code, and more |
@@ -84,13 +84,14 @@ Tier 3 — Specialists (Sonnet/Haiku)
### Engine Specialists
-The template includes agent sets for all three major engines. Use the set that matches your project:
+The template includes agent sets for all four major engine families. Use the set that matches your project:
| Engine | Lead Agent | Sub-Specialists |
|--------|-----------|-----------------|
-| **Godot 4** | `godot-specialist` | GDScript, Shaders, GDExtension |
+| **Godot 4** | `godot-specialist` | GDScript, C#, Shaders, GDExtension |
| **Unity** | `unity-specialist` | DOTS/ECS, Shaders/VFX, Addressables, UI Toolkit |
| **Unreal Engine 5** | `unreal-specialist` | GAS, Blueprints, Replication, UMG/CommonUI |
+| **HTML5 / PixiJS** | `html5-specialist` | PixiJS 8, WebGL Shaders, Vite/Build, Playwright E2E |
## Slash Commands
@@ -175,7 +176,7 @@ versions, and which files are safe to overwrite vs. which need a manual merge.
CLAUDE.md # Master configuration
.claude/
settings.json # Hooks, permissions, safety rules
- agents/ # 49 agent definitions (markdown + YAML frontmatter)
+ agents/ # 54 agent definitions (markdown + YAML frontmatter)
skills/ # 73 slash commands (subdirectory per skill)
hooks/ # 12 hook scripts (bash, cross-platform)
rules/ # 11 path-scoped coding standards
@@ -274,7 +275,7 @@ This is a **template**, not a locked framework. Everything is meant to be custom
- **Modify skills** — adjust workflows to match your team's process
- **Add rules** — create new path-scoped rules for your project's directory structure
- **Tune hooks** — adjust validation strictness, add new checks
-- **Pick your engine** — use the Godot, Unity, or Unreal agent set (or none)
+- **Pick your engine** — use the Godot, Unity, Unreal, or HTML5/PixiJS agent set (or none)
- **Set review intensity** — `full` (all director gates), `lean` (phase gates only), or `solo` (none). Set during `/start` or edit `production/review-mode.txt`. Override per-run with `--review solo` on any skill.
## Platform Support
diff --git a/docs/CLAUDE.md b/docs/CLAUDE.md
index 1da325920f..7ba6600bee 100644
--- a/docs/CLAUDE.md
+++ b/docs/CLAUDE.md
@@ -30,4 +30,5 @@ ADR Dependencies, Engine Compatibility, GDD Requirements Addressed
Version-pinned engine API snapshots. **Always check here before using any
engine API** — the LLM's training data predates the pinned engine version.
-Current engine: see `docs/engine-reference/godot/VERSION.md`
+Current engine: see `docs/engine-reference//VERSION.md` (pinned by `/setup-engine`).
+Available reference sets: `godot/`, `unity/`, `unreal/`, `html5/`.
diff --git a/docs/engine-reference/README.md b/docs/engine-reference/README.md
index 34d2a0a5f6..30ae6c4f44 100644
--- a/docs/engine-reference/README.md
+++ b/docs/engine-reference/README.md
@@ -7,9 +7,18 @@ has a cutoff date** and game engines update frequently.
## Why This Exists
Claude's training data has a knowledge cutoff (currently May 2025). Game engines
-like Godot, Unity, and Unreal ship updates that introduce breaking API changes,
-new features, and deprecated patterns. Without these reference files, agents will
-suggest outdated code.
+like Godot, Unity, Unreal, and the PixiJS / Vite / Playwright stack ship updates
+that introduce breaking API changes, new features, and deprecated patterns.
+Without these reference files, agents will suggest outdated code.
+
+## Supported Engine Families
+
+| Family | Directory | Specialist Agents |
+|--------|-----------|-------------------|
+| Godot 4 | `godot/` | `godot-specialist`, `godot-gdscript-specialist`, `godot-csharp-specialist`, `godot-shader-specialist`, `godot-gdextension-specialist` |
+| Unity | `unity/` | `unity-specialist`, `unity-dots-specialist`, `unity-shader-specialist`, `unity-ui-specialist`, `unity-addressables-specialist` |
+| Unreal Engine 5 | `unreal/` | `unreal-specialist`, `ue-blueprint-specialist`, `ue-gas-specialist`, `ue-replication-specialist`, `ue-umg-specialist` |
+| HTML5 / PixiJS | `html5/` | `html5-specialist`, `pixijs-specialist`, `webgl-shader-specialist`, `web-build-specialist`, `playwright-e2e-specialist` |
## Structure
@@ -21,12 +30,17 @@ Each engine gets its own directory:
├── breaking-changes.md # API changes between versions, organized by risk level
├── deprecated-apis.md # "Don't use X → Use Y" lookup tables
├── current-best-practices.md # New practices not in model training data
+├── PLUGINS.md # Optional packages / libraries (unity, unreal, html5)
└── modules/ # Per-subsystem quick references (~150 lines max each)
├── rendering.md
├── physics.md
└── ...
```
+The `html5/` family is unusual: the "engine" is actually a combined runtime
+(browser + PixiJS framework + Vite build tooling + Playwright tests), so its
+VERSION.md tracks multiple version pins rather than one product.
+
## How Agents Use These Files
Engine-specialist agents are instructed to:
diff --git a/docs/engine-reference/html5/PLUGINS.md b/docs/engine-reference/html5/PLUGINS.md
new file mode 100644
index 0000000000..929b8f29fa
--- /dev/null
+++ b/docs/engine-reference/html5/PLUGINS.md
@@ -0,0 +1,189 @@
+# HTML5 / PixiJS — Optional Packages & Libraries
+
+**Last verified:** 2026-06-11
+
+This document indexes **optional libraries** commonly paired with PixiJS 8 for
+specific game genres. These are NOT part of PixiJS core but solve recurring
+problems (audio, physics, animation, mobile UX) where the browser's native
+APIs are too low-level.
+
+---
+
+## How to Use This Guide
+
+- **✅ Production-Ready** — Widely used, maintained, recommended
+- **🟡 Brief Overview Only** — Use WebSearch for current state
+- **⚠️ Caveat** — Specific concern noted
+- **📦 Package Required** — Install via npm
+
+---
+
+## Production-Ready Libraries
+
+### ✅ pixi-filters
+- **Purpose**: Extra filters not in core PixiJS (Bloom, Glitch, Outline, CRT, Godray, etc.)
+- **When to use**: Visual polish — stylization, post-FX, retro effects
+- **Knowledge Gap**: Some filters rewritten for v8 — verify each filter against the v8 package version
+- **Status**: Production-Ready
+- **Package**: `pixi-filters` (peer dep on `pixi.js@^8`)
+- **Official**: https://github.com/pixijs/filters
+
+---
+
+### ✅ Howler.js
+- **Purpose**: WebAudio wrapper — sprites, fade, spatial, mobile audio unlock
+- **When to use**: Any game needing >2-3 sounds. WebAudio raw is painful for sprite-based sound (cutting one sample out of a loop).
+- **Why over native WebAudio**: Automatic mobile audio context unlock on first touch (the iOS/Android requirement that crashes naive `new Audio()` code), built-in audio sprites (sub-clips of a long file), cross-format fallback
+- **Status**: Production-Ready (stable, low-churn)
+- **Package**: `howler` + `@types/howler`
+- **Official**: https://howlerjs.com/
+
+---
+
+### ✅ GSAP (GreenSock)
+- **Purpose**: Tweening engine — smooth UI animations, eased motion, sequence chains
+- **When to use**: Anywhere PixiJS's built-in linear interpolation isn't enough — menu transitions, card flips, juice/feedback animations
+- **PixiJS-specific tip**: GSAP doesn't need a Pixi plugin — just tween `sprite.x`, `sprite.scale.x`, `sprite.alpha` directly. GSAP picks them up via property access.
+- **Licensing**: Standard license is free for most use; commercial features (SplitText, MotionPath full) require Club GreenSock membership
+- **Status**: Production-Ready
+- **Package**: `gsap`
+- **Official**: https://gsap.com/
+
+---
+
+### ✅ Matter.js
+- **Purpose**: 2D rigid-body physics (gravity, collision, constraints)
+- **When to use**: Physics-driven gameplay — Angry Birds style, ragdoll, sandbox. NOT needed for simple AABB collision (write your own).
+- **Pairing with PixiJS**: Run Matter as a separate world; in each Ticker tick, copy `body.position` → `sprite.position` and `body.angle` → `sprite.rotation`
+- **Status**: Production-Ready
+- **Package**: `matter-js` + `@types/matter-js`
+- **Official**: https://brm.io/matter-js/
+
+---
+
+### ✅ Box2D (via wasm)
+- **Purpose**: Industry-standard 2D physics (more accurate than Matter, used by Angry Birds, Limbo)
+- **When to use**: When physics quality is core to the game feel and Matter's solver isn't tight enough
+- **Caveat**: ⚠️ WASM build adds ~500KB to bundle. Don't reach for this unless physics is the game.
+- **Status**: Production-Ready (multiple WASM ports — `box2d-wasm` is current)
+- **Package**: `box2d-wasm`
+
+---
+
+### ✅ Spine / DragonBones (Skeletal Animation)
+- **Purpose**: 2D skeletal animation runtimes
+- **When to use**: Character animation more complex than sprite sheets (smooth IK, weighted meshes, deformation)
+- **PixiJS integration**: `@esotericsoftware/spine-pixi-v8` (official Spine runtime for PixiJS 8)
+- **Caveat**: ⚠️ Spine requires a paid editor license for commercial use ($69 Essential / $399 Professional). DragonBones is free but less actively maintained.
+- **Status**: Production-Ready
+- **Package**: `@esotericsoftware/spine-pixi-v8`
+
+---
+
+### ✅ nipplejs
+- **Purpose**: Virtual joystick / d-pad overlay for mobile web
+- **When to use**: Any action game targeting mobile web that can't rely on tap-only input
+- **Caveat**: ⚠️ The library is DOM-based (renders separately from Pixi canvas) — be careful with z-index and pointer-events: none on the right children
+- **Status**: Production-Ready (low churn)
+- **Package**: `nipplejs`
+- **Official**: https://yoannmoi.net/nipplejs/
+
+---
+
+## Brief Overview Only
+
+### 🟡 PixiJS Sound (`@pixi/sound`)
+- **Purpose**: PixiJS's own audio package
+- **When to use**: If you want audio integrated with Pixi's Assets system
+- **Tradeoff vs Howler**: Tighter Pixi integration, but Howler has more mature mobile-quirk handling. For complex games → Howler. For simple ambient audio integrated with asset bundles → @pixi/sound is fine.
+- **Package**: `@pixi/sound`
+
+### 🟡 Tone.js
+- **Purpose**: Music synthesis / interactive music
+- **When to use**: Games with adaptive music, procedural sound, music-as-mechanic (rhythm games)
+- **Caveat**: ⚠️ Heavy (~150KB). Overkill for static music playback — use Howler.
+
+### 🟡 Hammer.js
+- **Purpose**: Touch gesture library (pinch, rotate, swipe, multi-touch)
+- **When to use**: When Pixi's `FederatedPointerEvent` doesn't cover gesture detection you need
+- **Caveat**: ⚠️ Last release was years ago. Consider native Pointer Events with manual gesture detection unless you need Hammer's specific event abstractions.
+
+### 🟡 p2.js
+- **Purpose**: Alternative 2D physics engine
+- **When to use**: Rarely chosen now over Matter or Box2D. Listed for completeness.
+
+### 🟡 Stats.js / Pixi DevTools
+- **Purpose**: FPS counter, draw call inspector
+- **When to use**: Development only — strip from production builds
+- **Pixi DevTools**: Chrome extension for inspecting the Pixi scene graph at runtime — install during development
+
+### 🟡 i18next
+- **Purpose**: i18n for game UI text
+- **When to use**: Localized games. Pairs with `react-i18next` if you have React UI overlay, or use core library directly with Pixi `Text` elements.
+
+---
+
+## Networking (for Multiplayer)
+
+### 🟡 Colyseus
+- **Purpose**: Authoritative game server with state sync
+- **When to use**: Realtime multiplayer (lobby + room-based games)
+- **Caveat**: ⚠️ Server-side Node.js component required
+
+### 🟡 PartyKit / Socket.IO
+- **Purpose**: Lower-level realtime messaging
+- **When to use**: Custom netcode, or hosting on edge (PartyKit on Cloudflare)
+
+### 🟡 WebRTC (native)
+- **Purpose**: Peer-to-peer (no server)
+- **When to use**: 2-player games where matchmaking can be solved externally (URL share). Avoid for >4 players (mesh complexity).
+
+---
+
+## NOT Recommended
+
+### ❌ Pixi v7 plugins on v8 projects
+Many community plugins haven't migrated. Always check the package's
+`peerDependencies` for `"pixi.js": "^8"` before installing.
+
+### ❌ `pixi-spine` (old)
+Use `@esotericsoftware/spine-pixi-v8` — official runtime, maintained.
+
+### ❌ jQuery / lodash for game code
+ESM imports + modern JS (`Object.entries`, `Array.flat`, etc.) cover almost
+all utility needs. lodash for one helper = 100KB you didn't need.
+
+### ❌ Web Components / Lit for in-canvas UI
+The DOM overlay above the canvas is a valid pattern, but mixing component
+frameworks with the WebGL canvas adds layout cost. Use Pixi-native `Container`
+hierarchies for in-game UI.
+
+---
+
+## Installation Cheat Sheet
+
+```bash
+# Core (most common combo)
+npm i pixi.js pixi-filters howler gsap
+
+# Mobile-first action game
+npm i pixi.js pixi-filters howler gsap nipplejs
+
+# Physics-driven game
+npm i pixi.js pixi-filters howler matter-js
+
+# Animation-heavy character game
+npm i pixi.js pixi-filters howler @esotericsoftware/spine-pixi-v8
+
+# Dev / testing
+npm i -D vite vitest @playwright/test typescript @types/node @types/howler @types/matter-js
+```
+
+---
+
+## See Also
+
+- [`current-best-practices.md`](current-best-practices.md) — How these libraries fit into project structure
+- [`modules/audio.md`](modules/audio.md) — Howler patterns in depth
+- [`modules/physics.md`](modules/physics.md) — Matter / Box2D patterns
+- [`modules/networking.md`](modules/networking.md) — Multiplayer architectures
diff --git a/docs/engine-reference/html5/VERSION.md b/docs/engine-reference/html5/VERSION.md
new file mode 100644
index 0000000000..1e905fcd09
--- /dev/null
+++ b/docs/engine-reference/html5/VERSION.md
@@ -0,0 +1,76 @@
+# HTML5 (PixiJS) — Version Reference
+
+| Field | Value |
+|-------|-------|
+| **Engine Family** | HTML5 / Web (PixiJS-based) |
+| **Renderer** | PixiJS 8.16.0 (Feb 2026 latest) |
+| **Build Tool** | Vite 8.0.0 (Mar 2026) — or 7.3 LTS / 6.4 (security patches only) |
+| **Language** | TypeScript 5.x |
+| **Test Frameworks** | Vitest (unit) + Playwright 1.49+ (e2e/browser) |
+| **Target Runtime** | Modern evergreen browsers (Chrome/Firefox/Safari/Edge), iOS Safari 16+, Android Chrome 110+ |
+| **Project Pinned** | 2026-06-11 |
+| **Last Docs Verified** | 2026-06-11 |
+| **LLM Knowledge Cutoff** | May 2025 |
+| **Risk Level** | **HIGH** — PixiJS v8 introduced near-complete API redesign post-cutoff |
+
+## Knowledge Gap Warning
+
+The LLM training data likely covers **PixiJS up to ~v7.x**. PixiJS v8 (released
+Feb 2024) was a near-complete API redesign — most v7 code patterns are now
+incorrect. Always cross-reference [`breaking-changes.md`](breaking-changes.md)
+and [`deprecated-apis.md`](deprecated-apis.md) before writing or reviewing
+PixiJS code.
+
+Vite also moved from v5 (training-data-era) → v6 → v7 → **v8 (Rolldown-based,
+Mar 2026)**. Vite 8 swaps esbuild + Rollup for Rolldown + Oxc — performance
+profile and some configuration semantics differ. If a project is still on Vite 5
+or 6, treat it as **legacy** for tooling purposes (PixiJS 8 code itself is
+agnostic to the bundler version).
+
+## Post-Cutoff Version Timeline
+
+### PixiJS
+
+| Version | Release | Risk | Key Theme |
+|---------|---------|------|-----------|
+| 8.0 | Feb 2024 | **HIGH** | Single package, async `Application.init()`, Graphics API redesign, ParticleContainer rework, TextureSource separation |
+| 8.6 | Oct 2025 | MEDIUM | Documentation overhaul, WebGPU stability improvements |
+| 8.12 | Dec 2025 | LOW | Performance and bugfixes |
+| 8.13 | Jan 2026 | LOW | Bugfixes |
+| 8.16 | Feb 2026 | LOW | HTMLText word wrapping fix, CubeTexture environment maps, external texture support |
+
+### Vite
+
+| Version | Release | Risk | Key Theme |
+|---------|---------|------|-----------|
+| 6.0 | Late 2024 | MEDIUM | Environment API, runtime API changes |
+| 7.0 | Mid 2025 | MEDIUM | Default targets, Node.js requirement bump |
+| 8.0 | Mar 2026 | **HIGH** | **Rolldown** replaces esbuild + Rollup, Oxc-based tooling, ~15 MB larger install size, lightningcss as normal dep |
+
+### Playwright
+
+| Version | Release | Risk | Key Theme |
+|---------|---------|------|-----------|
+| 1.45+ | 2024+ | LOW | Mobile device descriptor expansion (100+ devices) |
+| 1.49+ | 2026 | LOW | Improved touch event handling, better WebKit parity, network condition control |
+
+## BagelMVP Specific Note
+
+The reference project `BagelMVP` (`pop-prototype`) currently pins:
+- `pixi.js ^8.0.0` — covered by this reference (use v8.16.0 patterns)
+- `vite ^5.0.0` — **legacy**, predates the docs above (`/setup-engine upgrade vite 5 8` to migrate)
+- `vitest ^1.0.0` — paired with Vite 5; Vitest 3.x pairs with Vite 8
+- `@playwright/test ^1.40.0` — predates 1.49 mobile improvements; upgrade recommended
+- `typescript ^5.0.0` — within range
+
+Project may stay on Vite 5 for stability; the PixiJS code itself is bundler-agnostic.
+
+## Verified Sources
+
+- PixiJS v8 migration guide: https://pixijs.com/8.x/guides/migrations/v8
+- PixiJS versions index: https://pixijs.com/versions
+- PixiJS 8.16 release notes: https://pixijs.com/blog/8.16.0
+- Vite 8 release: https://vite.dev/releases
+- Vite 8 vs 7 changelog: https://github.com/vitejs/vite/blob/main/packages/vite/CHANGELOG.md
+- Playwright emulation: https://playwright.dev/docs/emulation
+- Playwright mobile devices: https://playwright.dev/docs/api/class-devices
diff --git a/docs/engine-reference/html5/breaking-changes.md b/docs/engine-reference/html5/breaking-changes.md
new file mode 100644
index 0000000000..ada1c1c276
--- /dev/null
+++ b/docs/engine-reference/html5/breaking-changes.md
@@ -0,0 +1,256 @@
+# HTML5 / PixiJS — Breaking Changes by Version
+
+**Last verified:** 2026-06-11
+
+Authoritative source for API changes that will break v7-era or pre-v8 code patterns.
+Read before suggesting any PixiJS, Vite, or Playwright API.
+
+---
+
+## PixiJS v7 → v8 (HIGH RISK — Near-complete rewrite)
+
+### Package Structure
+
+| Concept | v7 (DO NOT USE) | v8 (CURRENT) |
+|---------|-----------------|--------------|
+| Imports | `@pixi/app`, `@pixi/sprite`, etc. | Single `pixi.js` package |
+
+```ts
+// v7 — broken
+import { Application } from '@pixi/app';
+import { Sprite } from '@pixi/sprite';
+
+// v8 — correct
+import { Application, Sprite } from 'pixi.js';
+```
+
+### Application Initialization
+
+**v7**: synchronous constructor. **v8**: must call `await app.init()` separately.
+
+```ts
+// v7 — broken
+const app = new Application({ width: 800, height: 600 });
+
+// v8 — correct
+const app = new Application();
+await app.init({ width: 800, height: 600, preference: 'webgpu' });
+document.body.appendChild(app.canvas); // v7: app.view → v8: app.canvas
+```
+
+### Graphics API (Completely Redesigned)
+
+| v7 Pattern | v8 Equivalent |
+|-----------|---------------|
+| `beginFill(0xff0000)` | (removed — fill is terminal) |
+| `endFill()` | `.fill(0xff0000)` after shape |
+| `drawRect(x,y,w,h)` | `.rect(x,y,w,h)` |
+| `drawCircle(x,y,r)` | `.circle(x,y,r)` |
+| `drawEllipse(...)` | `.ellipse(...)` |
+| `drawPolygon([...])` | `.poly([...])` |
+| `drawRoundedRect(...)` | `.roundRect(...)` |
+| `lineStyle(w, color)` | `.stroke({ width: w, color })` after shape |
+
+```ts
+// v7 — broken
+const g = new Graphics()
+ .beginFill(0xff0000)
+ .drawRect(50, 50, 100, 100)
+ .endFill();
+
+// v8 — correct
+const g = new Graphics()
+ .rect(50, 50, 100, 100)
+ .fill(0xff0000);
+```
+
+### Container & DisplayObject
+
+- **`DisplayObject` removed** — `Container` is now the base class for all renderables
+- **Leaf nodes no longer accept children**: `Sprite`, `Mesh`, `Graphics` will throw if `addChild` is called
+- **`updateTransform()` removed** — use `onRender` callback instead
+- **`cacheAsBitmap` → `cacheAsTexture()`** (method, not property)
+- **`container.name` → `container.label`**
+- **`getBounds()` returns `Bounds` object** — access `Rectangle` via `.rectangle`
+
+```ts
+// v7 — broken
+sprite.name = 'player';
+const rect = sprite.getBounds();
+
+// v8 — correct
+sprite.label = 'player';
+const rect = sprite.getBounds().rectangle;
+```
+
+### Texture & TextureSource Split
+
+**v7**: `BaseTexture` handles resource loading.
+**v8**: Resource pre-loading is separate from `Texture`. Use `Assets.load()` for URLs.
+
+```ts
+// v7 — broken
+const texture = Texture.from('player.png'); // loaded URLs
+
+// v8 — correct
+await Assets.load('player.png');
+const texture = Texture.from('player.png'); // resolves from Assets cache only
+```
+
+For manual texture construction, use `TextureSource` subclasses (`ImageSource`,
+`VideoSource`, `CanvasSource`).
+
+### Assets System
+
+```ts
+// v7 — broken
+Assets.add('bunny', 'bunny.png');
+
+// v8 — correct
+Assets.add({ alias: 'bunny', src: 'bunny.png' });
+await Assets.load('bunny');
+```
+
+### ParticleContainer (Major Rework)
+
+| v7 | v8 |
+|----|----|
+| Accepts `Sprite` children | Accepts only objects implementing `IParticle` |
+| `container.addChild(sprite)` | `container.addParticle(new Particle(texture))` |
+| Iterates `children` array | Iterates `particleChildren` array |
+| Automatic bounds | **`boundsArea` must be set manually** |
+
+```ts
+// v8 — correct
+const pc = new ParticleContainer({
+ dynamicProperties: { position: true, scale: false, rotation: false },
+});
+pc.boundsArea = new Rectangle(0, 0, 800, 600); // REQUIRED in v8
+pc.addParticle(new Particle({ texture, x, y }));
+```
+
+### Filters
+
+```ts
+// v7 — broken
+new Filter(vertex, fragment, uniforms);
+
+// v8 — correct
+new Filter({
+ glProgram: GlProgram.from({ vertex, fragment }),
+ resources: { uTime: { value: 0, type: 'f32' } },
+});
+```
+
+Uniforms now require explicit `type` strings (`'f32'`, `'vec2'`, etc.)
+
+### Constructors — Object-Based
+
+Most filter/effect constructors moved from positional args to options objects:
+
+```ts
+// v7 — broken
+new BlurFilter(8, 4, 1, 5);
+
+// v8 — correct
+new BlurFilter({ strength: 8, quality: 4, resolution: 1, kernelSize: 5 });
+```
+
+### Mesh Class Renames
+
+| v7 | v8 |
+|----|----|
+| `SimpleMesh` | `MeshSimple` |
+| `SimplePlane` | `MeshPlane` |
+| `SimpleRope` | `MeshRope` |
+| `NineSlicePlane` | `NineSliceSprite` |
+
+### Ticker
+
+```ts
+// v7 — broken
+Ticker.shared.add((delta) => {
+ sprite.x += delta * speed;
+});
+
+// v8 — correct
+Ticker.shared.add((ticker) => {
+ sprite.x += ticker.deltaTime * speed;
+});
+```
+
+Callback receives the `Ticker` instance, not a delta number.
+
+### Settings & Adapters
+
+| v7 | v8 |
+|----|----|
+| `settings.RESOLUTION = 2` | `AbstractRenderer.defaultOptions.resolution = 2` |
+| `settings.ADAPTER = X` | `DOMAdapter.set(X)` |
+| `SCALE_MODES.LINEAR` | `'linear'` (plain strings) |
+| `WRAP_MODES.CLAMP` | `'clamp-to-edge'` |
+| `utils.hex2string(...)` | direct import: `import { hex2string } from 'pixi.js'` |
+
+### `Application.view` → `Application.canvas`
+
+Renamed for clarity.
+
+---
+
+## Vite 5 → 6 → 7 → 8 (HIGH RISK — Toolchain swap)
+
+### Vite 5 → 6 (Late 2024)
+- **Environment API** introduced — plugins migrating to multi-environment model
+- Server runtime separated from build (`server.environments`, `build.rollupOptions` interactions changed)
+- Node.js minimum: 18.x
+
+### Vite 6 → 7 (Mid 2025)
+- Default `target` bumped: `'modules'` → `'baseline-widely-available'`
+- Node.js minimum: 20.x
+- Some plugin hooks renamed in Environment API
+
+### Vite 7 → 8 (Mar 2026) — Rolldown Swap
+- **Bundler swap**: esbuild + Rollup → **Rolldown** (Rust-based) + Oxc
+- Most user code unaffected, but **custom Rollup plugins may need adaptation**
+- `lightningcss` is now a normal dependency (~+15 MB install)
+- Some niche `optimizeDeps` flags renamed
+- Build output should be byte-similar but not byte-identical to v7
+
+**Strategy for BagelMVP-class projects**: PixiJS game code is bundler-agnostic.
+The migration is mostly about `vite.config.ts` and plugin compatibility. Pin
+`vite@^7` for stability if Rolldown plugin ecosystem is still catching up;
+adopt `vite@^8` for new projects.
+
+---
+
+## Playwright (Lower Risk — Mostly Additive)
+
+### 1.40 → 1.49+ (2025-2026)
+- Device descriptor catalog expanded to 100+ devices
+- Better touch event simulation (closer to real mobile)
+- Improved WebKit parity (Safari rendering)
+- Network throttling — finer-grained control
+- `page.evaluate()` performance improvements
+
+No major breaking changes; mostly drop-in upgrades. `@playwright/test ^1.40`
+in BagelMVP works but lacks newer mobile device profiles.
+
+---
+
+## TypeScript 5.x — Notes
+
+PixiJS 8 uses TypeScript-first design with extensive generics:
+- `Container` — type-narrow child iteration
+- `Assets.load(url)` — typed asset returns
+- `Sprite.from(source)` — generic texture sources
+
+Code targeting `tsconfig` with `strict: true` is the assumed baseline. `any`
+escape hatches are a smell — `pixijs-specialist` should flag.
+
+---
+
+## See Also
+
+- [`deprecated-apis.md`](deprecated-apis.md) — quick lookup of v7→v8 patterns
+- [`current-best-practices.md`](current-best-practices.md) — idiomatic v8 patterns
+- [`modules/rendering.md`](modules/rendering.md) — WebGL vs WebGPU selection
diff --git a/docs/engine-reference/html5/current-best-practices.md b/docs/engine-reference/html5/current-best-practices.md
new file mode 100644
index 0000000000..cb7c3e90f7
--- /dev/null
+++ b/docs/engine-reference/html5/current-best-practices.md
@@ -0,0 +1,394 @@
+# HTML5 / PixiJS — Current Best Practices
+
+**Last verified:** 2026-06-11
+
+Idiomatic patterns for PixiJS 8 + Vite + TypeScript projects targeting modern
+browsers (especially mobile web). Pre-v8 patterns are documented in
+[`deprecated-apis.md`](deprecated-apis.md) — this file shows the **positive**
+patterns: what to do, not just what to avoid.
+
+---
+
+## Project Bootstrap
+
+### Application Init Pattern (v8)
+
+```ts
+import { Application } from 'pixi.js';
+
+export async function bootstrap(): Promise {
+ const app = new Application();
+
+ await app.init({
+ resizeTo: window, // auto-resize to viewport
+ backgroundColor: 0x000000,
+ antialias: true,
+ resolution: window.devicePixelRatio || 1,
+ autoDensity: true,
+ preference: 'webgpu', // try WebGPU, fall back to WebGL2
+ preferWebGLVersion: 2,
+ powerPreference: 'high-performance',
+ });
+
+ document.body.appendChild(app.canvas);
+ return app;
+}
+```
+
+**Why**:
+- `await init()` is mandatory in v8 (constructor cannot accept options anymore)
+- `autoDensity: true` + `resolution: dpr` handles retina/mobile high-DPI
+- `preference: 'webgpu'` opts into WebGPU where available; PixiJS falls back to WebGL2 transparently
+- `app.canvas` (not `app.view`) is the new accessor
+
+### Renderer Choice
+
+| Target | Recommendation | Reason |
+|--------|---------------|--------|
+| Desktop modern browsers | `preference: 'webgpu'` | Best perf, future-proof |
+| iOS Safari | `preference: 'webgl'` | WebGPU on iOS still gated behind flags in some versions |
+| Universal default | `preference: 'webgpu'` (auto-fallback) | PixiJS handles fallback |
+| Low-end Android | Pin to `'webgl'`, use `preferWebGLVersion: 1` only as last resort | WebGL2 has wider coverage by 2026 |
+
+---
+
+## Asset Loading
+
+### Modern Pattern — Manifests + `Assets`
+
+```ts
+import { Assets } from 'pixi.js';
+
+// Manifest declared upfront (typically in a config module)
+Assets.init({
+ manifest: {
+ bundles: [
+ {
+ name: 'preload',
+ assets: [
+ { alias: 'logo', src: 'assets/logo.png' },
+ { alias: 'ui_atlas', src: 'assets/ui.json' },
+ ],
+ },
+ {
+ name: 'gameplay',
+ assets: [
+ { alias: 'sprites', src: 'assets/sprites.json' },
+ { alias: 'bgm', src: 'assets/bgm.mp3' },
+ ],
+ },
+ ],
+ },
+});
+
+// Load on demand
+await Assets.loadBundle('preload');
+// ... show menu
+await Assets.loadBundle('gameplay');
+// ... start game
+```
+
+**Why**: Bundles let you progressively load — critical for mobile web where
+the initial download must be minimal. Typed return: `Assets.load(alias)`.
+
+### Spritesheets (use PixiJS's native format)
+
+Spritesheets generated by TexturePacker (JSON Hash format) load via:
+```ts
+const sheet = await Assets.load('assets/sprites.json');
+const playerTexture = sheet.textures['player_idle.png'];
+```
+
+---
+
+## Graphics (v8 Builder Style)
+
+```ts
+import { Graphics } from 'pixi.js';
+
+const card = new Graphics()
+ .roundRect(0, 0, 200, 280, 16)
+ .fill(0x1a1a1a)
+ .stroke({ width: 2, color: 0xffffff, alpha: 0.3 });
+```
+
+**Why**: Builder pattern; each shape method returns `this`. `.fill()` and
+`.stroke()` are terminals that apply to the most recent shape.
+
+**Gotcha**: A `Graphics` instance with multiple shapes needs `.fill()` /
+`.stroke()` between each shape:
+
+```ts
+const g = new Graphics();
+g.rect(0, 0, 100, 100).fill(0xff0000); // red square
+g.circle(150, 50, 40).fill(0x00ff00); // green circle
+// Without intermediate fills, only the last shape would be filled
+```
+
+---
+
+## Containers & Children
+
+### Use `Container` as Base for Composites
+
+```ts
+// Bad in v8 — Sprite cannot have children
+const player = new Sprite(texture);
+player.addChild(healthBar); // throws
+
+// Good — wrap in Container
+class Player extends Container {
+ private body: Sprite;
+ private healthBar: Graphics;
+
+ constructor(texture: Texture) {
+ super();
+ this.body = new Sprite(texture);
+ this.healthBar = new Graphics();
+ this.addChild(this.body, this.healthBar);
+ }
+}
+```
+
+### Type-Safe Child Access
+
+```ts
+// Tell TypeScript what children to expect
+const ui = new Container();
+ui.addChild(sprite1, sprite2); // only Sprite allowed
+ui.children[0].texture; // typed as Texture, no cast
+```
+
+---
+
+## Ticker / Game Loop
+
+```ts
+import { Ticker } from 'pixi.js';
+
+const speed = 200; // pixels/sec
+Ticker.shared.add((ticker: Ticker) => {
+ const dt = ticker.deltaMS / 1000; // seconds since last frame
+ player.x += player.vx * dt;
+ player.y += player.vy * dt;
+});
+```
+
+**Use `deltaMS / 1000`** for time-based physics (frame-rate independent).
+`ticker.deltaTime` is normalized to "60fps frames" — convenient for visual
+tweens but not for physics.
+
+### Pause / Resume
+
+```ts
+const gameLoopTicker = new Ticker(); // private ticker, not shared
+gameLoopTicker.add(updateGame);
+gameLoopTicker.start();
+
+// Pause without stopping shared (UI, tween) ticker
+function pause() { gameLoopTicker.stop(); }
+function resume() { gameLoopTicker.start(); }
+```
+
+---
+
+## Input — Federated Events
+
+```ts
+import { FederatedPointerEvent } from 'pixi.js';
+
+sprite.eventMode = 'static'; // 'static' | 'dynamic' | 'passive' | 'auto' | 'none'
+sprite.cursor = 'pointer';
+
+sprite.on('pointertap', (e: FederatedPointerEvent) => {
+ console.log(e.global.x, e.global.y);
+});
+```
+
+**`eventMode`** replaced v7's `interactive: true`:
+- `'static'`: hit-testable, doesn't move (most UI)
+- `'dynamic'`: hit-testable, moves (game objects)
+- `'passive'`: children testable, self not
+- `'auto'`: inherit
+- `'none'`: opt out completely (performance)
+
+**For mobile**: set `eventMode: 'static'` on the root container and bubble
+events upward. Tap targets should be ≥48×48 CSS pixels (WCAG 2.5.5).
+
+---
+
+## Filters
+
+```ts
+import { Filter, GlProgram, BlurFilter } from 'pixi.js';
+
+// Preset filter
+sprite.filters = [new BlurFilter({ strength: 4, quality: 4 })];
+
+// Custom filter
+const myFilter = new Filter({
+ glProgram: GlProgram.from({
+ vertex: defaultVertexShader,
+ fragment: myFragmentShader,
+ }),
+ resources: {
+ uTime: { value: 0, type: 'f32' },
+ uMouse: { value: [0, 0], type: 'vec2' },
+ },
+});
+
+Ticker.shared.add((ticker) => {
+ myFilter.resources.uTime.value += ticker.deltaMS / 1000;
+});
+```
+
+---
+
+## TypeScript Strictness
+
+`tsconfig.json` baseline for PixiJS 8 projects:
+
+```json
+{
+ "compilerOptions": {
+ "target": "ES2022",
+ "module": "ESNext",
+ "moduleResolution": "Bundler",
+ "strict": true,
+ "noImplicitAny": true,
+ "strictNullChecks": true,
+ "noUncheckedIndexedAccess": true,
+ "noImplicitOverride": true,
+ "exactOptionalPropertyTypes": true,
+ "skipLibCheck": true,
+ "lib": ["ES2022", "DOM", "DOM.Iterable", "WebWorker"]
+ }
+}
+```
+
+**`noUncheckedIndexedAccess`** is critical for game code — `arr[i]` typed as
+`T | undefined` forces bound checks (catches many "off by one" bugs in hot loops).
+
+### No `any` in PixiJS Code
+
+The PixiJS public API is fully typed. Reaching for `any` is almost always a
+sign you missed a generic parameter or a built-in type guard. Examples:
+- `Assets.load(url)` → use `Assets.load(url)` for typed return
+- `Container.children[0]` → declare `Container` for known child type
+- Event handlers → use `FederatedPointerEvent`, `FederatedWheelEvent`, etc.
+
+---
+
+## Mobile Web Performance
+
+### Frame Budget
+
+- **Target**: 60fps on iPhone X / Galaxy S10 baseline (~16.6ms)
+- **Acceptable degraded**: 30fps locked (33.3ms) — set `Ticker.shared.maxFPS = 30`
+- **Battery saver**: 30fps + reduce particle count, blur kernel, post-FX
+
+### Asset Size Budget (Mobile Web)
+
+| Asset Type | Initial Download | Cumulative |
+|------------|------------------|------------|
+| Total initial bundle (JS + CSS) | <500 KB gzipped | — |
+| First playable scene | <2 MB | — |
+| All gameplay assets | — | <10 MB |
+| Music/SFX | — | <5 MB |
+
+### Critical: Use Spritesheets, Not Loose Images
+
+Each `Texture.from(url)` for a unique image = one HTTP request + one GPU upload.
+A single spritesheet of 100 sprites = 1 request + 1 upload. **Always atlas**.
+
+### Texture Compression (Future)
+
+PixiJS 8 supports KTX2/Basis Universal compressed textures via the Assets
+system. ~50-75% memory reduction on GPU. Recommended for any project >5 MB
+of art assets.
+
+---
+
+## Vite Configuration (Game-Specific)
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+ base: './', // for static hosting + itch.io
+ build: {
+ target: 'es2022',
+ sourcemap: true, // disable in prod if size critical
+ rollupOptions: {
+ output: {
+ manualChunks: {
+ pixi: ['pixi.js'], // pixi gets its own chunk
+ },
+ },
+ },
+ assetsInlineLimit: 0, // never inline — atlases must stay separate files
+ },
+ server: {
+ host: '0.0.0.0', // mobile device LAN testing
+ port: 5173,
+ },
+});
+```
+
+**Why**:
+- `base: './'` — relative paths so the build works on any subpath (itch.io, GitHub Pages)
+- Pixi in its own chunk — cached separately, browser revalidates only your code
+- `assetsInlineLimit: 0` — never inline binary; keep spritesheets out of bundle
+
+---
+
+## Testing
+
+### Vitest (Unit)
+
+For pure logic (game rules, scoring, RNG seeding): standard Vitest. PixiJS
+rendering should NOT be unit tested — use Playwright for that.
+
+```ts
+import { describe, it, expect } from 'vitest';
+import { computeMatchScore } from './scoring';
+
+describe('matchScore', () => {
+ it('grants 100 base + 10 per chain', () => {
+ expect(computeMatchScore({ matched: 3, chain: 2 })).toBe(120);
+ });
+});
+```
+
+### Playwright (E2E / Browser)
+
+For the canvas itself, user input, mobile emulation, visual regression:
+
+```ts
+import { test, expect, devices } from '@playwright/test';
+
+test.use({ ...devices['iPhone 13'] });
+
+test('player can tap to fire', async ({ page }) => {
+ await page.goto('/');
+ await page.waitForFunction(() => window.__GAME_READY__ === true);
+ await page.tap('canvas', { position: { x: 200, y: 400 } });
+ // Assert via game state exposed on window for testing
+ const score = await page.evaluate(() => window.__GAME__.score);
+ expect(score).toBeGreaterThan(0);
+});
+```
+
+**Pattern**: Expose a minimal `window.__GAME__` object in dev/test builds for
+state inspection. Don't try to read pixel data from canvas (slow, flaky).
+
+---
+
+## See Also
+
+- [`modules/rendering.md`](modules/rendering.md) — Renderer/Application detail
+- [`modules/input.md`](modules/input.md) — Pointer/Touch/Gamepad
+- [`modules/audio.md`](modules/audio.md) — WebAudio + Howler
+- [`modules/build.md`](modules/build.md) — Vite tuning
+- [`PLUGINS.md`](PLUGINS.md) — Optional libraries (filters, Howler, GSAP)
diff --git a/docs/engine-reference/html5/deprecated-apis.md b/docs/engine-reference/html5/deprecated-apis.md
new file mode 100644
index 0000000000..56e5a7725b
--- /dev/null
+++ b/docs/engine-reference/html5/deprecated-apis.md
@@ -0,0 +1,162 @@
+# HTML5 / PixiJS — Deprecated API Quick Reference
+
+**Last verified:** 2026-06-11
+
+**Purpose**: Fast "don't use X → use Y" lookup. When in doubt about a PixiJS
+API, search this file first. For full context on why each change happened,
+see [`breaking-changes.md`](breaking-changes.md).
+
+---
+
+## PixiJS v7 (or earlier) → v8
+
+### Imports
+
+| ❌ Deprecated | ✅ Use Instead |
+|--------------|---------------|
+| `import { X } from '@pixi/app'` | `import { X } from 'pixi.js'` |
+| `import { X } from '@pixi/sprite'` | `import { X } from 'pixi.js'` |
+| `import { X } from '@pixi/graphics'` | `import { X } from 'pixi.js'` |
+| `import { utils } from 'pixi.js'` | `import { hex2rgb, ... } from 'pixi.js'` (direct) |
+
+### Application Lifecycle
+
+| ❌ Deprecated | ✅ Use Instead |
+|--------------|---------------|
+| `new Application({ ... })` (with options) | `new Application(); await app.init({ ... });` |
+| `app.view` | `app.canvas` |
+| `app.renderer.view` | `app.renderer.canvas` |
+
+### Graphics
+
+| ❌ Deprecated | ✅ Use Instead |
+|--------------|---------------|
+| `.beginFill(c)` | (delete — use `.fill(c)` after shape) |
+| `.endFill()` | (delete — `.fill(c)` is terminal) |
+| `.drawRect(x,y,w,h)` | `.rect(x,y,w,h)` |
+| `.drawCircle(x,y,r)` | `.circle(x,y,r)` |
+| `.drawEllipse(x,y,w,h)` | `.ellipse(x,y,w,h)` |
+| `.drawPolygon([...])` | `.poly([...])` |
+| `.drawRoundedRect(x,y,w,h,r)` | `.roundRect(x,y,w,h,r)` |
+| `.drawStar(x,y,points,r)` | `.star(x,y,points,r)` |
+| `.lineStyle(w, color)` | `.stroke({ width: w, color })` (after shape) |
+| `.lineTo(x,y)` | `.lineTo(x,y)` (unchanged but pair with `.stroke()`) |
+
+### Container & DisplayObject
+
+| ❌ Deprecated | ✅ Use Instead |
+|--------------|---------------|
+| `extends DisplayObject` | `extends Container` |
+| `sprite.addChild(other)` | (removed for `Sprite`/`Mesh`/`Graphics` — wrap in `Container`) |
+| `obj.name` | `obj.label` |
+| `obj.updateTransform()` override | `obj.onRender = (renderer) => { ... }` |
+| `cacheAsBitmap = true` | `cacheAsTexture()` (method call) |
+| `getBounds()` (returns Rectangle) | `getBounds().rectangle` (Bounds object → .rectangle) |
+
+### Textures
+
+| ❌ Deprecated | ✅ Use Instead |
+|--------------|---------------|
+| `Texture.from('url')` (auto-loads) | `await Assets.load('url'); Texture.from('url')` |
+| `BaseTexture` | `TextureSource` subclasses: `ImageSource`, `VideoSource`, `CanvasSource` |
+| `new BaseTexture(resource)` | `new ImageSource({ resource })` (or matching subclass) |
+
+### Assets
+
+| ❌ Deprecated | ✅ Use Instead |
+|--------------|---------------|
+| `Loader` (entire class) | `Assets` (already in v7, but now mandatory in v8) |
+| `Assets.add('alias', 'url')` | `Assets.add({ alias: 'alias', src: 'url' })` |
+
+### ParticleContainer
+
+| ❌ Deprecated | ✅ Use Instead |
+|--------------|---------------|
+| `pc.addChild(sprite)` | `pc.addParticle(new Particle({ texture, x, y }))` |
+| `pc.children` | `pc.particleChildren` |
+| Automatic bounds | `pc.boundsArea = new Rectangle(...)` (required) |
+| Sprite-based properties | `Particle` with `dynamicProperties` config |
+
+### Filters
+
+| ❌ Deprecated | ✅ Use Instead |
+|--------------|---------------|
+| `new Filter(vert, frag, uniforms)` | `new Filter({ glProgram: GlProgram.from({vert, frag}), resources: {...} })` |
+| Untyped uniforms `{ uTime: 0 }` | Typed: `{ uTime: { value: 0, type: 'f32' } }` |
+| `new BlurFilter(8, 4, 1, 5)` | `new BlurFilter({ strength: 8, quality: 4, resolution: 1, kernelSize: 5 })` |
+
+### Mesh
+
+| ❌ Deprecated | ✅ Use Instead |
+|--------------|---------------|
+| `SimpleMesh` | `MeshSimple` |
+| `SimplePlane` | `MeshPlane` |
+| `SimpleRope` | `MeshRope` |
+| `NineSlicePlane` | `NineSliceSprite` |
+
+### Ticker
+
+| ❌ Deprecated | ✅ Use Instead |
+|--------------|---------------|
+| `Ticker.shared.add((delta: number) => ...)` | `Ticker.shared.add((ticker: Ticker) => { ticker.deltaTime })` |
+
+### Constants & Settings
+
+| ❌ Deprecated | ✅ Use Instead |
+|--------------|---------------|
+| `SCALE_MODES.LINEAR` | `'linear'` (string) |
+| `SCALE_MODES.NEAREST` | `'nearest'` |
+| `WRAP_MODES.CLAMP` | `'clamp-to-edge'` |
+| `WRAP_MODES.REPEAT` | `'repeat'` |
+| `BLEND_MODES.NORMAL` | `'normal'` |
+| `BLEND_MODES.ADD` | `'add'` |
+| `settings.RESOLUTION = N` | `AbstractRenderer.defaultOptions.resolution = N` |
+| `settings.ADAPTER = X` | `DOMAdapter.set(X)` |
+
+### Renderer Detection
+
+| ❌ Deprecated | ✅ Use Instead |
+|--------------|---------------|
+| `autoDetectRenderer({...})` | `await autoDetectRenderer({...})` (now async) |
+| Pin to `WebGLRenderer` only | `preference: 'webgl'` in init options |
+| Pin to `WebGPURenderer` only | `preference: 'webgpu'` in init options |
+
+---
+
+## Vite 5/6 → 7/8
+
+| ❌ Older Pattern | ✅ Use Instead |
+|--------------|---------------|
+| `build.target: 'modules'` (Vite 6 default) | `'baseline-widely-available'` (Vite 7+ default) |
+| `define: { 'process.env': ... }` | Prefer `import.meta.env.*` directly |
+| `optimizeDeps.entries: 'src/**/*.ts'` (glob string) | Use array of explicit paths |
+| Single `server` config | `server.environments` (Vite 6+ multi-env) |
+
+For Rolldown-specific (Vite 8) notes, see [`current-best-practices.md`](current-best-practices.md).
+
+---
+
+## Playwright
+
+No major deprecations between 1.40 and 1.49 — mostly additive. Older Playwright
+code keeps working; just lacks newer device descriptors and improved touch sim.
+
+---
+
+## TypeScript Patterns to Avoid in PixiJS Code
+
+| ❌ Anti-Pattern | ✅ Use Instead |
+|---------------|---------------|
+| `(sprite as any).foo` | Cast through proper type guard or extend `Container` properly |
+| `any` for Asset return | `Assets.load(url)` (typed return) |
+| Loose `Container.children` access | Type-narrow with `Container` |
+| Untyped event handlers | Use `FederatedPointerEvent`, `FederatedWheelEvent`, etc. |
+
+---
+
+## When in Doubt
+
+1. Check this file first
+2. If not found, check [`breaking-changes.md`](breaking-changes.md)
+3. WebSearch `"pixijs v8 [API name]"` for confirmation
+4. Verify against https://pixijs.com/8.x/guides
diff --git a/docs/engine-reference/html5/modules/animation.md b/docs/engine-reference/html5/modules/animation.md
new file mode 100644
index 0000000000..85a9209e49
--- /dev/null
+++ b/docs/engine-reference/html5/modules/animation.md
@@ -0,0 +1,315 @@
+# HTML5 / PixiJS — Animation Module
+
+**Last verified:** 2026-06-11
+
+Sprite animation, tweening with GSAP, Pixi Ticker integration, skeletal
+animation (Spine), and timing patterns for game feel.
+
+---
+
+## Three Layers of Animation
+
+| Layer | Tool | Use For |
+|-------|------|---------|
+| Frame animation (sprite sheets) | `AnimatedSprite` | Character walk cycles, explosions |
+| Tweening (interpolation) | GSAP or manual | Menu transitions, card flips, UI motion |
+| Skeletal | Spine / DragonBones | Complex character animation, IK |
+
+---
+
+## AnimatedSprite (Frame Animation)
+
+```ts
+import { Assets, AnimatedSprite, Texture } from 'pixi.js';
+
+const sheet = await Assets.load('assets/player.json'); // spritesheet
+
+const idleFrames = Object.values(sheet.animations.idle); // Texture[]
+const player = new AnimatedSprite(idleFrames);
+player.animationSpeed = 0.15;
+player.loop = true;
+player.play();
+
+// Switch animation
+function setAnim(name: 'idle' | 'walk' | 'jump') {
+ player.textures = sheet.animations[name];
+ player.play();
+}
+```
+
+### Spritesheet Format
+
+Use TexturePacker JSON Hash with named animation groups, or Aseprite export
+with explicit frame tags:
+
+```json
+{
+ "frames": { "player_idle_01.png": { ... }, "player_walk_01.png": { ... } },
+ "animations": {
+ "idle": ["player_idle_01.png", "player_idle_02.png"],
+ "walk": ["player_walk_01.png", "player_walk_02.png", "player_walk_03.png"]
+ }
+}
+```
+
+PixiJS parses `animations` directly into `sheet.animations[name]`.
+
+---
+
+## GSAP Tweening
+
+GSAP picks up Pixi properties via direct property access — no plugin needed.
+
+```ts
+import { gsap } from 'gsap';
+
+// Simple tween
+gsap.to(card, { x: 400, duration: 0.5, ease: 'power2.out' });
+
+// Chained sequence
+gsap.timeline()
+ .to(card, { scale: 1.2, duration: 0.2 })
+ .to(card, { rotation: Math.PI, duration: 0.4 })
+ .to(card, { scale: 1.0, duration: 0.2 });
+
+// Pixi-specific properties
+gsap.to(sprite.scale, { x: 1.5, y: 1.5, duration: 0.3 });
+gsap.to(sprite, { alpha: 0, duration: 0.3, onComplete: () => sprite.destroy() });
+```
+
+### Eases for Game Feel
+
+| Ease | Use |
+|------|-----|
+| `'power2.out'` | Most UI motion (decelerating arrival) |
+| `'back.out(1.7)'` | Overshoot landing (bouncy cards) |
+| `'elastic.out(1, 0.3)'` | Spring effect (button press release) |
+| `'expo.in'` | Whoosh-out (exit transitions) |
+| `'sine.inOut'` | Continuous loops (bobbing, floating) |
+| `'steps(N)'` | Choppy / 8-bit style |
+
+### Ticker Integration
+
+GSAP runs on its own RAF loop by default. To synchronize with Pixi's Ticker
+(for pause/resume in sync with game time):
+
+```ts
+import { gsap } from 'gsap';
+import { Ticker } from 'pixi.js';
+
+gsap.ticker.lagSmoothing(0); // disable GSAP's own smoothing
+gsap.ticker.remove(gsap.updateRoot); // stop GSAP's auto-tick
+
+Ticker.shared.add((ticker) => {
+ gsap.updateRoot(ticker.lastTime / 1000); // drive GSAP from Pixi
+});
+```
+
+Now `Ticker.shared.stop()` pauses both Pixi rendering AND GSAP tweens.
+
+---
+
+## Manual Tweening (No Library)
+
+For simple cases or when you want full control:
+
+```ts
+class Tween {
+ private elapsed = 0;
+ constructor(
+ private target: any,
+ private prop: string,
+ private from: number,
+ private to: number,
+ private duration: number,
+ private ease: (t: number) => number = (t) => t,
+ ) {}
+
+ update(dt: number): boolean {
+ this.elapsed += dt;
+ const t = Math.min(this.elapsed / this.duration, 1);
+ this.target[this.prop] = this.from + (this.to - this.from) * this.ease(t);
+ return t < 1;
+ }
+}
+
+// Easing functions
+const easeOutCubic = (t: number) => 1 - Math.pow(1 - t, 3);
+const easeInOutQuad = (t: number) => t < 0.5 ? 2*t*t : 1 - Math.pow(-2*t+2, 2)/2;
+```
+
+When tween count > ~20, switch to GSAP — its scheduler is far more efficient
+than naive arrays of tweens.
+
+---
+
+## Pixi Ticker
+
+```ts
+import { Ticker } from 'pixi.js';
+
+// Add update (default: 60fps target)
+Ticker.shared.add((ticker) => {
+ const dt = ticker.deltaMS / 1000; // seconds since last frame
+ player.x += player.vx * dt;
+});
+
+// Limit FPS (battery saving)
+Ticker.shared.maxFPS = 30;
+
+// Pause / resume
+Ticker.shared.stop();
+Ticker.shared.start();
+
+// Priority (run before/after default updates)
+Ticker.shared.add(updateInput, { priority: UPDATE_PRIORITY.HIGH });
+Ticker.shared.add(updatePhysics, { priority: UPDATE_PRIORITY.NORMAL });
+Ticker.shared.add(updateRender, { priority: UPDATE_PRIORITY.LOW });
+```
+
+### Time-Based vs Frame-Based
+
+| Approach | When | Pros / Cons |
+|----------|------|-------------|
+| `ticker.deltaMS / 1000` | Physics, movement | Frame-rate independent. Required for any time-sensitive logic. |
+| `ticker.deltaTime` | Visual tweens, animations | Normalized to 60fps frames. Convenient for "advance by 1 frame" logic. |
+
+**Default rule**: use `deltaMS` for game logic. Use `deltaTime` only for legacy
+60fps-locked animations.
+
+### Fixed Timestep Game Loop
+
+```ts
+const FIXED_DT = 1 / 60; // 60 game updates per second
+let accumulator = 0;
+
+Ticker.shared.add((ticker) => {
+ accumulator += ticker.deltaMS / 1000;
+ while (accumulator >= FIXED_DT) {
+ updateGameLogic(FIXED_DT); // deterministic
+ accumulator -= FIXED_DT;
+ }
+ const alpha = accumulator / FIXED_DT;
+ interpolateRender(alpha); // smooth interpolation between game states
+});
+```
+
+Use this when:
+- Physics needs determinism (replays, multiplayer)
+- Game logic must be reproducible
+- High-refresh-rate displays (120Hz, 144Hz) should not run logic faster
+
+---
+
+## Particles
+
+For 100s-1000s of particles, use `ParticleContainer`:
+
+```ts
+import { ParticleContainer, Particle, Texture } from 'pixi.js';
+
+const pc = new ParticleContainer({
+ dynamicProperties: {
+ position: true,
+ scale: false,
+ rotation: false,
+ color: false,
+ },
+});
+pc.boundsArea = new Rectangle(0, 0, app.renderer.width, app.renderer.height);
+
+interface MyParticle {
+ particle: Particle;
+ vx: number; vy: number; life: number;
+}
+
+const particles: MyParticle[] = [];
+
+function spawn(x: number, y: number, texture: Texture) {
+ const p = new Particle({ texture, x, y });
+ pc.addParticle(p);
+ particles.push({ particle: p, vx: (Math.random()-0.5)*200, vy: -200, life: 1 });
+}
+
+Ticker.shared.add((ticker) => {
+ const dt = ticker.deltaMS / 1000;
+ for (let i = particles.length - 1; i >= 0; i--) {
+ const p = particles[i];
+ p.particle.x += p.vx * dt;
+ p.particle.y += p.vy * dt;
+ p.vy += 500 * dt; // gravity
+ p.life -= dt;
+ if (p.life <= 0) {
+ pc.removeParticle(p.particle);
+ particles.splice(i, 1);
+ }
+ }
+});
+```
+
+**Why `ParticleContainer`**: Explicit batching, no per-particle bounds check,
+no per-particle event system. 10-50x faster than `Container` for >500
+particles.
+
+---
+
+## Spine (Skeletal)
+
+For character animation more complex than sprite sheets, see
+[`../PLUGINS.md`](../PLUGINS.md) for `@esotericsoftware/spine-pixi-v8`.
+
+Basic usage:
+
+```ts
+import { Spine } from '@esotericsoftware/spine-pixi-v8';
+
+const spineboy = Spine.from({ skeleton: 'spineboy.json', atlas: 'spineboy.atlas' });
+spineboy.state.setAnimation(0, 'walk', true);
+spineboy.skeleton.scaleX = 1;
+app.stage.addChild(spineboy);
+```
+
+---
+
+## Animation State Machines
+
+For character logic, separate "what animation is playing" from "what the
+character should be doing":
+
+```ts
+type AnimState = 'idle' | 'walk' | 'jump' | 'attack';
+
+class Character {
+ private state: AnimState = 'idle';
+ private sprite: AnimatedSprite;
+
+ setState(next: AnimState) {
+ if (this.state === next) return;
+ this.state = next;
+ this.sprite.textures = sheet.animations[next];
+ this.sprite.play();
+ }
+}
+```
+
+For complex behavior trees, use a library like XState — but for typical game
+characters, an enum + switch is sufficient.
+
+---
+
+## Common Pitfalls
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Tween snaps to end on resume | Ticker stop doesn't pause GSAP | Drive GSAP from Pixi Ticker (above) |
+| Animation jumps when switching | New textures applied mid-frame | Set `sprite.currentFrame = 0` after swap |
+| AnimatedSprite stuck on last frame | `loop: false` and no callback | Use `onComplete: () => ...` to advance state |
+| Particle "popcorn" snapping | Particle position not interpolated | Use fixed timestep + interpolation alpha |
+
+---
+
+## See Also
+
+- [`rendering.md`](rendering.md) — Container hierarchy
+- [`../PLUGINS.md`](../PLUGINS.md) — GSAP, Spine
+- [`../current-best-practices.md`](../current-best-practices.md) — Ticker patterns
diff --git a/docs/engine-reference/html5/modules/audio.md b/docs/engine-reference/html5/modules/audio.md
new file mode 100644
index 0000000000..968d017865
--- /dev/null
+++ b/docs/engine-reference/html5/modules/audio.md
@@ -0,0 +1,235 @@
+# HTML5 / PixiJS — Audio Module
+
+**Last verified:** 2026-06-11
+
+WebAudio basics, Howler.js patterns, mobile audio unlock, audio sprites, and
+common pitfalls.
+
+---
+
+## The Mobile Audio Problem
+
+Browsers (Chrome, Safari, mobile especially) block audio playback until
+**the user makes a gesture** (tap, click, key). Naive code like
+`new Audio('bgm.mp3').play()` will fail silently on first load.
+
+**Solution**: Initialize audio after the first `pointerdown` event, OR use
+a library (Howler) that handles the unlock automatically.
+
+---
+
+## Recommendation: Howler.js
+
+For anything beyond a single ambient track, **use Howler**. See
+[`../PLUGINS.md`](../PLUGINS.md) for rationale.
+
+### Basic Setup
+
+```ts
+import { Howl, Howler } from 'howler';
+
+const bgm = new Howl({
+ src: ['assets/bgm.webm', 'assets/bgm.mp3'], // fallback chain
+ loop: true,
+ volume: 0.5,
+ html5: false, // false = WebAudio (lower latency); true = HTML5 streaming (less RAM, higher latency)
+});
+
+const sfx_jump = new Howl({
+ src: ['assets/sfx.webm', 'assets/sfx.mp3'],
+ sprite: {
+ jump: [0, 300], // [start_ms, duration_ms]
+ hit: [500, 200],
+ coin: [800, 250],
+ },
+});
+
+// Wait for first user gesture before playing
+window.addEventListener('pointerdown', () => {
+ bgm.play();
+}, { once: true });
+```
+
+### Audio Sprites (Critical for Mobile)
+
+A single audio file with multiple sub-clips. Saves HTTP requests AND decode
+work. Tool: [audiosprite](https://github.com/tonistiigi/audiosprite) generates
+JSON config; pass it to Howler:
+
+```ts
+const sfx = new Howl({
+ src: ['sfx.webm', 'sfx.mp3'],
+ sprite: { /* generated */ },
+});
+
+sfx.play('jump');
+sfx.play('coin');
+```
+
+### Volume Categories
+
+```ts
+// Global mixer
+Howler.volume(0.8); // 0..1
+
+// Per-category (manual via your own grouping)
+const sfxHowls: Howl[] = [];
+function setSfxVolume(v: number) {
+ sfxHowls.forEach((h) => h.volume(v));
+}
+```
+
+For complex mixing, build a simple mixer wrapper:
+
+```ts
+class AudioMixer {
+ private masterVol = 1;
+ private bgmVol = 0.5;
+ private sfxVol = 0.8;
+
+ private bgm: Howl | null = null;
+ private sfx: Howl[] = [];
+
+ setMaster(v: number) { this.masterVol = v; this.applyAll(); }
+ setBgm(v: number) { this.bgmVol = v; this.applyBgm(); }
+ setSfx(v: number) { this.sfxVol = v; this.applySfx(); }
+
+ private applyAll() { Howler.volume(this.masterVol); }
+ private applyBgm() { this.bgm?.volume(this.bgmVol); }
+ private applySfx() { this.sfx.forEach((h) => h.volume(this.sfxVol)); }
+}
+```
+
+---
+
+## Native WebAudio (No Library)
+
+Use only when:
+- You need procedural synthesis (oscillators, Tone.js territory)
+- You have ONE ambient track and don't want a dependency
+- You're building a rhythm game with sample-accurate scheduling
+
+```ts
+let ctx: AudioContext | null = null;
+
+function initAudio() {
+ if (ctx) return;
+ ctx = new AudioContext();
+}
+
+window.addEventListener('pointerdown', initAudio, { once: true });
+
+async function playSample(url: string) {
+ if (!ctx) return;
+ const buf = await fetch(url).then((r) => r.arrayBuffer());
+ const audioBuf = await ctx.decodeAudioData(buf);
+ const src = ctx.createBufferSource();
+ src.buffer = audioBuf;
+ src.connect(ctx.destination);
+ src.start();
+}
+```
+
+For "play same sound 100 times rapid" — pre-decode once, then reuse the
+`AudioBuffer`. Don't re-decode each time.
+
+---
+
+## Format Strategy
+
+| Format | Browser Support | Compression | Use |
+|--------|----------------|-------------|-----|
+| WebM (Opus) | Chrome/Firefox/Edge/Safari 14.1+ | Excellent | Primary |
+| MP3 | Universal | Good | Fallback for older Safari |
+| OGG | Firefox/Chrome (NOT Safari) | Excellent | Skip — WebM covers same niche |
+| WAV | Universal | None | Dev only, never ship |
+
+**Pattern**: provide WebM + MP3 in Howler's `src` array — Howler picks the
+first the browser accepts.
+
+```bash
+# Convert with ffmpeg
+ffmpeg -i bgm.wav -c:a libopus -b:a 96k bgm.webm
+ffmpeg -i bgm.wav -c:a libmp3lame -b:a 128k bgm.mp3
+```
+
+---
+
+## Bitrate Recommendations
+
+| Content | Format | Bitrate | Notes |
+|---------|--------|---------|-------|
+| BGM (mono) | Opus / MP3 | 64-96 kbps | Mobile-friendly |
+| BGM (stereo) | Opus | 96-128 kbps | Most mobile games are mono |
+| SFX (short) | Opus | 64 kbps | Often imperceptible at lower |
+| Voice | Opus | 32-64 kbps | Speech codec is efficient |
+
+**Mobile total audio budget**: 3-5 MB for entire game. Each MB of audio is
+seconds added to first-load on a 4G connection.
+
+---
+
+## Latency
+
+WebAudio: ~20-50ms typical latency on modern devices. Acceptable for casual
+games. NOT acceptable for rhythm games — those need:
+
+- AudioWorklet for precise scheduling
+- `audioContext.outputLatency` to compensate timings
+- Visual cues offset by latency (don't show "tap now" at the same moment
+ the user should hear)
+
+For rhythm/music games, consider Tone.js (built on AudioWorklet) over Howler.
+
+---
+
+## Common Pitfalls
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Audio silent on mobile | No user gesture yet | Init Howler / AudioContext after first `pointerdown` |
+| iOS Safari plays only one sound | WebAudio context suspended | Call `Howler.ctx.resume()` after each unlock event |
+| BGM cut off when minimizing | Browser suspends inactive tabs | Use `Howler.autoSuspend = false` (drain battery — opt-in) |
+| Clicking sound on play | Volume snaps from 0 to N | Use Howler `fade()` for ramps |
+| SFX delayed on first play | First decode happens during play | Pre-warm: `sfx.play('jump'); sfx.stop();` at load |
+| Stuttering on Android | Multiple Howl instances of same sound | Use one Howl with sprites, not multiple Howls |
+
+---
+
+## Volume Persistence
+
+```ts
+// Save
+localStorage.setItem('vol_master', String(mixer.masterVol));
+localStorage.setItem('vol_bgm', String(mixer.bgmVol));
+localStorage.setItem('vol_sfx', String(mixer.sfxVol));
+
+// Load on init
+const masterVol = parseFloat(localStorage.getItem('vol_master') ?? '0.8');
+```
+
+For richer persistence, use IndexedDB (e.g., `idb-keyval` library).
+
+---
+
+## Testing Audio in Playwright
+
+Playwright disables audio by default in headless mode. To test audio paths:
+
+```ts
+test.use({
+ launchOptions: {
+ args: ['--autoplay-policy=no-user-gesture-required'],
+ },
+});
+```
+
+Or just assert that the `play()` call was made (mock Howler in tests).
+
+---
+
+## See Also
+
+- [`../PLUGINS.md`](../PLUGINS.md) — Howler, Tone.js, @pixi/sound
+- [`input.md`](input.md) — First-gesture pattern
+- [`../current-best-practices.md`](../current-best-practices.md) — Mobile loading strategy
diff --git a/docs/engine-reference/html5/modules/build.md b/docs/engine-reference/html5/modules/build.md
new file mode 100644
index 0000000000..bf81ce1f8c
--- /dev/null
+++ b/docs/engine-reference/html5/modules/build.md
@@ -0,0 +1,329 @@
+# HTML5 / PixiJS — Build Module
+
+**Last verified:** 2026-06-11
+
+Vite configuration, bundle optimization, asset pipeline, PWA setup, and
+deployment patterns for HTML5 games. This module exists because mobile web
+games are uniquely bandwidth-sensitive — every kilobyte costs first-load time.
+
+---
+
+## Vite Setup Baseline
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+ base: './', // relative paths — works on itch.io, GitHub Pages, etc.
+ build: {
+ target: 'es2022',
+ minify: 'esbuild', // Vite 7 default; Vite 8 uses Oxc
+ sourcemap: true, // turn OFF for prod if size critical
+ cssCodeSplit: false, // games typically have one CSS file
+ rollupOptions: {
+ output: {
+ manualChunks: {
+ pixi: ['pixi.js'],
+ gsap: ['gsap'],
+ howler: ['howler'],
+ },
+ },
+ },
+ assetsInlineLimit: 0, // never inline binary assets
+ chunkSizeWarningLimit: 1500, // games hit this; raise the threshold
+ },
+ server: {
+ host: '0.0.0.0', // mobile device LAN testing
+ port: 5173,
+ },
+ preview: {
+ port: 5174, // separate from dev to avoid cache confusion
+ },
+});
+```
+
+### Why these settings
+
+| Setting | Reason |
+|---------|--------|
+| `base: './'` | Relative paths so the build works on any subpath without rebuild |
+| `manualChunks` | Pixi (~250KB), GSAP (~70KB), Howler (~30KB) each cache independently from your code |
+| `assetsInlineLimit: 0` | Inlined assets break browser HTTP caching for shared atlases |
+| `host: '0.0.0.0'` | Critical for testing on real phones over WiFi |
+| `cssCodeSplit: false` | Games have minimal CSS — splitting adds requests without benefit |
+
+---
+
+## Bundle Size Targets
+
+| Layer | Target gzipped | Why |
+|-------|---------------|-----|
+| First HTML | <5 KB | Single round-trip parse |
+| First JS (your code + entry) | <50 KB | Show loading screen ASAP |
+| Pixi chunk | ~150 KB | Cached separately |
+| All vendor chunks combined | <300 KB | Lazy-loaded after init |
+| Initial assets (atlas + 1 font) | <500 KB | First playable scene |
+
+**Total time-to-playable target on 4G**: <3 seconds.
+
+To audit: `vite build` produces `dist/`; inspect `dist/assets/*` sizes.
+For interactive breakdown: `rollup-plugin-visualizer`:
+
+```bash
+npm i -D rollup-plugin-visualizer
+```
+
+```ts
+import { visualizer } from 'rollup-plugin-visualizer';
+export default defineConfig({
+ plugins: [visualizer({ open: true, gzipSize: true })],
+});
+```
+
+---
+
+## Asset Pipeline
+
+### Sprite Atlases
+
+Use TexturePacker or `free-tex-packer` to combine images into atlases:
+
+- One atlas per logical group (UI, characters, environment)
+- Power-of-two dimensions (1024×1024, 2048×2048) — best GPU compatibility
+- Trim whitespace, rotate where helpful
+- Generate PixiJS JSON Hash format (Pixi parses it natively)
+
+### Texture Compression (KTX2)
+
+For projects > 5 MB of art:
+
+1. Use `toktx` or `basisu` to convert PNGs → KTX2 Basis Universal
+2. PixiJS 8 supports KTX2 via Assets system
+3. 50-75% GPU memory reduction; smaller download too
+
+```bash
+# Convert single atlas
+basisu -ktx2 -uastc atlas.png -output_path atlas.ktx2
+```
+
+### Audio Compression
+
+- BGM: Opus at 64-96kbps → ~1 MB / minute
+- SFX: Opus at 48-64kbps via audio sprites → one 200-500 KB file holds all SFX
+- See [`audio.md`](audio.md) for full format strategy
+
+### Image Optimization
+
+For non-atlas images (loading screen, splash):
+
+- PNG: use `oxipng` or `pngquant` (lossy palette quantization)
+- JPEG: `mozjpeg`
+- WebP: 25-35% smaller than equivalent JPEG; universal browser support by 2026
+- AVIF: 50% smaller than JPEG; supported but encode is slow — use for static images only
+
+```bash
+# Bulk WebP convert
+for f in *.png; do cwebp -q 85 "$f" -o "${f%.png}.webp"; done
+```
+
+---
+
+## Code Splitting
+
+Lazy-load gameplay code after the menu loads:
+
+```ts
+// main.ts — entry, ~10 KB
+import { showMenu } from './menu';
+
+showMenu({
+ onStart: async () => {
+ const { startGame } = await import('./game'); // separate chunk
+ startGame();
+ },
+});
+```
+
+Vite automatically code-splits on dynamic `import()`. Your menu loads instantly;
+the gameplay code (and its assets) load when the player presses Start.
+
+---
+
+## Pre-compression
+
+Configure your host or build to serve pre-compressed assets:
+
+```ts
+import { compression } from 'vite-plugin-compression2';
+
+export default defineConfig({
+ plugins: [
+ compression({ algorithm: 'gzip' }),
+ compression({ algorithm: 'brotliCompress', ext: '.br' }),
+ ],
+});
+```
+
+Produces `.gz` and `.br` alongside originals. Configure your CDN / web server
+to serve them when `Accept-Encoding` matches.
+
+**Brotli is ~15% smaller than gzip** for text. For binary assets (PNG, MP3),
+already-compressed formats won't gain — only enable for JS/CSS/HTML/JSON.
+
+---
+
+## PWA — Progressive Web App
+
+For installable, offline-capable HTML5 games:
+
+```bash
+npm i -D vite-plugin-pwa
+```
+
+```ts
+import { VitePWA } from 'vite-plugin-pwa';
+
+export default defineConfig({
+ plugins: [
+ VitePWA({
+ registerType: 'autoUpdate',
+ includeAssets: ['favicon.png', 'apple-touch-icon.png'],
+ manifest: {
+ name: 'Your Game',
+ short_name: 'Game',
+ theme_color: '#000000',
+ background_color: '#000000',
+ display: 'fullscreen',
+ orientation: 'portrait',
+ start_url: '/',
+ icons: [
+ { src: 'icon-192.png', sizes: '192x192', type: 'image/png' },
+ { src: 'icon-512.png', sizes: '512x512', type: 'image/png' },
+ ],
+ },
+ workbox: {
+ globPatterns: ['**/*.{js,css,html,png,webp,mp3,webm,woff2,json}'],
+ maximumFileSizeToCacheInBytes: 10 * 1024 * 1024,
+ },
+ }),
+ ],
+});
+```
+
+**Benefits**:
+- Installable to homescreen (iOS, Android)
+- Offline play after first load
+- Push notifications (with consent)
+- Full-screen presentation (no browser chrome)
+
+**Caveat**: iOS PWA support has historically lagged. By 2026 the gap has
+narrowed, but Web Push on iOS still requires the user to install the PWA
+first (not just visit). Verify on actual devices.
+
+---
+
+## Service Worker Caching Strategy
+
+For games, the default Workbox "precache everything" works well — it's exactly
+what you want for offline-capable games. The downside: every code change
+busts the entire cache on next visit. Mitigate by splitting:
+
+- Vendor chunks (Pixi, GSAP) — long-cached, only invalidates on dep upgrade
+- App chunks — hash-named, invalidate when your code changes
+- Asset chunks — also hash-named
+
+Vite handles content hashing automatically.
+
+---
+
+## Mobile Performance Headers
+
+Configure your host to send:
+
+```
+Cache-Control: public, max-age=31536000, immutable # for hashed assets
+Cache-Control: no-cache # for index.html
+Content-Encoding: br # if Brotli pre-compressed
+```
+
+`immutable` is critical — tells the browser to never revalidate hashed asset
+URLs even on hard refresh.
+
+---
+
+## Deployment Targets
+
+| Target | Strategy |
+|--------|----------|
+| Itch.io | `vite build`, zip `dist/`, upload — done |
+| GitHub Pages | `vite build --base=/repo-name/`, push `dist/` to `gh-pages` branch |
+| Netlify / Vercel | `vite build`, configure publish dir = `dist/` |
+| Cloudflare Pages | Same as Netlify; better edge perf for global audiences |
+| Custom CDN | Build, sync `dist/` to S3/R2, point CDN at bucket |
+| Mobile app store (wrapped) | Capacitor (preferred 2026) or Cordova → builds native binary |
+
+### itch.io Specific
+
+- Game must be in a `.zip` with `index.html` at root
+- Set viewport in itch.io project settings (matches your game canvas)
+- "Frame your game" → choose Fullscreen for mobile
+- Use `--base=./` (relative paths) so the zip works without absolute URLs
+
+---
+
+## CI Build
+
+GitHub Actions example:
+
+```yaml
+name: Build
+on: [push, pull_request]
+
+jobs:
+ build:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v4
+ - uses: actions/setup-node@v4
+ with: { node-version: '20' }
+ - run: npm ci
+ - run: npm run typecheck
+ - run: npm test
+ - run: npm run build
+ - uses: actions/upload-artifact@v4
+ with: { name: dist, path: dist/ }
+```
+
+For Playwright e2e (see [`../current-best-practices.md`](../current-best-practices.md)):
+
+```yaml
+ - run: npx playwright install --with-deps
+ - run: npx playwright test
+ - if: failure()
+ uses: actions/upload-artifact@v4
+ with: { name: playwright-report, path: playwright-report/ }
+```
+
+---
+
+## Vite 7 → 8 Migration
+
+Vite 8 (Mar 2026) swaps esbuild + Rollup for Rolldown + Oxc. For most game
+projects, the migration is:
+
+1. Bump `vite` to `^8`
+2. Update plugin versions to ones declaring `vite: '^8'` peer dep
+3. Test the build output — should be byte-similar but not identical
+4. If you have custom Rollup plugins, check Rolldown compatibility
+
+**Hold off** if you have ecosystem dependencies that haven't released v8-compatible
+versions. Vite 7.3 will get security patches through 2026.
+
+---
+
+## See Also
+
+- [`../PLUGINS.md`](../PLUGINS.md) — Optional libraries with bundle size notes
+- [`../current-best-practices.md`](../current-best-practices.md) — Test patterns
+- [`audio.md`](audio.md) — Audio format / size strategy
diff --git a/docs/engine-reference/html5/modules/input.md b/docs/engine-reference/html5/modules/input.md
new file mode 100644
index 0000000000..2543b18495
--- /dev/null
+++ b/docs/engine-reference/html5/modules/input.md
@@ -0,0 +1,288 @@
+# HTML5 / PixiJS — Input Module
+
+**Last verified:** 2026-06-11
+
+PixiJS 8 Federated Events, native Pointer/Touch/Gamepad APIs, and
+mobile-web-specific input concerns.
+
+---
+
+## Federated Events (v8 unified pointer model)
+
+PixiJS 8 replaces v7's `interactive: true` with `eventMode`:
+
+```ts
+sprite.eventMode = 'static'; // hit-testable, doesn't move
+sprite.cursor = 'pointer';
+
+sprite.on('pointertap', (e: FederatedPointerEvent) => {
+ console.log('tap at', e.global.x, e.global.y);
+});
+```
+
+### `eventMode` Values
+
+| Mode | Hit-Testable | Performance | Use For |
+|------|--------------|-------------|---------|
+| `'static'` | ✅ | Best | UI buttons, fixed game objects |
+| `'dynamic'` | ✅ | OK | Game objects that move every tick |
+| `'passive'` | Children only | Best | Container that holds interactive children but is not itself a target |
+| `'auto'` | Inherits | OK | Default — rarely set explicitly |
+| `'none'` | ❌ | Best | Pure-visual layers (background, particles) |
+
+**Performance rule**: Default everything to `'none'` or `'passive'`; opt in
+to `'static'` / `'dynamic'` only for things that need clicks. Hit testing is
+not free.
+
+---
+
+## Event Types
+
+| Event | When |
+|-------|------|
+| `pointerdown` | Touch start / mouse down |
+| `pointerup` | Touch end / mouse up |
+| `pointertap` | Down + up on same target without dragging |
+| `pointermove` | Move during interaction |
+| `pointerover` | Cursor entered (mouse only) |
+| `pointerout` | Cursor left (mouse only) |
+| `pointerupoutside` | Released outside the original target |
+| `globalpointermove` | Move anywhere on stage (more expensive — opt-in via `Container.eventMode = 'static'` + listening on stage) |
+| `wheel` | Scroll wheel — `FederatedWheelEvent` |
+
+```ts
+import { FederatedPointerEvent } from 'pixi.js';
+
+button.on('pointertap', (e: FederatedPointerEvent) => {
+ e.stopPropagation(); // don't bubble to parent containers
+});
+```
+
+---
+
+## Globals — `e.global` vs `e.local`
+
+```ts
+sprite.on('pointertap', (e) => {
+ e.global // stage coordinates (CSS pixel space adjusted for renderer)
+ e.client // viewport (window) coordinates
+ e.screen // physical screen pixels
+ e.getLocalPosition(targetContainer) // local coordinates of any container
+});
+```
+
+Most game code wants `e.global` for "where on the play field did this happen?"
+
+---
+
+## Mobile Web Input
+
+### iOS / Android Quirks
+
+| Quirk | Cause | Fix |
+|-------|-------|-----|
+| Audio doesn't play until first tap | Browser autoplay policy | Initialize WebAudio (or Howler) only after first `pointerdown` |
+| Tap delay (~300ms) on old WebViews | Legacy double-tap-to-zoom | Set viewport meta with `user-scalable=no` (use cautiously — accessibility tradeoff) |
+| Pinch zoom interferes with game | Default browser gesture | `touch-action: none` CSS on canvas |
+| Scroll bounce on iOS Safari | Overscroll | `overscroll-behavior: none` on body |
+| Address bar resize mid-play | URL bar collapses | Use `visualViewport.height` not `window.innerHeight` |
+
+### Required CSS Baseline
+
+```css
+html, body {
+ margin: 0;
+ padding: 0;
+ width: 100%;
+ height: 100%;
+ overflow: hidden;
+ overscroll-behavior: none;
+ -webkit-tap-highlight-color: transparent;
+ user-select: none;
+ -webkit-user-select: none;
+ touch-action: none;
+}
+
+canvas {
+ display: block;
+ touch-action: none;
+}
+```
+
+### Tap Target Size
+
+WCAG 2.5.5 recommends ≥48×48 CSS pixels. Mobile games should:
+- Visible button: ≥48×48 px
+- Game world tap target: hit area can be wider than sprite via `sprite.hitArea = new Rectangle(...)`
+
+```ts
+button.hitArea = new Rectangle(-20, -20, 140, 140); // 100x100 sprite + 20px padding
+```
+
+---
+
+## Multi-Touch
+
+```ts
+const activePointers = new Map();
+
+sprite.on('pointerdown', (e) => {
+ activePointers.set(e.pointerId, { x: e.global.x, y: e.global.y });
+});
+
+sprite.on('pointermove', (e) => {
+ if (activePointers.has(e.pointerId)) {
+ activePointers.set(e.pointerId, { x: e.global.x, y: e.global.y });
+ }
+});
+
+sprite.on('pointerup', (e) => activePointers.delete(e.pointerId));
+sprite.on('pointerupoutside', (e) => activePointers.delete(e.pointerId));
+```
+
+For pinch / rotate gestures, track two pointers and compute delta distance / angle.
+
+---
+
+## Virtual Joystick (Mobile)
+
+For action games on mobile web, neither tap nor swipe is enough — use a virtual
+joystick. Either:
+
+1. **Library**: `nipplejs` (DOM overlay) — see [`../PLUGINS.md`](../PLUGINS.md)
+2. **Pixi-native**: draw the joystick as a `Container` with a base and a knob
+ sprite; track pointerdown/move/up and compute the angle/distance
+
+Pixi-native pattern:
+
+```ts
+class VirtualStick extends Container {
+ private base: Sprite;
+ private knob: Sprite;
+ private pointerId: number | null = null;
+ private radius = 60;
+
+ public vector = { x: 0, y: 0 }; // normalized -1..1
+
+ constructor(baseTex: Texture, knobTex: Texture) {
+ super();
+ this.base = new Sprite(baseTex);
+ this.knob = new Sprite(knobTex);
+ this.addChild(this.base, this.knob);
+ this.eventMode = 'static';
+ this.on('pointerdown', this.onDown);
+ this.on('globalpointermove', this.onMove);
+ this.on('pointerup', this.onUp);
+ this.on('pointerupoutside', this.onUp);
+ }
+
+ private onDown = (e: FederatedPointerEvent) => {
+ if (this.pointerId !== null) return;
+ this.pointerId = e.pointerId;
+ };
+
+ private onMove = (e: FederatedPointerEvent) => {
+ if (e.pointerId !== this.pointerId) return;
+ const local = this.toLocal(e.global);
+ const dist = Math.hypot(local.x, local.y);
+ const clamped = Math.min(dist, this.radius);
+ const angle = Math.atan2(local.y, local.x);
+ this.knob.x = Math.cos(angle) * clamped;
+ this.knob.y = Math.sin(angle) * clamped;
+ this.vector.x = this.knob.x / this.radius;
+ this.vector.y = this.knob.y / this.radius;
+ };
+
+ private onUp = (e: FederatedPointerEvent) => {
+ if (e.pointerId !== this.pointerId) return;
+ this.pointerId = null;
+ this.knob.x = 0;
+ this.knob.y = 0;
+ this.vector.x = 0;
+ this.vector.y = 0;
+ };
+}
+```
+
+---
+
+## Keyboard (Desktop)
+
+Pixi has NO built-in keyboard handling. Use native `window.addEventListener`:
+
+```ts
+const keys = new Set();
+window.addEventListener('keydown', (e) => keys.add(e.code));
+window.addEventListener('keyup', (e) => keys.delete(e.code));
+
+Ticker.shared.add(() => {
+ if (keys.has('ArrowLeft')) player.x -= 5;
+ if (keys.has('ArrowRight')) player.x += 5;
+});
+```
+
+Use `KeyboardEvent.code` (layout-independent: `KeyW`, `Space`, `ArrowUp`)
+not `KeyboardEvent.key` (layout-dependent).
+
+---
+
+## Gamepad API
+
+Modern browsers support Xbox/PS controllers via the Gamepad API:
+
+```ts
+function pollGamepad() {
+ const pads = navigator.getGamepads();
+ for (const pad of pads) {
+ if (!pad) continue;
+ const lx = pad.axes[0]; // -1..1
+ const ly = pad.axes[1];
+ const aButton = pad.buttons[0].pressed;
+ // ...
+ }
+}
+
+Ticker.shared.add(pollGamepad);
+```
+
+Gamepad events DO NOT fire — must poll each frame.
+
+---
+
+## Pointer Lock (FPS-style mouse)
+
+```ts
+canvas.requestPointerLock(); // browser must accept after user gesture
+
+document.addEventListener('mousemove', (e) => {
+ if (document.pointerLockElement) {
+ yaw -= e.movementX * sensitivity;
+ pitch -= e.movementY * sensitivity;
+ }
+});
+```
+
+Rarely used in 2D PixiJS games; included for completeness.
+
+---
+
+## Visual Viewport (Mobile URL Bar)
+
+The `window.innerHeight` is unreliable on mobile because of the collapsing
+address bar. Use `visualViewport`:
+
+```ts
+function getViewportHeight(): number {
+ return window.visualViewport?.height ?? window.innerHeight;
+}
+
+window.visualViewport?.addEventListener('resize', onResize);
+```
+
+---
+
+## See Also
+
+- [`rendering.md`](rendering.md) — Resize handling
+- [`../current-best-practices.md`](../current-best-practices.md) — Mobile-specific CSS
+- [`../PLUGINS.md`](../PLUGINS.md) — nipplejs, Hammer.js
diff --git a/docs/engine-reference/html5/modules/navigation.md b/docs/engine-reference/html5/modules/navigation.md
new file mode 100644
index 0000000000..d149298ba3
--- /dev/null
+++ b/docs/engine-reference/html5/modules/navigation.md
@@ -0,0 +1,279 @@
+# HTML5 / PixiJS — Navigation & Pathfinding Module
+
+**Last verified:** 2026-06-11
+
+Pathfinding (A*, flow fields), 2D navigation patterns for grid and freeform
+spaces. PixiJS has no built-in navigation system — this module documents
+common patterns.
+
+---
+
+## Decision Tree
+
+```
+Movement style?
+├── Grid-based (chess, roguelike) → A* on grid
+├── Tile-based (RTS, top-down) → A* + path smoothing
+├── Continuous (boids, large crowd) → Flow field
+├── Click-to-move (point-and-click) → A* + Bezier smoothing
+└── Free-roam with simple obstacles → Raycast + steering
+```
+
+---
+
+## A* on Grid
+
+Classic A* for grid-based pathfinding:
+
+```ts
+interface Node { x: number; y: number; g: number; h: number; f: number; parent?: Node; }
+
+function astar(start: {x:number;y:number}, goal: {x:number;y:number}, grid: number[][]): Node[] {
+ const open: Node[] = [];
+ const closed = new Set();
+ const startNode: Node = { ...start, g: 0, h: manhattan(start, goal), f: 0 };
+ startNode.f = startNode.g + startNode.h;
+ open.push(startNode);
+
+ while (open.length > 0) {
+ open.sort((a, b) => a.f - b.f);
+ const current = open.shift()!;
+ if (current.x === goal.x && current.y === goal.y) {
+ return reconstructPath(current);
+ }
+ closed.add(`${current.x},${current.y}`);
+
+ for (const [dx, dy] of [[1,0],[-1,0],[0,1],[0,-1]]) {
+ const nx = current.x + dx;
+ const ny = current.y + dy;
+ if (nx < 0 || ny < 0 || nx >= grid[0].length || ny >= grid.length) continue;
+ if (grid[ny][nx] === 1) continue; // wall
+ if (closed.has(`${nx},${ny}`)) continue;
+
+ const g = current.g + 1;
+ const h = manhattan({ x: nx, y: ny }, goal);
+ const node: Node = { x: nx, y: ny, g, h, f: g + h, parent: current };
+
+ const existing = open.find((n) => n.x === nx && n.y === ny);
+ if (existing && existing.g <= g) continue;
+ if (existing) open.splice(open.indexOf(existing), 1);
+ open.push(node);
+ }
+ }
+
+ return []; // no path
+}
+
+function manhattan(a: {x:number;y:number}, b: {x:number;y:number}): number {
+ return Math.abs(a.x - b.x) + Math.abs(a.y - b.y);
+}
+
+function reconstructPath(end: Node): Node[] {
+ const path: Node[] = [];
+ let current: Node | undefined = end;
+ while (current) { path.unshift(current); current = current.parent; }
+ return path;
+}
+```
+
+**Use `manhattan` heuristic for 4-direction grids, `octile` for 8-direction.**
+
+### Performance Notes
+
+- Use a **binary heap** for `open` if maps exceed 50×50 (linear `sort()` becomes O(n²) over the search)
+- Cache the path; don't re-run A* every frame
+- Re-path only when destination changes or path becomes blocked
+
+---
+
+## A* on Hex Grid
+
+Hex requires either offset or axial coordinates. Axial is more elegant:
+
+```ts
+type Hex = { q: number; r: number };
+
+function hexDistance(a: Hex, b: Hex): number {
+ return (Math.abs(a.q - b.q) + Math.abs(a.q + a.r - b.q - b.r) + Math.abs(a.r - b.r)) / 2;
+}
+
+const HEX_NEIGHBORS = [
+ { q: 1, r: 0 }, { q: 1, r: -1 }, { q: 0, r: -1 },
+ { q: -1, r: 0 }, { q: -1, r: 1 }, { q: 0, r: 1 },
+];
+```
+
+Reuse the A* skeleton with `hexDistance` and `HEX_NEIGHBORS`.
+
+---
+
+## Flow Fields
+
+For many units chasing the same goal (RTS, tower defense crowds), compute
+ONE flow field instead of N A* paths:
+
+```ts
+// 1. BFS from goal, computing distance to every walkable tile
+function buildIntegrationField(grid: number[][], goal: {x:number;y:number}): number[][] {
+ const dist: number[][] = grid.map((row) => row.map(() => Infinity));
+ dist[goal.y][goal.x] = 0;
+ const queue: {x:number;y:number}[] = [goal];
+
+ while (queue.length > 0) {
+ const { x, y } = queue.shift()!;
+ for (const [dx, dy] of [[1,0],[-1,0],[0,1],[0,-1]]) {
+ const nx = x + dx, ny = y + dy;
+ if (nx < 0 || ny < 0 || nx >= grid[0].length || ny >= grid.length) continue;
+ if (grid[ny][nx] === 1) continue;
+ if (dist[ny][nx] !== Infinity) continue;
+ dist[ny][nx] = dist[y][x] + 1;
+ queue.push({ x: nx, y: ny });
+ }
+ }
+ return dist;
+}
+
+// 2. For each tile, point toward the lowest-distance neighbor
+function buildFlowField(dist: number[][]): {dx:number;dy:number}[][] {
+ return dist.map((row, y) => row.map((_, x) => {
+ let best = { dx: 0, dy: 0, d: dist[y][x] };
+ for (const [dx, dy] of [[1,0],[-1,0],[0,1],[0,-1]]) {
+ const nx = x + dx, ny = y + dy;
+ if (nx < 0 || ny < 0 || nx >= dist[0].length || ny >= dist.length) continue;
+ if (dist[ny][nx] < best.d) { best = { dx, dy, d: dist[ny][nx] }; }
+ }
+ return { dx: best.dx, dy: best.dy };
+ }));
+}
+
+// 3. Each unit reads its current tile's flow vector
+function updateUnit(unit: { x: number; y: number; vx: number; vy: number }, flow: {dx:number;dy:number}[][]) {
+ const tx = Math.floor(unit.x / TILE);
+ const ty = Math.floor(unit.y / TILE);
+ const f = flow[ty]?.[tx];
+ if (f) {
+ unit.vx = f.dx * SPEED;
+ unit.vy = f.dy * SPEED;
+ }
+}
+```
+
+Re-build the field only when the goal moves or the map changes.
+
+---
+
+## Path Smoothing
+
+A* paths are blocky (orthogonal turns). For natural movement, smooth:
+
+```ts
+// Catmull-Rom spline through path waypoints
+function catmullRom(p0: P, p1: P, p2: P, p3: P, t: number): P {
+ const t2 = t * t, t3 = t2 * t;
+ return {
+ x: 0.5 * (2*p1.x + (-p0.x + p2.x)*t + (2*p0.x - 5*p1.x + 4*p2.x - p3.x)*t2 + (-p0.x + 3*p1.x - 3*p2.x + p3.x)*t3),
+ y: 0.5 * (2*p1.y + (-p0.y + p2.y)*t + (2*p0.y - 5*p1.y + 4*p2.y - p3.y)*t2 + (-p0.y + 3*p1.y - 3*p2.y + p3.y)*t3),
+ };
+}
+```
+
+Or use Pixi's `SmoothGraphics` for visual paths.
+
+---
+
+## Click-to-Move
+
+Pattern: convert pointer to world coords → run A* → follow waypoints.
+
+```ts
+app.stage.eventMode = 'static';
+app.stage.on('pointertap', (e) => {
+ const local = world.toLocal(e.global);
+ const targetTile = { x: Math.floor(local.x / TILE), y: Math.floor(local.y / TILE) };
+ const playerTile = { x: Math.floor(player.x / TILE), y: Math.floor(player.y / TILE) };
+ const path = astar(playerTile, targetTile, gridData);
+ player.followPath(path);
+});
+```
+
+For `player.followPath`, advance one waypoint per arrival:
+
+```ts
+class Player {
+ private path: Node[] = [];
+ private waypoint = 0;
+
+ followPath(p: Node[]) {
+ this.path = p;
+ this.waypoint = 1; // skip starting tile
+ }
+
+ update(dt: number) {
+ if (this.waypoint >= this.path.length) return;
+ const target = this.path[this.waypoint];
+ const tx = target.x * TILE + TILE / 2;
+ const ty = target.y * TILE + TILE / 2;
+ const dx = tx - this.x;
+ const dy = ty - this.y;
+ const dist = Math.hypot(dx, dy);
+ const step = SPEED * dt;
+ if (dist <= step) {
+ this.x = tx;
+ this.y = ty;
+ this.waypoint++;
+ } else {
+ this.x += dx / dist * step;
+ this.y += dy / dist * step;
+ }
+ }
+}
+```
+
+---
+
+## Steering Behaviors
+
+For crowds, mixing flow fields with steering:
+
+| Behavior | Vector | Use |
+|----------|--------|-----|
+| Seek | target - position, normalized * speed | Move toward goal |
+| Flee | position - target | Move away |
+| Arrival | seek with slowdown radius | Stop smoothly at target |
+| Wander | random angle delta, biased forward | Idle / patrol |
+| Separation | sum of (position - neighbor) for nearby | Avoid clumping |
+| Alignment | average of neighbor velocities | Move with the group |
+| Cohesion | toward average position of neighbors | Stay in group |
+
+Combine with weighted sum: `final_velocity = 1.0*seek + 0.3*separation + 0.1*wander`.
+
+---
+
+## Pathfinding Libraries
+
+For non-trivial cases, prefer libraries:
+
+- **pathfinding** (npm) — A*, Dijkstra, JPS on grids. Mature.
+- **easystar.js** — A* with weighted tiles. Simpler API.
+- **PathFinding.js** (different package) — same name conflict; check the actual package
+
+Most casual mobile games can get by with the inline A* above; libraries shine
+when you need JPS (Jump Point Search — 5-10x faster A*) on big maps.
+
+---
+
+## Common Pitfalls
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Path runs A* every frame | Re-pathing on every input | Cache path; re-run only on target/map change |
+| Long pause at click | A* on big map blocks main thread | Move to a Web Worker; or use JPS |
+| Units jitter at waypoint | Threshold for "arrived" too small | Use `dist <= step` not `dist === 0` |
+| Diagonal paths illegal | Map only allows orthogonal | Filter diagonal neighbors in A* |
+
+---
+
+## See Also
+
+- [`physics.md`](physics.md) — Collision detection
+- [`animation.md`](animation.md) — Smooth movement interpolation
diff --git a/docs/engine-reference/html5/modules/networking.md b/docs/engine-reference/html5/modules/networking.md
new file mode 100644
index 0000000000..850afbb06c
--- /dev/null
+++ b/docs/engine-reference/html5/modules/networking.md
@@ -0,0 +1,258 @@
+# HTML5 / PixiJS — Networking Module
+
+**Last verified:** 2026-06-11
+
+WebSocket, WebRTC, multiplayer architectures, and leaderboard / cloud save
+patterns for HTML5 games.
+
+---
+
+## Decision Tree
+
+```
+Need multiplayer?
+├── No (single-player) → REST for leaderboards/saves
+└── Yes
+ ├── Realtime, > 2 players → Authoritative server (Colyseus / custom Node)
+ ├── Realtime, 2 players → WebRTC P2P (no server) or Colyseus (server)
+ ├── Turn-based → REST polling or WebSocket
+ └── Async (Wordle-class) → REST + daily snapshot
+```
+
+---
+
+## REST — Leaderboards, Saves, IAP
+
+Plain `fetch()` for almost everything. Don't reach for libraries.
+
+```ts
+async function postScore(score: number, name: string) {
+ const res = await fetch('/api/score', {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({ score, name }),
+ });
+ return await res.json();
+}
+```
+
+For game backends, **don't** trust the client. Validate:
+- Time elapsed since session start (client can fake but adds friction)
+- Action counts (clicks, taps) match score plausibility
+- HMAC signature with shared secret (still fakeable but raises bar)
+
+For high-stakes leaderboards, **replay validation** on the server is the only
+robust approach: client uploads input log, server replays the game.
+
+---
+
+## WebSocket — Custom Realtime
+
+```ts
+const ws = new WebSocket('wss://your-server.example/game');
+
+ws.addEventListener('open', () => {
+ ws.send(JSON.stringify({ type: 'join', room: 'lobby' }));
+});
+
+ws.addEventListener('message', (e) => {
+ const msg = JSON.parse(e.data);
+ switch (msg.type) {
+ case 'state': applyState(msg.state); break;
+ case 'event': handleEvent(msg.event); break;
+ }
+});
+
+ws.addEventListener('close', () => {
+ // reconnect with backoff
+});
+
+function send(payload: object) {
+ if (ws.readyState === WebSocket.OPEN) {
+ ws.send(JSON.stringify(payload));
+ }
+}
+```
+
+### Protocol Design
+
+Use a tagged union for messages:
+
+```ts
+type ClientMessage =
+ | { type: 'join'; room: string }
+ | { type: 'input'; tick: number; keys: number }
+ | { type: 'leave' };
+
+type ServerMessage =
+ | { type: 'state'; state: GameState }
+ | { type: 'event'; event: GameEvent }
+ | { type: 'error'; code: string };
+```
+
+For high-frequency input (>10/s), use binary (`ArrayBuffer` + DataView) instead
+of JSON to save bandwidth.
+
+### Reconnection with Backoff
+
+```ts
+class ReconnectingSocket {
+ private ws: WebSocket | null = null;
+ private attempts = 0;
+
+ connect(url: string) {
+ this.ws = new WebSocket(url);
+ this.ws.addEventListener('open', () => { this.attempts = 0; });
+ this.ws.addEventListener('close', () => {
+ const delay = Math.min(30_000, 1000 * 2 ** this.attempts);
+ this.attempts++;
+ setTimeout(() => this.connect(url), delay);
+ });
+ }
+}
+```
+
+---
+
+## Colyseus — Authoritative Multiplayer
+
+Server-authoritative state sync with delta encoding. Best fit for room-based
+realtime games (party games, .io-style).
+
+```ts
+import { Client } from 'colyseus.js';
+
+const client = new Client('wss://your-server.example');
+const room = await client.joinOrCreate('battle');
+
+room.onStateChange((state) => {
+ // sync sprites to state.players, state.bullets, etc.
+});
+
+room.onMessage('hit', (msg) => {
+ // play SFX, show hit effect
+});
+
+room.send('input', { x: stick.vector.x, y: stick.vector.y });
+```
+
+**Why Colyseus over raw WebSocket**:
+- State diffing built-in (only changed fields sent)
+- Schema-based message format (binary, typed)
+- Room lifecycle handled (matchmaking, idle cleanup)
+
+**Tradeoff**: Server is Node.js — requires hosting (Fly.io, Railway, custom VPS).
+
+---
+
+## WebRTC — Peer-to-Peer (No Server)
+
+Use for 1v1 games where matchmaking can be solved externally (shareable URL,
+discord bot, etc.).
+
+```ts
+const pc = new RTCPeerConnection({
+ iceServers: [{ urls: 'stun:stun.l.google.com:19302' }],
+});
+
+const dc = pc.createDataChannel('game', { ordered: false, maxRetransmits: 0 });
+
+dc.addEventListener('open', () => { dc.send('hello'); });
+dc.addEventListener('message', (e) => { handleMessage(e.data); });
+
+// Signaling (offer/answer exchange) still needs a server or out-of-band channel
+const offer = await pc.createOffer();
+await pc.setLocalDescription(offer);
+// ... exchange SDP via Firebase, shareable URL, etc.
+```
+
+### Caveats
+- Signaling requires SOMETHING — even if game itself is P2P, you need a way to
+ exchange the initial offer/answer
+- NAT traversal fails on some networks (~15% of consumer networks need TURN
+ servers — STUN alone insufficient)
+- Not suitable for > 4 players (mesh becomes O(n²) connections)
+
+---
+
+## Cloud Save Patterns
+
+### Anonymous Persistent ID
+
+```ts
+function getOrCreatePlayerId(): string {
+ let id = localStorage.getItem('player_id');
+ if (!id) {
+ id = crypto.randomUUID();
+ localStorage.setItem('player_id', id);
+ }
+ return id;
+}
+
+async function saveProgress(progress: SaveData) {
+ await fetch('/api/save', {
+ method: 'POST',
+ body: JSON.stringify({ playerId: getOrCreatePlayerId(), progress }),
+ });
+}
+```
+
+### Last-Write-Wins (Simple)
+
+Server stores the most recent payload per player. Acceptable for single-device
+players. Loses data if player plays on two devices simultaneously.
+
+### Version Vectors (Robust)
+
+Each save bumps a `version` counter. Server rejects writes with stale version.
+Client merges or prompts user on conflict.
+
+---
+
+## IAP — Web Monetization
+
+For HTML5 games sold via:
+
+- **Itch.io**: built-in payment, you receive a postback
+- **Self-hosted with Stripe/Paddle**: standard checkout flow, verify webhook on backend
+- **Mobile app wrappers (Capacitor, Cordova)**: native IAP through StoreKit/Play Billing
+- **Coil / Web Monetization**: micropayments (niche, low adoption)
+
+**Never** trust the client to confirm purchase. Always verify the webhook
+signature server-side before granting entitlements.
+
+---
+
+## Analytics
+
+For HTML5 games, prefer:
+- **PostHog** (self-hosted optional, GDPR-friendlier)
+- **Plausible** (lightweight, no cookies)
+- **Custom endpoint** posting to your own backend
+
+Avoid Google Analytics for game telemetry — it's optimized for marketing
+funnels, not gameplay events. The "event volume" for an active gameplay
+session can exceed GA's reasonable limits.
+
+---
+
+## Latency Mitigation
+
+For realtime games at 50ms+ latency:
+
+| Technique | Effect |
+|-----------|--------|
+| Client-side prediction | Apply input locally immediately, reconcile on server confirm |
+| Server reconciliation | Server periodically sends authoritative state; client lerps |
+| Lag compensation | Server rewinds time for hit detection (FPS-style) |
+| Interpolation | Show remote players slightly delayed but smooth |
+
+For a 2D party game, simple client prediction + last-known-position
+interpolation handles 200ms latency acceptably.
+
+---
+
+## See Also
+
+- [`../PLUGINS.md`](../PLUGINS.md) — Colyseus, PartyKit
+- [`../current-best-practices.md`](../current-best-practices.md) — Testing strategy
diff --git a/docs/engine-reference/html5/modules/physics.md b/docs/engine-reference/html5/modules/physics.md
new file mode 100644
index 0000000000..6d6e77b316
--- /dev/null
+++ b/docs/engine-reference/html5/modules/physics.md
@@ -0,0 +1,232 @@
+# HTML5 / PixiJS — Physics Module
+
+**Last verified:** 2026-06-11
+
+When to use a physics engine vs roll-your-own, integration patterns with PixiJS
+scene graph, and tradeoffs between Matter.js / Box2D / no-physics.
+
+---
+
+## Decision Tree
+
+```
+Need physics?
+├── No (most casual games) → AABB / circle collision yourself
+├── Light (bouncing, gravity) → Matter.js
+└── Heavy (constraints, joints)
+ ├── Quality matters → Box2D (WASM)
+ └── Speed of integration → Matter.js
+```
+
+**Rule of thumb**: If you can implement the collision in < 50 lines, do it
+yourself. Physics engines add 50-500 KB to the bundle.
+
+---
+
+## Roll-Your-Own — AABB Collision
+
+For grid games, platformers with rectangular bodies, or simple shooters:
+
+```ts
+interface AABB {
+ x: number; y: number; w: number; h: number;
+}
+
+function intersects(a: AABB, b: AABB): boolean {
+ return a.x < b.x + b.w && a.x + a.w > b.x &&
+ a.y < b.y + b.h && a.y + a.h > b.y;
+}
+
+function sweepX(body: AABB, dx: number, solids: AABB[]): number {
+ // Simple swept AABB — clamp dx if a collision occurs
+ body.x += dx;
+ for (const s of solids) {
+ if (intersects(body, s)) {
+ if (dx > 0) body.x = s.x - body.w;
+ else body.x = s.x + s.w;
+ return 0;
+ }
+ }
+ return dx;
+}
+```
+
+For circles: distance check `(dx*dx + dy*dy) < (r1+r2)**2`. Faster than AABB
+when both shapes are round.
+
+---
+
+## Spatial Partitioning
+
+When entity count > ~50, naive N×N collision becomes the bottleneck. Options:
+
+| Approach | Complexity | When |
+|----------|-----------|------|
+| None (N²) | O(n²) | < 50 entities |
+| Uniform grid | O(n) avg | Many small entities, even distribution |
+| Quadtree | O(n log n) | Wide range of entity sizes |
+| Sweep & prune | O(n log n) | Entities mostly stationary |
+
+```ts
+// Uniform grid example
+class Grid {
+ private cells = new Map();
+ constructor(private cellSize: number) {}
+
+ add(body: AABB) {
+ const x0 = Math.floor(body.x / this.cellSize);
+ const y0 = Math.floor(body.y / this.cellSize);
+ const x1 = Math.floor((body.x + body.w) / this.cellSize);
+ const y1 = Math.floor((body.y + body.h) / this.cellSize);
+ for (let cx = x0; cx <= x1; cx++) {
+ for (let cy = y0; cy <= y1; cy++) {
+ const key = `${cx},${cy}`;
+ if (!this.cells.has(key)) this.cells.set(key, []);
+ this.cells.get(key)!.push(body);
+ }
+ }
+ }
+
+ query(body: AABB): AABB[] {
+ const out = new Set();
+ // ... iterate overlapping cells, collect candidates
+ return [...out];
+ }
+
+ clear() { this.cells.clear(); }
+}
+```
+
+---
+
+## Matter.js Integration
+
+Best for: bouncing, gravity, joints, simple ragdoll, constraint puzzles.
+
+```ts
+import Matter from 'matter-js';
+import { Container, Sprite, Ticker } from 'pixi.js';
+
+const engine = Matter.Engine.create({
+ gravity: { x: 0, y: 1 },
+});
+
+// One Matter body per game entity
+const ball = Matter.Bodies.circle(100, 0, 20, { restitution: 0.8 });
+Matter.Composite.add(engine.world, ball);
+
+// One Pixi sprite per body
+const ballSprite = new Sprite(ballTexture);
+ballSprite.anchor.set(0.5);
+
+// Sync each tick
+Ticker.shared.add((ticker) => {
+ Matter.Engine.update(engine, ticker.deltaMS);
+ ballSprite.x = ball.position.x;
+ ballSprite.y = ball.position.y;
+ ballSprite.rotation = ball.angle;
+});
+```
+
+### Pattern: Entity wraps both body and sprite
+
+```ts
+class Ball {
+ body: Matter.Body;
+ sprite: Sprite;
+
+ constructor(x: number, y: number, texture: Texture) {
+ this.body = Matter.Bodies.circle(x, y, 20, { restitution: 0.8 });
+ this.sprite = new Sprite(texture);
+ this.sprite.anchor.set(0.5);
+ }
+
+ sync() {
+ this.sprite.x = this.body.position.x;
+ this.sprite.y = this.body.position.y;
+ this.sprite.rotation = this.body.angle;
+ }
+}
+```
+
+### Collision Events
+
+```ts
+Matter.Events.on(engine, 'collisionStart', (e) => {
+ for (const pair of e.pairs) {
+ const a = pair.bodyA;
+ const b = pair.bodyB;
+ // identify via body.label or custom property
+ }
+});
+```
+
+### Fixed Timestep
+
+For deterministic physics (replays, network sync), use a fixed timestep:
+
+```ts
+let accumulator = 0;
+const STEP_MS = 1000 / 60;
+
+Ticker.shared.add((ticker) => {
+ accumulator += ticker.deltaMS;
+ while (accumulator >= STEP_MS) {
+ Matter.Engine.update(engine, STEP_MS);
+ accumulator -= STEP_MS;
+ }
+ // sync sprites once per render frame, not per physics step
+ for (const e of entities) e.sync();
+});
+```
+
+---
+
+## Box2D (WASM)
+
+Use when physics quality is core to gameplay (Angry Birds class).
+
+```ts
+import { Box2D } from 'box2d-wasm';
+
+const Box2DInstance = await Box2D();
+const world = new Box2DInstance.b2World(new Box2DInstance.b2Vec2(0, 10));
+
+// ... heavier API surface, see box2d-wasm docs
+```
+
+**Tradeoffs vs Matter**:
+- ✅ More accurate solver, fewer artifacts
+- ✅ Better continuous collision detection (no tunneling at high speed)
+- ❌ WASM blob adds ~400-500KB to bundle
+- ❌ Steeper API
+- ❌ Async init (`await Box2D()`)
+
+---
+
+## Pitfalls
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| Sprite snaps far each frame | Physics ms ≠ render ms | Use `ticker.deltaMS`, not a fixed 16.6 |
+| Bodies tunneling through walls | Frame too long, body too fast | Cap `deltaMS` at e.g. 32, or use continuous collision |
+| Jitter at rest | Floating-point noise | Set `sleepThreshold` lower, or freeze when velocity < epsilon |
+| Wrong rotation direction | Pixi y-down vs physics y-up | Most JS physics engines also y-down — usually fine; verify with one test body |
+| Restitution doesn't bounce | Both bodies need restitution | `restitution` from contact uses max of both bodies |
+
+---
+
+## When NOT to Use Physics
+
+- Tap puzzles (Bejeweled-class) — board logic, no physics needed
+- Tile-based platformers — write a `move_x(amount)` + `move_y(amount)` with AABB cast
+- Card games — animations via GSAP, no physics
+- Top-down shooters with fixed-speed bullets — write yourself
+- Simple particle systems — `ParticleContainer` + manual velocity + gravity is faster than Matter for 1000s of particles
+
+---
+
+## See Also
+
+- [`../PLUGINS.md`](../PLUGINS.md) — Matter, Box2D package info
+- [`rendering.md`](rendering.md) — ParticleContainer for non-physics particles
diff --git a/docs/engine-reference/html5/modules/rendering.md b/docs/engine-reference/html5/modules/rendering.md
new file mode 100644
index 0000000000..0a4629ce59
--- /dev/null
+++ b/docs/engine-reference/html5/modules/rendering.md
@@ -0,0 +1,237 @@
+# HTML5 / PixiJS — Rendering Module
+
+**Last verified:** 2026-06-11
+
+Renderer choice, Application lifecycle, scene graph, and v8-specific rendering
+concerns. Read alongside [`../breaking-changes.md`](../breaking-changes.md).
+
+---
+
+## WebGL2 vs WebGPU (v8 Choice)
+
+PixiJS 8 supports both backends through a unified `Renderer` interface.
+
+| Backend | Browser Support (2026) | Performance | When to Use |
+|---------|------------------------|-------------|-------------|
+| WebGPU | Chrome/Edge/Firefox stable; Safari 17.5+ (gated on iOS) | Best | Default for new projects |
+| WebGL2 | Universal | Excellent | Fallback / iOS Safari < 17.5 / older Android |
+| WebGL1 | Universal | Adequate | Last-resort fallback (don't pin to it) |
+
+```ts
+const app = new Application();
+await app.init({
+ preference: 'webgpu', // try first, fall back to WebGL2
+ preferWebGLVersion: 2, // never WebGL1 if avoidable
+ powerPreference: 'high-performance',
+});
+
+// Check which renderer was actually selected
+console.log(app.renderer.type); // 'webgl' | 'webgpu'
+```
+
+**Don't** assume one backend or the other in custom shaders — use Pixi's
+`Filter` API which generates both GLSL (WebGL) and WGSL (WebGPU). See
+[`../current-best-practices.md`](../current-best-practices.md) Filters section.
+
+---
+
+## Application Lifecycle
+
+```ts
+// 1. Construct
+const app = new Application();
+
+// 2. Init (async, REQUIRED in v8)
+await app.init({
+ resizeTo: window, // auto-resize to viewport
+ backgroundColor: 0x000000,
+ antialias: true,
+ resolution: window.devicePixelRatio || 1,
+ autoDensity: true, // CSS-pixel-aware sizing
+ preference: 'webgpu',
+});
+
+// 3. Attach to DOM
+document.body.appendChild(app.canvas); // not app.view
+
+// 4. Add scene
+const root = new Container();
+app.stage.addChild(root);
+
+// 5. Tick (optional — Pixi starts the shared ticker by default)
+app.ticker.add((ticker) => {
+ // game update
+});
+
+// 6. Teardown (SPA navigation, hot-reload)
+app.destroy(true, { children: true, texture: true, textureSource: true });
+```
+
+### Hot Reload Pitfalls (Vite Dev)
+
+Vite HMR can leave orphaned WebGL contexts. Always call `app.destroy(true)`
+before re-creating in dev. Pattern:
+
+```ts
+if (import.meta.hot) {
+ import.meta.hot.dispose(() => {
+ app.destroy(true, { children: true, texture: true, textureSource: true });
+ });
+}
+```
+
+---
+
+## Resolution & High-DPI
+
+```ts
+await app.init({
+ resolution: window.devicePixelRatio || 1,
+ autoDensity: true,
+});
+```
+
+- `resolution: 2` on a retina iPhone → renderer draws at 2x then CSS scales to logical size
+- `autoDensity: true` → Pixi sets `canvas.style.width/height` to the CSS size automatically
+- Without these, sprites look blurry on high-DPI displays
+
+**Mobile perf tradeoff**: `resolution: 2` doubles fragment work. On low-end
+phones, consider `resolution: Math.min(window.devicePixelRatio, 1.5)` to cap.
+
+---
+
+## Scene Graph (`Container` Tree)
+
+```
+app.stage (Container)
+├── world (Container) — game world, scaled/scrolled
+│ ├── background (Sprite)
+│ ├── entities (Container)
+│ │ ├── player (Sprite)
+│ │ └── enemies[i] (Sprite)
+│ └── effects (ParticleContainer)
+└── ui (Container) — fixed overlay, unscaled
+ ├── hud (Container)
+ └── menu (Container)
+```
+
+**Why two top-level containers**: world transforms (camera, zoom) apply to
+`world` only. UI stays unaffected by camera. Cleaner than untangling per-element
+transforms.
+
+### Children Limits (v8)
+
+- `Sprite`, `Mesh`, `Graphics`: **NO children** (throws on `.addChild`)
+- `Container`: unlimited
+- `ParticleContainer`: holds `Particle` (NOT `Sprite`) via `addParticle()`
+
+To group a Sprite with children, wrap both in a `Container`:
+
+```ts
+const entity = new Container();
+entity.addChild(new Sprite(bodyTex));
+entity.addChild(new Sprite(weaponTex));
+```
+
+---
+
+## Batching & Draw Calls
+
+PixiJS auto-batches sprites that share a texture (or atlas) within the same
+container. Rules:
+
+1. **Use spritesheets** — sprites from the same atlas batch automatically
+2. **Avoid mid-batch state changes** — alternating filters, blend modes, or mask boundaries breaks batches
+3. **`ParticleContainer` over `Container` for >500 similar sprites** — explicit batching, faster
+4. **Profile with Pixi DevTools** — look at draw call count, not just FPS
+
+### When Batching Breaks
+
+| Action | Result |
+|--------|--------|
+| Different texture (no atlas) | New batch |
+| Sprite with filter | New batch (filter render target) |
+| Sprite with mask | New batch |
+| Sprite with non-default blend mode | New batch |
+| Adding a Graphics in the middle | New batch (Graphics uses different pipeline) |
+
+---
+
+## Camera / World Transform
+
+PixiJS has no built-in camera — you transform the world container:
+
+```ts
+const world = new Container();
+app.stage.addChild(world);
+
+// "Camera" controls
+function setCamera(targetX: number, targetY: number, zoom: number) {
+ world.scale.set(zoom);
+ world.x = app.renderer.width / 2 - targetX * zoom;
+ world.y = app.renderer.height / 2 - targetY * zoom;
+}
+```
+
+Lerp toward target each tick for smooth follow.
+
+---
+
+## Resizing & Letterboxing
+
+For fixed-aspect-ratio games (most casual mobile):
+
+```ts
+const GAME_W = 720;
+const GAME_H = 1280;
+
+function fitGame() {
+ const scale = Math.min(window.innerWidth / GAME_W, window.innerHeight / GAME_H);
+ app.renderer.resize(GAME_W * scale, GAME_H * scale);
+ world.scale.set(scale);
+}
+
+window.addEventListener('resize', fitGame);
+fitGame();
+```
+
+For full-bleed games: `resizeTo: window` in init handles it.
+
+---
+
+## RenderTexture (Off-Screen Rendering)
+
+```ts
+const rt = RenderTexture.create({ width: 256, height: 256 });
+app.renderer.render({ container: someScene, target: rt });
+
+const cached = new Sprite(rt);
+app.stage.addChild(cached);
+```
+
+Use for: minimap, paint-style mechanics, baking complex graphics once.
+
+`Container.cacheAsTexture()` is the high-level convenience for "render me once
+and reuse the result until I change."
+
+---
+
+## Common Pitfalls
+
+| Symptom | Likely Cause | Fix |
+|---------|--------------|-----|
+| Blurry sprites on retina | `resolution: 1` ignored DPR | Set `resolution: window.devicePixelRatio`, `autoDensity: true` |
+| Black screen on init | Forgot `await app.init()` | v8 init is async |
+| `addChild` throws on sprite | Sprite cannot have children in v8 | Wrap in `Container` |
+| FPS tanks with many sprites | Each sprite uses a different texture | Atlas into spritesheet |
+| `Texture.from(url)` returns blank | URL not pre-loaded | `await Assets.load(url)` first |
+| Filter looks broken | Old v7 filter constructor | Use `{ glProgram, resources }` object form |
+
+---
+
+## See Also
+
+- [`../current-best-practices.md`](../current-best-practices.md) — Application bootstrap pattern
+- [`../breaking-changes.md`](../breaking-changes.md) — v7→v8 rendering changes
+- [`input.md`](input.md) — Federated event system
+- [`animation.md`](animation.md) — Ticker integration
diff --git a/docs/engine-reference/html5/modules/ui.md b/docs/engine-reference/html5/modules/ui.md
new file mode 100644
index 0000000000..1c925107d9
--- /dev/null
+++ b/docs/engine-reference/html5/modules/ui.md
@@ -0,0 +1,287 @@
+# HTML5 / PixiJS — UI Module
+
+**Last verified:** 2026-06-11
+
+PixiJS-native UI vs DOM overlay, when to use which, text rendering, and
+responsive layout for mobile web.
+
+---
+
+## DOM vs Pixi UI — When to Use Which
+
+| Use DOM (HTML overlay) | Use Pixi (canvas) |
+|------------------------|-------------------|
+| Settings menu, pause menu | HUD (score, health) |
+| Long text (story, credits) | Floating combat text |
+| Email/text input | Buttons inside game world |
+| Tab-able links, anchors | Anything that needs to align with world coords |
+| Accessibility-critical (screen reader) | Visual-only ornaments |
+| Forms / IAP receipts | Anything animated by Ticker |
+
+**General rule**: DOM for typography-heavy / accessibility-needed UI, Pixi for
+game-feel UI integrated with the rendered world.
+
+---
+
+## DOM Overlay Pattern
+
+Place a single transparent DOM container above the canvas:
+
+```html
+
+```
+
+```css
+#app {
+ position: fixed;
+ inset: 0;
+}
+
+#pixi, #dom-ui {
+ position: absolute;
+ inset: 0;
+}
+
+#dom-ui {
+ pointer-events: none; /* canvas catches input by default */
+}
+
+#dom-ui > * {
+ pointer-events: auto; /* opt back in for actual UI widgets */
+}
+```
+
+This keeps DOM elements out of canvas hit-testing unless they explicitly want input.
+
+---
+
+## Pixi Text
+
+```ts
+import { Text, TextStyle } from 'pixi.js';
+
+const style = new TextStyle({
+ fontFamily: 'Arial',
+ fontSize: 24,
+ fill: 0xffffff,
+ stroke: { width: 2, color: 0x000000 },
+ dropShadow: { color: 0x000000, blur: 4, distance: 2 },
+});
+
+const label = new Text({ text: 'Score: 0', style });
+```
+
+### Performance: Static vs Updating
+
+- **Static text** (title, copyright): use `Text`. Internally rasterizes once.
+- **Updating text** (score that changes every frame): use `BitmapText` for performance.
+
+### BitmapText
+
+Pre-rendered bitmap font, much faster than re-rasterizing `Text`:
+
+```ts
+import { Assets, BitmapText } from 'pixi.js';
+
+await Assets.load('assets/font.fnt'); // BMFont format
+
+const score = new BitmapText({
+ text: '0',
+ style: { fontFamily: 'PressStart2P', fontSize: 32, fill: 0xffff00 },
+});
+
+// Updating each frame is cheap
+Ticker.shared.add(() => { score.text = String(currentScore); });
+```
+
+Tools: [SnowB BMFont](http://www.angelcode.com/products/bmfont/) or
+[bmfont-online](https://snowb.org/) to generate `.fnt` + atlas PNG.
+
+### Sources of Text Performance Bugs
+
+| Bug | Cause |
+|-----|-------|
+| Score text drops FPS | Using `Text` instead of `BitmapText` for per-frame updates |
+| Text blurry on retina | Resolution mismatch — set `style.resolution = window.devicePixelRatio` or use `BitmapText` |
+| Korean / Chinese text broken | Font not loaded yet — `await document.fonts.ready` before creating `Text` |
+| Text jitters during animation | Sub-pixel position — round to integer or use `Math.round(x)` for text positions |
+
+---
+
+## HTMLText (v8 New)
+
+Renders HTML via SVG foreignObject. Use when you need rich text (bold, italic,
+mixed colors inline):
+
+```ts
+import { HTMLText } from 'pixi.js';
+
+const rich = new HTMLText({
+ text: 'Score: 100',
+ style: { fontSize: 24, fill: 0xffffff },
+});
+```
+
+**Caveat**: HTMLText has higher cost than regular Text. Use for static or
+infrequently-updated rich text only.
+
+---
+
+## Buttons in Pixi
+
+Pixi has no `Button` class. Roll your own:
+
+```ts
+import { Container, Sprite, Text } from 'pixi.js';
+
+class Button extends Container {
+ constructor(label: string, bgTexture: Texture, onTap: () => void) {
+ super();
+ const bg = new Sprite(bgTexture);
+ bg.anchor.set(0.5);
+ const text = new Text({ text: label, style: { fontSize: 20, fill: 0xffffff } });
+ text.anchor.set(0.5);
+ this.addChild(bg, text);
+
+ this.eventMode = 'static';
+ this.cursor = 'pointer';
+
+ this.on('pointerdown', () => { bg.tint = 0xcccccc; });
+ this.on('pointerup', () => { bg.tint = 0xffffff; onTap(); });
+ this.on('pointerupoutside', () => { bg.tint = 0xffffff; });
+ }
+}
+```
+
+### Tap Target Padding
+
+WCAG ≥48×48 px:
+
+```ts
+button.hitArea = new Rectangle(-24, -24, button.width + 48, button.height + 48);
+```
+
+---
+
+## Layout — Constraint-Based (Anchors)
+
+Pixi has no layout engine — you compute positions manually on resize:
+
+```ts
+function layout() {
+ const { width: W, height: H } = app.renderer;
+
+ scoreLabel.x = 20;
+ scoreLabel.y = 20;
+
+ pauseButton.x = W - 60;
+ pauseButton.y = 20;
+
+ joystick.x = 100;
+ joystick.y = H - 100;
+}
+
+window.addEventListener('resize', layout);
+layout();
+```
+
+For complex UI, consider [@pixi/layout](https://github.com/pixijs/layout)
+(flex-style layout for Pixi containers — production-ready in 2026).
+
+---
+
+## Safe Area (iOS Notch)
+
+iOS notch / Dynamic Island intrudes on the top of the canvas. Use CSS env
+variables in the DOM:
+
+```css
+#app {
+ padding-top: env(safe-area-inset-top);
+ padding-bottom: env(safe-area-inset-bottom);
+}
+```
+
+For canvas-based UI, read the safe area via JS:
+
+```ts
+function getSafeArea() {
+ const s = getComputedStyle(document.documentElement);
+ return {
+ top: parseInt(s.getPropertyValue('--sat') ?? '0', 10),
+ bottom: parseInt(s.getPropertyValue('--sab') ?? '0', 10),
+ };
+}
+```
+
+After setting CSS custom props:
+
+```css
+:root {
+ --sat: env(safe-area-inset-top);
+ --sab: env(safe-area-inset-bottom);
+}
+```
+
+---
+
+## Modals / Dialogs
+
+Pattern: full-screen `Container` with semi-transparent background, eats input:
+
+```ts
+class Modal extends Container {
+ constructor(content: Container) {
+ super();
+ const bg = new Graphics()
+ .rect(0, 0, app.renderer.width, app.renderer.height)
+ .fill({ color: 0x000000, alpha: 0.5 });
+ bg.eventMode = 'static'; // eat clicks behind the modal
+ this.addChild(bg, content);
+ }
+}
+```
+
+---
+
+## Accessibility — Limits & Strategy
+
+PixiJS canvas is opaque to screen readers. For accessible games:
+
+1. **Mirror critical UI in DOM** — keep score, menu, settings in HTML overlays
+2. **ARIA labels** on canvas itself: `