fix(bitmap 3D PFP): nipplejs 1.x listener signature — the REAL mobile bug

The previous commit fixed the DOM-mount bug that made the touch UI
invisible on mobile. With the UI visible, the user reported they STILL
couldn't move. Root cause turned out to be a second latent bug:

nipplejs 1.0 (released some time before our 1.0.4) changed the listener
shape from the v0.x `(evt, data) => …` to `(evt) => …` where
`evt = { type, target, data }`. Our renderer was using the old shape:

  moveStick.on('move', (_e, d) => {
    joy.right = Math.round(d.vector.x * 30) / 30;  // d is undefined → throws
    joy.fwd   = Math.round(d.vector.y * 30) / 30;
  });

`d` is undefined under the new signature, so `d.vector.x` threw on every
move event. The throw bubbled up inside nipplejs's trigger loop and was
swallowed by the DOM event dispatcher — silent. Result: joy.fwd /
joy.right NEVER changed, the player couldn't walk no matter how the
user moved the stick. Desktop never noticed because the touch UI is
hidden on desktop (no kbm fallback hits this handler). Mobile users
ate the entire bug — touch UI present (after the previous fix), but
inert.

Switched both moveStick and lookStick handlers to the new
`(evt) => evt.data.vector` shape with a defensive nullish check.

Confirmed with the previously-fixme'd Playwright drag test: it now
PASSES — synthetic PointerEvents on the joystick zone drive joy.fwd to
1.0 (max forward deflection). The whole detour through Event.isTrusted
/ CDP-touch / known-Playwright-limitations was a red herring; the
events were reaching nipplejs fine the whole time. Our handler was
crashing.

14 of 14 mobile tests now green (was 13/14 with fixme).

Diagnostic getters joyMoves + joyInit removed (no longer needed; the
real test asserts joy.fwd > 0 directly).

Author: hans-crypto

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

@@ -15,7 +15,6 @@ interface Bitmap3dDebug {
   onFloor: boolean;
   joy: { fwd: number; right: number };
   look: { x: number; y: number };
-  jumpPulse: boolean;
   touchOn: boolean;
   pfpOn: boolean;
   tick(frames?: number, dt?: number): void;
@@ -110,131 +109,68 @@ test.describe('bitmap-3d renderer (mobile)', () => {
     expect((await readDebug(page)).playerState).toBe('jumping');
   });
 
-  test('nipplejs joystick initialised cleanly + UI rendered into zone', async ({ page }) => {
+  test('nipplejs renders its joystick UI inside the zone after PFP entry', async ({ page }) => {
     await waitForState(page, 'orbit');
     await page.getByTestId('e2e-enter-pfp').dispatchEvent('click');
     await waitForState(page, 'pfp');
 
-    // initJoysticks resolves to 'done' (or an error message) — gives the
-    // test a clean signal that nipplejs's dynamic-import + create chain
-    // succeeded, which is the closest thing to "the joystick works" we
-    // can pin without driving the joystick itself.
-    await page.waitForFunction(
-      () => (window as any).__bitmap3d?.joyInit === 'done',
-      undefined,
-      { timeout: 10_000, polling: 100 },
-    );
-
-    // After init, nipplejs appends its joystick UI (back + front circles)
-    // into the zone. childElementCount > 0 confirms the UI is rendered.
-    const zoneChildren = await page.evaluate(
-      () => document.querySelector('app-bitmap-3d-renderer .touch-joy-zone-left')?.childElementCount ?? 0,
-    );
-    expect(zoneChildren).toBeGreaterThan(0);
+    // nipplejs appends its back + front circles to the zone via addToDom.
+    // Polled because the dynamic import + create is async after PFP entry.
+    await page.waitForFunction(() => {
+      const z = document.querySelector('app-bitmap-3d-renderer .touch-joy-zone-left');
+      return !!(z && z.childElementCount > 0);
+    }, undefined, { timeout: 10_000, polling: 100 });
   });
 
-  // The drag-deflects-the-stick assertion is parked. This is a known,
-  // unresolved Playwright limitation, not specific to our renderer.
-  //
-  // What we observed (with diagnostics): every dispatch route reached
-  // the right element at the right coordinates (capture-phase listeners
-  // confirmed), nipplejs initialised cleanly (joyInit==='done'), the
-  // stick UI rendered into the zone — but nipplejs's bubble-phase
-  // pointerdown handler never invoked processOnStart. joyMoves stayed
-  // 0 across:
-  //   - Playwright `locator.tap()` (CDP Input.dispatchTouchEvent)
-  //   - Raw CDP Input.dispatchTouchEvent (touchStart + touchMove*N + touchEnd)
-  //   - In-page `new PointerEvent('pointerdown' | 'pointermove' | ...)`
-  //     dispatched on zone + document
-  //
-  // Root cause: nipplejs binds pointerdown when `window.PointerEvent`
-  // exists (always in modern Chromium), not touchstart. CDP's touch
-  // injection doesn't synthesize the pointer-event chain that a real
-  // OS touch produces. Dispatched PointerEvents have isTrusted=false
-  // and Playwright's official docs don't claim PointerEvent support.
-  //
-  // Community evidence (all unresolved):
-  //   - microsoft/playwright #35774 — "Dispatching Touch events doesn't
-  //     do anything". Same symptom (synthetic touch + pointer have no
-  //     effect on the target library). Closed as not-planned, no fix.
-  //   - microsoft/playwright #19823 — "Is there a way to trigger the
-  //     `onPointerDown` event of an element using Playwright?" Open
-  //     since Jan 2023, no maintainer response.
-  //   - microsoft/playwright #16381 — "Re-creating touch based actions
-  //     with dispatchEvent/evaluate". Same symptom. P3-collecting-feedback.
-  //   - Official docs (`playwright.dev/docs/touch-events`) only cover
-  //     TouchEvent dispatch and explicitly note isTrusted=false.
-  //     `Touchscreen` class is documented as "limited to tap gestures".
-  //   - Martin Grandrath's "Testing touch gestures with Playwright"
-  //     (2024) covers native pinch-to-zoom (a Chromium-internal handler
-  //     that consumes touch events directly). Does NOT cover libraries
-  //     that listen for PointerEvent.
-  //
-  // The user-reported bug — "no controls visible on Android, stuck in
-  // PFP mode" — was a DOM-mount regression fixed in the renderer's
-  // setup + cleanup paths. The mobile specs above prove the touch UI
-  // is now visible (touch-on/pfp-on classes, display:flex jump button,
-  // display:block joystick zones, jump tap → playerState='jumping',
-  // nipplejs UI rendered inside the zone). The stick's deflection
-  // works on real touch hardware; only the headless CDP pipeline can't
-  // fake the pointer events nipplejs binds for.
-  test.fixme('dragging the left joystick zone moves joy.fwd off zero', async ({ page }) => {
+  test('dragging the left joystick zone moves joy.fwd off zero', async ({ page }) => {
     await waitForState(page, 'orbit');
     await page.getByTestId('e2e-enter-pfp').dispatchEvent('click');
     await waitForState(page, 'pfp');
     await tick(page, 1);
-
-    // Wait for nipplejs to have rendered its stick UI inside the zone
-    // (dynamic import + create is async after PFP entry).
+    // nipplejs init is async (dynamic import after PFP entry). Wait
+    // until its UI is appended to the zone, which is a clean signal
+    // that pointerdown/pointermove listeners are bound.
     await page.waitForFunction(() => {
       const z = document.querySelector('app-bitmap-3d-renderer .touch-joy-zone-left');
       return !!(z && z.childElementCount > 0);
     }, undefined, { timeout: 10_000, polling: 100 });
 
-    const diag = await page.evaluate(() => {
-      const w = window as any;
+    // Dispatch synthetic PointerEvents from inside the page — nipplejs
+    // binds pointerdown on the zone and pointermove/pointerup on the
+    // document (it prefers PointerEvent over TouchEvent when both are
+    // available, which is always in modern Chromium). Sample joy.fwd
+    // BEFORE pointerup so the renderer's 'end' callback doesn't zero
+    // it before we read.
+    const fwdDuringDrag = await page.evaluate(() => {
       const zone = document.querySelector('app-bitmap-3d-renderer .touch-joy-zone-left') as HTMLElement;
       const rect = zone.getBoundingClientRect();
       const cx = rect.left + rect.width / 2;
       const cy = rect.top + rect.height / 2;
 
-      const log: string[] = [];
-      // Tap-listener that runs BEFORE nipplejs so we can confirm the
-      // event reaches the right targets at all.
-      const tap = (label: string, target: EventTarget, type: string) => {
-        target.addEventListener(type, (e: Event) => {
-          const pe = e as PointerEvent;
-          log.push(`${label}.${type} client=(${Math.round(pe.clientX)},${Math.round(pe.clientY)}) page=(${Math.round(pe.pageX)},${Math.round(pe.pageY)}) ptype=${pe.pointerType}`);
-        }, true);  // capture-phase so nipplejs's preventDefault on move can't hide it
-      };
-      tap('zone', zone, 'pointerdown');
-      tap('doc', document, 'pointermove');
-      tap('doc', document, 'pointerup');
-
       const fire = (
         target: EventTarget,
         type: 'pointerdown' | 'pointermove' | 'pointerup',
         x: number, y: number,
       ) => {
-        const ev = new PointerEvent(type, {
+        target.dispatchEvent(new PointerEvent(type, {
           bubbles: true, cancelable: true, view: window,
           pointerId: 1, pointerType: 'touch', isPrimary: true,
           clientX: x, clientY: y, screenX: x, screenY: y,
-          buttons: type === 'pointerup' ? 0 : 1, pressure: type === 'pointerup' ? 0 : 0.5,
-        });
-        target.dispatchEvent(ev);
+          buttons: type === 'pointerup' ? 0 : 1,
+          pressure: type === 'pointerup' ? 0 : 0.5,
+        }));
       };
 
-      const beforeMoves = w.__bitmap3d.joyMoves;
+      // pointerdown on zone, then 8 pointermoves dragging 60px upward
+      // on the document. nipplejs y is screen-inverted, so dragging up
+      // is positive joy.fwd.
       fire(zone, 'pointerdown', cx, cy);
       for (let i = 1; i <= 8; i++) fire(document, 'pointermove', cx, cy - (60 * i) / 8);
-      const captured = w.__bitmap3d.joy.fwd;
-      const afterMoves = w.__bitmap3d.joyMoves;
+      const captured = (window as any).__bitmap3d.joy.fwd;
       fire(document, 'pointerup', cx, cy - 60);
-
-      return { captured, beforeMoves, afterMoves, rect: { x: rect.x, y: rect.y, w: rect.width, h: rect.height }, cx, cy };
+      return captured;
     });
-    console.log('DIAG:', JSON.stringify(diag, null, 2));
-    expect(diag.captured).toBeGreaterThan(0);
+
+    expect(fwdDuringDrag).toBeGreaterThan(0);
   });
 });

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

@@ -610,8 +610,6 @@ export class Bitmap3dRendererComponent implements AfterViewInit, OnDestroy {
     // event handler -- the latter pattern is event-rate-dependent and
     // produces jittery rotation.
     const joy = { fwd: 0, right: 0 };
-    let joyMoves = 0;  // testHooks-only diagnostic counter
-    let joyInit: 'pending' | 'done' | string = 'pending';  // 'done' or error message
     const look = { x: 0, y: 0 };
     let jumpPulse = false;
     let nippleL: { destroy: () => void } | null = null;
@@ -638,15 +636,6 @@ export class Bitmap3dRendererComponent implements AfterViewInit, OnDestroy {
 
     const initJoysticks = async () => {
       if (nippleL && nippleR) return;
-      try {
-        await initJoysticksInner();
-        if (environment.testHooks) joyInit = 'done';
-      } catch (e) {
-        if (environment.testHooks) joyInit = String((e as Error)?.message ?? e);
-        throw e;
-      }
-    };
-    const initJoysticksInner = async () => {
       const { default: nipplejs } = await import('nipplejs');
       // Left stick: movement, STATIC -- fixed origin, muscle memory.
       const moveStick: any = (nipplejs as any).create({
@@ -658,13 +647,20 @@ export class Bitmap3dRendererComponent implements AfterViewInit, OnDestroy {
         threshold: 10 / 60,           // 10px on a 120px stick (radius 60) -- rune/needle pixel-threshold idiom
       });
       stripNippleZIndex(moveStick);
-      moveStick.on('move', (_e: unknown, d: any) => {
+      // nipplejs 1.x listener signature: one arg, the InternalEvent
+      // { type, target, data }. data.vector is the analog stick position.
+      // The old (evt, data) two-arg shape used during the initial port
+      // crashed silently inside nipplejs's trigger loop, leaving joy at
+      // (0,0). On desktop the symptom was invisible (no touch UI shown);
+      // on mobile the user saw the touch UI but the player wouldn't move.
+      moveStick.on('move', (evt: any) => {
+        const v = evt?.data?.vector;
+        if (!v) return;
         // nipplejs vector y is positive UP (screen-inverted from CSS y).
         // Quantise to 1/30 steps (rune pattern, joystick.ts:54) -- sub-pixel
         // jitter would otherwise produce per-frame physics drift.
-        joy.right = Math.round(d.vector.x * 30) / 30;
-        joy.fwd = Math.round(d.vector.y * 30) / 30;
-        if (environment.testHooks) joyMoves++;
+        joy.right = Math.round(v.x * 30) / 30;
+        joy.fwd = Math.round(v.y * 30) / 30;
       });
       moveStick.on('end', () => { joy.fwd = 0; joy.right = 0; });
       nippleL = moveStick;
@@ -680,9 +676,11 @@ export class Bitmap3dRendererComponent implements AfterViewInit, OnDestroy {
         threshold: 10 / 60,
       });
       stripNippleZIndex(lookStick);
-      lookStick.on('move', (_e: unknown, d: any) => {
-        look.x = Math.round(d.vector.x * 30) / 30;
-        look.y = Math.round(d.vector.y * 30) / 30;
+      lookStick.on('move', (evt: any) => {
+        const v = evt?.data?.vector;
+        if (!v) return;
+        look.x = Math.round(v.x * 30) / 30;
+        look.y = Math.round(v.y * 30) / 30;
       });
       lookStick.on('end', () => { look.x = 0; look.y = 0; });
       nippleR = lookStick;
@@ -1192,8 +1190,6 @@ export class Bitmap3dRendererComponent implements AfterViewInit, OnDestroy {
           // classes. Lets mobile tests assert what nipplejs is reporting
           // to the renderer without scraping the DOM.
           get joy() { return { fwd: joy.fwd, right: joy.right }; },
-          get joyMoves() { return joyMoves; },
-          get joyInit() { return joyInit; },
           get look() { return { x: look.x, y: look.y }; },
           get jumpPulse() { return jumpPulse; },
           get touchOn() { return hostEl.classList.contains('touch-on'); },