# Phase 06.1: gap-closure D-39..D-46 (UAT 2026-05-11) - Pattern Map
**Mapped:** 2026-05-11
**Files analyzed:** 2 NEW + 9 MODIFIED + 4 NEW tests
**Analogs found:** 15 / 15 (every NEW file has a strong in-repo analog from Phase 6)
---
## Workspace + Boundary Rules
Phase 06.1 is **edits-only inside the existing tree** — no new workspace members, no new tools, no new directories above `src/`. See `06-PATTERNS.md` §"Workspace + Boundary Rules" for the locked `pnpm-workspace.yaml` boundary; Phase 06.1 inherits it unchanged.
| Touch surface | Workspace member? | Phase 06.1 action |
|---|---|---|
| `apps/client/src/render/*` | YES (via `apps/*`) | MODIFY 4, NEW 2 |
| `apps/client/src/scenes/GameScene.ts` | YES | MODIFY |
| `apps/client/src/prediction/input-dispatcher.ts` | YES | MODIFY |
| `apps/client/public/assets/fonts/FixedsysExcelsior.woff2` | YES (static) | NEW (vendored binary) |
| `apps/client/index.html` | YES | MODIFY (@font-face block) |
| `packages/game-logic/src/{constants,step,types}.ts` | YES | MODIFY |
| `tools/asset-pipeline/src/bootstrap.ts` | NO (standalone tool) | MODIFY |
| `apps/server/public/{atlas-mvp.{png,json},pipeline-manifest.json}` | YES (static) | REGEN |
| `apps/client/test/e2e/*.e2e.test.ts` | YES | NEW 4 |
| `tools/asset-pipeline/test/alpha-key.test.ts` | NO | NEW |
| `packages/game-logic/tests/*.test.ts` | YES | NEW 4 |
**Critical purity boundary:** `packages/game-logic/src/**` is policed by `tools/scripts/lint-game-logic-purity.mjs` (regex denylist for `Date.*`, `Math.random`, `fs.*`, `process.*`, `fetch(`, `node:fs`, `node:os`). The NaviMask bbox + walkable-region edge-block port must add no forbidden APIs. `step()` receives the walkable grid as data via `state.room_layout` — no Phaser, no DOM imports.
---
## File Classification
### Modified files (apps/client/src/render/)
| File | Role | Data Flow | Closest Analog | Match Quality |
|------|------|-----------|----------------|---------------|
| `PlayerRenderer.ts` | renderer | sim-tick callsite | self @ Phase 6 (lines 128-187) | exact (in-place edit) |
| `SpriteStateMachine.ts` | pure-sim helper (render) | sim-tick transform | self @ Phase 6 (lines 158-199) | exact (in-place edit) |
| `RoomRenderer.ts` | renderer + asset-load | room-load transform | self @ Phase 6 (lines 103-167) | exact (in-place edit) |
| `Nameplate.ts` | renderer (chrome) | follow-callback | self @ Phase 6 (lines 42-48) | exact (in-place edit) |
### NEW files (apps/client/src/render/)
| File | Role | Data Flow | Closest Analog | Match Quality |
|------|------|-----------|----------------|---------------|
| `BackgroundRenderer.ts` | renderer | sim-tick + render-frame | `RoomRenderer.ts` (sprite group + atlas-keyed frames + dispose) | exact-role |
| `RoomCollision.ts` | pure helper (browser-side) | room-load transform | `RoomRenderer.renderNew` (lines 103-125, tiles[] scan) + `packages/game-logic/src/collision.ts` (AABB-only helpers) | role-match |
### Modified files (packages/game-logic/)
| File | Role | Data Flow | Closest Analog | Match Quality |
|------|------|-----------|----------------|---------------|
| `constants.ts` | pure data | n/a | self @ Phase 4 (lines 22-33: WALK_SPEED with full GML citation comment) | exact (in-place edit, citation pattern) |
| `step.ts` | pure-sim | server-shared (Node + browser) | self @ Phase 4 (lines 70-160 movement loop) | exact (in-place edit) |
| `types.ts` | pure data | server-shared | self @ Phase 4 (lines 30-33: `RoomLayout`) | exact (in-place edit, add walkable-grid field) |
### Modified files (apps/client/src/scenes/, prediction/)
| File | Role | Data Flow | Closest Analog | Match Quality |
|------|------|-----------|----------------|---------------|
| `scenes/GameScene.ts` | scene-wiring | render-frame + sim-tick | self @ Phase 6 (lines 555-581 applyCameraFollow; 634-685 update loop) | exact (in-place edit) |
| `prediction/input-dispatcher.ts` | net/input | event-driven keydown/up | self @ Phase 6 (lines 90-152) | exact (in-place edit) |
| `index.html` | static-shell | n/a | self (Vite scaffold from Phase 6) | exact (add `
```
---
### `apps/client/src/scenes/GameScene.ts` (MODIFY — D-46 deferred startFollow + idempotent applyCameraFollow + drop setBounds + RUN_SPEED + BackgroundRenderer wire-up)
**Analog:** Self (current `applyCameraFollow` at lines 555-581; update loop at lines 634-685; layout-handler at lines 500-553).
**Concrete edits:**
**1. Drop `setBounds`, add `setRoundPixels`, lock deadzone to 32×32 (D6.1-14/16):** Replace lines 564-581:
```ts
private applyCameraFollow(): void {
const localSprite = this.playerRenderer?.getLocalSprite();
if (!localSprite) return;
// D6.1-15 idempotent: if camera already follows THIS sprite, no-op.
// If follow target was destroyed (cookie-resume self-heal), re-bind.
// Phaser private: cameras.main._follow holds the current target.
// eslint-disable-next-line @typescript-eslint/no-explicit-any
const currentTarget = (this.cameras.main as any)._follow;
if (this.cameraFollowApplied && currentTarget === localSprite) return;
// D6.1-16: camera UNBOUNDED — DO NOT call setBounds().
// World feels infinite; bkdraw background masks the void past room edge.
this.cameras.main.startFollow(localSprite, true); // roundPixels=true
this.cameras.main.setDeadzone(32, 32); // D6.1-14 — BNCentral hBorder/vBorder
this.cameras.main.setRoundPixels(true); // D6.1-16 — HiDPI nearest-neighbor
this.cameraFollowApplied = true;
}
```
**2. Defer startFollow until sprite exists (D6.1-15):** the existing call at line 552 already runs after `this.roomRenderer?.render(layout)`. The bug is that local sprite isn't created until `onLocalSnapshot` populates it; add a second invocation point in the onLocalSnapshot handler (find it in GameScene around line 380-460 — planner will identify) so `applyCameraFollow()` re-runs when the local sprite first exists. Existing `cameraFollowApplied` flag prevents double-apply unless target changed.
**3. Reset `cameraFollowApplied` when PlayerRenderer recreates the sprite (Pitfall 5):** if option A from PlayerRenderer (returning `wasRecreated`), set `cameraFollowApplied = false` whenever `wasRecreated === true`.
**4. Update loop — replace `* 3` magic with `RUN_SPEED_PX_PER_TICK` (lines 653-654):**
```ts
import { RUN_SPEED_PX_PER_TICK, FRAMES_PER_TICK_AT_RUN } from '@rebno/game-logic';
// ...
const vx = (p.axis_x_held ?? 0) * RUN_SPEED_PX_PER_TICK;
const vy = (p.axis_y_held ?? 0) * RUN_SPEED_PX_PER_TICK;
this.playerRenderer.onSimulationTickRemote(sessionId, vx, vy, p.x ?? 0, p.y ?? 0);
```
**5. Background wire-up (D6.1-17):**
```ts
import { BackgroundRenderer } from '../render/BackgroundRenderer.js';
// In create() after roomRenderer init:
this.backgroundRenderer = new BackgroundRenderer(this);
this.backgroundRenderer.build();
// In update() sim-tick block (currently lines 639-664):
if (this.simTickAccumulator >= SIM_TICK_MS) {
// ... existing local + remote sim-tick calls ...
this.backgroundRenderer?.onSimulationTick(); // bkdraw advance
}
// At end of update() (every render frame, NOT gated by sim-tick):
this.backgroundRenderer?.tickRender(this.cameras.main); // position sprites
```
**6. Sim-tick accumulator subtraction (Pitfall 4):** Replace line 640 `this.simTickAccumulator = 0` with `this.simTickAccumulator -= SIM_TICK_MS` and add a cap to prevent spiral-of-death:
```ts
while (this.simTickAccumulator >= SIM_TICK_MS) {
this.simTickAccumulator -= SIM_TICK_MS;
// (cap accumulator at 5*SIM_TICK_MS before this block to prevent spiral)
// ... existing sim-tick body ...
}
```
**7. D-40 bail-open or fix (Pitfall 2):** the `if (!verified) return;` at line 529-537 short-circuits rendering when Ed25519 verify fails. Either change to "log and render anyway" (single-line edit) OR fix the canonical stringification. Planner picks; verification log via `console.warn` already in place — promote bail-open if Pitfall 2 is the D-40 root cause.
---
### `apps/client/src/prediction/input-dispatcher.ts` (MODIFY — Shift-stand)
**Analog:** Self (current key-tracker at lines 30-32, `currentAxes` at lines 139-145, `onKey` at lines 122-137).
**Concrete edits (D6.1-09):**
**1. Add Shift to tracked keys + facing-hint state:**
```ts
const SHIFT_KEYS = new Set(['SHIFT']);
const MOVE_KEYS = new Set([...X_KEYS, ...Y_KEYS, ...SHIFT_KEYS]);
// Add private field
private shiftDown = false;
private facingHint: { x: -1 | 0 | 1; y: -1 | 0 | 1 } = { x: 0, y: 0 };
```
**2. Handle Shift in `onKey` (after line 124's `_frozen` check):**
```ts
if (SHIFT_KEYS.has(key)) {
this.shiftDown = kind === 'down';
// Re-dispatch so server learns about the axes flip
this.dispatch();
return;
}
```
**3. Modify `currentAxes` (lines 139-145):**
```ts
private currentAxes(): { x: Axis; y: Axis } {
const heldX: Axis = this.xOrder[0] === 'D' ? 1 : this.xOrder[0] === 'A' ? -1 : 0;
const heldY: Axis = this.yOrder[0] === 'S' ? 1 : this.yOrder[0] === 'W' ? -1 : 0;
// D6.1-09: Shift held + direction → axes (0,0), preserve facingHint locally.
// Server treats this as "no movement"; remote players see this player stand.
// Local renderer reads facingHint to pick STAND_FRAME[facing] direction.
if (this.shiftDown && (heldX !== 0 || heldY !== 0)) {
this.facingHint = { x: heldX, y: heldY };
return { x: 0, y: 0 };
}
if (heldX !== 0 || heldY !== 0) this.facingHint = { x: heldX, y: heldY };
return { x: heldX, y: heldY };
}
/** Public getter for PlayerRenderer to bias stand-frame direction. */
getFacingHint(): { x: -1 | 0 | 1; y: -1 | 0 | 1 } {
return this.facingHint;
}
```
**4. Drop legacy Ctrl+R toggle code paths (D6.1-05):** grep `Ctrl` / `KeyR` / `vk_alt` in this file — none observed currently; assertion test that none exist (anti-port enforcement).
**Anti-pattern enforcement:** Do NOT add a wire-schema field for Shift-stand. CONTEXT D6.1-09 keeps the protocol unchanged. The `axes={0,0}` payload is server-indistinguishable from "fully idle" — that's intentional.
---
### `tools/asset-pipeline/src/bootstrap.ts` (MODIFY — alpha-key + background ingestion)
**Analog:** Self (current decode→sharp pipeline at lines 99-122).
**Concrete edits (D6.1-01..04, D6.1-20):**
**1. Insert alpha-key step between `decodeBmp` (line 111) and `sharp(rgba, ...)` (line 117):**
```ts
const { width, height, rgba } = decodeBmp(buf);
if (width !== meta.width || height !== meta.height) {
throw new Error(/* existing */);
}
// D6.1-01/02: alpha-key transparent sprites — exact-RGB match against
// top-left pixel of frame 0. GameMaker canonical rule (BMPs are 8-bit
// paletted, no anti-alias fringe — exact match is correct).
// `meta.transparent` is the per-sprite flag from extracted meta.json.
if (meta.transparent) {
const sentinelR = rgba[0]!;
const sentinelG = rgba[1]!;
const sentinelB = rgba[2]!;
for (let i = 0; i < rgba.length; i += 4) {
if (rgba[i] === sentinelR && rgba[i + 1] === sentinelG && rgba[i + 2] === sentinelB) {
rgba[i + 3] = 0; // alpha = 0
}
}
}
const png = await sharp(rgba, { raw: { width, height, channels: 4 } })
.png(PNG_OPTS).toBuffer();
```
**2. Extend `ExtractedSpriteMeta` interface (lines 32-39) to declare `transparent`:**
```ts
interface ExtractedSpriteMeta {
width: number;
height: number;
originX: number;
originY: number;
name: string;
id: number;
transparent?: boolean; // D6.1-01 — gates alpha-key path
}
```
**3. Background ingestion (D6.1-20):** the bootstrap iterates sprite directories generically by `^\d{4}-` regex (line 41). To include `0064-BKA1` and `0024-TSide1`, the call site that passes `spriteIds` (Plan 06-14 hard-coded list) must add those two IDs. Find the call in `tools/asset-pipeline/cli.ts` or wherever the Plan 06-14 list lives. Both are `transparent: false` per their meta.json — the alpha-key step naturally skips them.
**4. Path separation (D6.1-01 two-path pipeline):** `bootstrap.ts` is the BMP-input path → ALPHA-KEY APPLIES. `build.ts` (Aseprite-PNG path) → trust embedded alpha, NO key step. Verify by reading `build.ts` and confirming it does not call any pixel-loop alpha logic.
**Regression test (D6.1-03):** `tools/asset-pipeline/test/alpha-key.test.ts` — for each transparent sprite, assert (a) output PNG has alpha channel (`info.channels === 4`), (b) zero pixels at the sentinel RGB with `alpha === 255`. Use `sharp(out).raw().toBuffer({ resolveWithObject: true })` to introspect.
---
### Test patterns (NEW files)
**E2E test analog (`apps/client/test/e2e/camera-follow.e2e.test.ts` lines 16-89):** the existing test is the exact template — login fixture, `waitForGameReady`, `__rebno` deterministic hook for state assertion (NOT canvas pixel sampling), keyboard.down/up + waitForTimeout, before/after delta assertion. Mirror this shape for:
- `cli-08-camera.e2e.test.ts` — verbatim copy with `RUN_SPEED_PX_PER_TICK` magnitude in the delta threshold (8 px → 20 px since speed jumped 3→5).
- `cli-08-tiles.e2e.test.ts` — assert `window.__rebno.loadedTextures` contains `'atlas-mvp'` AND probe the canvas for non-background-color pixels at known tile positions (or, cleaner: add a `__rebno.tileCount` field in `RoomRenderer.renderNew` and assert > 0).
- `cli-08-nameplate.e2e.test.ts` — adapt `sprite-state.e2e.test.ts` lines 48-59 (the `[data-nameplate]` DOM-mirror count + computed-style color assertion via `evaluate(el => getComputedStyle(el).color)`).
- `cli-08-anim.e2e.test.ts` — adapt `sprite-state.e2e.test.ts` lines 16-46 (sample `__rebno.localFrame` over 1 s, count distinct frame keys, assert ≥ 3 unique frames at RUN cadence).
**Unit test analog (`packages/game-logic/tests/step.test.ts` — existing):** the test directory is `tests/` (NOT `__test__/`), uses vitest defaults. New tests:
- `run-speed.test.ts` — `expect(RUN_SPEED_PX_PER_TICK).toBe(5)`.
- `navi-mask-bbox.test.ts` — `expect(NAVI_MASK).toEqual({left:9, top:40, right:26, bottom:46})`.
- `wall-slide.test.ts` — set up `WalkableGrid` with a corner; input diagonal axes; assert player slides along free axis when blocked.
- `walkable-edge.test.ts` — set up `WalkableGrid` 3×3 walkable region; place player at edge tile; assert step() does not allow movement past the boundary.
**Unit test analog (`tools/asset-pipeline/test/bootstrap.test.ts` — existing):** new test `test/alpha-key.test.ts` mirrors its setup pattern (tempdir + fixture bmp + run bootstrap + read output PNG + assert).
---
## Shared Patterns (cross-cutting)
### S-01: Tag every artifact with traceable-reqs
**Source:** `CLAUDE.md` §"Tagging contract"; seen on every Phase-6 file (e.g. `PlayerRenderer.ts:2`, `step.ts:1`, `bootstrap.ts:2`).
**Apply to:** Every new/modified TS file in Phase 06.1. Phase 06.1 closes existing REQ-IDs (no new IDs) — use these tags:
```ts
// [impl->REQ-AST-01] → tools/asset-pipeline/src/bootstrap.ts edits, alpha-key test
// [impl->REQ-CLI-04] → game-logic constants, step, sprite-state, input-dispatcher, depth-set
// [impl->REQ-CLI-05] → Nameplate (CLI-05 = chat & in-world UI per ROADMAP)
// [impl->REQ-CLI-06] → RoomRenderer D-40 fix (CLI-06 = room rendering)
// [impl->REQ-CLI-07] → BackgroundRenderer, RoomCollision, GameScene camera (CLI-07 = asset & atlas integration)
// [impl->REQ-CLI-08] → e2e tests (CLI-08 = hard milestone)
// [int->REQ-CLI-08] → on all 4 new e2e test files
// [unit->REQ-CLI-04] → run-speed, navi-mask-bbox, wall-slide, walkable-edge tests
// [unit->REQ-AST-01] → alpha-key.test.ts
```
### S-02: Extract → cite → name (every constant carries a GML SOURCE comment)
**Source:** `packages/game-logic/src/constants.ts` lines 22-128 — every export has `SOURCE: extracted/client-5-8/...:N` in its JSDoc. CLAUDE.md hard rule #6.
**Apply to:** New constants `RUN_SPEED_PX_PER_TICK`, `FRAMES_PER_TICK_AT_RUN`, `NAVI_MASK`, and any inline `PLAYER_LAYER`/`TILE_LAYER`/`TSIDE_LAYER` magic in renderers. Without the SOURCE comment the value is unverifiable on review — block at PR.
### S-03: Sim-tick callsite contract (D-31 lock — re-enforce)
**Source:** `apps/client/src/render/PlayerRenderer.ts` lines 18-22 (file header) + GameScene.ts lines 634-665 (sim-tick accumulator block).
**Apply to:** EVERY animation/depth/render-position update added in Phase 06.1.
- `BackgroundRenderer.onSimulationTick()` fires from the sim-tick block, NOT the render-frame block.
- `setDepth` for player fires from `onSimulationTickLocal/Remote`, not from a separate render loop.
- `BackgroundRenderer.tickRender(camera)` for per-tile position update is allowed at render-frame rate (60 Hz) — it's pure positional, not state-advancing. The visual scroll is governed by `dxoff/dyoff` which advance ONLY in sim-tick.
### S-04: Lint-purity-respecting pure module (packages/game-logic)
**Source:** `tools/scripts/lint-game-logic-purity.mjs` regex denylist (lines 14-25). Forbidden: `Date.*`, `new Date(`, `Math.random`, `process.*`, `fs.*`, `fetch(`, `import 'http'`, `import 'node:fs'`, `import 'node:os'`.
**Apply to:** New code in `packages/game-logic/src/constants.ts`, `step.ts`, `types.ts`, `collision.ts`. Specifically: `Uint8Array` is allowed (web-standard); `Math.floor/round/sign/abs/hypot/SQRT2` are allowed; `Math.random` is FORBIDDEN. Run `pnpm trace:check` AND `node tools/scripts/lint-game-logic-purity.mjs` before commit.
### S-05: Frame-key naming `${spriteId}_${padStart(3,'0')}`
**Source:** `apps/client/src/render/RoomRenderer.ts:117`, `apps/client/src/render/SpriteStateMachine.ts:197`, `apps/client/src/render/PlayerRenderer.ts:271`.
**Apply to:** `BackgroundRenderer` (`0064-BKA1_${pad3(floor(bgframe))}`), TSide1 placement (`0024-TSide1_000`). One convention, no variants.
### S-06: Optional-chained Phaser API for Rectangle fallback (Pitfall 6)
**Source:** `apps/client/src/render/PlayerRenderer.ts:138, 181`.
**Apply to:** Every `setFrame` / `setDepth` / `setTexture` call added in Phase 06.1. The atlas-missing fallback returns a Phaser Rectangle (jsdom unit tests; pre-atlas-load on real client) which lacks these methods. Use `sprite.setDepth?.(...)`, `sprite.setFrame?.(...)`.
### S-07: Hot-swap dispose-before-build (RoomRenderer pattern)
**Source:** `apps/client/src/render/RoomRenderer.ts:88-97` (`render(layout)` calls `this.dispose()` first) + `:264-274` (dispose body).
**Apply to:** `BackgroundRenderer` — provide `dispose()` and call from `GameScene.dispose()` (lines 687-720 — existing teardown). Tests that recreate the scene depend on this.
### S-08: `__rebno` deterministic test hook (D-35)
**Source:** `apps/client/src/scenes/GameScene.ts:670-684` + `apps/client/src/render/PlayerRenderer.ts:146-157`.
**Apply to:** Any Phase 06.1 e2e assertion that needs to read in-Phaser state. Add fields to `window.__rebno` from the relevant renderer:
```ts
// In BackgroundRenderer (gate to DEV / test mode like PlayerRenderer):
if (import.meta.env.DEV || import.meta.env.MODE === 'test') {
(globalThis as any).__rebno = {
...((globalThis as any).__rebno ?? {}),
bgframe: this.bgframe,
bgDxoff: this.dxoff,
};
}
// In RoomRenderer.renderNew after tile loop:
// (globalThis as any).__rebno.tileCount = this.group.getLength();
```
Production bundle strips these via Vite tree-shaking on `import.meta.env.DEV` constant-folding.
### S-09: Playwright fixtures + `loginAs` + `waitForGameReady`
**Source:** `apps/client/test/e2e/fixtures.ts` (exports `loginAs`, `waitForGameReady`, `accountA`, `accountB`, `inviteSuffix`).
**Apply to:** All 4 new e2e files. NEVER reimplement login. Pattern:
```ts
import { test, expect, loginAs, waitForGameReady } from './fixtures.js';
test('Phase 06.1 ...', async ({ page, accountA, inviteSuffix }) => {
await loginAs(page, accountA, inviteSuffix);
await waitForGameReady(page);
// ... assertions using window.__rebno ...
});
```
### S-10: Atomic regen of atlas + manifest in one plan (D6.1-04)
**Source:** `06-PATTERNS.md` §"Tool ↔ workspace bridge" + STATE.md UAT 2026-05-11 manual-deploy note.
**Apply to:** Plan that touches `bootstrap.ts` MUST also commit (in the same plan):
- `assets/source/sprites/0064-BKA1.{png,json}` (NEW)
- `assets/source/sprites/0024-TSide1.{png,json}` (NEW)
- `assets/source/sprites/.png` (REGEN)
- `apps/server/public/atlas-mvp.{png,json}` (REGEN)
- `apps/server/public/pipeline-manifest.json` (REGEN)
Re-run `pnpm asset-pipeline bootstrap` + `pnpm asset-pipeline build` from the plan body. CI auto-rebuilds the client bundle on merge.
---
## No Analog Found
None. Every Phase 06.1 file has a strong in-repo analog from Phase 6 (where the renderer/scene/asset-pipeline scaffolding was built). The closest-to-novel item is `BackgroundRenderer.ts` but the sprite-group + atlas-key + sim-tick-advance pattern is fully covered by `RoomRenderer` + `PlayerRenderer` analogs.
The font asset `FixedsysExcelsior.woff2` is a vendored binary (CC0 public domain) — no code analog needed; the `index.html` `