bitmap 3D PFP: simplify pass after /simplify review

Hot path
- frameForward / frameSide cached once per frame in pfpFrame
  (cacheFrameVectors after applyLookStick) instead of re-deriving from
  camera.getWorldDirection 10× per substep. Saves ~18 matrix decomposes
  + 9 normalizes per frame on the move path.
- applyEyeSafety skipped when playerVelocity.lengthSq() < 1e-4. Saves
  one octree raycast per idle frame; the previous frame's eye check
  still holds while the capsule is at rest.
- Dropped dead playerDirection scratch (replaced by frameForward/Side).
- New moveAddScratch keeps the cached frame vectors immutable across
  the two add operations in applyControls.

Dedup
- captureLookAtQuat helper extracted from beginFlyToPfp / beginFlyToIso
  (saved 16 lines of saved-state / lookAt / restore boilerplate from
  both fly setups). InstanceType<typeof THREE.X> type alias keeps
  param annotations in the runtime-namespace world.
- SPEED_RUN_SQ + SPEED_WALK_SQ moved from a renderer-local const to
  bitmap-3d-physics.ts as named exports. Renderer + jest spec import
  one source of truth; threshold tweaks are a single edit.
- Shared Playwright helpers extracted to playwright/specs/_shared/
  bitmap-3d-debug.ts (Bitmap3dDebug type, readDebug, waitForState,
  tick, setKey, mountFixture, loadBitmapFixture). Desktop + mobile
  specs collapse to a single import block + mountFixture beforeEach.
  Folder is outside both project testDirs so Playwright doesn't try
  to execute it.

Tidy
- Dropped redundant cdr.markForCheck() from Bitmap3dE2EComponent;
  OnPush + (click) bindings already mark the view dirty.
- Dropped (navigator as any)?.maxTouchPoints cast — it's standard
  Navigator since DOM lib 2018+.

Comment trim (per workspace HARD RULE: keep JSDoc / "why" / sourcing /
encoding / example / edge-case comment blocks; only trim bombast +
before/after history TEXT INSIDE):
- fitDist comment: dropped "previously used Math.atan instead of
  Math.tan, fix while we're here" before/after history.
- finalCamera magnitude comment: dropped "previously the iso corner
  was at sqrt(3/2)*distance..." before/after history.
- PLAYER_RADIUS comment: trimmed "bumped from 0.12 -> 0.22 to fix
  the wall-clip bug" before/after history to current-tense rationale.
- nipplejs move-listener comment: trimmed "the old (evt, data) two-arg
  shape used during the initial port crashed silently..." to one-line
  current-tense "Two-arg (evt, data) throws on every move."

All other JSDoc + sourcing + edge-case blocks (sun direction lookup,
needle/rune pixel-threshold idiom, ecctrl line refs, nipplejs #61/#64
defences, three.js#21921 eye-safety, etc.) untouched per HARD RULE.

Tests
- jest: 279/279 (incl. all 40 bitmap-3d-physics tests with the
  imported SPEED_*_SQ constants).
- playwright: 17/17 across desktop + mobile projects.

Author: hans-crypto

frontend/playwright/specs/_shared/bitmap-3d-debug.ts

@@ -0,0 +1,79 @@
+import { expect, Page } from '@playwright/test';
+import * as fs from 'fs';
+import * as path from 'path';
+
+/**
+ * Shared helpers + types for the bitmap-3d Playwright specs (desktop +
+ * mobile). Lives outside both project testDirs so Playwright doesn't try
+ * to execute it as a spec file.
+ */
+
+export interface Bitmap3dDebug {
+  state: 'intro' | 'orbit' | 'fly-to-pfp' | 'pfp' | 'fly-to-iso' | 'exit-done';
+  playerState: 'idle' | 'walking' | 'running' | 'jumping' | 'falling';
+  pos: [number, number, number];
+  fov: number;
+  onFloor: boolean;
+  vel: [number, number, number];
+  joy: { fwd: number; right: number };
+  look: { x: number; y: number };
+  touchOn: boolean;
+  pfpOn: boolean;
+  tick(frames?: number, dt?: number): void;
+  setKey(code: string, down: boolean): void;
+  jump(): void;
+}
+
+type Win = Window & { __bitmap3d?: Bitmap3dDebug };
+
+/**
+ * Block 800,000 — canonical E2E bitmap. Healthy variety of cube sizes
+ * (1-6) so step-up (size-1 auto-climb) and jump (size-2+) both get
+ * exercised, immutable on-chain, lives in playwright/fixtures/.
+ */
+export const loadBitmapFixture = (height = 800_000): { sizes: number[] } =>
+  JSON.parse(
+    fs.readFileSync(
+      path.resolve(__dirname, `../../fixtures/bitmap-${height}.json`),
+      'utf8',
+    ),
+  );
+
+export const readDebug = (page: Page) =>
+  page.evaluate(() => (window as unknown as Win).__bitmap3d!);
+
+/**
+ * In-browser polling for a state value. Avoids Node<->CDP roundtrip per
+ * probe and unlike expect.poll catches transient values reliably.
+ */
+export const waitForState = (page: Page, target: Bitmap3dDebug['state'], timeout = 30_000) =>
+  page.waitForFunction(
+    s => (window as unknown as Win).__bitmap3d?.state === s,
+    target,
+    { timeout, polling: 100 },
+  );
+
+/**
+ * Run N PFP physics frames at a fixed dt in-browser. Replaces real-time
+ * rAF (which headless Chromium throttles to ~1Hz) with a deterministic
+ * loop. 60 frames @ 1/60 dt = 1 simulated second.
+ */
+export const tick = (page: Page, frames: number) =>
+  page.evaluate(n => (window as unknown as Win).__bitmap3d?.tick(n), frames);
+
+export const setKey = (page: Page, code: string, down: boolean) =>
+  page.evaluate(
+    args => (window as unknown as Win).__bitmap3d?.setKey(args.code, args.down),
+    { code, down },
+  );
+
+/**
+ * Common beforeEach: inject the fixture via addInitScript so it's
+ * available before the SPA boots, navigate to /e2e/bitmap-3d, assert
+ * the renderer mounted.
+ */
+export const mountFixture = async (page: Page, sizes: number[]): Promise<void> => {
+  await page.addInitScript(`window.__bitmap3dFixture = ${JSON.stringify({ sizes })};`);
+  await page.goto('/e2e/bitmap-3d');
+  await expect(page.getByTestId('bitmap-3d-renderer')).toBeAttached();
+};

frontend/playwright/specs/desktop/bitmap-3d.spec.ts

@@ -1,55 +1,18 @@
-import { test, expect, Page } from '@playwright/test';
-import * as fs from 'fs';
-import * as path from 'path';
-
-// Block 800,000 — picked as the canonical E2E bitmap. Healthy variety of
-// cube sizes (1-6) so step-up (size-1 auto-climb) and jump (size-2+) both
-// get exercised, immutable on-chain, lives forever in playwright/fixtures/.
-const fixture = JSON.parse(
-  fs.readFileSync(path.resolve(__dirname, '../../fixtures/bitmap-800000.json'), 'utf8'),
-);
-
-interface Bitmap3dDebug {
-  state: 'intro' | 'orbit' | 'fly-to-pfp' | 'pfp' | 'fly-to-iso' | 'exit-done';
-  playerState: 'idle' | 'walking' | 'running' | 'jumping' | 'falling';
-  pos: [number, number, number];
-  fov: number;
-  onFloor: boolean;
-  vel: [number, number, number];
-  tick(frames?: number, dt?: number): void;
-  setKey(code: string, down: boolean): void;
-  jump(): void;
-}
-
-const readDebug = (page: Page) =>
-  page.evaluate(() => (window as unknown as { __bitmap3d?: Bitmap3dDebug }).__bitmap3d!);
-
-// In-browser polling for a state value: avoids the Node<->CDP roundtrip
-// per probe, and unlike expect.poll catches transient values reliably.
-const waitForState = (page: Page, target: Bitmap3dDebug['state'], timeout = 30_000) =>
-  page.waitForFunction(
-    s => (window as unknown as { __bitmap3d?: { state: string } }).__bitmap3d?.state === s,
-    target,
-    { timeout, polling: 100 },
-  );
-
-// Run N PFP physics frames at a fixed dt in-browser. Replaces real-time
-// rAF (which headless Chromium throttles to ~1Hz) with a deterministic
-// loop the test can wait on. 60 frames @ 1/60 dt = 1 simulated second.
-const tick = (page: Page, frames: number) =>
-  page.evaluate(n => (window as unknown as { __bitmap3d?: Bitmap3dDebug }).__bitmap3d?.tick(n), frames);
-
-const setKey = (page: Page, code: string, down: boolean) =>
-  page.evaluate(
-    args => (window as unknown as { __bitmap3d?: Bitmap3dDebug }).__bitmap3d?.setKey(args.code, args.down),
-    { code, down },
-  );
+import { test, expect } from '@playwright/test';
+import {
+  loadBitmapFixture,
+  mountFixture,
+  readDebug,
+  setKey,
+  tick,
+  waitForState,
+} from '../_shared/bitmap-3d-debug';
+
+const fixture = loadBitmapFixture();
 
 test.describe('bitmap-3d renderer', () => {
   test.beforeEach(async ({ page }) => {
-    await page.addInitScript(`window.__bitmap3dFixture = ${JSON.stringify({ sizes: fixture.sizes })};`);
-    await page.goto('/e2e/bitmap-3d');
-    await expect(page.getByTestId('bitmap-3d-renderer')).toBeAttached();
+    await mountFixture(page, fixture.sizes);
   });
 
   test('mounts the renderer and reaches the orbit state', async ({ page }) => {

frontend/playwright/specs/mobile/bitmap-3d.spec.ts

@@ -1,45 +1,17 @@
-import { test, expect, Page } from '@playwright/test';
-import * as fs from 'fs';
-import * as path from 'path';
-
-// Same canonical fixture as the desktop spec.
-const fixture = JSON.parse(
-  fs.readFileSync(path.resolve(__dirname, '../../fixtures/bitmap-800000.json'), 'utf8'),
-);
-
-interface Bitmap3dDebug {
-  state: string;
-  playerState: string;
-  pos: [number, number, number];
-  fov: number;
-  onFloor: boolean;
-  joy: { fwd: number; right: number };
-  look: { x: number; y: number };
-  touchOn: boolean;
-  pfpOn: boolean;
-  tick(frames?: number, dt?: number): void;
-  setKey(code: string, down: boolean): void;
-  jump(): void;
-}
-
-const readDebug = (page: Page) =>
-  page.evaluate(() => (window as unknown as { __bitmap3d?: Bitmap3dDebug }).__bitmap3d!);
-
-const waitForState = (page: Page, target: string, timeout = 30_000) =>
-  page.waitForFunction(
-    s => (window as unknown as { __bitmap3d?: { state: string } }).__bitmap3d?.state === s,
-    target,
-    { timeout, polling: 100 },
-  );
-
-const tick = (page: Page, frames: number) =>
-  page.evaluate(n => (window as unknown as { __bitmap3d?: Bitmap3dDebug }).__bitmap3d?.tick(n), frames);
+import { test, expect } from '@playwright/test';
+import {
+  loadBitmapFixture,
+  mountFixture,
+  readDebug,
+  tick,
+  waitForState,
+} from '../_shared/bitmap-3d-debug';
+
+const fixture = loadBitmapFixture();
 
 test.describe('bitmap-3d renderer (mobile)', () => {
   test.beforeEach(async ({ page }) => {
-    await page.addInitScript(`window.__bitmap3dFixture = ${JSON.stringify({ sizes: fixture.sizes })};`);
-    await page.goto('/e2e/bitmap-3d');
-    await expect(page.getByTestId('bitmap-3d-renderer')).toBeAttached();
+    await mountFixture(page, fixture.sizes);
   });
 
   test('renderer mounts on a touch device + reports a touch viewport', async ({ page }) => {

frontend/src/app/components/_ordpool/digital-artifact-viewer/bitmap-viewer/bitmap-3d-e2e.component.ts

@@ -1,4 +1,4 @@
-import { ChangeDetectionStrategy, ChangeDetectorRef, Component, inject } from '@angular/core';
+import { ChangeDetectionStrategy, Component } from '@angular/core';
 
 /**
  * Playwright E2E mount point for the bitmap 3D renderer.
@@ -47,14 +47,14 @@ import { ChangeDetectionStrategy, ChangeDetectorRef, Component, inject } from '@
   standalone: false,
 })
 export class Bitmap3dE2EComponent {
-  private cdr = inject(ChangeDetectorRef);
-
+  // OnPush + (click) bindings — Angular runs CD on the bound event, so
+  // these setters don't need an explicit markForCheck.
   sizes: number[] | null = ((window as unknown as { __bitmap3dFixture?: { sizes: number[] } })
     .__bitmap3dFixture?.sizes) ?? null;
   pfp = false;
   exit = false;
 
-  enterPfp(): void { this.pfp = true; this.exit = false; this.cdr.markForCheck(); }
-  exitPfp(): void { this.exit = true; this.cdr.markForCheck(); }
-  onExitDone(): void { this.pfp = false; this.exit = false; this.cdr.markForCheck(); }
+  enterPfp(): void { this.pfp = true; this.exit = false; }
+  exitPfp(): void { this.exit = true; }
+  onExitDone(): void { this.pfp = false; this.exit = false; }
 }

frontend/src/app/components/_ordpool/digital-artifact-viewer/bitmap-viewer/bitmap-3d-physics.spec.ts

@@ -6,12 +6,11 @@ import {
   easeAlpha,
   fovTarget,
   gravityForStep,
+  SPEED_RUN_SQ as RUN_SQ,
+  SPEED_WALK_SQ as WALK_SQ,
 } from './bitmap-3d-physics';
 
 describe('derivePlayerState', () => {
-  // Match the renderer's tuned thresholds so callers see the same boundary.
-  const RUN_SQ = 1.5 * 1.5;
-  const WALK_SQ = 0.5 * 0.5;
 
   it('rising velocity in air -> jumping', () => {
     expect(derivePlayerState(0, 5, 0, false, false, RUN_SQ, WALK_SQ)).toBe('jumping');

frontend/src/app/components/_ordpool/digital-artifact-viewer/bitmap-viewer/bitmap-3d-physics.ts

@@ -8,6 +8,14 @@
 
 export type PlayerState = 'idle' | 'walking' | 'running' | 'jumping' | 'falling';
 
+/**
+ * Horizontal-speed thresholds (squared, so the hot path skips sqrt).
+ * Shared with the renderer's derivePlayerState call AND the jest spec,
+ * so threshold changes are a single edit.
+ */
+export const SPEED_RUN_SQ = 1.5 * 1.5;
+export const SPEED_WALK_SQ = 0.5 * 0.5;
+
 /**
  * Player state derivation.
  *