feat: single-page title menu, in-game quickbar and smooth ghosts

- welcome: one-page menu (vitrine brand lockup, landing-size h1,
controls grid with pad variant), pre-boot spinner veil
- in-game: live colour + legs/rollers quickbar bottom-left, back
button, big mode readout top-right, telemetry stack bottom-right
(peers, speed, odometer, fps, ctrl rate)
- ghosts: snapshot interpolation at 15 Hz replaces the exponential
chase (no more micro-stutter, background tabs degrade gracefully)
- modules landed with this batch: ceremony (entrance/respawn), fx
(wireframe/glitch), controls stack, ball actor, comic stickers

Co-authored-by: Cursor <cursoragent@cursor.com>

README.md

@@ -48,6 +48,14 @@ and [apirrone/mjlab_microduck](https://github.com/apirrone/mjlab_microduck).
 In roller mode the legs-only actions (kicks, sit) are disabled and their
 hints fade out; play the ball by driving into it.
 
+### URL parameters
+
+- `?boot=1`: skip the welcome modal and land straight on the BIOS console,
+  which then shows the real loading progress live (honest loader) before
+  the normal entrance plays. Boot failures (missing asset, policy fetch
+  error...) freeze the console on a `SYSTEM HALTED` screen with the error
+  detail - handy for debugging.
+
 The ball is local-only: it lives in your tab's physics and is not shared
 with the multiplayer ghosts. A square arena (3 x 3 m) fences the play
 area so neither the ball nor the duck can wander off.

ball-actor.js

@@ -0,0 +1,102 @@
+// Ball actor: physics stays in rl.js, this owns the mesh + wireframe FX.
+//
+// visual:
+//   hidden  parked, mesh off
+//   live    following qpos, optional appear scan playing
+//   ghost   physics already parked; mesh frozen at last pose while the
+//           reverse scan peels it away
+//
+// spawn while live/ghost queues a pop: despawn finishes, then the caller
+// places physics and appear()s.
+
+// Appear/disappear speed. The shared wireframe FX timeline lasts
+// fx.TOTAL_S (0.9 s, tuned for the duck's ceremony); the ball plays the
+// same timeline time-scaled to these snappier durations.
+const BALL_APPEAR_S = 0.2; // spawn pop-in (scan up)
+const BALL_DISAPPEAR_S = 0.15; // despawn/park peel-away (reverse scan)
+
+export function createBallActor({ THREE, scene, camera, renderer, fxModule, mesh, group }) {
+  const fx = fxModule.createWireframeFx();
+  fx.init({ THREE, scene, root: group, camera, renderer, hidden: false });
+
+  let visual = "hidden"; // hidden | live | ghost
+  let ghost = null;
+  let pendingSpawn = false;
+  let fxPrev = null;
+
+  function appear() {
+    visual = "live";
+    ghost = null;
+    mesh.visible = true;
+    fx.start();
+    fxPrev = performance.now();
+  }
+
+  function despawn({ cancelQueued = false, parkPhysics }) {
+    if (cancelQueued) pendingSpawn = false;
+    if (visual === "hidden") return;
+    if (visual === "live") {
+      ghost = {
+        pos: mesh.position.clone(),
+        quat: mesh.quaternion.clone(),
+      };
+      visual = "ghost";
+    }
+    parkPhysics();
+    fx.startReverse();
+    fxPrev = performance.now();
+  }
+
+  function queueRespawn() {
+    pendingSpawn = true;
+  }
+
+  function poseFromQpos(qpos, adr) {
+    mesh.position.set(qpos[adr], qpos[adr + 1], qpos[adr + 2]);
+    mesh.quaternion.set(qpos[adr + 4], qpos[adr + 5], qpos[adr + 6], qpos[adr + 3]);
+  }
+
+  function sync(qpos, adr, physicsLive) {
+    if (visual === "ghost" && ghost) {
+      mesh.visible = true;
+      mesh.position.copy(ghost.pos);
+      mesh.quaternion.copy(ghost.quat);
+    } else if (physicsLive) {
+      mesh.visible = true;
+      poseFromQpos(qpos, adr);
+    } else {
+      mesh.visible = false;
+    }
+  }
+
+  function drive(onQueuedSpawn) {
+    if (fx.playing) {
+      const now = performance.now();
+      if (fxPrev === null) fxPrev = now;
+      const dt = Math.min((now - fxPrev) / 1000, 0.25);
+      fxPrev = now;
+      // Time-scale the FX so the ball pops in/out at its own speed.
+      const speed = fx.TOTAL_S / (fx.reversing ? BALL_DISAPPEAR_S : BALL_APPEAR_S);
+      fx.update(dt * speed);
+    }
+    if (visual === "ghost" && fx.isDone()) {
+      mesh.visible = false;
+      visual = "hidden";
+      ghost = null;
+      fx.restore();
+      const queued = pendingSpawn;
+      pendingSpawn = false;
+      if (queued) onQueuedSpawn();
+    }
+  }
+
+  return {
+    appear,
+    despawn,
+    queueRespawn,
+    poseFromQpos,
+    sync,
+    drive,
+    get visual() { return visual; },
+  };
+}

ceremony.js

@@ -0,0 +1,171 @@
+// Cutscene layer: page-load entrance and every later respawn.
+//
+// Physics (resetSim) snaps the duck to the stand keyframe; this module
+// owns what the player sees around that snap. Two mutually exclusive
+// timelines share the duck's wireframe FX:
+//
+//   entrance (once)  grid + walls draw in, then the duck scans up
+//   respawn  (every kill / Space / loco switch)
+//     0.00  duck clipped away, camera glides home from the kill view
+//     0.80  camera almost settled -> duck scan-up cues
+//     0.90  camera lands
+//     1.70  scan done, inputs unlock
+//
+// rl.js injects the world (rig, grid, camera reset) and the lock/flash
+// callbacks; this file never touches MuJoCo.
+
+export const CAM_RESET_S = 0.9;
+export const RESPAWN_SCAN_AT = 0.8; // cue scan-up at 80% of the camera glide
+
+const ENTRANCE_GRID_S = 1.1;
+const ENTRANCE_WALL_DELAY_S = 0.35;
+const ENTRANCE_WALL_S = 0.9;
+const ENTRANCE_FX_START_S = 0.6;
+
+const clamp01 = (x) => Math.min(Math.max(x, 0), 1);
+
+export function createCeremony({
+  THREE, scene, camera, renderer, fx,
+  getRig, grid, wallMats,
+  syncRig, startCameraReset,
+  setLocked, flashReset,
+}) {
+  const ENTRANCE_TOTAL_S = Math.max(
+    ENTRANCE_GRID_S,
+    ENTRANCE_WALL_DELAY_S + ENTRANCE_WALL_S,
+    ENTRANCE_FX_START_S + fx.TOTAL_S,
+  );
+
+  let fxRig = null;
+  let fxPrev = null;
+  let entranceT0 = null;
+  let entranceFxCued = false;
+  let entranceDone = false;
+  let respawn = null; // { t0, scanCued } | null
+  let entranceFinishedResolve;
+  const entranceFinished = new Promise((r) => { entranceFinishedResolve = r; });
+
+  function bind() {
+    const rig = getRig();
+    if (fxRig === rig) return;
+    fx.dispose();
+    fx.init({ THREE, scene, rig, camera, renderer });
+    rig.placer.traverse((o) => {
+      if (o.isMesh && !o.userData.meshName) o.userData.fxOverlay = true;
+    });
+    fxRig = rig;
+  }
+
+  function fxStart() {
+    bind();
+    fx.start();
+    fxPrev = performance.now();
+  }
+  function fxDrive() {
+    if (fxPrev === null || fx.isDone()) return;
+    const now = performance.now();
+    const dt = Math.min((now - fxPrev) / 1000, 0.25);
+    fxPrev = now;
+    fx.update(dt);
+  }
+  function fxForceFinish() {
+    if (!fx.isDone()) fx.update(1e3);
+  }
+
+  function startEntrance() {
+    if (entranceT0 !== null || entranceDone) return;
+    entranceT0 = performance.now();
+    entranceFxCued = false;
+    grid.material.uniforms.uReveal.value = 0;
+    for (const m of wallMats) m.uniforms.uReveal.value = 0;
+  }
+
+  function driveEntrance() {
+    if (entranceT0 === null) return;
+    const t = (performance.now() - entranceT0) / 1000;
+    grid.material.uniforms.uReveal.value = clamp01(t / ENTRANCE_GRID_S);
+    const wallR = clamp01((t - ENTRANCE_WALL_DELAY_S) / ENTRANCE_WALL_S);
+    for (const m of wallMats) m.uniforms.uReveal.value = wallR;
+    if (t >= ENTRANCE_FX_START_S && !entranceFxCued) {
+      entranceFxCued = true;
+      fxStart();
+    }
+    fxDrive();
+    if (t >= ENTRANCE_TOTAL_S) {
+      if (!fx.isDone() && t < ENTRANCE_TOTAL_S + 0.5) return;
+      fxForceFinish();
+      entranceT0 = null;
+      entranceDone = true;
+      grid.material.uniforms.uReveal.value = 1;
+      for (const m of wallMats) m.uniforms.uReveal.value = 1;
+      setLocked(false);
+      entranceFinishedResolve();
+    }
+  }
+
+  function playRespawn() {
+    if (!entranceDone) return;
+    setLocked(true);
+    flashReset();
+    bind();
+    startCameraReset();
+    syncRig();
+    fx.setProgress(0);
+    respawn = { t0: performance.now(), scanCued: false };
+  }
+
+  function driveRespawn() {
+    if (!respawn) return;
+    const u = (performance.now() - respawn.t0) / 1000 / CAM_RESET_S;
+    if (!respawn.scanCued && u >= RESPAWN_SCAN_AT) {
+      respawn.scanCued = true;
+      fxStart();
+    }
+    if (respawn.scanCued) fxDrive();
+    if (respawn.scanCued && fx.isDone()) {
+      respawn = null;
+      setLocked(false);
+    }
+  }
+
+  function drive() {
+    driveEntrance();
+    driveRespawn();
+  }
+
+  function setReveal(floor, wall = floor) {
+    entranceT0 = null;
+    grid.material.uniforms.uReveal.value = floor;
+    for (const m of wallMats) m.uniforms.uReveal.value = wall;
+  }
+
+  function setFx(p) {
+    entranceT0 = null;
+    respawn = null;
+    bind();
+    if (p >= 1) {
+      fx.start();
+      fxForceFinish();
+      setLocked(false);
+      entranceFinishedResolve();
+    } else {
+      fx.setProgress(p);
+    }
+  }
+
+  // Boot hidden: clip parked below the feet from the first frame.
+  bind();
+
+  return {
+    CAM_RESET_S,
+    startEntrance,
+    playRespawn,
+    drive,
+    bind,
+    setReveal,
+    setFx,
+    entranceFinished,
+    get entranceDone() { return entranceDone; },
+    get respawnActive() { return respawn !== null; },
+  };
+}

controls/controller.js

@@ -0,0 +1,188 @@
+// Controller: the video-game-style input core. Aggregates pluggable input
+// SOURCES (keyboard, gamepad, later touch) into one game-facing surface:
+//
+//   - a continuous COMMAND: the [vx, vy, wz] twist the policy tracks, plus
+//     auxiliary analog AXES (jaw 0..1, camera-orbit rates -1..1);
+//   - discrete ACTIONS: edge-triggered events (roll, kicks, ball spawn...)
+//     dispatched to subscribers the moment a source fires them;
+//   - HUD support: per-source pressed-state snapshots and activity info so
+//     the hint keycaps can light up per physical control and per device.
+//
+// The game code (rl.js) instantiates the sources, registers them here,
+// calls update(dt) once per render frame, reads getCommand()/getAxes()
+// where it builds the policy observation, and subscribes its trigger
+// functions with on(action, cb).
+//
+// ── Source interface contract ────────────────────────────────────────────
+// Every input source module (keyboard.js, gamepad.js, a future touch.js
+// with a virtual joystick + buttons) implements:
+//
+//   id          Unique string ("keyboard", "gamepad", "touch"...). Action
+//               subscribers receive it as meta.source, so game code can
+//               attribute HUD flashes / keycap lighting to the right device.
+//   connected   Boolean hardware presence. Keyboard: always true. Gamepad:
+//               a pad is currently reported by navigator.getGamepads().
+//   command     Float32Array(3) [vx, vy, wz], ALREADY scaled to the game's
+//               velocity limits (sources take a getVelocityLimits() callback
+//               returning [fwd, back, ang], so limits can change at runtime,
+//               e.g. the legs <-> rollers switch). Must be a stable array
+//               reference updated in place: getCommand() hands it out
+//               without copying, and the control loop reads it between
+//               render frames.
+//   axes        { jaw, orbitX, orbitY } - auxiliary continuous channels.
+//               jaw in [0, 1] (mouth opening), orbit axes in [-1, 1]
+//               (camera orbit rate; the inertia/smoothing lives downstream
+//               in the camera code, sources report raw deflection). Stable
+//               object reference, updated in place. Channels a source does
+//               not drive stay 0.
+//   pressed     Plain object of booleans (stable reference) mirroring which
+//               physical controls are currently down. HUD highlighting
+//               only - never game logic.
+//   isActive()  Whether the source currently claims authority over the
+//               continuous command. Keyboard: any move key held. Gamepad:
+//               stick deflected, and it keeps the claim until its smoothed
+//               command settles back to ~zero.
+//   init()      Attach event listeners / hardware hooks. Called by
+//               Controller.init(), NOT at construction (rl.js constructs
+//               the sources early but arms the listeners at the same point
+//               in the boot where they historically went live).
+//   dispose()   Detach everything init() attached.
+//   poll(dt)    Per-frame tick (dt in seconds, clamped by the caller).
+//               Read the hardware, update command/axes/pressed in place,
+//               and fire edge-triggered actions via this.onAction(name).
+//   onAction    (name, meta?) => void, assigned by the Controller at
+//               registration. Sources may call it from poll() (gamepad
+//               button edges) or straight from event handlers (keyboard:
+//               keeps the historical press-to-effect latency).
+//
+// ── Arbitration ──────────────────────────────────────────────────────────
+// Continuous command: sources are registered in PRIORITY order (first =
+// highest). Each frame the first source reporting isActive() owns the
+// twist; when none is active the LAST registered source's command is used
+// as the fallback (it reads zero when idle). With [gamepad, keyboard] this
+// reproduces the historical `padActive ? padCmd : velCmd` exactly: live
+// sticks win over held keys, and the keyboard takes back over once the
+// pad's smoothed command has settled.
+// Aux axes are merged across ALL sources regardless of who owns the twist
+// (the pad triggers drive the jaw even while walking on the keyboard):
+// jaw = max over sources, orbit = largest-magnitude value per axis.
+//
+// ── Actions ──────────────────────────────────────────────────────────────
+//   roll          one-shot roll (crouch-glide in roller mode; game decides)
+//   kickL, kickR  one-shot kicks, explicit foot
+//   alternateKick one-shot kick, feet alternated by the game
+//   spawnBall     pop / respawn the kickable ball
+//   sitToggle     sit <-> stand (game gates it to legs mode)
+//   locoToggle    legs <-> rollers switch
+//   chaseToggle   chase camera on/off
+//   reset         full sim reset (Space)
+//   walk          back to the walk/run mode (pad DpadUp short press)
+//   quack         chirp + jaw flap (pad RT edge, Schmitt-triggered)
+//
+// ── Input lock ───────────────────────────────────────────────────────────
+// setLocked(true) zeroes getCommand() - the twist gate used while the
+// entrance/respawn ceremony plays. Discrete actions still dispatch: each
+// game trigger applies its own lock policy (e.g. Space-reset and the
+// chase-cam toggle historically work while locked, kicks don't).
+
+const ZERO_CMD = new Float32Array(3);
+
+export class Controller {
+  #sources = [];
+  #listeners = new Map(); // action -> Set(cb)
+  #locked = false;
+  #axes = { jaw: 0, orbitX: 0, orbitY: 0 };
+
+  constructor({ sources = [] } = {}) {
+    for (const s of sources) this.addSource(s);
+  }
+
+  // Register in priority order (first registered wins arbitration ties).
+  addSource(source) {
+    source.onAction = (action, meta) =>
+      this.#dispatch(action, { source: source.id, ...meta });
+    this.#sources.push(source);
+  }
+
+  // Read-only source list, for advanced per-source queries the merged view
+  // can't answer (e.g. "is ANY source commanding a turn right now?").
+  get sources() {
+    return this.#sources;
+  }
+
+  // Arm every source's listeners/hardware hooks.
+  init() {
+    for (const s of this.#sources) s.init?.();
+  }
+
+  dispose() {
+    for (const s of this.#sources) s.dispose?.();
+  }
+
+  // Per-frame tick: poll every source (they fire their edge actions from
+  // inside poll), then merge the aux axes.
+  update(dt) {
+    for (const s of this.#sources) s.poll?.(dt);
+    let jaw = 0, ox = 0, oy = 0;
+    for (const s of this.#sources) {
+      const a = s.axes;
+      if (!a) continue;
+      jaw = Math.max(jaw, a.jaw ?? 0);
+      if (Math.abs(a.orbitX ?? 0) > Math.abs(ox)) ox = a.orbitX;
+      if (Math.abs(a.orbitY ?? 0) > Math.abs(oy)) oy = a.orbitY;
+    }
+    this.#axes.jaw = jaw;
+    this.#axes.orbitX = ox;
+    this.#axes.orbitY = oy;
+  }
+
+  setLocked(v) {
+    this.#locked = !!v;
+  }
+
+  get locked() {
+    return this.#locked;
+  }
+
+  // Merged continuous twist [vx, vy, wz] (see the arbitration notes above).
+  // Returns live source arrays without copying - treat as read-only.
+  getCommand() {
+    if (this.#locked) return ZERO_CMD;
+    for (const s of this.#sources) if (s.isActive()) return s.command;
+    const fallback = this.#sources[this.#sources.length - 1];
+    return fallback ? fallback.command : ZERO_CMD;
+  }
+
+  // Merged aux axes { jaw, orbitX, orbitY }, refreshed by update().
+  getAxes() {
+    return this.#axes;
+  }
+
+  // Any source claiming twist authority (HUD "user is driving" signal).
+  anyActive() {
+    return this.#sources.some((s) => s.isActive());
+  }
+
+  // Per-source pressed snapshots for HUD keycap highlighting:
+  // { keyboard: {...}, gamepad: {...} }.
+  getPressed() {
+    const out = {};
+    for (const s of this.#sources) out[s.id] = s.pressed ?? {};
+    return out;
+  }
+
+  // Subscribe to a discrete action; cb(meta) with meta.source = source id.
+  // Returns an unsubscribe function.
+  on(action, cb) {
+    let set = this.#listeners.get(action);
+    if (!set) this.#listeners.set(action, (set = new Set()));
+    set.add(cb);
+    return () => set.delete(cb);
+  }
+
+  #dispatch(action, meta) {
+    const set = this.#listeners.get(action);
+    if (!set) return;
+    for (const cb of set) cb(meta);
+  }
+}

controls/gamepad.js

@@ -0,0 +1,153 @@
+// Gamepad input source (see controller.js for the source interface
+// contract). Same mapping as the robot runtime (microduck_runtime):
+//
+//   Left stick   vertical = vx (asymmetric fwd/back), horizontal = turn,
+//                EMA-smoothed like the runtime's cmd_alpha.
+//   Right stick  camera orbit rate (reported raw in axes.orbitX/Y; the
+//                velocity smoothing / coasting lives downstream in the
+//                camera code). R3 toggles the chase cam.
+//   X            roll (crouch-glide in roller mode - game decides)
+//   Y            ball spawn/respawn
+//   RB / LB      right / left kick
+//   DpadDown     sit <-> stand
+//   DpadUp       short press = back to run; HOLD ~1 s = legs <-> rollers
+//                (like the robot's 3 s hold, shortened for the web)
+//   RT / LT      analog jaw (max of both); RT edge quacks through a
+//                Schmitt trigger (fire at >= 0.35, re-arm below 0.2 - a
+//                single threshold re-fires on jitter, which is how one
+//                squeeze used to quack several times).
+
+const PAD_DEADZONE = 0.15;
+const PAD_ALPHA = 0.12; // EMA smoothing toward the stick target
+const dz = (v) => (Math.abs(v) < PAD_DEADZONE ? 0 : v);
+
+// Standard-mapping button indices.
+const BTN_X = 2, BTN_Y = 3, BTN_LB = 4, BTN_RB = 5, BTN_LT = 6, BTN_RT = 7;
+const BTN_R3 = 11, BTN_DPAD_UP = 12, BTN_DPAD_DOWN = 13;
+
+const DPAD_UP_HOLD_MS = 1000; // hold-to-switch-loco duration
+
+export class GamepadSource {
+  id = "gamepad";
+  connected = false;
+  command = new Float32Array(3); // [vx, 0, wz], EMA-smoothed
+  axes = { jaw: 0, orbitX: 0, orbitY: 0 };
+  pressed = {
+    x: false, y: false, rb: false, lb: false, r3: false,
+    dpadDown: false, dpadUp: false,
+  };
+  onAction = () => {}; // assigned by the Controller at registration
+
+  #getVelocityLimits;
+  #active = false; // owns twist authority (stick input, until EMA settles)
+  #dpadUpAt = 0; // wall-clock of the current DpadUp press
+  #dpadUpFired = false; // latch: one loco switch per hold
+  #rtArmed = true; // Schmitt trigger state for the RT quack
+
+  constructor({ getVelocityLimits }) {
+    this.#getVelocityLimits = getVelocityLimits;
+  }
+
+  init() {} // poll-based: nothing to attach
+  dispose() {}
+
+  isActive() {
+    return this.#active;
+  }
+
+  poll() {
+    const prev = this.pressed;
+    const gp = [...(navigator.getGamepads?.() ?? [])].find((p) => p && p.connected);
+    this.connected = !!gp;
+    if (!gp) {
+      if (this.#active) {
+        this.#active = false;
+        this.command.fill(0);
+        this.axes.jaw = 0;
+      }
+      this.axes.orbitX = 0;
+      this.axes.orbitY = 0;
+      return;
+    }
+    const now = performance.now();
+
+    // Left stick only: vertical = forward/back, horizontal = turn.
+    // (No strafe; the right stick doesn't drive movement.)
+    const lx = dz(gp.axes[0] ?? 0), ly = dz(gp.axes[1] ?? 0);
+    const up = -ly; // browser sticks report up as -1
+    const [limF, limB, limA] = this.#getVelocityLimits();
+    const target = [
+      up >= 0 ? up * limF : up * -limB,
+      0,
+      -lx * limA,
+    ];
+    for (let i = 0; i < 3; i++) this.command[i] += PAD_ALPHA * (target[i] - this.command[i]);
+    // Sticks grab command authority on first input, release when back at
+    // rest (then the keyboard takes over again through the Controller's
+    // arbitration).
+    const stickInput = lx !== 0 || ly !== 0;
+    if (stickInput) this.#active = true;
+    else if (
+      this.#active &&
+      Math.abs(this.command[0]) + Math.abs(this.command[1]) + Math.abs(this.command[2]) < 0.01
+    ) {
+      this.#active = false;
+      this.command.fill(0);
+    }
+
+    // Right stick: raw (deadzoned) orbit rate. Reported every frame - the
+    // downstream camera step needs the zeros too so a released stick
+    // coasts to a stop.
+    this.axes.orbitX = dz(gp.axes[2] ?? 0);
+    this.axes.orbitY = dz(gp.axes[3] ?? 0);
+
+    // R3 (right stick click): chase-cam toggle, gamepad twin of KeyC.
+    const r3 = !!gp.buttons[BTN_R3]?.pressed;
+    if (r3 && !prev.r3) this.onAction("chaseToggle");
+    prev.r3 = r3;
+
+    const x = !!gp.buttons[BTN_X]?.pressed;
+    if (x && !prev.x) this.onAction("roll");
+    prev.x = x;
+
+    const y = !!gp.buttons[BTN_Y]?.pressed;
+    if (y && !prev.y) this.onAction("spawnBall");
+    prev.y = y;
+
+    const rb = !!gp.buttons[BTN_RB]?.pressed;
+    if (rb && !prev.rb) this.onAction("kickR");
+    prev.rb = rb;
+    const lb = !!gp.buttons[BTN_LB]?.pressed;
+    if (lb && !prev.lb) this.onAction("kickL");
+    prev.lb = lb;
+
+    const dpadDown = !!gp.buttons[BTN_DPAD_DOWN]?.pressed;
+    if (dpadDown && !prev.dpadDown) this.onAction("sitToggle");
+    prev.dpadDown = dpadDown;
+
+    // DpadUp: short press = back to run; hold fires ONE loco switch.
+    const dpadUp = !!gp.buttons[BTN_DPAD_UP]?.pressed;
+    if (dpadUp && !prev.dpadUp) {
+      this.#dpadUpAt = now;
+      this.#dpadUpFired = false;
+      this.onAction("walk");
+    }
+    if (dpadUp && !this.#dpadUpFired && now - this.#dpadUpAt >= DPAD_UP_HOLD_MS) {
+      this.#dpadUpFired = true; // latch: one switch per hold
+      this.onAction("locoToggle");
+    }
+    prev.dpadUp = dpadUp;
+
+    // Triggers drive the mouth (max of both); RT quacks on its
+    // Schmitt-triggered rising edge.
+    const rt = gp.buttons[BTN_RT]?.value ?? 0;
+    const lt = gp.buttons[BTN_LT]?.value ?? 0;
+    this.axes.jaw = Math.max(rt, lt);
+    if (this.#rtArmed && rt >= 0.35) {
+      this.onAction("quack");
+      this.#rtArmed = false;
+    } else if (!this.#rtArmed && rt < 0.2) {
+      this.#rtArmed = true;
+    }
+  }
+}

controls/keyboard.js

@@ -0,0 +1,116 @@
+// Keyboard input source (see controller.js for the source interface
+// contract). Hold-to-command movement keys plus one-shot action keys.
+//
+// e.code is the PHYSICAL key position, so one map covers QWERTY and AZERTY:
+// arrows / WASD (ZQSD) run + turn. No strafe - vy stays 0.
+
+const KEYMAP = {
+  ArrowUp: "fwd", KeyW: "fwd",
+  ArrowDown: "back", KeyS: "back",
+  ArrowLeft: "turnl", KeyA: "turnl",
+  ArrowRight: "turnr", KeyD: "turnr",
+};
+
+// One-shot keys -> controller actions. Physical Q/E (A/E on AZERTY) are the
+// explicit left / right kicks, mirroring the pad's LB / RB; F alternates.
+const ACTION_KEYS = {
+  KeyB: "spawnBall",
+  KeyC: "chaseToggle",
+  KeyM: "locoToggle",
+  KeyR: "roll",
+  KeyQ: "kickL",
+  KeyE: "kickR",
+  KeyF: "alternateKick",
+};
+
+export class KeyboardSource {
+  id = "keyboard";
+  connected = true; // a keyboard is always assumed present
+  command = new Float32Array(3); // [vx, 0, wz], scaled to velocity limits
+  axes = { jaw: 0, orbitX: 0, orbitY: 0 }; // keyboard drives none of these
+  pressed = { fwd: false, back: false, turnl: false, turnr: false };
+  onAction = () => {}; // assigned by the Controller at registration
+
+  #held = new Set();
+  #getVelocityLimits;
+  // Limits snapshot so poll() only re-maps held keys when they actually
+  // change (the legs <-> rollers switch); event handlers do the live work.
+  #lims = [NaN, NaN, NaN];
+  #onKeyDown = null;
+  #onKeyUp = null;
+  #onBlur = null;
+
+  constructor({ getVelocityLimits }) {
+    this.#getVelocityLimits = getVelocityLimits;
+  }
+
+  init() {
+    this.#onKeyDown = (e) => {
+      if (e.repeat) return;
+      // Space always resets, and must not scroll the page.
+      if (e.code === "Space") {
+        e.preventDefault();
+        this.onAction("reset");
+        return;
+      }
+      const action = ACTION_KEYS[e.code];
+      if (action) {
+        this.onAction(action);
+        return;
+      }
+      const move = KEYMAP[e.code];
+      if (!move) return;
+      e.preventDefault();
+      this.#held.add(move);
+      this.#refresh();
+    };
+    this.#onKeyUp = (e) => {
+      const move = KEYMAP[e.code];
+      if (!move) return;
+      this.#held.delete(move);
+      this.#refresh();
+    };
+    // Losing window focus drops every held key (keyup events are missed).
+    this.#onBlur = () => {
+      this.#held.clear();
+      this.#refresh();
+    };
+    window.addEventListener("keydown", this.#onKeyDown);
+    window.addEventListener("keyup", this.#onKeyUp);
+    window.addEventListener("blur", this.#onBlur);
+  }
+
+  dispose() {
+    window.removeEventListener("keydown", this.#onKeyDown);
+    window.removeEventListener("keyup", this.#onKeyUp);
+    window.removeEventListener("blur", this.#onBlur);
+  }
+
+  // Claims twist authority while any movement key is held.
+  isActive() {
+    return this.#held.size > 0;
+  }
+
+  // The command is event-driven (recomputed on keydown/keyup/blur, so a
+  // press lands the same tick, not on the next frame); poll only re-maps
+  // held keys onto fresh velocity limits after a locomotion switch.
+  poll() {
+    const [limF, limB, limA] = this.#getVelocityLimits();
+    if (limF !== this.#lims[0] || limB !== this.#lims[1] || limA !== this.#lims[2]) {
+      this.#refresh();
+    }
+  }
+
+  #refresh() {
+    const lims = this.#getVelocityLimits();
+    const [limF, limB, limA] = lims;
+    this.#lims = lims;
+    const held = this.#held;
+    this.command[0] = held.has("fwd") ? limF : held.has("back") ? limB : 0;
+    this.command[2] = held.has("turnl") ? limA : held.has("turnr") ? -limA : 0;
+    this.pressed.fwd = held.has("fwd");
+    this.pressed.back = held.has("back");
+    this.pressed.turnl = held.has("turnl");
+    this.pressed.turnr = held.has("turnr");
+  }
+}

fx/demo-glitch.html

@@ -0,0 +1,140 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>fx demo - glitch materialization</title>
+    <style>
+      html, body { margin: 0; height: 100%; background: #0b0d10; overflow: hidden; }
+      #app { position: fixed; inset: 0; }
+      #replay {
+        position: fixed; top: 16px; left: 16px; z-index: 10;
+        font: 700 13px/1 "SF Mono", ui-monospace, Menlo, monospace;
+        letter-spacing: 0.14em;
+        color: #ff7a2f; background: rgba(11, 13, 16, 0.85);
+        border: 1px solid #ff7a2f; border-radius: 4px;
+        padding: 10px 18px; cursor: pointer;
+        text-shadow: 0 0 8px rgba(255, 122, 47, 0.5);
+      }
+      #replay:hover { background: rgba(255, 122, 47, 0.15); box-shadow: 0 0 14px rgba(255, 122, 47, 0.35); }
+      #replay:active { transform: translateY(1px); }
+      #status {
+        position: fixed; bottom: 14px; left: 16px; z-index: 10;
+        font: 11px/1.4 ui-monospace, Menlo, monospace;
+        color: #3d4652; letter-spacing: 0.08em; user-select: none;
+      }
+    </style>
+    <script type="importmap">
+      {
+        "imports": {
+          "three": "https://cdn.jsdelivr.net/npm/three@0.164.1/build/three.module.js",
+          "three/addons/": "https://cdn.jsdelivr.net/npm/three@0.164.1/examples/jsm/"
+        }
+      }
+    </script>
+  </head>
+  <body>
+    <div id="app"></div>
+    <button id="replay" type="button" aria-label="Replay the glitch materialization">REPLAY</button>
+    <div id="status">loading rig...</div>
+    <script type="module">
+      import * as THREE from "three";
+      import { OrbitControls } from "three/addons/controls/OrbitControls.js";
+      import { RoomEnvironment } from "three/addons/environments/RoomEnvironment.js";
+      import { loadKinematics, buildRig, groundFullBody } from "../duck.js";
+      import { VARIANTS, materialHookFor } from "../variants.js";
+      import * as fx from "./fx-glitch.js";
+
+      const mount = document.getElementById("app");
+      const statusEl = document.getElementById("status");
+
+      const scene = new THREE.Scene();
+      scene.background = new THREE.Color(0x0b0d10);
+
+      const camera = new THREE.PerspectiveCamera(40, 1, 0.02, 30);
+      camera.position.set(0.42, 0.22, 0.5);
+
+      const renderer = new THREE.WebGLRenderer({ antialias: true });
+      renderer.setPixelRatio(Math.min(2, window.devicePixelRatio));
+      renderer.toneMapping = THREE.ACESFilmicToneMapping;
+      mount.appendChild(renderer.domElement);
+
+      const pmrem = new THREE.PMREMGenerator(renderer);
+      scene.environment = pmrem.fromScene(new RoomEnvironment()).texture;
+      scene.environmentIntensity = 0.45;
+
+      // Same light rig as the live playground.
+      scene.add(new THREE.AmbientLight(0xffffff, 0.6));
+      const keyLight = new THREE.DirectionalLight(0xffffff, 1.6);
+      keyLight.position.set(2, 4, 2);
+      scene.add(keyLight);
+      const fill = new THREE.DirectionalLight(0xffffff, 0.4);
+      fill.position.set(-2, 2, 1.5);
+      scene.add(fill);
+      const rim = new THREE.DirectionalLight(0xffb366, 0.7);
+      rim.position.set(0, 3, -2);
+      scene.add(rim);
+
+      // Ground: dark disc + faint grid.
+      const ground = new THREE.Mesh(
+        new THREE.CircleGeometry(1.4, 64).rotateX(-Math.PI / 2),
+        new THREE.MeshStandardMaterial({ color: 0x11141a, roughness: 0.95, metalness: 0 }),
+      );
+      scene.add(ground);
+      const grid = new THREE.GridHelper(2.4, 48, 0x232a33, 0x161b22);
+      grid.position.y = 0.001;
+      scene.add(grid);
+
+      const controls = new OrbitControls(camera, renderer.domElement);
+      controls.enableDamping = true;
+      controls.target.set(0, 0.1, 0);
+      controls.minDistance = 0.15;
+      controls.maxDistance = 3;
+
+      function resize() {
+        const w = mount.clientWidth, h = mount.clientHeight;
+        camera.aspect = w / h;
+        camera.updateProjectionMatrix();
+        renderer.setSize(w, h);
+      }
+      window.addEventListener("resize", resize);
+      resize();
+
+      // ── Isolated duck rig (classic variant, standing pose) ────────────
+      // MODEL_DIR is page-relative ("./robot/mjlab") and resolves wrong from
+      // /fx/; mesh_dir inside the JSON is root-absolute so only this differs.
+      const k = await loadKinematics("../robot/mjlab/kinematics.json");
+      const rig = await buildRig(k, { materialForMesh: materialHookFor(VARIANTS.classic) });
+      groundFullBody(rig, 0);
+      scene.add(rig.placer);
+
+      // Aim the camera at the duck's actual center.
+      const box = new THREE.Box3().setFromObject(rig.placer);
+      const center = box.getCenter(new THREE.Vector3());
+      controls.target.copy(center);
+
+      fx.init({ THREE, scene, rig, camera, renderer });
+      statusEl.textContent = `fx: ${fx.name} | drag to orbit`;
+
+      document.getElementById("replay").addEventListener("click", () => fx.start());
+
+      // Debug hook for deterministic mid-effect screenshots.
+      window.fx = {
+        start: () => fx.start(),
+        setProgress: (p) => fx.setProgress(p),
+        isDone: () => fx.isDone(),
+      };
+
+      const clock = new THREE.Clock();
+      renderer.setAnimationLoop(() => {
+        const dt = Math.min(0.05, clock.getDelta());
+        fx.update(dt, clock.elapsedTime);
+        controls.update();
+        renderer.render(scene, camera);
+      });
+
+      // Auto-play once everything is loaded.
+      setTimeout(() => fx.start(), 500);
+    </script>
+  </body>
+</html>

fx/demo-wireframe.html

@@ -0,0 +1,113 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>FX demo - holographic wireframe scan-up</title>
+  <style>
+    html, body { margin: 0; height: 100%; background: #0b0d10; overflow: hidden; }
+    #app { position: fixed; inset: 0; }
+    #hud {
+      position: fixed; top: 14px; left: 14px; z-index: 10;
+      font: 12px/1.4 ui-monospace, SFMono-Regular, Menlo, monospace;
+      color: #ff7a2f; user-select: none;
+    }
+    #replay {
+      margin-top: 8px; padding: 7px 18px; cursor: pointer;
+      font: 600 12px ui-monospace, SFMono-Regular, Menlo, monospace;
+      letter-spacing: 0.12em; color: #ff7a2f;
+      background: rgba(255, 122, 47, 0.08);
+      border: 1px solid rgba(255, 122, 47, 0.55); border-radius: 4px;
+    }
+    #replay:hover { background: rgba(255, 122, 47, 0.2); }
+  </style>
+  <script type="importmap">
+    {
+      "imports": {
+        "three": "https://cdn.jsdelivr.net/npm/three@0.164.1/build/three.module.js",
+        "three/addons/": "https://cdn.jsdelivr.net/npm/three@0.164.1/examples/jsm/"
+      }
+    }
+  </script>
+</head>
+<body>
+  <div id="app"></div>
+  <div id="hud">
+    FX: HOLOGRAPHIC WIREFRAME SCAN-UP<br />
+    <button id="replay">REPLAY</button>
+  </div>
+  <script type="module">
+    import * as THREE from "three";
+    import { OrbitControls } from "three/addons/controls/OrbitControls.js";
+    import { loadKinematics, buildRig, groundFullBody } from "../duck.js";
+    import { VARIANTS, materialHookFor } from "../variants.js";
+    import * as fx from "./fx-wireframe.js";
+
+    const mount = document.getElementById("app");
+
+    const scene = new THREE.Scene();
+    scene.background = new THREE.Color(0x0b0d10);
+
+    const camera = new THREE.PerspectiveCamera(40, 1, 0.02, 30);
+    const renderer = new THREE.WebGLRenderer({ antialias: true });
+    renderer.setPixelRatio(Math.min(2, window.devicePixelRatio));
+    renderer.toneMapping = THREE.ACESFilmicToneMapping;
+    mount.appendChild(renderer.domElement);
+
+    // Same light rig as the live app so materials read identically.
+    scene.add(new THREE.AmbientLight(0xffffff, 0.6));
+    const keyLight = new THREE.DirectionalLight(0xffffff, 1.6);
+    keyLight.position.set(2, 4, 2);
+    scene.add(keyLight);
+    const fill = new THREE.DirectionalLight(0xffffff, 0.4);
+    fill.position.set(-2, 2, 1.5);
+    scene.add(fill);
+    const rim = new THREE.DirectionalLight(0xffb366, 0.7);
+    rim.position.set(0, 3, -2);
+    scene.add(rim);
+
+    const grid = new THREE.GridHelper(2, 40, 0x232c3a, 0x151a22);
+    scene.add(grid);
+
+    const resize = () => {
+      const w = mount.clientWidth, h = mount.clientHeight;
+      camera.aspect = w / h;
+      camera.updateProjectionMatrix();
+      renderer.setSize(w, h);
+    };
+    window.addEventListener("resize", resize);
+    resize();
+
+    // Isolated duck rig, classic colourway.
+    const k = await loadKinematics("/robot/mjlab/kinematics.json");
+    const rig = await buildRig(k, { materialForMesh: materialHookFor(VARIANTS.classic) });
+    groundFullBody(rig);
+    scene.add(rig.placer);
+
+    // Frame the duck.
+    rig.placer.updateWorldMatrix(true, true);
+    const box = new THREE.Box3().setFromObject(rig.placer);
+    const center = box.getCenter(new THREE.Vector3());
+    const size = box.getSize(new THREE.Vector3()).length();
+    camera.position.set(center.x + size * 1.5, center.y + size * 0.85, center.z + size * 1.9);
+    const controls = new OrbitControls(camera, renderer.domElement);
+    controls.target.copy(center);
+    controls.enableDamping = true;
+    controls.update();
+
+    fx.init({ THREE, scene, rig, camera, renderer });
+    fx.start();
+    window.fx = fx; // fx.setProgress(p) for deterministic captures
+
+    document.getElementById("replay").addEventListener("click", () => fx.start());
+
+    const clock = new THREE.Clock();
+    renderer.setAnimationLoop(() => {
+      const dt = Math.min(clock.getDelta(), 0.05);
+      fx.update(dt, clock.elapsedTime);
+      controls.update();
+      renderer.render(scene, camera);
+    });
+  </script>
+</body>
+</html>

fx/fx-glitch.js

@@ -0,0 +1,311 @@
+// Cyberpunk 2077-style glitch materialization for the Microduck rig.
+//
+// The duck appears as stacked horizontal slices that flicker in and out
+// with random screen-space horizontal offsets, converging to their true
+// position. Chromatic aberration is faked with two additive silhouette
+// ghosts (cyan / orange) offset left-right, digital noise blocks flash
+// emissive or invert the surface colour, and a final warm flash "snaps"
+// everything crisp.
+//
+// Implementation: onBeforeCompile injections on CACHED clones of the rig
+// materials (same pattern and same program-cache trap as the entrance
+// dissolve in rl.js: clones are cached per original material and reused
+// on every replay, each with a unique customProgramCacheKey, otherwise
+// three.js would reuse a compiled program without re-binding uniforms).
+// All uniforms are shared singleton objects so one JS write per frame
+// drives every material.
+
+export const name = "glitch";
+
+const DURATION = 1.15; // seconds
+const TICK_HZ = 30; // discrete glitch update rate (digital feel)
+const SLICES = 24;
+
+// ── Shared uniforms (one instance drives all cloned materials) ──────────
+const uP = { value: 0 }; // progress 0..1 (0 = invisible)
+const uSeed = { value: 0 }; // discrete tick, drives all hashes
+const uAmp = { value: 0 }; // slice offset amplitude (view-space meters)
+const uFlash = { value: 0 }; // final snap flash intensity
+const uGhostOff = { value: 0 }; // RGB-split ghost separation (meters)
+const uB = { value: null }; // vec4(minY, height, sliceH, 0) world bounds
+
+let T = null; // injected THREE namespace
+let rigRef = null;
+let playing = false;
+let scrubbed = false;
+let done = true;
+let elapsed = 0;
+
+// Deterministic JS-side hash, mirrors the GLSL one.
+const jhash = (n) => {
+  const s = Math.sin(n * 127.1 + 311.7) * 43758.5453;
+  return s - Math.floor(s);
+};
+
+// ── GLSL injection ──────────────────────────────────────────────────────
+const GLSL_HELPERS = /* glsl */ `
+varying vec3 vGlW;
+uniform float uGlP, uGlSeed;
+uniform vec4 uGlB;
+float glHash2(vec2 q) { return fract(sin(dot(q, vec2(127.1, 311.7))) * 43758.5453); }
+vec3 glHash3(vec2 q) { return vec3(glHash2(q), glHash2(q + 17.17), glHash2(q + 31.3)); }
+`;
+
+function injectGlitch(shader, { signU = null, ghost = false } = {}) {
+  shader.uniforms.uGlP = uP;
+  shader.uniforms.uGlSeed = uSeed;
+  shader.uniforms.uGlAmp = uAmp;
+  shader.uniforms.uGlFlash = uFlash;
+  shader.uniforms.uGlGhostOff = uGhostOff;
+  shader.uniforms.uGlSign = signU ?? { value: 0 };
+  shader.uniforms.uGlB = uB;
+
+  shader.vertexShader = shader.vertexShader
+    .replace(
+      "#include <common>",
+      "#include <common>\n" + GLSL_HELPERS + "uniform float uGlAmp, uGlSign, uGlGhostOff;\n",
+    )
+    .replace(
+      "#include <project_vertex>",
+      /* glsl */ `#include <project_vertex>
+vec4 glWp = modelMatrix * vec4(transformed, 1.0);
+vGlW = glWp.xyz;
+if (uGlP < 1.0) {
+  float glSid = floor((glWp.y - uGlB.x) / uGlB.z);
+  // Fraction of moving slices shrinks as p rises: convergence.
+  float glMove = step(0.25 + 0.62 * uGlP, glHash2(vec2(glSid * 1.71 + 4.2, uGlSeed + 13.0)));
+  float glOff = (glHash2(vec2(glSid, uGlSeed)) - 0.5) * 2.0 * uGlAmp * glMove;
+  // Occasional whole-body frame jump for one tick.
+  if (glHash2(vec2(uGlSeed, 3.17)) > 0.86) {
+    glOff += (glHash2(vec2(uGlSeed, 9.91)) - 0.5) * 3.0 * uGlAmp;
+  }
+  glOff += uGlSign * uGlGhostOff;
+  // View-space X = screen-horizontal, the classic spawn-glitch axis.
+  mvPosition.x += glOff;
+  gl_Position = projectionMatrix * mvPosition;
+}`,
+    );
+
+  const sliceDiscard = /* glsl */ `
+float glEdge = 0.0, glInvAmt = 0.0;
+vec3 glAddC = vec3(0.0);
+if (uGlP < 1.0) {
+  float glSid = floor((vGlW.y - uGlB.x) / uGlB.z);
+  float glH = glHash2(vec2(glSid, uGlSeed + 0.7));
+  float glVis = smoothstep(0.02, 0.82, uGlP) * 1.35;
+  // Two-three full-silhouette pre-flashes right at the start.
+  float glPre = (uGlP > 0.015 && uGlP < 0.14 && glHash2(vec2(uGlSeed, 7.7)) > 0.72) ? 1.0 : 0.0;
+  glVis = max(glVis, glPre);
+  if (glH > glVis) discard;
+  glEdge = max(glPre * 0.7, (1.0 - smoothstep(0.0, 0.3, glVis - glH)) * (1.0 - uGlP));
+${ghost ? "" : /* glsl */ `
+  // Digital noise blocks: world-space rectangular patches, re-seeded per
+  // tick. Some invert the surface colour, most flash emissive.
+  vec2 glBq = floor((vGlW.xy + vec2(vGlW.z * 0.7, vGlW.z * 0.3)) * 52.0
+                    + vec2(uGlSeed * 0.373, uGlSeed * 0.719));
+  vec3 glBh = glHash3(glBq + uGlSeed);
+  float glBGate = (1.0 - uGlP) * 0.16;
+  if (glBh.x > 1.0 - glBGate) {
+    if (glBh.y < 0.3) glInvAmt = 1.0;
+    else glAddC += (glBh.z < 0.6 ? vec3(0.15, 1.3, 1.5)
+                  : (glBh.z < 0.85 ? vec3(1.4) : vec3(1.6, 0.5, 0.06))) * (0.7 + glBh.y);
+  }
+  // Faint rolling scanline shimmer.
+  glAddC += vec3(0.05, 0.3, 0.35) * (1.0 - uGlP) * 0.18
+            * step(0.6, fract(vGlW.y * 150.0 - uGlSeed * 0.21));
+`}
+}`;
+
+  const emissiveOut = ghost
+    ? "" // ghosts are pre-tinted additive silhouettes, no extra emissive
+    : /* glsl */ `
+gl_FragColor.rgb = mix(gl_FragColor.rgb, vec3(1.1) - gl_FragColor.rgb, glInvAmt);
+gl_FragColor.rgb += glAddC;
+gl_FragColor.rgb += glEdge * vec3(0.25, 1.15, 1.35);
+gl_FragColor.rgb += uGlFlash * vec3(1.25, 0.7, 0.35);`;
+
+  shader.fragmentShader = shader.fragmentShader
+    .replace(
+      "#include <common>",
+      "#include <common>\n" + GLSL_HELPERS + "uniform float uGlFlash;\n",
+    )
+    .replace("#include <clipping_planes_fragment>", "#include <clipping_planes_fragment>" + sliceDiscard)
+    .replace("#include <dithering_fragment>", "#include <dithering_fragment>" + emissiveOut);
+}
+
+// ── Material clones (cached, never disposed between replays) ────────────
+const clones = new Map(); // original material uuid -> glitch clone
+let cloneNonce = 0;
+let saved = null; // Array<[mesh, originalMat, cloneMat]> while active
+
+function cloneFor(orig) {
+  let m = clones.get(orig.uuid);
+  if (m) return m;
+  m = orig.clone();
+  m.onBeforeCompile = (shader) => injectGlitch(shader);
+  const key = `microduck-glitch-${cloneNonce++}`;
+  m.customProgramCacheKey = () => key;
+  m.needsUpdate = true;
+  clones.set(orig.uuid, m);
+  return m;
+}
+
+function applyGlitchMats() {
+  if (saved) return;
+  saved = [];
+  rigRef.placer.traverse((o) => {
+    if (!o.isMesh || o.userData.glGhost) return;
+    const orig = o.material;
+    const m = cloneFor(orig);
+    saved.push([o, orig, m]);
+    o.material = m;
+  });
+}
+
+function restoreMats() {
+  if (!saved) return;
+  for (const [mesh, orig, clone] of saved) {
+    if (mesh.material === clone) mesh.material = orig;
+  }
+  saved = null;
+}
+
+// ── RGB-split ghosts ────────────────────────────────────────────────────
+// Two additive unlit silhouette copies of every rig mesh (cyan right,
+// orange left), sharing the slice-discard shader so their outline always
+// matches the sliced duck. Added as children of each mesh: they inherit
+// the full kinematic transform for free.
+let ghostMats = [];
+let ghostMeshes = [];
+
+function makeGhostMat(r, g, b, sign) {
+  const m = new T.MeshBasicMaterial({
+    transparent: true,
+    opacity: 0,
+    depthWrite: false,
+    blending: T.AdditiveBlending,
+  });
+  m.color.setRGB(r, g, b);
+  const signU = { value: sign };
+  m.onBeforeCompile = (shader) => injectGlitch(shader, { signU, ghost: true });
+  m.customProgramCacheKey = () => `microduck-glitch-ghost-${sign > 0 ? "r" : "l"}`;
+  return m;
+}
+
+function buildGhosts() {
+  ghostMats = [makeGhostMat(0.0, 1.1, 1.3, +1), makeGhostMat(1.3, 0.35, 0.02, -1)];
+  const hosts = [];
+  rigRef.placer.traverse((o) => {
+    if (o.isMesh && !o.userData.glGhost) hosts.push(o);
+  });
+  for (const mesh of hosts) {
+    for (const mat of ghostMats) {
+      const gm = new T.Mesh(mesh.geometry, mat);
+      gm.userData.glGhost = true;
+      gm.renderOrder = 2;
+      gm.frustumCulled = false;
+      gm.visible = false;
+      mesh.add(gm);
+      ghostMeshes.push(gm);
+    }
+  }
+}
+
+function setGhostsVisible(v) {
+  for (const gm of ghostMeshes) gm.visible = v;
+}
+
+// ── Deterministic per-progress uniform state ────────────────────────────
+// Everything derives from p alone (tick included), so setProgress(p) gives
+// reproducible frames for debugging/screenshots.
+function setUniformsFor(p) {
+  uP.value = p;
+  const tick = Math.floor(p * DURATION * TICK_HZ);
+  uSeed.value = tick;
+  const h = uB.value.y; // duck height
+  const gate = 0.35 + 0.65 * jhash(tick + 3.7);
+  uAmp.value = p < 0.92 ? h * 0.3 * Math.pow(1 - p, 1.3) * gate : 0;
+  uGhostOff.value =
+    p > 0.04 && p < 0.9 ? (0.06 + 0.3 * jhash(tick + 11.1)) * (1 - p) * h : 0;
+  uFlash.value = p > 0.86 ? 1.5 * Math.exp(-16 * (p - 0.86) * DURATION) : 0;
+  const ghostOp =
+    p > 0.04 && p < 0.9 ? (0.05 + 0.32 * (1 - p)) * (0.4 + 0.6 * jhash(tick + 5.5)) : 0;
+  for (const m of ghostMats) m.opacity = ghostOp;
+}
+
+function finish() {
+  uP.value = 1;
+  uFlash.value = 0;
+  setGhostsVisible(false);
+  restoreMats();
+  playing = false;
+  done = true;
+}
+
+// ── Public interface ────────────────────────────────────────────────────
+export function init({ THREE, scene, rig, camera, renderer }) {
+  T = THREE;
+  rigRef = rig;
+  rig.placer.updateWorldMatrix(true, true);
+  const box = new T.Box3().setFromObject(rig.placer);
+  const minY = box.min.y;
+  const height = Math.max(1e-3, box.max.y - minY);
+  uB.value = new T.Vector4(minY, height, height / SLICES, 0);
+  buildGhosts();
+  // Duck starts invisible: p=0 discards every fragment.
+  uP.value = 0;
+  applyGlitchMats();
+  done = true;
+  playing = false;
+}
+
+export function start() {
+  applyGlitchMats();
+  setGhostsVisible(true);
+  elapsed = 0;
+  playing = true;
+  scrubbed = false;
+  done = false;
+  setUniformsFor(0);
+}
+
+export function update(dt, t) {
+  if (!playing || scrubbed) return;
+  elapsed += dt;
+  const p = Math.min(1, elapsed / DURATION);
+  setUniformsFor(p);
+  if (p >= 1) finish();
+}
+
+export function isDone() {
+  return done;
+}
+
+export function dispose() {
+  restoreMats();
+  for (const gm of ghostMeshes) gm.parent?.remove(gm);
+  ghostMeshes = [];
+  for (const m of ghostMats) m.dispose();
+  ghostMats = [];
+  for (const m of clones.values()) m.dispose();
+  clones.clear();
+  playing = false;
+  done = true;
+  rigRef = null;
+}
+
+// Debug hook: freeze the effect at an exact progress value (deterministic,
+// used by the demo page for mid-effect screenshots). start() resumes
+// normal playback.
+export function setProgress(p) {
+  scrubbed = true;
+  if (p >= 1) {
+    finish();
+    return;
+  }
+  playing = true;
+  done = false;
+  applyGlitchMats();
+  setGhostsVisible(true);
+  setUniformsFor(Math.max(0, p));
+}

fx/fx-wireframe.js

@@ -0,0 +1,320 @@
+// Holographic wireframe scan-up materialization effect.
+//
+// Sequence (~0.9 s, reversible):
+//   1. An invisible scan height rises from the floor through the target;
+//      the boundary reads on the surface itself (bright wireframe band
+//      right under the scan height - no standalone disc geometry).
+//   2. Below the scan line the target shows as a flickering additive
+//      wireframe hologram (scanline stripes, brightness boost near the
+//      scan line).
+//   3. A second, fainter "solidify" line trails behind: fragments below
+//      it render the real PBR materials (world-Y clip injected via
+//      onBeforeCompile), with a hot edge right at the line. Once it
+//      clears the top the original materials are restored directly.
+//
+// Played backwards, the same timeline de-materializes (solid peel ->
+// hologram -> gone). Used for the ball despawn; the duck only ever
+// materializes.
+//
+// createWireframeFx() returns an independent instance (duck and ball
+// scan at the same time without sharing uniforms). The module-level
+// named exports wrap a singleton so demo-wireframe.html is unchanged.
+//
+// Instance interface:
+//   init({ THREE, scene, rig | root, camera, renderer, hidden? })
+//   start() / startReverse() / update(dt) / isDone() / restore() / dispose()
+// Extra: setProgress(p), playing, reversing, TOTAL_S.
+
+export const name = "wireframe";
+
+// ── Timeline (seconds) ──────────────────────────────────────────────────
+const SCAN_S = 0.6; // wireframe scan line: floor -> top
+const SOLID_DELAY_S = 0.3; // solidify line starts this long after the scan
+const SOLID_S = 0.6; // solidify line: floor -> top
+export const TOTAL_S = SOLID_DELAY_S + SOLID_S; // 0.9
+
+const clamp01 = (x) => Math.min(Math.max(x, 0), 1);
+// Ease-out only: the rise starts at full speed the instant the scan cues
+// (a smoothstep ease-in reads as a stall near the feet) and lands softly.
+const ease = (x) => 1 - (1 - x) * (1 - x);
+
+// Deterministic pseudo-random flicker so setProgress(p) captures are
+// reproducible (no Math.random).
+const hash = (x) => {
+  const s = Math.sin(x * 127.1) * 43758.5453;
+  return s - Math.floor(s);
+};
+const flickerAt = (time) => {
+  let f = 0.82 + 0.18 * hash(Math.floor(time * 60) + 0.5);
+  if (hash(Math.floor(time * 24) + 7.7) < 0.12) f *= 0.5; // dropouts
+  return f;
+};
+
+// Unique customProgramCacheKey values across every instance: a fresh
+// clone of the same source material would otherwise reuse the compiled
+// program without re-running onBeforeCompile, leaving clip uniforms
+// unbound (see the dissolve comment in rl.js).
+let clipNonce = 0;
+
+const BOTTOM_PAD = 0.025;
+
+export function createWireframeFx() {
+  // Per-instance uniforms: duck and ball must not share a scan height.
+  const uScanY = { value: -1e3 };
+  const uSolidY = { value: -1e3 };
+  const uFlicker = { value: 1 };
+  const uTime = { value: 0 };
+
+  let ctx = null; // { THREE, scene, root, camera, renderer }
+  let t = 0;
+  let dir = 1; // +1 materialize, -1 dematerialize
+  let playing = false;
+  let finished = false;
+
+  let minY = 0;
+  let spanY = 0.3;
+
+  const clipClones = new Map();
+  let clipSaved = null; // Array<[mesh, originalMat, cloneMat]> while active
+
+  let wireMat = null;
+  let wireMeshes = [];
+
+  const isTargetMesh = (o) => o.isMesh && !o.userData.fxOverlay;
+
+  function clipCloneFor(orig) {
+    let m = clipClones.get(orig.uuid);
+    if (m) return m;
+    m = orig.clone();
+    m.onBeforeCompile = (shader) => {
+      shader.uniforms.uFxSolidY = uSolidY;
+      shader.vertexShader = shader.vertexShader
+        .replace("#include <common>", "#include <common>\nvarying vec3 vFxW;")
+        .replace(
+          "#include <worldpos_vertex>",
+          "#include <worldpos_vertex>\nvFxW = (modelMatrix * vec4(transformed, 1.0)).xyz;",
+        );
+      shader.fragmentShader = shader.fragmentShader
+        .replace(
+          "#include <common>",
+          "#include <common>\nvarying vec3 vFxW;\nuniform float uFxSolidY;",
+        )
+        .replace(
+          "#include <clipping_planes_fragment>",
+          /* glsl */ `#include <clipping_planes_fragment>
+float fxEdge = 0.0;
+if (vFxW.y > uFxSolidY) discard;
+fxEdge = 1.0 - smoothstep(0.002, 0.018, uFxSolidY - vFxW.y);`,
+        )
+        .replace(
+          "#include <dithering_fragment>",
+          /* glsl */ `#include <dithering_fragment>
+gl_FragColor.rgb += fxEdge * vec3(0.95, 0.32, 0.05);`,
+        );
+    };
+    const key = `microduck-fx-wireframe-${clipNonce++}`;
+    m.customProgramCacheKey = () => key;
+    m.needsUpdate = true;
+    clipClones.set(orig.uuid, m);
+    return m;
+  }
+
+  function applyClipMaterials() {
+    if (clipSaved) return;
+    clipSaved = [];
+    ctx.root.traverse((o) => {
+      if (!isTargetMesh(o)) return;
+      const orig = o.material;
+      const clone = clipCloneFor(orig);
+      clipSaved.push([o, orig, clone]);
+      o.material = clone;
+    });
+  }
+
+  function restoreClipMaterials() {
+    if (!clipSaved) return;
+    for (const [mesh, orig, clone] of clipSaved) {
+      if (mesh.material === clone) mesh.material = orig;
+    }
+    clipSaved = null;
+  }
+
+  function makeWireMaterial(THREE) {
+    return new THREE.ShaderMaterial({
+      uniforms: { uScanY, uSolidY, uFlicker, uTime },
+      vertexShader: /* glsl */ `
+        varying vec3 vW;
+        void main() {
+          vec4 wp = modelMatrix * vec4(position, 1.0);
+          vW = wp.xyz;
+          gl_Position = projectionMatrix * viewMatrix * wp;
+        }`,
+      fragmentShader: /* glsl */ `
+        uniform float uScanY, uSolidY, uFlicker, uTime;
+        varying vec3 vW;
+        void main() {
+          if (vW.y > uScanY || vW.y < uSolidY) discard;
+          float lead = 1.0 - smoothstep(0.0, 0.06, uScanY - vW.y);
+          float tail = smoothstep(0.0, 0.018, vW.y - uSolidY);
+          float stripes = 0.7 + 0.3 * sin(vW.y * 900.0 - uTime * 45.0);
+          vec3 c = vec3(1.0, 0.34, 0.06) * (0.55 + 1.6 * lead);
+          float a = (0.10 + 0.40 * lead) * stripes * tail * uFlicker;
+          gl_FragColor = vec4(c, a);
+        }`,
+      wireframe: true,
+      transparent: true,
+      blending: THREE.AdditiveBlending,
+      depthWrite: false,
+      depthTest: true,
+    });
+  }
+
+  function buildWireOverlays(THREE, root) {
+    wireMat = makeWireMaterial(THREE);
+    root.traverse((o) => {
+      if (!isTargetMesh(o)) return;
+      // Child of the source mesh with identity transform so the overlay
+      // follows whatever pose the caller writes (duck joints or ball qpos).
+      const w = new THREE.Mesh(o.geometry, wireMat);
+      w.userData.fxOverlay = true;
+      w.renderOrder = 5;
+      w.visible = false;
+      o.add(w);
+      wireMeshes.push(w);
+    });
+  }
+
+  function applyAt(time) {
+    const scanP = ease(clamp01(time / SCAN_S));
+    const solidP = ease(clamp01((time - SOLID_DELAY_S) / SOLID_S));
+    uFlicker.value = flickerAt(time);
+    uTime.value = time;
+
+    const jitter = scanP > 0 && scanP < 1 ? (hash(time * 41.3) - 0.5) * 0.02 * spanY : 0;
+    uScanY.value = minY + spanY * scanP + jitter;
+    uSolidY.value = minY + spanY * solidP;
+
+    const wiresOn = time > 0 && solidP < 1;
+    for (const w of wireMeshes) w.visible = wiresOn;
+  }
+
+  function finish() {
+    // Forward: restore the real materials (fully solid). Reverse: leave
+    // the clip parked at t=0 (fully hidden) so restoring wouldn't flash
+    // the solid mesh for a frame; the caller hides the object then
+    // restore()s.
+    if (dir > 0) restoreClipMaterials();
+    else applyAt(0);
+    for (const w of wireMeshes) w.visible = false;
+    finished = true;
+    playing = false;
+  }
+
+  function computeRange() {
+    const { THREE, root } = ctx;
+    root.updateWorldMatrix(true, true);
+    const box = new THREE.Box3().setFromObject(root);
+    minY = Math.min(box.min.y, 0) - BOTTOM_PAD;
+    spanY = Math.max(box.max.y - minY, 0.04) * 1.06;
+  }
+
+  function arm(nextDir, resetT) {
+    dir = nextDir;
+    if (resetT) t = nextDir > 0 ? 0 : TOTAL_S;
+    finished = false;
+    computeRange();
+    applyClipMaterials();
+    applyAt(t);
+    playing = true;
+  }
+
+  function init({ THREE, scene, rig, root, camera, renderer, hidden = true }) {
+    const target = root ?? rig.placer;
+    ctx = { THREE, scene, root: target, camera, renderer };
+    computeRange();
+    buildWireOverlays(THREE, target);
+    t = 0;
+    dir = 1;
+    finished = false;
+    playing = false;
+    if (hidden) {
+      applyClipMaterials();
+      applyAt(0);
+    }
+  }
+
+  function start() {
+    // Mid-reverse: keep the current t and turn around. Fresh play: from 0.
+    arm(1, !playing);
+  }
+
+  function startReverse() {
+    arm(-1, !playing);
+  }
+
+  function update(dt) {
+    if (!playing || finished) return;
+    t += dir * dt;
+    if (dir > 0 && t >= TOTAL_S) {
+      t = TOTAL_S;
+      applyAt(t);
+      finish();
+      return;
+    }
+    if (dir < 0 && t <= 0) {
+      t = 0;
+      applyAt(t);
+      finish();
+      return;
+    }
+    applyAt(t);
+  }
+
+  function isDone() {
+    return finished;
+  }
+
+  function setProgress(p) {
+    playing = false;
+    finished = false;
+    dir = 1;
+    computeRange();
+    applyClipMaterials();
+    t = clamp01(p) * TOTAL_S;
+    applyAt(t);
+  }
+
+  function restore() {
+    restoreClipMaterials();
+  }
+
+  function dispose() {
+    restoreClipMaterials();
+    for (const w of wireMeshes) w.parent?.remove(w);
+    wireMeshes = [];
+    wireMat?.dispose();
+    wireMat = null;
+    ctx = null;
+    playing = false;
+    finished = false;
+  }
+
+  return {
+    init, start, startReverse, update, isDone, setProgress, restore, dispose,
+    get playing() { return playing; },
+    get reversing() { return playing && dir < 0; },
+    TOTAL_S,
+  };
+}
+
+// Singleton for the duck (and the isolated demo page). New callers that
+// need a second scan (the ball) go through createWireframeFx().
+const singleton = createWireframeFx();
+export const init = (...a) => singleton.init(...a);
+export const start = (...a) => singleton.start(...a);
+export const startReverse = (...a) => singleton.startReverse(...a);
+export const update = (...a) => singleton.update(...a);
+export const isDone = (...a) => singleton.isDone(...a);
+export const setProgress = (...a) => singleton.setProgress(...a);
+export const restore = (...a) => singleton.restore(...a);
+export const dispose = (...a) => singleton.dispose(...a);

ghosts.js

@@ -2,7 +2,7 @@
 // duck state over WebRTC and renders the other visitors as translucent
 // ducks. There is no backend - this is a static Space - so peer discovery
 // uses Trystero's serverless signaling over public Nostr relays. Payloads
-// are tiny (22 floats + a variant name at 10 Hz), and at most MAX_GHOSTS
+// are tiny (22 floats + a variant name at SEND_HZ), and at most MAX_GHOSTS
 // ghosts are instantiated regardless of how many peers are in the room.
 //
 // This module deliberately imports nothing from duck.js / variants.js:
@@ -13,14 +13,39 @@ const TRYSTERO_URL = "https://esm.run/trystero@0.25.3/nostr";
 const APP_ID = "microduck-sandbox";
 const ROOM = "lobby";
 const MAX_GHOSTS = 3;
-const SEND_HZ = 10;
+const SEND_HZ = 15;
 const GHOST_OPACITY = 0.35;
-// Per-frame easing toward the last received state (10 Hz updates, ~60 fps
-// rendering): position/joints converge in ~4 frames, fast but smooth.
-const EASE = 0.25;
+// Snapshot interpolation: each ghost renders INTERP_DELAY_MS in the past,
+// lerping between the two buffered snapshots that bracket the render time
+// (timed by local ARRIVAL, so no clock sync and no payload change - old
+// clients interoperate). This replaces the old exponential chase toward
+// the latest packet, whose move-then-stall rhythm read as micro-stutter.
+// The delay absorbs network jitter; past the newest snapshot the ghost
+// holds pose, so a background-throttled 1 Hz sender degrades into slow
+// discrete steps instead of teleports. Nobody synchronizes on ghosts, so
+// the added latency is invisible.
+const INTERP_DELAY_MS = 150;
+const BUF_MAX = 40; // snapshots kept per ghost (~2.5 s at 15 Hz)
+// Idle visitors stay invisible: a ghost is only shown once its peer has
+// strayed from the pose of its first state message (everyone spawns at
+// the arena center). Once revealed it stays visible for the whole peer
+// session, so a reset teleporting the duck back to center doesn't blink
+// the ghost out.
+const REVEAL_DIST = 0.2; // m, horizontal distance from spawn
+const REVEAL_YAW = 0.4; // rad (~23deg), turning in place also reveals
+
+// state.p is raw MuJoCo qpos[0..6]: [x, y, z, qw, qx, qy, qz], Z-up.
+const yawOf = (p) =>
+  Math.atan2(2 * (p[3] * p[6] + p[4] * p[5]), 1 - 2 * (p[5] * p[5] + p[6] * p[6]));
+const hasMoved = (spawn, p) => {
+  const dx = p[0] - spawn.x, dy = p[1] - spawn.y;
+  if (dx * dx + dy * dy > REVEAL_DIST * REVEAL_DIST) return true;
+  const dyaw = yawOf(p) - spawn.yaw;
+  return Math.abs(Math.atan2(Math.sin(dyaw), Math.cos(dyaw))) > REVEAL_YAW;
+};
 
 export async function initGhosts(env) {
-  const noop = { update() {}, peerCount: () => 0, ghostCount: () => 0, debug: () => [] };
+  const noop = { update() {}, peerCount: () => 0, ghostCount: () => 0, debug: () => [], mapDots: () => [] };
   let room;
   try {
     const { joinRoom } = await import(TRYSTERO_URL);
@@ -46,10 +71,36 @@ export async function initGhosts(env) {
   // Ghosts share geometry with the local rig (cloneRig), but get their own
   // transparent material clones so repainting them never touches the
   // visitor's own duck (variants.js caches materials globally).
+  //
+  // Rendering: a ghost reads as ONE translucent shell, not ~70 individually
+  // transparent meshes (through which every internal motor/PCB used to show).
+  // Classic depth-prepass silhouette, kept inside the transparent pass so the
+  // grid floor/walls (transparent ShaderMaterials at renderOrder 0) still
+  // draw behind ghosts instead of being depth-rejected:
+  //   PREPASS (renderOrder 1): every ghost mesh duplicated as a color-less
+  //     twin (colorWrite off, depthWrite on) -> the depth buffer ends up
+  //     holding the nearest ghost surface per pixel.
+  //   BEAUTY (renderOrder 2): the real meshes, transparent + depthWrite off;
+  //     the default LessEqual depth test then rejects everything except the
+  //     fragment matching the prepass depth, so internals and back shell
+  //     layers are skipped and each pixel is shaded exactly once.
+  // Orders are shared by all ghosts (not per-ghost pairs): every beauty pass
+  // tests against every ghost's prepass depth, so overlapping ghosts occlude
+  // each other like solids instead of double-blending.
+  const PREPASS_ORDER = 1;
+  const BEAUTY_ORDER = 2;
   const ghostify = (rig) => {
+    // Collect first: twins are added below and must not be re-traversed.
+    const meshes = [];
+    rig.root.traverse((o) => { if (o.isMesh) meshes.push(o); });
     const cache = new Map();
-    rig.root.traverse((o) => {
-      if (!o.isMesh) return;
+    let depthMat = null;
+    for (const o of meshes) {
+      // Materialization-FX wire overlays cloned along with the local rig:
+      // drop them, they share the LIVE scan shader material and would
+      // flash on this ghost every time the local duck re-materializes.
+      if (o.userData.fxOverlay) { o.parent?.remove(o); continue; }
+      if (o.userData.ghostPrepass) continue; // twin from a previous ghostify
       let m = cache.get(o.material.uuid);
       if (!m) {
         m = o.material.clone();
@@ -59,10 +110,31 @@ export async function initGhosts(env) {
         cache.set(o.material.uuid, m);
       }
       o.material = m;
-    });
+      o.renderOrder = BEAUTY_ORDER;
+      if (!o.userData.hasGhostTwin) {
+        if (!depthMat) {
+          // Depth-only material: cloned (no THREE import here) and muted.
+          // transparent stays true so the twin sorts into the transparent
+          // pass, after the grid but before the beauty meshes.
+          depthMat = m.clone();
+          depthMat.colorWrite = false;
+          depthMat.depthWrite = true;
+        }
+        // Twin as an identity-transform child: follows joints for free. No
+        // userData.meshName, so applyVariant never repaints it.
+        const twin = new o.constructor(o.geometry, depthMat);
+        twin.renderOrder = PREPASS_ORDER;
+        twin.userData.ghostPrepass = true;
+        o.userData.hasGhostTwin = true;
+        o.add(twin);
+      }
+    }
   };
 
   const ghosts = new Map(); // peerId -> ghost
+  // Interpolation snapshot: the pose parts of a state message, stamped
+  // with the local arrival time.
+  const snapOf = (state) => ({ p: state.p, j: state.j, w: state.w ?? 0, at: performance.now() });
   const makeGhost = (state) => {
     const rig = cloneRig(rigFor(state.l));
     applyVariant(rig, state.v);
@@ -73,7 +145,7 @@ export async function initGhosts(env) {
     trunk.position.set(state.p[0], state.p[1], state.p[2]);
     trunk.quaternion.set(state.p[4], state.p[5], state.p[6], state.p[3]);
     return {
-      rig, trunk, target: state, joints: state.j.slice(), jaw: state.w ?? 0,
+      rig, trunk, buf: [snapOf(state)],
       variant: state.v, loco: state.l ?? 0,
     };
   };
@@ -102,19 +174,31 @@ export async function initGhosts(env) {
       // sessions can arrive right after joining: only ghost live peers.
       if (!(peerId in room.getPeers())) return;
       g = makeGhost(state);
+      // Idle-visitor gate: remember where this peer first appeared and keep
+      // its rig invisible until it strays from there (see hasMoved above).
+      g.spawn = { x: state.p[0], y: state.p[1], yaw: yawOf(state.p) };
+      g.revealed = false;
+      g.rig.placer.visible = false;
       ghosts.set(peerId, g);
       g.lastSeen = performance.now();
       return;
     }
     g.lastSeen = performance.now();
-    g.target = state;
+    g.buf.push(snapOf(state));
+    if (g.buf.length > BUF_MAX) g.buf.shift();
+    if (!g.revealed && hasMoved(g.spawn, state.p)) {
+      g.revealed = true; // latched for the rest of this peer session
+      g.rig.placer.visible = true;
+    }
     // Peer switched legs <-> rollers: rebuild its ghost on the other rig
-    // (cheap - cloneRig shares geometry).
+    // (cheap - cloneRig shares geometry). The snapshot buffer carries over
+    // so the interpolated motion stays continuous across the swap.
     if ((state.l ?? 0) !== g.loco) {
-      const seen = g.lastSeen;
+      const { lastSeen, spawn, revealed, buf } = g;
       removeGhost(peerId);
       g = makeGhost(state);
-      g.lastSeen = seen;
+      Object.assign(g, { lastSeen, spawn, revealed, buf });
+      g.rig.placer.visible = revealed;
       ghosts.set(peerId, g);
       return;
     }
@@ -133,8 +217,9 @@ export async function initGhosts(env) {
     try { room.leave(); } catch {}
   });
   // ...and a staleness sweep for peers that vanished without leaving
-  // (crashed tab, dropped connection): 5 s without a state packet at
-  // 10 Hz means the peer is gone, not just lagging.
+  // (crashed tab, dropped connection): 5 s without a state packet means
+  // the peer is gone, not just lagging (even background-throttled tabs
+  // still send at ~1 Hz).
   const STALE_MS = 5000;
 
   // Broadcast + stale sweep on setInterval (not rAF) so both keep running
@@ -148,36 +233,55 @@ export async function initGhosts(env) {
     }
   }, 1000 / SEND_HZ);
 
-  // Scratch THREE.Quaternion without importing three: slerp needs a real
-  // instance, cloned here from any node of the already-built local rig.
-  const _q = env.rig.placer.quaternion.clone();
+  // Scratch THREE.Quaternions without importing three: slerp needs real
+  // instances, cloned here from any node of the already-built local rig.
+  const _qa = env.rig.placer.quaternion.clone();
+  const _qb = env.rig.placer.quaternion.clone();
   return {
     room,
     peerCount: () => Object.keys(room.getPeers()).length,
     ghostCount: () => ghosts.size,
+    // Minimap feed: revealed ghosts' arena positions in raw MJCF coords
+    // (trunk.position is set from qpos before the root's Z-up fix).
+    mapDots: () =>
+      [...ghosts.values()]
+        .filter((g) => g.revealed)
+        .map((g) => ({ x: g.trunk.position.x, y: g.trunk.position.y })),
     debug: () => [...ghosts.values()].map((g) => {
-      let meshes = 0, visible = 0, op = null;
+      let meshes = 0, visible = 0, op = null, twins = 0;
       g.rig.root.traverse((o) => {
-        if (o.isMesh) { meshes++; if (o.visible) visible++; op ??= o.material.opacity; }
+        if (!o.isMesh) return;
+        if (o.userData.ghostPrepass) { twins++; return; }
+        meshes++; if (o.visible) visible++; op ??= o.material.opacity;
       });
       const w = g.trunk.getWorldPosition(g.trunk.position.clone());
-      return { p: g.trunk.position.toArray(), world: w.toArray(), inScene: !!g.rig.placer.parent, meshes, visible, op, v: g.variant };
+      return { p: g.trunk.position.toArray(), world: w.toArray(), inScene: !!g.rig.placer.parent, revealed: g.revealed, meshes, visible, twins, op, v: g.variant };
     }),
     update() {
+      const renderT = performance.now() - INTERP_DELAY_MS;
       for (const g of ghosts.values()) {
-        const t = g.target;
+        const buf = g.buf;
+        // Drop snapshots fully in the past; keep [0] and [1] bracketing
+        // renderT (or the two newest, if renderT has caught up).
+        while (buf.length > 2 && buf[1].at <= renderT) buf.shift();
+        const a = buf[0];
+        const b = buf.length > 1 ? buf[1] : a;
+        // Clamped: before the segment -> a, past the newest -> hold b.
+        const span = b.at - a.at;
+        const u = span > 0 ? Math.min(1, Math.max(0, (renderT - a.at) / span)) : 1;
         // Trunk pose in raw MJCF coords: the cloned root applies Z-up -> Y-up.
-        g.trunk.position.x += (t.p[0] - g.trunk.position.x) * EASE;
-        g.trunk.position.y += (t.p[1] - g.trunk.position.y) * EASE;
-        g.trunk.position.z += (t.p[2] - g.trunk.position.z) * EASE;
-        _q.set(t.p[4], t.p[5], t.p[6], t.p[3]); // THREE order x,y,z,w
-        g.trunk.quaternion.slerp(_q, EASE);
+        g.trunk.position.set(
+          a.p[0] + (b.p[0] - a.p[0]) * u,
+          a.p[1] + (b.p[1] - a.p[1]) * u,
+          a.p[2] + (b.p[2] - a.p[2]) * u,
+        );
+        _qa.set(a.p[4], a.p[5], a.p[6], a.p[3]); // THREE order x,y,z,w
+        _qb.set(b.p[4], b.p[5], b.p[6], b.p[3]);
+        g.trunk.quaternion.copy(_qa.slerp(_qb, u));
         for (let i = 0; i < jointNames.length; i++) {
-          g.joints[i] += (t.j[i] - g.joints[i]) * EASE;
-          setJoint(g.rig, jointNames[i], g.joints[i]);
+          setJoint(g.rig, jointNames[i], a.j[i] + (b.j[i] - a.j[i]) * u);
         }
-        g.jaw += ((t.w ?? 0) - g.jaw) * EASE;
-        setJawOpen(g.rig, g.jaw);
+        setJawOpen(g.rig, a.w + (b.w - a.w) * u);
       }
     },
   };

index.html

@@ -3,11 +3,12 @@
   <head>
     <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>Microduck RL playground</title>
+    <title>Microduck</title>
     <style>
       :root {
         --ink: #08080c;
-        --yellow: #ffd23f;
+        --orange: #ff7a2f;
+        --yellow: var(--orange);
       }
       * { margin: 0; padding: 0; box-sizing: border-box; }
       html, body { height: 100%; }
@@ -17,31 +18,139 @@
         font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
         overflow: hidden;
       }
-      #scene { position: fixed; inset: 0; }
+      #scene { position: fixed; inset: 0; z-index: 1; }
       #scene canvas { display: block; }
+      /* Pre-boot veil: covers everything until the title page's logo and
+         fonts are in, so the menu never pops in half-assembled. Light grey
+         spinner, centered on the ink. */
+      #preboot {
+        position: fixed;
+        inset: 0;
+        z-index: 40;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        background: var(--ink);
+        opacity: 1;
+        transition: opacity 0.25s ease;
+      }
+      #preboot.off { opacity: 0; pointer-events: none; }
+      #preboot .spin {
+        width: 22px;
+        height: 22px;
+        border-radius: 50%;
+        border: 2px solid rgba(255, 255, 255, 0.14);
+        border-top-color: rgba(255, 255, 255, 0.55);
+        animation: preboot-spin 0.8s linear infinite;
+      }
+      @keyframes preboot-spin {
+        to { transform: rotate(360deg); }
+      }
+      @media (prefers-reduced-motion: reduce) {
+        #preboot .spin { animation-duration: 1.6s; }
+      }
       .halftone {
         position: fixed;
         inset: 0;
+        z-index: 2;
         pointer-events: none;
         background-image: radial-gradient(rgba(255, 255, 255, 0.05) 1px, transparent 1.5px);
         background-size: 21px 21px;
         mask-image: linear-gradient(to bottom, transparent 30%, black 100%);
         -webkit-mask-image: linear-gradient(to bottom, transparent 30%, black 100%);
       }
-      /* Top-left corner: what this is */
-      #brand {
+      /* ── CRT / old-TV overlay ──────────────────────────────────────
+         Independent full-viewport layers stacked over the 3D scene at
+         z-index 5: above the canvas and the halftone dots, below the
+         HUD (z 10), the BIOS boot screen (z 20) and the welcome modal
+         (z 30) - so the interface stays crisp and only the scene gets
+         the old-TV treatment.
+
+         Each effect lives in its own child div + CSS block and can be
+         removed by deleting that block and its <div id="crt"> child:
+           .crt-scanlines  fine horizontal lines + faint RGB fringe
+           .crt-noise      boiling static grain (tiled SVG turbulence)
+           .crt-vignette   darkened edges, curved-glass feel (optional)
+
+         Tuning knobs (custom properties on #crt):
+           --crt-scanline-opacity   line strength        (0 = off)
+           --crt-scanline-pitch     line spacing in px
+           --crt-noise-opacity      grain strength       (0 = off)
+           --crt-vignette-opacity   edge darkening       (0 = off)
+
+         Performance: the only animation is a transform-only jitter on
+         the noise layer, so everything stays on the compositor and
+         never triggers repaints of the WebGL canvas underneath. */
+      #crt {
         position: fixed;
-        top: 1.4rem;
-        left: 1.6rem;
-        z-index: 10;
-        font-size: 0.72rem;
-        font-weight: 600;
-        letter-spacing: 0.14em;
-        text-transform: uppercase;
-        color: rgba(255, 255, 255, 0.55);
-        line-height: 1.8;
+        inset: 0;
+        z-index: 5;
+        pointer-events: none;
+        overflow: hidden;
+        --crt-scanline-opacity: 0.13;
+        --crt-scanline-pitch: 3px;
+        --crt-noise-opacity: 0.045;
+        --crt-vignette-opacity: 0.42;
+      }
+      /* SCANLINES: one thin dark line every --crt-scanline-pitch, plus a
+         very faint vertical RGB fringe (aperture-grille tint). Static,
+         zero runtime cost. */
+      #crt .crt-scanlines {
+        position: absolute;
+        inset: 0;
+        background:
+          repeating-linear-gradient(
+            to bottom,
+            rgba(0, 0, 0, 0.55) 0,
+            rgba(0, 0, 0, 0.55) 1px,
+            transparent 1px,
+            transparent var(--crt-scanline-pitch)
+          ),
+          repeating-linear-gradient(
+            to right,
+            rgba(255, 70, 60, 0.05) 0,
+            rgba(255, 70, 60, 0.05) 1px,
+            rgba(70, 255, 90, 0.035) 1px,
+            rgba(70, 255, 90, 0.035) 2px,
+            rgba(70, 110, 255, 0.05) 2px,
+            rgba(70, 110, 255, 0.05) 3px
+          );
+        opacity: var(--crt-scanline-opacity);
+      }
+      /* NOISE: a small tiled SVG turbulence texture (white specks with
+         noisy alpha), jittered between four offsets with steps() so the
+         grain "boils" like broadcast static. The layer is oversized so
+         the jumps never reveal an edge; only transform animates. */
+      #crt .crt-noise {
+        position: absolute;
+        inset: -80px;
+        background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='160' height='160'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.8' numOctaves='2' stitchTiles='stitch'/%3E%3CfeColorMatrix type='matrix' values='0 0 0 0 1 0 0 0 0 1 0 0 0 0 1 0 0 0 0.7 0'/%3E%3C/filter%3E%3Crect width='160' height='160' filter='url(%23n)'/%3E%3C/svg%3E");
+        background-size: 160px 160px;
+        opacity: var(--crt-noise-opacity);
+        animation: crt-noise 0.5s steps(1) infinite;
+        will-change: transform;
+      }
+      @keyframes crt-noise {
+        0% { transform: translate(0, 0); }
+        25% { transform: translate(-45px, 30px); }
+        50% { transform: translate(25px, -55px); }
+        75% { transform: translate(-30px, -15px); }
+        100% { transform: translate(0, 0); }
+      }
+      /* VIGNETTE (optional): gently darkened corners, like the curved
+         glass of a CRT tube. Static. */
+      #crt .crt-vignette {
+        position: absolute;
+        inset: 0;
+        background: radial-gradient(
+          115% 90% at 50% 50%,
+          transparent 62%,
+          rgba(0, 0, 0, var(--crt-vignette-opacity)) 100%
+        );
+      }
+      @media (prefers-reduced-motion: reduce) {
+        #crt .crt-noise { animation: none; }
       }
-      #brand b { color: var(--yellow); font-weight: 600; }
       /* BIOS/POST boot readout: hidden while the welcome modal is up (the
          real load runs silently behind it); rl.js reveals it after the
          first "Waddle in" and replays / tracks the milestones over an
@@ -50,9 +159,10 @@
         position: fixed;
         inset: 0;
         display: none;
-        align-items: center;
-        justify-content: center;
-        padding: 0 2rem;
+        /* POST readout sits bottom-left like a real BIOS, not centered */
+        align-items: flex-end;
+        justify-content: flex-start;
+        padding: 2.2rem 2.4rem;
         background: var(--ink);
         z-index: 20;
         pointer-events: none;
@@ -62,25 +172,42 @@
       #loading.off { opacity: 0; }
       #loading .post {
         min-width: min(380px, 84vw);
+        /* Grow upward from the bottom-left anchor; when the log outgrows
+           the viewport, clip the OLDEST lines at the top (content is
+           bottom-aligned) so the newest line + cursor stay visible. */
+        max-height: calc(100vh - 4.4rem);
+        display: flex;
+        flex-direction: column;
+        justify-content: flex-end;
+        overflow: hidden;
+        /* Raw 90s POST look: small, tight, unsmoothed monospace - no glow,
+           no tracking, plain weight. Reads like a firmware screen, not a
+           styled terminal. */
         font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
-        font-size: 0.72rem;
-        line-height: 2.1;
-        letter-spacing: 0.06em;
+        font-size: 12px;
+        font-weight: 400;
+        line-height: 1.55;
+        letter-spacing: 0;
         text-transform: uppercase;
         text-align: left;
-        color: rgba(255, 210, 63, 0.72);
-        text-shadow: 0 0 10px rgba(255, 210, 63, 0.2);
+        /* Robot orange (classic duck's BRIGHT_ORANGE, #ff7a2f in sRGB) */
+        color: rgba(255, 122, 47, 0.92);
         white-space: pre-wrap;
         overflow-wrap: break-word;
       }
       #loading .post > div:first-child {
-        color: rgba(255, 255, 255, 0.8);
-        margin-bottom: 0.3rem;
+        color: rgba(255, 255, 255, 0.85);
+        margin-bottom: 0.55em;
       }
       /* Blinking block cursor at the end of the newest line */
       #loading .post > div:last-child::after {
         content: "\2588";
-        margin-left: 0.4em;
+        margin-left: 0.15em;
+        animation: post-blink 1s steps(1) infinite;
+      }
+      /* Fatal boot failure: SYSTEM HALTED blinks like an old POST fault */
+      #loading .post > div.halt {
+        color: rgba(255, 82, 47, 0.95);
         animation: post-blink 1s steps(1) infinite;
       }
       @keyframes post-blink {
@@ -133,31 +260,151 @@
         border-color: #ffc61e;
         color: #08080c;
       }
-      /* Current-state label: quiet line above the telemetry, slot-machine
-         roll on change */
+      /* Active policy/mode readout, top-right: bright orange caption over a
+         big white monospace name. rl.js scrambles the letters on change
+         (Matrix-style), so the span is plain flow - no slot-machine
+         transforms. Monospace keeps the width stable mid-scramble. */
+      #mode-wrap {
+        position: fixed;
+        top: 1.4rem;
+        right: 1.6rem;
+        z-index: 10;
+        font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+        pointer-events: none;
+        text-align: right;
+      }
+      #mode-wrap .caption {
+        display: block;
+        margin-bottom: 0.35rem;
+        font-size: 0.78rem;
+        font-weight: 600;
+        letter-spacing: 0.24em;
+        text-transform: uppercase;
+        color: var(--orange);
+        text-shadow: 0 0 10px rgba(255, 122, 47, 0.35);
+      }
       .mode {
-        position: relative;
-        overflow: hidden;
-        height: 1.2em;
         min-width: 8ch;
-        font-size: 0.72rem;
+        min-height: 1.2em;
+        font-size: 1.7rem;
         font-weight: 600;
-        letter-spacing: 0.2em;
+        letter-spacing: 0.16em;
         text-transform: uppercase;
-        color: rgba(255, 210, 63, 0.8);
+        color: rgba(255, 255, 255, 0.95);
         text-align: right;
-        text-shadow: 0 0 8px rgba(255, 210, 63, 0.3);
-      }
-      .mode .mode-text {
-        position: absolute;
-        left: 0;
-        top: 0;
-        width: 100%;
+        text-shadow: 0 0 12px rgba(255, 255, 255, 0.28);
         line-height: 1.2;
-        transition: transform 0.3s cubic-bezier(0.2, 0.8, 0.2, 1), opacity 0.3s ease;
       }
-      .mode .mode-text.in { transform: translateY(130%); opacity: 0; }
-      .mode .mode-text.out { transform: translateY(-130%); opacity: 0; }
+      /* In-game back-to-menu button, top-left */
+      #back-btn {
+        position: fixed;
+        top: 1.4rem;
+        left: 1.6rem;
+        z-index: 10;
+        appearance: none;
+        display: inline-flex;
+        align-items: center;
+        gap: 0.45em;
+        border: 1px solid rgba(255, 255, 255, 0.16);
+        background: rgba(8, 8, 12, 0.55);
+        color: rgba(255, 255, 255, 0.75);
+        font: inherit;
+        font-size: 0.8rem;
+        font-weight: 600;
+        letter-spacing: 0.14em;
+        text-transform: uppercase;
+        padding: 0.6rem 1.15rem;
+        border-radius: 999px;
+        cursor: pointer;
+        transition: color 0.15s ease, background 0.15s ease, border-color 0.15s ease;
+      }
+      #back-btn:hover {
+        color: #fff;
+        border-color: rgba(255, 255, 255, 0.4);
+        background: rgba(255, 255, 255, 0.06);
+      }
+      #back-btn:focus-visible {
+        outline: 2px solid var(--orange);
+        outline-offset: 2px;
+      }
+      /* In-game quick picks, bottom-left: colour dots + legs/rollers, live.
+         Same pill language as the vitrine DuckPlayground. */
+      #quickbar {
+        position: fixed;
+        bottom: 1.4rem;
+        left: 1.6rem;
+        z-index: 10;
+        display: flex;
+        flex-wrap: wrap;
+        align-items: center;
+        gap: 0.6rem;
+      }
+      #quickbar .dots,
+      #quickbar .seg {
+        display: inline-flex;
+        gap: 0.24rem;
+        padding: 0.26rem;
+        border: 1px solid rgba(255, 255, 255, 0.14);
+        border-radius: 999px;
+        background: rgba(8, 8, 12, 0.55);
+      }
+      #quickbar .dots button {
+        appearance: none;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        width: auto;
+        height: 2.3rem;
+        padding: 0 0.5rem;
+        border: none;
+        border-radius: 999px;
+        background: transparent;
+        cursor: pointer;
+      }
+      #quickbar .dots button .dot {
+        width: 1.4rem;
+        height: 1.4rem;
+        border-radius: 50%;
+        opacity: 0.45;
+        transition: transform 0.2s ease, opacity 0.2s ease;
+      }
+      #quickbar .dots button:hover .dot { opacity: 1; }
+      #quickbar .dots button.on .dot {
+        opacity: 1;
+        transform: scale(1.15);
+      }
+      #quickbar .seg button {
+        appearance: none;
+        border: none;
+        background: transparent;
+        height: 2.3rem;
+        padding: 0 1.05rem;
+        border-radius: 999px;
+        font: inherit;
+        font-size: 0.76rem;
+        font-weight: 600;
+        letter-spacing: 0.14em;
+        text-transform: uppercase;
+        color: rgba(255, 255, 255, 0.45);
+        cursor: pointer;
+        transition: color 0.2s ease, background 0.2s ease;
+      }
+      #quickbar .seg button.on {
+        background: rgba(255, 122, 47, 0.14);
+        color: var(--orange);
+      }
+      #quickbar .dots button:focus-visible,
+      #quickbar .seg button:focus-visible {
+        outline: 2px solid var(--orange);
+        outline-offset: 2px;
+      }
+      /* Narrow screens: pull the quickbar back a notch so it stays on one
+         line and clear of the bottom-right telemetry. */
+      @media (max-width: 480px) {
+        #quickbar .dots button { height: 2rem; padding: 0 0.42rem; }
+        #quickbar .dots button .dot { width: 1.2rem; height: 1.2rem; }
+        #quickbar .seg button { height: 2rem; padding: 0 0.8rem; font-size: 0.68rem; }
+      }
       /* Colour swatches */
       #swatches { gap: 0.6rem; }
       #swatches button {
@@ -257,7 +504,7 @@
          a phosphor-glow monospace. No scanlines - the type does the work. */
       #stats-wrap {
         position: fixed;
-        top: 1.4rem;
+        top: 6.1rem; /* below the mode readout */
         right: 1.6rem;
         z-index: 10;
         display: flex;
@@ -289,166 +536,216 @@
         0%, 58% { opacity: 1; }
         59%, 100% { opacity: 0.12; }
       }
-      #stats {
+      /* Telemetry stack, bottom-right: peers / speed + odometer / loop
+         rates, one line each, quietest at the bottom. */
+      #ctrl-hz {
+        position: fixed;
+        bottom: 1.4rem;
+        right: 1.6rem;
+        z-index: 10;
+        pointer-events: none;
+        font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
         font-size: 0.62rem;
         letter-spacing: 0.14em;
         text-transform: uppercase;
-        text-align: right;
-        color: rgba(255, 255, 255, 0.45);
-        line-height: 1.7;
+        color: rgba(255, 255, 255, 0.35);
         font-variant-numeric: tabular-nums;
-        text-shadow: 0 0 6px rgba(255, 255, 255, 0.18);
+        text-shadow: 0 0 6px rgba(255, 255, 255, 0.15);
+        white-space: pre-line;
+        text-align: right;
+        line-height: 1.8;
+      }
+      /* Radar minimap: top-down arena view in the top-right OSD stack */
+      #minimap {
+        width: 132px;
+        height: 132px;
+        margin-top: 0.45rem;
+        pointer-events: none;
+        background: rgba(0, 0, 0, 0.38);
+        border: 1px solid rgba(255, 122, 47, 0.4);
+        border-radius: 2px;
       }
       /* BIOS-style line while the roller variant streams in on first switch */
       #osd-load[hidden] { display: none; }
       #osd-load {
         font-size: 0.68rem;
         letter-spacing: 0.14em;
-        color: var(--yellow, #ffd23f);
-        text-shadow: 0 0 8px rgba(255, 210, 63, 0.4);
+        color: var(--orange);
+        text-shadow: 0 0 8px rgba(255, 122, 47, 0.4);
       }
       .osd-load-cursor {
         display: inline-block;
         margin-left: 0.15em;
         animation: rec-blink 0.8s steps(1) infinite;
       }
+      /* Temporarily hidden HUD pieces (CSS-only so the DOM, ids and JS
+         wiring stay intact and each can be re-enabled by deleting a line):
+         - #osd-time: the VHS play/time counter (REC + ONLINE stay);
+         - #hud .keys: the keycap hints + mini joysticks block;
+         - #hud .stack: the in-game colour swatch pill (the welcome modal
+           still clicks the hidden #swatches buttons programmatically). */
+      #osd-time { display: none; }
+      #hud .keys { display: none; }
+      #hud .stack { display: none; }
+      .osd-rec { display: none; }
+      #minimap { display: none; }
       /* Roller mode: legs-only actions (kicks, sit) are inert - fade their
          hints; rl.js toggles body.rollers on every variant switch. */
       body.rollers .legs-only { opacity: 0.25; }
       @media (max-width: 700px) {
         #hud { flex-direction: column; align-items: flex-start; }
         #hud .keys { display: none; }
-        #brand .sub { display: none; }
-        /* Drop the OSD below the (single-line) brand so they never collide */
-        #stats-wrap { top: 3.4rem; }
       }
-      /* ── Welcome modal ─────────────────────────────────────────────── */
-      /* display:flex would override the hidden attribute's UA display:none,
-         so hidden must win explicitly. */
+      /* HUD stays off while the title flow / pause overlay is up. */
+      body.welcome-open #hud,
+      body.welcome-open #mode-wrap,
+      body.welcome-open #stats-wrap,
+      body.welcome-open #back-btn,
+      body.welcome-open #quickbar,
+      body.welcome-open #ctrl-hz { display: none !important; }
+      /* ── Title / pause overlay (full viewport, no card) ────────────── */
       #welcome[hidden] { display: none; }
       #welcome {
         position: fixed;
         inset: 0;
         z-index: 30;
         display: flex;
-        padding: 1.25rem;
-        overflow-y: auto;
-        background: rgba(8, 8, 12, 0.5);
-        backdrop-filter: blur(18px) saturate(1.3);
-        -webkit-backdrop-filter: blur(18px) saturate(1.3);
+        flex-direction: column;
+        align-items: center;
+        justify-content: center;
+        padding: 2.4rem 1.4rem 1.8rem;
+        background: var(--ink);
         opacity: 1;
-        transition: opacity 0.35s ease;
+        overflow-y: auto;
+        transition: opacity 0.35s ease, background 0.4s ease;
       }
       #welcome.closing { opacity: 0; pointer-events: none; }
-      #welcome .card {
-        position: relative;
-        /* Auto margins center the card and degrade to scroll on overflow */
-        margin: auto;
+      @keyframes row-in {
+        from { transform: translateY(8px); opacity: 0; }
+        to { transform: none; opacity: 1; }
+      }
+      #welcome .wstep {
         width: 100%;
-        max-width: 480px;
-        padding: 2.3rem 2.4rem 1.8rem;
-        border: 1px solid rgba(255, 255, 255, 0.1);
-        border-radius: 24px;
-        background:
-          radial-gradient(130% 80% at 50% 0%, rgba(255, 210, 63, 0.06), transparent 55%),
-          rgba(13, 13, 19, 0.94);
-        box-shadow:
-          inset 0 1px 0 rgba(255, 255, 255, 0.06),
-          0 24px 60px rgba(0, 0, 0, 0.55),
-          0 80px 160px rgba(0, 0, 0, 0.4);
+        max-width: 36rem;
         text-align: center;
-        animation: card-in 0.5s cubic-bezier(0.22, 1, 0.36, 1) both;
       }
-      @keyframes card-in {
-        from { transform: translateY(14px) scale(0.965); opacity: 0; }
-        to { transform: none; opacity: 1; }
+      #welcome .wstep[hidden] { display: none; }
+      #welcome .wstep > * {
+        animation: row-in 0.45s cubic-bezier(0.22, 1, 0.36, 1) both;
       }
-      /* Rows fade in with a gentle stagger; no bounce anywhere. */
-      #welcome .card > * {
-        animation: row-in 0.55s cubic-bezier(0.22, 1, 0.36, 1) both;
+      #welcome .wstep > :nth-child(2) { animation-delay: 0.06s; }
+      #welcome .wstep > :nth-child(3) { animation-delay: 0.12s; }
+      @media (prefers-reduced-motion: reduce) {
+        #welcome .wstep > * { animation: none; }
       }
-      #welcome .card > :nth-child(1) { animation-delay: 0.05s; }
-      #welcome .card > :nth-child(2) { animation-delay: 0.11s; }
-      #welcome .card > :nth-child(3) { animation-delay: 0.17s; }
-      #welcome .card > :nth-child(4) { animation-delay: 0.23s; }
-      #welcome .card > :nth-child(5) { animation-delay: 0.27s; }
-      @keyframes row-in {
-        from { transform: translateY(8px); opacity: 0; }
-        to { transform: none; opacity: 1; }
+      #welcome .facts {
+        display: flex;
+        flex-wrap: wrap;
+        align-items: center;
+        justify-content: center;
+        gap: 0.6rem;
+        margin-bottom: 1.15rem;
+        font-size: 0.72rem;
+        font-weight: 600;
+        letter-spacing: 0.14em;
+        text-transform: uppercase;
+        color: rgba(255, 255, 255, 0.78);
       }
-      @media (prefers-reduced-motion: reduce) {
-        #welcome .card, #welcome .card > * { animation: none; }
+      #welcome .facts span:not(:last-child)::after {
+        content: "·";
+        color: var(--orange);
+        padding-left: 0.6em;
       }
-      /* Header: duck-head mark (closed by default, open on hover - same
-         swap as the site) over a clean typographic identity. */
-      #welcome .logo-head {
+      /* Vitrine brand lockup, centered above the title: drawn duck head +
+         name. Hovering swaps to the open-beak frame, same hard sprite swap
+         as the vitrine header. */
+      #welcome .wbrand {
+        display: flex;
+        flex-direction: column;
+        align-items: center;
+        justify-content: center;
+        gap: 0.55rem;
+        margin-bottom: 1.3rem;
+        user-select: none;
+      }
+      #welcome .wbrand-head {
         position: relative;
-        width: 5.8rem;
-        margin: 0 auto;
-        filter: drop-shadow(0 10px 24px rgba(0, 0, 0, 0.45));
+        display: block;
+        height: 3rem;
       }
-      #welcome .logo-head img { display: block; width: 100%; }
-      #welcome .logo-head .open { position: absolute; inset: 0; opacity: 0; }
-      #welcome .logo-head:hover .open { opacity: 1; }
-      #welcome .logo-head:hover .closed { opacity: 0; }
-      #welcome .title {
-        margin-top: 0.8rem;
-        font-size: 1.4rem;
-        font-weight: 700;
-        letter-spacing: -0.01em;
-        color: rgba(255, 255, 255, 0.95);
+      #welcome .wbrand-head .duck-closed {
+        display: block;
+        height: 100%;
+        width: auto;
       }
-      #welcome .subtitle {
-        margin-top: 0.35rem;
-        font-size: 0.6rem;
+      /* The open frame's canvas (460x333) is a hair wider/taller than the
+         closed one (454x269): the dropped jaw sticks out past the head.
+         Offsets pin the head in place while the jaw hangs below. */
+      #welcome .wbrand-head .duck-open {
+        position: absolute;
+        top: -0.75%;
+        left: -1.1%;
+        width: 101.3%;
+        max-width: none;
+        height: auto;
+        opacity: 0;
+      }
+      #welcome .wbrand:hover .duck-closed { opacity: 0; }
+      #welcome .wbrand:hover .duck-open { opacity: 1; }
+      #welcome .wbrand-name {
         font-weight: 700;
-        letter-spacing: 0.34em;
-        text-indent: 0.34em; /* recenter: tracking pads the right edge only */
-        text-transform: uppercase;
-        color: rgba(255, 210, 63, 0.8);
+        letter-spacing: -0.03em;
+        font-size: 1.6rem;
+        color: #fff;
       }
-      #welcome .tagline {
-        margin: 0.8rem auto 0;
-        max-width: 42ch;
-        font-size: 0.78rem;
-        line-height: 1.6;
-        color: rgba(255, 255, 255, 0.58);
+      /* Landing-grade h1: same type conventions as the vitrine hero
+         (600, tight tracking, line-height 1), the loudest line on the page. */
+      #welcome .title {
+        margin: 0 auto;
+        max-width: 20ch;
+        font-size: clamp(2.4rem, 5vw, 3.75rem);
+        font-weight: 600;
+        letter-spacing: -0.03em;
+        color: #fff;
+        line-height: 1.02;
         text-wrap: balance;
       }
-      /* Section label with hairlines on both sides */
-      #welcome .section-label {
-        display: flex;
-        align-items: center;
-        gap: 0.9rem;
-        margin: 1.5rem 0 0.8rem;
-        font-size: 0.56rem;
-        font-weight: 700;
-        letter-spacing: 0.28em;
-        text-indent: 0.28em;
+      #welcome .label {
+        font-size: 0.68rem;
+        font-weight: 600;
+        letter-spacing: 0.18em;
+        text-indent: 0.18em;
         text-transform: uppercase;
-        color: rgba(255, 255, 255, 0.35);
+        color: var(--orange);
       }
-      #welcome .section-label::before,
-      #welcome .section-label::after {
-        content: "";
-        flex: 1;
-        height: 1px;
-        background: rgba(255, 255, 255, 0.08);
+      #welcome .tagline {
+        margin: 1.25rem auto 0;
+        max-width: 36ch;
+        font-size: clamp(1.05rem, 1.5vw, 1.3rem);
+        line-height: 1.5;
+        letter-spacing: -0.012em;
+        color: rgba(255, 255, 255, 0.72);
+        text-wrap: balance;
       }
-      /* Controls: six keycap tiles on a tidy grid */
       #welcome .grid {
         display: grid;
         grid-template-columns: repeat(3, 1fr);
-        gap: 0.5rem;
-      }
+        gap: 0.55rem;
+        margin-top: 1.4rem;
+      }
+      #welcome .grid-pad { display: none; }
+      body.pad-connected #welcome .grid-kb { display: none; }
+      body.pad-connected #welcome .grid-pad { display: grid; }
+      #welcome .kb-hint { display: block; }
+      #welcome .pad-hint { display: none; }
+      body.pad-connected #welcome .kb-hint { display: none; }
+      body.pad-connected #welcome .pad-hint { display: block; }
       #welcome .tile {
-        padding: 0.75rem 0.4rem 0.7rem;
-        border: 1px solid rgba(255, 255, 255, 0.07);
-        border-radius: 14px;
-        background: rgba(255, 255, 255, 0.03);
+        padding: 0.85rem 0.45rem 0.75rem;
+        border: 1px solid rgba(255, 255, 255, 0.08);
+        border-radius: 18px;
+        background: rgba(255, 255, 255, 0.035);
       }
-      /* Fixed-height keycap area so every tile's label sits on the same
-         baseline whether it holds one cap or the arrow cluster. */
       #welcome .caps {
         display: flex;
         flex-direction: column;
@@ -459,153 +756,135 @@
       }
       #welcome .caps .krow {
         display: flex;
-        gap: 0.2rem;
+        gap: 0.22rem;
         justify-content: center;
       }
       #welcome kbd {
         display: inline-flex;
         align-items: center;
         justify-content: center;
-        min-width: 1.55rem;
-        height: 1.55rem;
+        min-width: 1.65rem;
+        height: 1.65rem;
         padding: 0 0.45rem;
         font: inherit;
         font-size: 0.68rem;
         font-weight: 600;
-        color: rgba(255, 255, 255, 0.88);
-        background: linear-gradient(180deg, rgba(255, 255, 255, 0.1), rgba(255, 255, 255, 0.04));
-        border: 1px solid rgba(255, 255, 255, 0.16);
-        border-radius: 6px;
-        box-shadow: 0 2px 0 rgba(0, 0, 0, 0.45), inset 0 1px 0 rgba(255, 255, 255, 0.08);
+        color: #fff;
+        background: #14141c;
+        border: 2px solid var(--ink);
+        border-radius: 8px;
+        box-shadow: 0 0 0 2px rgba(255, 255, 255, 0.82);
       }
-      /* The arrow cluster packs six caps in two rows, so its caps shrink a
-         notch; every other tile keeps the full-size cap. */
       #welcome .caps.cluster kbd { min-width: 1.4rem; height: 1.4rem; padding: 0 0.3rem; font-size: 0.62rem; }
       #welcome .t-name {
         margin-top: 0.55rem;
-        font-size: 0.62rem;
-        font-weight: 700;
-        letter-spacing: 0.18em;
-        text-indent: 0.18em;
-        text-transform: uppercase;
-        color: rgba(255, 255, 255, 0.85);
+        font-size: 0.72rem;
+        font-weight: 600;
+        letter-spacing: -0.01em;
+        text-transform: none;
+        text-indent: 0;
+        color: #fff;
       }
       #welcome .t-hint {
-        margin-top: 0.2rem;
-        font-size: 0.6rem;
-        color: rgba(255, 255, 255, 0.38);
-      }
-      #welcome .orbit-hint {
-        margin-top: 0.7rem;
+        margin-top: 0.18rem;
         font-size: 0.62rem;
-        letter-spacing: 0.08em;
-        color: rgba(255, 255, 255, 0.35);
-      }
-      /* Secondary row: gamepad + live ghosts */
-      #welcome .extras {
-        display: grid;
-        grid-template-columns: 1fr 1fr;
-        gap: 1.2rem;
-        margin-top: 1.3rem;
-        padding-top: 1.1rem;
-        border-top: 1px solid rgba(255, 255, 255, 0.07);
-      }
-      #welcome .x-label {
-        display: block;
-        margin-bottom: 0.3rem;
-        font-size: 0.56rem;
-        font-weight: 700;
-        letter-spacing: 0.24em;
-        text-indent: 0.24em;
+        font-weight: 600;
+        letter-spacing: 0.12em;
         text-transform: uppercase;
-        color: rgba(255, 210, 63, 0.7);
+        color: var(--orange);
       }
-      #welcome .x-item {
+      #welcome .orbit-hint {
+        margin-top: 1rem;
         font-size: 0.68rem;
-        line-height: 1.5;
-        color: rgba(255, 255, 255, 0.5);
-        text-wrap: balance;
+        font-weight: 600;
+        letter-spacing: 0.08em;
+        color: rgba(255, 255, 255, 0.4);
       }
-      #welcome .cta {
-        margin-top: 1.5rem;
+      #welcome .foot {
+        display: flex;
+        flex-direction: column;
+        align-items: center;
+        gap: 1rem;
+        margin-top: 1.6rem;
+        width: 100%;
       }
-      #welcome-go {
+      #welcome .wbtn {
         appearance: none;
-        border: none;
-        background: var(--yellow);
+        border: 3px solid var(--ink);
+        background: var(--orange);
         color: var(--ink);
         font: inherit;
-        font-size: 0.75rem;
-        font-weight: 700;
-        letter-spacing: 0.14em;
-        text-indent: 0.14em;
-        text-transform: uppercase;
-        padding: 0.8rem 2.6rem;
+        font-size: 1.02rem;
+        font-weight: 600;
+        letter-spacing: -0.01em;
+        text-transform: none;
+        text-indent: 0;
+        padding: 0.85rem 1.9rem;
         border-radius: 999px;
+        box-shadow: 0 0 0 3px #fff;
         cursor: pointer;
-        transition: transform 0.15s ease, box-shadow 0.15s ease;
+        transition: transform 0.2s ease, box-shadow 0.2s ease;
       }
-      #welcome-go:hover {
-        transform: translateY(-1px);
-        box-shadow: 0 8px 28px rgba(255, 210, 63, 0.3);
+      #welcome .wbtn:hover {
+        transform: translateY(-2px);
+        box-shadow: 0 0 0 3px #fff, 0 10px 26px rgba(255, 122, 47, 0.3);
       }
-      #welcome-go:focus-visible {
-        outline: 2px solid rgba(255, 255, 255, 0.85);
-        outline-offset: 3px;
+      #welcome .wbtn:active {
+        transform: translateY(1px);
+        box-shadow: 0 0 0 3px #fff;
       }
-      #welcome .fineprint {
-        margin-top: 0.9rem;
-        font-size: 0.58rem;
-        letter-spacing: 0.1em;
-        text-transform: uppercase;
-        color: rgba(255, 255, 255, 0.28);
+      #welcome .wbtn:focus-visible {
+        outline: 2px solid #fff;
+        outline-offset: 4px;
       }
-      /* Narrow screens: stack the grid two-up, tighten the whole rhythm so
-         the card still fits a small phone viewport without scrolling */
       @media (max-width: 480px) {
-        #welcome .card { padding: 1.6rem 1.3rem 1.4rem; border-radius: 20px; }
-        #welcome .logo-head { width: 4.3rem; }
-        #welcome .title { margin-top: 0.6rem; font-size: 1.2rem; }
-        #welcome .tagline { margin-top: 0.55rem; font-size: 0.73rem; }
-        #welcome .section-label { margin: 1.1rem 0 0.7rem; }
-        #welcome .grid { grid-template-columns: repeat(2, 1fr); gap: 0.45rem; }
-        #welcome .tile { padding: 0.6rem 0.4rem 0.55rem; }
-        #welcome .caps { height: 2.7rem; }
-        #welcome .t-name { margin-top: 0.4rem; }
-        #welcome .orbit-hint { margin-top: 0.55rem; }
-        #welcome .extras { grid-template-columns: 1fr; gap: 0.5rem; margin-top: 1rem; padding-top: 0.9rem; }
-        #welcome .x-label { display: inline; margin-right: 0.45rem; }
-        #welcome .cta { margin-top: 1.1rem; }
-      }
-      /* Short laptop viewports: shave vertical rhythm so it never scrolls */
-      @media (max-height: 760px) {
-        #welcome .logo-head { width: 4.8rem; }
-        #welcome .card { padding-top: 1.7rem; }
-        #welcome .title { margin-top: 0.6rem; font-size: 1.25rem; }
-        #welcome .tagline { margin-top: 0.6rem; }
-        #welcome .section-label { margin: 1.1rem 0 0.7rem; }
-        #welcome .extras { margin-top: 1rem; padding-top: 0.9rem; }
-        #welcome .cta { margin-top: 1.1rem; }
-      }
-      #brand { cursor: pointer; }
+        #welcome .wbrand-head { height: 2.4rem; }
+        #welcome .wbrand-name { font-size: 1.3rem; }
+        #welcome .title { font-size: 2rem; }
+        #welcome .tagline { font-size: 0.95rem; }
+        #welcome .grid { grid-template-columns: repeat(2, 1fr); }
+        #welcome .tile { padding: 0.65rem 0.35rem 0.6rem; }
+        #welcome .caps { height: 2.8rem; }
+        #welcome .wbtn { font-size: 0.95rem; padding: 0.75rem 1.5rem; }
+      }
+      @media (max-height: 700px) {
+        #welcome .tagline { margin-top: 0.85rem; }
+        #welcome .foot { margin-top: 1.1rem; }
+      }
     </style>
   </head>
   <body>
+    <div id="preboot" aria-hidden="true"><div class="spin"></div></div>
     <div id="scene"></div>
     <div class="halftone"></div>
-    <div id="brand">
-      <b>Microduck</b> &middot; real trained policies<br />
-      <span class="sub">MuJoCo + ONNX, live in your browser</span>
+    <!-- CRT overlay: each child is one effect; delete a div together with
+         its CSS block in <style> to drop that effect. -->
+    <div id="crt" aria-hidden="true">
+      <div class="crt-scanlines"></div>
+      <div class="crt-noise"></div>
+      <div class="crt-vignette"></div>
+    </div>
+    <button type="button" id="back-btn">&larr; Back</button>
+    <div id="quickbar">
+      <div class="dots" id="quick-colors" role="group" aria-label="Duck colours"></div>
+      <div class="seg" id="quick-loco" role="group" aria-label="Locomotion mode">
+        <button type="button" data-loco="legs" class="on" aria-pressed="true">Legs</button>
+        <button type="button" data-loco="rollers" aria-pressed="false">Rollers</button>
+      </div>
+    </div>
+    <div id="mode-wrap">
+      <span class="caption">Mode</span>
+      <div class="mode" id="mode-label"><span class="mode-text">Run</span></div>
     </div>
     <div id="stats-wrap">
       <div class="osd-top">
         <span class="osd-rec"><span class="rec-dot">&#9679;</span>&nbsp;REC</span>
         <span id="osd-time">&#9654; 00:00:00</span>
       </div>
-      <div class="mode" id="mode-label"><span class="mode-text">Run</span></div>
-      <div id="stats"></div>
+      <canvas id="minimap" width="264" height="264" aria-hidden="true"></canvas>
       <div id="osd-load" hidden>LOADING ROLLERS<span class="osd-load-cursor">&#9608;</span></div>
     </div>
+    <div id="ctrl-hz"></div>
     <div id="hud" hidden>
       <div class="stack">
         <span class="caption">Colour</span>
@@ -646,109 +925,263 @@
     </div>
     <div id="loading"><div class="post"></div></div>
 
-    <div id="welcome" hidden>
-      <div class="card" role="dialog" aria-modal="true" aria-label="Microduck playground">
-        <header>
-          <div class="logo-head">
-            <img class="closed" id="logo-head-closed" alt="Microduck" />
-            <img class="open" id="logo-head-open" alt="" aria-hidden="true" />
-          </div>
-          <h1 class="title">Microduck</h1>
-          <div class="subtitle">RL playground</div>
-          <p class="tagline">
-            Real physics, real trained neural policies, running live in
-            your browser fifty times a second.
-          </p>
-        </header>
-        <section aria-label="Controls">
-          <div class="section-label">Controls</div>
-          <div class="grid">
-            <div class="tile">
-              <div class="caps cluster">
-                <span class="krow"><kbd>&uarr;</kbd></span>
-                <span class="krow"><kbd>&larr;</kbd><kbd>&darr;</kbd><kbd>&rarr;</kbd></span>
-              </div>
-              <div class="t-name">Move</div>
-              <div class="t-hint">arrows or ZQSD</div>
-            </div>
-            <div class="tile">
-              <div class="caps"><span class="krow"><kbd>A</kbd><kbd>E</kbd></span></div>
-              <div class="t-name">Kick</div>
-              <div class="t-hint">left / right</div>
-            </div>
-            <div class="tile">
-              <div class="caps"><kbd>R</kbd></div>
-              <div class="t-name">Roll</div>
-              <div class="t-hint">barrel roll</div>
-            </div>
-            <div class="tile">
-              <div class="caps"><kbd>B</kbd></div>
-              <div class="t-name">Ball</div>
-              <div class="t-hint">pop one in</div>
-            </div>
-            <div class="tile">
-              <div class="caps"><kbd>C</kbd></div>
-              <div class="t-name">Camera</div>
-              <div class="t-hint">toggle chase</div>
-            </div>
-            <div class="tile">
-              <div class="caps"><kbd>Space</kbd></div>
-              <div class="t-name">Reset</div>
-              <div class="t-hint">fresh start</div>
+    <div id="welcome" hidden role="dialog" aria-modal="true" aria-label="Microduck">
+      <div class="wstep" id="wstep-0">
+        <div class="wbrand" aria-hidden="true">
+          <span class="wbrand-head">
+            <img class="duck-closed" id="wbrand-head-closed" alt="" />
+            <img class="duck-open" id="wbrand-head-open" alt="" />
+          </span>
+          <span class="wbrand-name">MicroDuck</span>
+        </div>
+        <div class="facts">
+          <span>$399</span>
+          <span>Ships before Christmas 2026</span>
+        </div>
+        <h1 class="title">A tiny biped you drive in the browser</h1>
+        <p class="tagline">Same body, same policies as the real robot.</p>
+        <div class="grid grid-kb">
+          <div class="tile">
+            <div class="caps cluster">
+              <span class="krow"><kbd>&uarr;</kbd></span>
+              <span class="krow"><kbd>&larr;</kbd><kbd>&darr;</kbd><kbd>&rarr;</kbd></span>
             </div>
+            <div class="t-name">Move</div>
+            <div class="t-hint">arrows or ZQSD</div>
+          </div>
+          <div class="tile">
+            <div class="caps"><span class="krow"><kbd>A</kbd><kbd>E</kbd></span></div>
+            <div class="t-name">Kick</div>
+            <div class="t-hint">left / right</div>
+          </div>
+          <div class="tile">
+            <div class="caps"><kbd>R</kbd></div>
+            <div class="t-name">Roll</div>
+            <div class="t-hint">barrel roll</div>
+          </div>
+          <div class="tile">
+            <div class="caps"><kbd>B</kbd></div>
+            <div class="t-name">Ball</div>
+            <div class="t-hint">pop one in</div>
+          </div>
+          <div class="tile">
+            <div class="caps"><kbd>C</kbd></div>
+            <div class="t-name">Camera</div>
+            <div class="t-hint">toggle chase</div>
+          </div>
+          <div class="tile">
+            <div class="caps"><kbd>Space</kbd></div>
+            <div class="t-name">Reset</div>
+            <div class="t-hint">fresh start</div>
+          </div>
+        </div>
+        <div class="grid grid-pad">
+          <div class="tile">
+            <div class="caps"><kbd>LS</kbd></div>
+            <div class="t-name">Move</div>
+            <div class="t-hint">left stick</div>
+          </div>
+          <div class="tile">
+            <div class="caps"><span class="krow"><kbd>LB</kbd><kbd>RB</kbd></span></div>
+            <div class="t-name">Kick</div>
+            <div class="t-hint">left / right</div>
+          </div>
+          <div class="tile">
+            <div class="caps"><kbd>X</kbd></div>
+            <div class="t-name">Roll</div>
+            <div class="t-hint">barrel roll</div>
           </div>
-          <div class="orbit-hint">drag to orbit &middot; scroll to zoom &middot; <b>M</b> swaps legs for roller skates</div>
-        </section>
-        <section class="extras">
-          <div class="x-item">
-            <span class="x-label">Gamepad</span>
-            Plug one in, same mapping as the real robot.
+          <div class="tile">
+            <div class="caps"><kbd>Y</kbd></div>
+            <div class="t-name">Ball</div>
+            <div class="t-hint">pop one in</div>
           </div>
-          <div class="x-item">
-            <span class="x-label">Live ghosts</span>
-            Other visitors appear as translucent ducks.
+          <div class="tile">
+            <div class="caps"><kbd>RS</kbd></div>
+            <div class="t-name">Camera</div>
+            <div class="t-hint">orbit</div>
+          </div>
+          <div class="tile">
+            <div class="caps"><kbd>&darr;</kbd></div>
+            <div class="t-name">Sit</div>
+            <div class="t-hint">stand up</div>
           </div>
-        </section>
-        <div class="cta">
-          <button id="welcome-go">Waddle in</button>
         </div>
-        <div class="fineprint">click the title anytime to see this again</div>
+        <p class="orbit-hint kb-hint">drag to orbit &middot; scroll to zoom</p>
+        <p class="orbit-hint pad-hint">R3 chase &middot; RT quack</p>
+      </div>
+
+      <div class="foot">
+        <button type="button" class="wbtn" id="welcome-cta">Waddle in</button>
       </div>
     </div>
 
     <script>
-      // Welcome modal: shown on every load, dismissible by button, Escape
-      // or clicking the blurred backdrop. The top-left brand reopens it.
+      // Single-page title / pause menu: pitch + controls + CTA. The first
+      // "Waddle in" cues the BIOS; later Esc / the in-game Menu button
+      // reopen it as pause. The in-game quickbar (bottom-left) picks the
+      // colour and locomotion live: colour clicks the hidden #swatches
+      // buttons, loco goes through rl.setLoco via a small reconciler that
+      // retries until the game allows the switch (mid-roll, respawn, ...).
       (() => {
         const modal = document.getElementById("welcome");
-        // Logo images need the same ?__sign JWT as every other subresource
-        // on the private Space (rl.js hasn't installed its signer yet).
         const sign = new URLSearchParams(location.search).get("__sign");
         const signedUrl = (u) => (sign ? `${u}?__sign=${encodeURIComponent(sign)}` : u);
-        document.getElementById("logo-head-closed").src = signedUrl("./assets/duck-head-mark.webp");
-        document.getElementById("logo-head-open").src = signedUrl("./assets/duck-head-mark-open.webp");
+        document.getElementById("wbrand-head-closed").src = signedUrl("./assets/duck-head-mark.webp");
+        document.getElementById("wbrand-head-open").src = signedUrl("./assets/duck-head-mark-open.webp");
+
+        const cta = document.getElementById("welcome-cta");
+
+        // ── Quickbar: colour + locomotion, applied live ─────────────────
+        const want = { color: "classic", loco: "legs" };
+        const gameSwatch = (name) =>
+          document.querySelector(`#swatches button[aria-label="${name} colours"]`);
+        const reconcile = () => {
+          let done = true;
+          const g = gameSwatch(want.color);
+          if (g) {
+            syncDotColors();
+            if (!g.classList.contains("on")) g.click();
+          } else done = false;
+          const rl = window.rl;
+          if (rl) {
+            if (want.loco === "rollers") rl.ensureRollers().catch(() => {});
+            if (rl.loco !== want.loco) {
+              done = false;
+              if (!rl.locoSwitching) rl.setLoco(want.loco);
+            }
+          } else if (want.loco !== "legs") done = false;
+          return done;
+        };
+        let reconciler = null;
+        const kick = () => {
+          if (reconciler || reconcile()) return;
+          reconciler = setInterval(() => {
+            if (reconcile()) { clearInterval(reconciler); reconciler = null; }
+          }, 250);
+        };
+
+        const DOTS = { classic: "#ff7a2f", charcoal: "#2f2f33", purple: "#7a5fc9", blue: "#6f9ec4" };
+        const dotsEl = document.getElementById("quick-colors");
+        const dotBtns = new Map();
+        for (const [name, hex] of Object.entries(DOTS)) {
+          const b = document.createElement("button");
+          b.type = "button";
+          b.setAttribute("aria-label", `${name} colours`);
+          const dot = document.createElement("span");
+          dot.className = "dot";
+          dot.style.background = hex;
+          b.appendChild(dot);
+          b.addEventListener("click", () => { want.color = name; syncPickers(); kick(); });
+          dotsEl.appendChild(b);
+          dotBtns.set(name, b);
+        }
+        const syncDotColors = () => {
+          for (const [name, b] of dotBtns) {
+            const g = gameSwatch(name);
+            if (g) b.querySelector(".dot").style.background = g.style.background;
+          }
+        };
+
+        const segBtns = [...document.querySelectorAll("#quick-loco button")];
+        for (const b of segBtns) {
+          b.addEventListener("click", () => { want.loco = b.dataset.loco; syncPickers(); kick(); });
+        }
+        const syncPickers = () => {
+          for (const [name, b] of dotBtns) {
+            b.classList.toggle("on", name === want.color);
+            b.setAttribute("aria-pressed", String(name === want.color));
+          }
+          for (const b of segBtns) {
+            b.classList.toggle("on", b.dataset.loco === want.loco);
+            b.setAttribute("aria-pressed", String(b.dataset.loco === want.loco));
+          }
+        };
+        syncPickers();
+        // Reflect game-side switches (M key, pad hold) back into the bar.
+        setInterval(() => {
+          if (reconciler) return;
+          const on = document.querySelector("#swatches button.on");
+          if (on) want.color = (on.getAttribute("aria-label") || "").split(" ")[0] || want.color;
+          if (window.rl && !window.rl.locoSwitching) want.loco = window.rl.loco;
+          syncDotColors();
+          syncPickers();
+        }, 500);
+
+        const pollPad = () => {
+          const gp = [...(navigator.getGamepads?.() ?? [])].find((p) => p && p.connected);
+          document.body.classList.toggle("pad-connected", !!gp);
+        };
+        window.addEventListener("gamepadconnected", pollPad);
+        window.addEventListener("gamepaddisconnected", pollPad);
+        pollPad();
+
+        // ── Menu open / close ────────────────────────────────────────────
         const open = () => {
           modal.hidden = false;
           modal.classList.remove("closing");
+          document.body.classList.add("welcome-open");
+          document.dispatchEvent(new CustomEvent("microduck:menu-open"));
+          cta.textContent = window.__microduckEntered ? "Resume" : "Waddle in";
         };
         const close = () => {
           modal.classList.add("closing");
+          document.body.classList.remove("welcome-open");
+          document.dispatchEvent(new CustomEvent("microduck:menu-close"));
           setTimeout(() => { modal.hidden = true; }, 380);
-          // First dismissal only: cue the BIOS boot replay in rl.js. The
-          // flag covers the race where the user enters before the module
-          // has finished evaluating.
           if (!window.__microduckEntered) {
             window.__microduckEntered = true;
             document.dispatchEvent(new CustomEvent("microduck:enter"));
           }
         };
-        open();
-        document.getElementById("welcome-go").addEventListener("click", close);
-        modal.addEventListener("click", (e) => { if (e.target === modal) close(); });
+
+        // Pre-boot veil: hold the title page until its logo and the fonts
+        // are in (grey spinner meanwhile), capped so a broken asset can
+        // never wall the menu off.
+        const preboot = document.getElementById("preboot");
+        const dropPreboot = () => {
+          preboot.classList.add("off");
+          setTimeout(() => preboot.remove(), 300);
+        };
+        if (new URLSearchParams(location.search).get("boot") === "1") {
+          modal.hidden = true;
+          window.__microduckEntered = true;
+          dropPreboot();
+          document.dispatchEvent(new CustomEvent("microduck:enter"));
+        } else {
+          const headImg = document.getElementById("wbrand-head-closed");
+          const imgReady = new Promise((res) => {
+            if (headImg.complete && headImg.naturalWidth) res();
+            else {
+              headImg.addEventListener("load", res, { once: true });
+              headImg.addEventListener("error", res, { once: true });
+            }
+          });
+          const fontsReady = document.fonts?.ready ?? Promise.resolve();
+          const cap = new Promise((res) => setTimeout(res, 2500));
+          Promise.race([Promise.all([imgReady, fontsReady]), cap]).then(() => {
+            open();
+            dropPreboot();
+          });
+        }
+        cta.addEventListener("click", close);
+        document.getElementById("back-btn").addEventListener("click", open);
+        const biosUp = () => document.getElementById("loading")?.style.display === "flex";
         window.addEventListener("keydown", (e) => {
-          if (e.code === "Escape" && !modal.hidden) close();
+          if (e.code === "Enter" && !modal.hidden) {
+            if (e.target instanceof HTMLButtonElement && e.target !== cta) return;
+            e.preventDefault();
+            close();
+            return;
+          }
+          if (e.code !== "Escape") return;
+          if (biosUp()) return;
+          if (!modal.hidden) {
+            if (window.__microduckEntered) close();
+            return;
+          }
+          if (window.__microduckEntered) open();
         });
-        document.getElementById("brand").addEventListener("click", open);
       })();
     </script>
 
@@ -764,7 +1197,7 @@
          appended: a plain src attribute can 401 when the browser blocks the
          *.static.hf.space auth cookie inside the hub iframe. -->
     <script type="module">
-      const V = "35"; // bump on rl.js changes to defeat heuristic caching
+      const V = "65"; // bump on rl.js changes to defeat heuristic caching
       const sign = new URLSearchParams(location.search).get("__sign");
       const suffix = sign ? `&__sign=${encodeURIComponent(sign)}` : "";
       import(`./rl.js?v=${V}${suffix}`);

rl.js

@@ -46,8 +46,16 @@ window.__hfSigned = signed; // duck.js uses it for kinematics + STL requests
 const SELF_V = new URL(import.meta.url).searchParams.get("v") ?? "0";
 const { buildRig, cloneRig, loadKinematics, setJoint, setJawOpen, MODEL_DIR, MESH_VERSION } =
   await import(signed(`./duck.js?v=${SELF_V}`));
-const { VARIANTS, VARIANT_NAMES, materialHookFor, randomVariantName, applyVariant, specToHex } =
+const { VARIANTS, VARIANT_NAMES, materialHookFor, DEFAULT_VARIANT, applyVariant, specToHex } =
   await import(signed(`./variants.js?v=${SELF_V}`));
+// Input stack: a video-game-style Controller aggregating pluggable sources
+// (keyboard + gamepad today, touch later). controller.js documents the
+// source interface contract and the action vocabulary.
+const [{ Controller }, { KeyboardSource }, { GamepadSource }] = await Promise.all([
+  import(signed(`./controls/controller.js?v=${SELF_V}`)),
+  import(signed(`./controls/keyboard.js?v=${SELF_V}`)),
+  import(signed(`./controls/gamepad.js?v=${SELF_V}`)),
+]);
 
 ort.env.wasm.wasmPaths = "https://cdn.jsdelivr.net/npm/onnxruntime-web@1.27.0/dist/";
 ort.env.wasm.numThreads = 1; // static hosting sends no COOP/COEP headers
@@ -93,8 +101,11 @@ const CTRL_DT = TIMESTEP * DECIMATION; // 50 Hz
 // No strafe input anymore: the lateral cmd slot stays zeroed for the obs.
 const VEL_FWD = 0.25, VEL_BACK = -0.2, VEL_ANG = 1.0;
 // Roller mode limits, from the runtime's roller branch: asymmetric vx
-// (0.6 push / 0.5 brake), no lateral, +-1.0 rad/s heading.
-const RVEL_FWD = 0.6, RVEL_BACK = -0.5, RVEL_ANG = 1.0;
+// (0.6 push / 0.5 brake), no lateral. The real runtime launches rollers
+// with --max-angular-vel 0.3: faster commanded turns tip the robot over,
+// so the playground clamps wz the same way (keyboard and pad both go
+// through velLims).
+const RVEL_FWD = 0.6, RVEL_BACK = -0.5, RVEL_ANG = 0.3;
 // Crouch-glide one-shot: command = [cos(2pi*phase), sin(2pi*phase), 0],
 // phase advancing at 1/CROUCH_PERIOD_S per second and the cycle exiting
 // at 0.7 - exactly the runtime's ground-pick slot the policy was trained
@@ -111,11 +122,22 @@ const BALL_PARK_POS = "50 0 0.05";
 const ARENA_HALF = 1.5; // inner half-size, m
 const ARENA_WALL_H = 0.25;
 const ARENA_WALL_T = 0.05;
+// Section grid: 5 cells across the 3 m arena (ODD, so a true middle
+// column/row of cells exists; the lattice is shifted half a cell in the
+// shaders so the walls land exactly on section lines).
+const GRID_SECTION = (2 * ARENA_HALF) / 5; // 0.6 m
+// Spawn: center of the middle section cell in the SECOND ROW FROM THE
+// BACK wall. The duck faces +X (identity freejoint quat, walks toward
+// local +X), so "back" is the -X wall: row centers sit at x = -1.2,
+// -0.6, 0, 0.6, 1.2 -> second row is -0.6; middle column is y = 0.
+// MJCF coordinates (three.js: x -> x, y -> -z).
+const SPAWN_X = -ARENA_HALF + 1.5 * GRID_SECTION; // -0.6
+const SPAWN_Y = 0;
 
 const mount = document.getElementById("scene");
 const loadingEl = document.getElementById("loading");
 const hudEl = document.getElementById("hud");
-const statsEl = document.getElementById("stats");
+const ctrlHzEl = document.getElementById("ctrl-hz");
 const osdTimeEl = document.getElementById("osd-time");
 
 // BIOS/POST boot readout. The real load runs silently behind the welcome
@@ -124,16 +146,27 @@ const osdTimeEl = document.getElementById("osd-time");
 // finished, or an honest live tracker (cursor blinking on the pending
 // line) when the user enters mid-load. Never slows the actual boot.
 const postEl = loadingEl.querySelector(".post");
-const bootLog = []; // { label, status, raw, el } - status null = pending
-const lineText = (e) =>
-  e.raw || e.status === null ? e.label : `${e.label} `.padEnd(26, ".") + ` ${e.status}`;
+const bootLog = []; // { label, status, raw, halt, progress, el } - status null = pending
+const lineText = (e) => {
+  if (e.raw) return e.label;
+  // Pending line: bare label, plus a live counter when the stage reports
+  // progress (e.g. "LOADING POLICIES [3/5]").
+  if (e.status === null) return e.progress ? `${e.label} [${e.progress}]` : e.label;
+  return `${e.label} `.padEnd(26, ".") + ` ${e.status}`;
+};
 const bootLine = (label) => {
-  const entry = { label, status: null, raw: false, el: null };
+  const entry = { label, status: null, raw: false, el: null, progress: null };
   bootLog.push(entry);
-  return (status = "OK") => {
+  const done = (status = "OK") => {
     entry.status = status;
     if (entry.el) entry.el.textContent = lineText(entry);
   };
+  // Live sub-progress while the stage is still pending (honest path).
+  done.progress = (p) => {
+    entry.progress = p;
+    if (entry.el && entry.status === null) entry.el.textContent = lineText(entry);
+  };
+  return done;
 };
 // Plain line with no dotted leader (header / error text).
 const bootNote = (label) => {
@@ -144,8 +177,27 @@ bootLine("MEMORY CHECK")("640K OK");
 bootLine("DUCK FIRMWARE")("PRESENT");
 
 let bootDone = false;
+let bootFailed = false;
 let biosStarted = false;
 const biosSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+// Fatal boot failure: freeze the sequence on the console. The BIOS never
+// prints READY, never fades out and never cues the entrance - the halt
+// screen IS the diagnostic surface. The welcome modal (if still up) is
+// dropped so the console isn't stuck behind its blur.
+function bootHalt(detail) {
+  if (bootFailed || bootDone) return;
+  bootFailed = true;
+  bootNote(`>> ${detail}`);
+  bootLog.push({ label: "SYSTEM HALTED", status: "", raw: true, el: null, halt: true });
+  const modal = document.getElementById("welcome");
+  if (modal) modal.hidden = true;
+  playBios();
+}
+// Seeded LCG: the replay rhythm is random-feeling but identical on every
+// load - real POST screens burst through most checks and stall on a few.
+// Seed picked so the draw reads burst/burst/burst/stall/burst/stall.
+let biosSeed = 11;
+const biosRand = () => (biosSeed = (biosSeed * 1103515245 + 12345) & 0x7fffffff) / 0x7fffffff;
 async function playBios() {
   if (biosStarted) return;
   biosStarted = true;
@@ -155,28 +207,68 @@ async function playBios() {
     if (i < bootLog.length) {
       const entry = bootLog[i++];
       entry.el = document.createElement("div");
-      entry.el.textContent = lineText(entry);
+      if (entry.halt) entry.el.className = "halt";
       postEl.appendChild(entry.el);
-      // Honest mode: hold on a stage still in flight (its completer will
-      // fill in the status), cursor blinking on it via CSS.
-      while (entry.status === null && !bootDone) await biosSleep(60);
-      await biosSleep(105); // rapid-fire pacing for finished lines
+      if (entry.status === null && !bootDone && !bootFailed) {
+        // Honest mode: show the stage label and hold while it's really in
+        // flight (its completer fills the status and .progress() updates
+        // the live counter), cursor blinking via CSS.
+        entry.el.textContent = lineText(entry);
+        while (entry.status === null && !bootDone && !bootFailed) {
+          await biosSleep(60);
+          entry.el.textContent = lineText(entry); // live [n/m] counter
+        }
+        await biosSleep(90);
+        entry.el.textContent = lineText(entry);
+      } else if (entry.raw || entry.status === null) {
+        // Header / note lines: quick, no dotted leader to animate.
+        entry.el.textContent = lineText(entry);
+        await biosSleep(20 + 60 * biosRand());
+      } else {
+        // Finished check: bursty POST pacing. Most lines snap in nearly
+        // instantly; the occasional one stalls on a "slow check" - and on
+        // a stall the dotted leader types out one dot at a time before
+        // the status lands.
+        const r = biosRand();
+        const stall = r < 0.75 ? 20 * biosRand() : 150 + 250 * biosRand();
+        if (stall < 45) {
+          entry.el.textContent = lineText(entry);
+          await biosSleep(stall);
+        } else {
+          const prefix = `${entry.label} `;
+          const nDots = Math.max(26 - prefix.length, 3);
+          entry.el.textContent = prefix;
+          const per = stall / nDots;
+          for (let d = 0; d < nDots; d++) {
+            await biosSleep(per);
+            entry.el.textContent += ".";
+          }
+          await biosSleep(40);
+          entry.el.textContent = lineText(entry);
+        }
+      }
     } else if (bootDone) {
       break;
     } else {
-      await biosSleep(60); // waiting for the next real stage
+      // Waiting for the next real stage. On a failed boot this parks the
+      // console forever: everything queued (FAIL line, error detail,
+      // SYSTEM HALTED) has been printed and nothing more will come.
+      await biosSleep(bootFailed ? 500 : 60);
     }
   }
   const ready = document.createElement("div");
   ready.textContent = "READY.";
   postEl.appendChild(ready);
   await biosSleep(500);
-  // Cue the world draw-in + duck dissolve right as the overlay fades.
-  // (Only ever reached after bootDone, so the scene exists by now.)
-  startEntrance();
   loadingEl.classList.add("off");
+  // Wait out the overlay's 0.45 s opacity transition BEFORE cueing the
+  // draw-in: starting it under the fading overlay hides the first (and
+  // busiest) part of the animation and only the tail end shows.
   await biosSleep(500);
   loadingEl.style.display = "none";
+  // Cue the world draw-in + duck scan-up on a fully black screen.
+  // (Only ever reached after bootDone, so the ceremony module exists.)
+  ceremony.startEntrance();
 }
 // Only the initial entry triggers the replay; reopening the modal from
 // the brand later never replays (biosStarted latches).
@@ -184,22 +276,32 @@ if (window.__microduckEntered) playBios();
 else document.addEventListener("microduck:enter", () => playBios(), { once: true });
 
 // Surface boot failures on the page itself: a rejected top-level await
-// otherwise leaves a dead page with no visible error.
+// otherwise leaves a dead page with no visible error. Gated on the boot
+// still being in flight: post-boot async noise (ghost relay hiccups,
+// audio autoplay rejections...) must NOT cue the BIOS replay early
+// behind the welcome modal - that replay belongs to the "Waddle in"
+// click alone. Boot-time errors route into the SYSTEM HALTED screen.
 window.addEventListener("unhandledrejection", (e) => {
-  const msg = e.reason?.stack || e.reason?.message || String(e.reason);
-  bootNote(`Boot failed: ${msg}`);
-  playBios();
   console.error("[rl] unhandled rejection", e.reason);
+  bootHalt(e.reason?.message || String(e.reason));
 });
 window.addEventListener("error", (e) => {
-  bootNote(`Boot failed: ${e.message}`);
-  playBios();
+  console.error("[rl] window error", e.message);
+  bootHalt(e.message);
 });
+// Halting at the failure site rather than relying on unhandledrejection:
+// a rejected top-level await only surfaces through the dynamic import()
+// chain in index.html, which does NOT reliably fire the window handler.
 const traced = (label, p) => {
   const done = bootLine(label);
   return p.then(
     (v) => { done("OK"); return v; },
-    (err) => { done("FAIL"); console.error(`[rl] ${label} FAILED`, err); throw err; },
+    (err) => {
+      done("FAILED");
+      console.error(`[rl] ${label} FAILED`, err);
+      bootHalt(err?.message || String(err));
+      throw err;
+    },
   );
 };
 
@@ -275,7 +377,7 @@ async function buildPhysicsXml(xmlFile) {
   // wheels) starts at zero. The ball's 7 free-joint values MUST be
   // appended or nq won't match and the model won't compile; parked 50 m
   // away = effectively absent.
-  const qposFree = "0 0 0.12 1 0 0 0";
+  const qposFree = `${SPAWN_X} ${SPAWN_Y} 0.12 1 0 0 0`;
   const poseByName = new Map(JOINT_NAMES.map((n, i) => [n, DEFAULT_POSE[i]]));
   const qposJoints = [...doc.querySelectorAll("body > joint")]
     .map((j) => poseByName.get(j.getAttribute("name")) ?? 0)
@@ -317,32 +419,67 @@ async function addMeshesToVfs(files) {
     }),
   );
 }
-await addMeshesToVfs(meshFiles);
+try {
+  await addMeshesToVfs(meshFiles);
+} catch (err) {
+  doneMeshes("FAILED");
+  bootHalt(err?.message || String(err));
+  throw err;
+}
 doneMeshes(`${meshFiles.length} FILES`);
 
 const sessions = {};
-let currentVariant = randomVariantName();
+// Always boot on the classic (orange) colourway; the swatches re-skin live.
+let currentVariant = DEFAULT_VARIANT;
 const rigPromise = (async () => {
   const doneRig = bootLine("RENDER RIG");
-  const rig = await buildRig(k, { materialForMesh: materialHookFor(VARIANTS[currentVariant]) });
-  doneRig("OK");
-  return rig;
+  try {
+    const rig = await buildRig(k, { materialForMesh: materialHookFor(VARIANTS[currentVariant]) });
+    doneRig("OK");
+    return rig;
+  } catch (err) {
+    doneRig("FAILED");
+    bootHalt(err?.message || String(err));
+    throw err;
+  }
 })();
+// Boot policies with a live [n/5] counter on the BIOS line; any single
+// session failure marks the whole line FAILED (the halt detail line names
+// the actual error).
 const donePolicies = bootLine("LOADING POLICIES");
 const sessionOpts = { executionProviders: ["wasm"] };
-[sessions.walk, sessions.sitstand, sessions.roll, sessions.kickL, sessions.kickR] =
-  await Promise.all([
-    ort.InferenceSession.create(signed(POLICIES.walk), sessionOpts),
-    ort.InferenceSession.create(signed(POLICIES.sitstand), sessionOpts),
-    ort.InferenceSession.create(signed(POLICIES.roll), sessionOpts),
-    ort.InferenceSession.create(signed(POLICIES.kickL), sessionOpts),
-    ort.InferenceSession.create(signed(POLICIES.kickR), sessionOpts),
-  ]);
+let policiesLoaded = 0;
+const bootPolicy = (url) =>
+  ort.InferenceSession.create(signed(url), sessionOpts).then((s) => {
+    donePolicies.progress(`${++policiesLoaded}/5`);
+    return s;
+  });
+try {
+  [sessions.walk, sessions.sitstand, sessions.roll, sessions.kickL, sessions.kickR] =
+    await Promise.all([
+      bootPolicy(POLICIES.walk),
+      bootPolicy(POLICIES.sitstand),
+      bootPolicy(POLICIES.roll),
+      bootPolicy(POLICIES.kickL),
+      bootPolicy(POLICIES.kickR),
+    ]);
+} catch (err) {
+  donePolicies("FAILED");
+  bootHalt(err?.message || String(err));
+  throw err;
+}
 donePolicies("5/5");
 
 const doneCompile = bootLine("COMPILING PHYSICS");
-let model = mujoco.MjModel.from_xml_string(xml, vfs);
-let data = new mujoco.MjData(model);
+let model, data;
+try {
+  model = mujoco.MjModel.from_xml_string(xml, vfs);
+  data = new mujoco.MjData(model);
+} catch (err) {
+  doneCompile("FAILED");
+  bootHalt(err?.message || String(err));
+  throw err;
+}
 doneCompile("COMPILED");
 
 // Addresses resolved once per compiled variant. qpos/qvel/sensordata views
@@ -382,25 +519,35 @@ let uiReady = false;
 const lastAction = new Float32Array(NUM_JOINTS);
 const obs = new Float32Array(OBS_SIZE);
 const cmd = new Float32Array(CMD_SIZE); // [vx, vy, wz, head(4), body(6)]
-const velCmd = new Float32Array(3); // twist command, driven by held keys
-// Gamepad twist (EMA-smoothed like the robot runtime). Declared up here:
-// the control loop reads it before the input section below has evaluated.
-const padCmd = new Float32Array(3);
-let padActive = false;
-const padPrev = {
-  x: false, y: false, rb: false, lb: false, r3: false, dpadDown: false,
-  dpadUp: false, dpadUpAt: 0, dpadUpFired: false, rtArmed: true,
-};
-// Right-stick camera state, read by renderStats before the gamepad
-// section below has evaluated (same reason as padCmd above).
+// Input controller (controls/controller.js): keyboard + gamepad sources
+// merged into one continuous command + discrete action surface. Registered
+// in priority order - live pad sticks win over held keys, exactly the old
+// padActive arbitration. Constructed up here because the control loop reads
+// it via effectiveCmd on the very first control step; the sources' event
+// listeners are only armed by controller.init() in the input-wiring
+// section below, where the raw listeners historically attached.
+const kbSource = new KeyboardSource({ getVelocityLimits: () => velLims() });
+const padSource = new GamepadSource({ getVelocityLimits: () => velLims() });
+const controller = new Controller({ sources: [padSource, kbSource] });
+// Right-stick camera state, read by renderStats before the camera-orbit
+// section below has evaluated.
 let padOrbitLive = false; // HUD: RS keycap lit while deflected
-// Declared before the control loop starts: buildObs reads it via
-// effectiveCmd on the very first control step.
-const held = new Set();
 // Robot input gate: twist commands, mode changes, rolls, kicks and ball
 // spawns all stay inert until the entrance sequence has fully played out
-// (updateEntrance flips this exactly when the choreography completes).
+// (ceremony.drive flips this exactly when the choreography completes).
+// Re-engaged by every post-entrance reset for the duck's re-scan.
 let inputLocked = true;
+// Cutscene + ball-actor modules, assigned once the scene exists. Boot
+// resetSim runs before that (physics only); later kills go through these.
+let ceremony = null;
+let ball = null;
+// Comic sticker popups (stickers.js). Nullable on purpose: every hook is a
+// one-line `stickers?.pop(...)`, so deleting the single import line below
+// (search for initStickers) removes the feature without breaking anything.
+let stickers = null;
+// HUD: Space keycap flash. Written by the respawn ceremony; read by
+// renderStats.
+let resetFlashAt = -Infinity;
 
 // "walk" is the main velocity-tracking mode in BOTH variants (legs walking
 // policy or roller drive policy - activeSession() picks); "crouch" is the
@@ -412,8 +559,9 @@ const isKick = () => mode === "kickL" || mode === "kickR";
 // (mesh hidden), true once popped in front of the duck.
 let ballActive = false;
 
-// The twist the policy actually receives: live gamepad sticks win over the
-// held keys. No input means zero command - the duck stands in place.
+// The twist the policy actually receives: the controller's merged command
+// (live gamepad sticks win over held keys via source arbitration). No
+// input means zero command - the duck stands in place.
 // Shared by buildObs and the HUD mini-sticks so they can never disagree.
 // Mid-roll every movement input is ignored (zero twist) until the roll
 // hands back to walk on its own - steering would only knock the roll over.
@@ -421,7 +569,7 @@ const ZERO_CMD = new Float32Array(3);
 function effectiveCmd() {
   if (inputLocked || mode === "roll" || mode === "crouch" || isKick() || postKickLock > 0)
     return ZERO_CMD;
-  return padActive ? padCmd : velCmd;
+  return controller.getCommand();
 }
 // One-shot roll tracking: trigger time + whether the trunk actually
 // tipped over yet. Set by triggerRoll, cleared when we hand back to walk.
@@ -449,13 +597,15 @@ let postKickLock = 0;
 // up handed to the walking policy mid-motion.
 let sitTimer = null;
 let standTimer = null;
+let fallenSince = null; // wall-clock start of the current fallen spell
 function clearModeTimers() {
   clearTimeout(sitTimer); sitTimer = null;
   clearTimeout(standTimer); standTimer = null;
 }
 
 function resetSim() {
-  // A reset is a full transition to the walking stand: cancel any roll in
+  // Single reset path: Space, fall-kill, failed roll, loco switch. A
+  // reset is a full transition to the walking stand: cancel any roll in
   // flight and any pending sit/stand hand-over, or they'd replay on the
   // freshly reset duck.
   clearModeTimers();
@@ -463,16 +613,20 @@ function resetSim() {
   kickRun = null;
   crouchRun = null;
   postKickLock = 0;
+  fallenSince = null;
   mode = "walk";
   mujoco.mj_resetDataKeyframe(model, data, standKeyId);
   mujoco.mj_forward(model, data);
   lastAction.fill(0);
   sitFlag = 0;
-  // The keyframe re-parks the ball 50 m away; reflect that in the flag
-  // so the render loop hides the mesh again.
+  // Park the ball in physics immediately; if it was on screen, the
+  // reverse scan peels it away at its last pose. A queued B-respawn is
+  // cancelled: a reset means no ball.
+  ball?.despawn({ cancelQueued: true, parkPhysics: parkBallPhysics });
   ballActive = false;
   // Buttons reflect sitFlag; keep them honest after auto-resets.
   if (uiReady) syncButtons();
+  ceremony?.playRespawn();
 }
 resetSim();
 
@@ -480,8 +634,31 @@ resetSim();
 // random heading + distance jitter so repeated pops land somewhere
 // nearby instead of always on the same spot. qvel is zeroed so a respawn
 // doesn't carry the old momentum.
-function spawnBall() {
-  if (inputLocked) return;
+// If the ball is already on screen, peel it away first (reverse scan)
+// and pop the new one when that finishes - same appear/disappear pair
+// as the duck's wireframe ceremony.
+function parkBallPhysics() {
+  const qpos = data.qpos, qvel = data.qvel;
+  qpos[ballQposAdr] = 50;
+  qpos[ballQposAdr + 1] = 0;
+  qpos[ballQposAdr + 2] = BALL_RADIUS;
+  qpos[ballQposAdr + 3] = 1;
+  qpos[ballQposAdr + 4] = 0;
+  qpos[ballQposAdr + 5] = 0;
+  qpos[ballQposAdr + 6] = 0;
+  for (let i = 0; i < 6; i++) qvel[ballDofAdr + i] = 0;
+  mujoco.mj_forward(model, data);
+  ballActive = false;
+}
+
+function spawnBall(opts = {}) {
+  if (inputLocked && !opts.fromQueue) return;
+  if (!ball) return;
+  if (ball.visual !== "hidden") {
+    ball.queueRespawn();
+    ball.despawn({ parkPhysics: parkBallPhysics });
+    return;
+  }
   const qpos = data.qpos, qvel = data.qvel;
   // Trunk yaw from the free-joint quaternion (qpos[3..6] = w x y z);
   // the duck walks toward its local +X.
@@ -505,6 +682,11 @@ function spawnBall() {
   for (let i = 0; i < 6; i++) qvel[ballDofAdr + i] = 0;
   mujoco.mj_forward(model, data);
   ballActive = true;
+  // Snap the mesh to the new pose BEFORE the scan starts: the FX
+  // recomputes its bbox from the live mesh.
+  ball.poseFromQpos(qpos, ballQposAdr);
+  ball.appear();
+  stickers?.pop("spawn");
 }
 
 // ── Observation ─────────────────────────────────────────────────────────
@@ -551,7 +733,21 @@ const activeSession = () =>
 
 // ── Control loop (50 Hz, async because ONNX inference is async) ────────
 let ctrlHz = 0;
-let fallenSince = null;
+
+// Dead pose: walk/sitstand have no get-up skill, so a kill here is just
+// a resetSim (same ceremony as Space). Height alone would false-positive
+// on a deep sit, so "fallen" = trunk tilted past ~60 deg (projected
+// gravity z above -0.5) or sunk below the floor. NaN/Inf is a solver
+// explosion: no grace, reset on the spot. The roll tumbles the trunk on
+// purpose and recovers on its own, so it gets a much longer grace window
+// before we call it stuck.
+function poseIsDead() {
+  const z = data.qpos[2];
+  const gz = obs[5]; // projected gravity z, from the last obs
+  if (!Number.isFinite(z) || !Number.isFinite(gz)) return "exploded";
+  if (gz > -0.5 || z < 0.02) return "fallen";
+  return null;
+}
 
 async function controlStep() {
   const feeds = { obs: new ort.Tensor("float32", buildObs(), [1, OBS_SIZE]) };
@@ -562,19 +758,14 @@ async function controlStep() {
   for (let j = 0; j < NUM_JOINTS; j++) ctrl[j] = DEFAULT_POSE[j] + act[j] * ACTION_SCALE;
   for (let s = 0; s < DECIMATION; s++) mujoco.mj_step(model, data);
 
-  // Fall detection: walk/sitstand have no get-up skill, so auto-reset when
-  // down for good. Height alone would false-positive on a deep sit, so
-  // "fallen" = trunk tilted past ~60 deg (projected gravity z above -0.5)
-  // or sunk below the floor, sustained for over a second. The roll tumbles
-  // the trunk on purpose and recovers on its own, so it gets a much longer
-  // grace window before we call it stuck.
-  const z = data.qpos[2];
-  const now = performance.now();
-  const tipped = obs[5] > -0.5; // projected gravity z, from the last obs
-  const graceMs = mode === "roll" ? 5000 : 1000;
-  if (tipped || z < 0.02) {
+  const death = poseIsDead();
+  if (death === "exploded") {
+    resetSim();
+  } else if (death === "fallen") {
+    const now = performance.now();
+    const graceMs = mode === "roll" ? 5000 : 1000;
     fallenSince ??= now;
-    if (now - fallenSince > graceMs) { resetSim(); fallenSince = null; }
+    if (now - fallenSince > graceMs) resetSim();
   } else {
     fallenSince = null;
   }
@@ -636,7 +827,7 @@ async function controlStep() {
       mode = "walk";
       lastAction.fill(0);
       // Timed out mid-roll: don't hand a tipped duck to the walking policy
-      // (it has no get-up skill), restart from the keyframe instead.
+      // (it has no get-up skill). Same ceremony as Space / fall-kill.
       if (!upright) resetSim();
       if (uiReady) syncButtons();
     }
@@ -667,10 +858,13 @@ const scene = new THREE.Scene();
 scene.background = new THREE.Color(0x08080c);
 
 const camera = new THREE.PerspectiveCamera(40, 1, 0.02, 30);
-camera.position.set(0.55, 0.35, 0.7);
+// Boot framing translated onto the spawn cell (the orbit target follows
+// below), so the follow-cam has nothing to drift toward during boot.
+camera.position.set(SPAWN_X + 0.55, 0.35, -SPAWN_Y + 0.7);
 
-const renderer = new THREE.WebGLRenderer({ antialias: true });
+const renderer = new THREE.WebGLRenderer({ antialias: true, alpha: true });
 renderer.setPixelRatio(Math.min(2, window.devicePixelRatio));
+renderer.setClearColor(0x08080c, 1);
 renderer.toneMapping = THREE.ACESFilmicToneMapping;
 mount.appendChild(renderer.domElement);
 
@@ -700,7 +894,7 @@ function makeInfiniteGrid() {
     depthWrite: false,
     uniforms: {
       uCell: { value: 0.1 },
-      uSection: { value: 0.5 },
+      uSection: { value: GRID_SECTION },
       uCellColor: { value: new THREE.Color(0x8e8371) },
       uSectionColor: { value: new THREE.Color(0xffb366) },
       uFadeDist: { value: 3.0 },
@@ -725,32 +919,65 @@ function makeInfiniteGrid() {
       // Tron-style line: a thicker antialiased core plus a faint, much
       // wider halo added on top (squared falloff keeps it a whisper of a
       // glow rather than a bloom wash).
+      float lineProf(float g) {
+        float core = 1.0 - smoothstep(0.0, 1.8, g);
+        float halo = 1.0 - smoothstep(0.0, 7.0, g);
+        return core + halo * halo * 0.22;
+      }
       float gridLine(vec2 p, float size) {
         vec2 r = p / size;
         vec2 g = abs(fract(r - 0.5) - 0.5) / fwidth(r);
-        float d = min(g.x, g.y);
-        float core = 1.0 - smoothstep(0.0, 1.8, d);
-        float halo = 1.0 - smoothstep(0.0, 7.0, d);
-        return core + halo * halo * 0.22;
+        return lineProf(min(g.x, g.y));
+      }
+      // Entrance draw-in: one family of parallel lines, drawn line by line.
+      // id picks the line, "along" runs down its length. Each line waits
+      // out its own hashed delay, then extends from the origin outward with
+      // a hard front. Returns (mask, head): head marks the bright segment
+      // right behind the draw front while the line is still growing.
+      vec2 drawLine(float id, float along, float t0, float spread, float dur, float maxLen) {
+        float jit = fract(sin(id * 127.1) * 43758.5453);
+        float grow = clamp((uReveal - t0 - jit * spread) / dur, 0.0, 1.0);
+        float len = grow * maxLen;
+        float a = abs(along);
+        float mask = 1.0 - smoothstep(len - 0.05, len, a);
+        float head = (1.0 - smoothstep(0.0, 0.6, len - a)) * mask
+                   * step(0.001, grow) * (1.0 - step(0.999, grow));
+        return vec2(mask, head);
       }
       void main() {
         float cell = gridLine(vWorld.xz, uCell);
-        float section = gridLine(vWorld.xz, uSection);
+        // Section lattice shifted half a cell: with 5 sections across the
+        // 3 m arena (odd count) this centers a CELL on the origin and puts
+        // section lines exactly on the walls at +-1.5.
+        vec2 pSec = vWorld.xz + 0.5 * uSection;
+        float section = gridLine(pSec, uSection);
         float d = distance(vWorld.xz, uFocus.xz);
         float fade = pow(clamp(1.0 - d / uFadeDist, 0.0, 1.0), 1.6);
         vec3 col = mix(uCellColor, uSectionColor, clamp(section, 0.0, 1.0));
         float alpha = min(max(section * 0.6, cell * 0.4) * fade, 1.0);
-        // Entrance draw-in: strokes appear radially from the arena center,
-        // each section tile staggered by a hash so lines pop one after
-        // another. Exactly the steady-state shader once uReveal hits 1.
+        // Entrance: only the bright section lines get the line-by-line draw
+        // (staggered, with a hot draw head); the fine cells just fade in
+        // over the reveal's second half - drawing every small line reads as
+        // visual noise. lineProf(min(gx, gy)) == max of per-axis profiles
+        // (profile is monotonic) and the cell fade lands on exactly the
+        // steady-state cell term, so at uReveal 1 this branch equals the
+        // formula above exactly (and is skipped).
         if (uReveal < 1.0) {
-          float rd = length(vWorld.xz) / 6.0;
-          vec2 tile = floor(vWorld.xz / uSection);
-          float jit = fract(sin(dot(tile, vec2(127.1, 311.7))) * 43758.5453);
-          float at = rd * 0.78 + jit * 0.24;
-          // step() clamps the smoothstep tail: center tiles have at < 0.12
-          // and would otherwise stay faintly visible at uReveal = 0.
-          alpha *= smoothstep(at - 0.12, at, uReveal * 1.06) * step(1e-4, uReveal);
+          vec2 rs = pSec / uSection;
+          vec2 gs = abs(fract(rs - 0.5) - 0.5) / fwidth(rs);
+          // Const-x lines run along z and vice versa; the offset
+          // decorrelates the two families' hashed delays.
+          vec2 sx = drawLine(floor(rs.x + 0.5), vWorld.z, 0.00, 0.30, 0.35, 8.0);
+          vec2 sz = drawLine(floor(rs.y + 0.5) + 57.0, vWorld.x, 0.05, 0.30, 0.35, 8.0);
+          float secR = max(lineProf(gs.x) * sx.x, lineProf(gs.y) * sz.x);
+          float cellR = cell * smoothstep(0.5, 1.0, uReveal);
+          float headGlow = max(lineProf(gs.x) * sx.y, lineProf(gs.y) * sz.y);
+          col = mix(uCellColor, uSectionColor, clamp(secR, 0.0, 1.0));
+          alpha = min(max(secR * 0.6, cellR * 0.4) * fade, 1.0);
+          // Bright draw head: a short white-hot tip sells the "drawing" read.
+          headGlow = clamp(headGlow, 0.0, 1.0);
+          col = mix(col, vec3(1.0, 0.86, 0.55), headGlow * 0.8);
+          alpha = min(alpha + headGlow * fade * 0.5, 1.0);
         }
         if (alpha < 0.004) discard;
         gl_FragColor = vec4(col, alpha);
@@ -775,7 +1002,7 @@ function makeWallGridMaterial(alongX) {
     side: THREE.DoubleSide,
     uniforms: {
       uCell: { value: 0.1 },
-      uSection: { value: 0.5 },
+      uSection: { value: GRID_SECTION },
       uCellColor: { value: new THREE.Color(0x8e8371) },
       uSectionColor: { value: new THREE.Color(0xffb366) },
       // Gentler radial fade than the floor: the walls sit 1.5+ m from the
@@ -801,34 +1028,61 @@ function makeWallGridMaterial(alongX) {
       uniform float uCell, uSection, uFadeDist, uWallH, uAlongX, uReveal;
       uniform vec3 uCellColor, uSectionColor, uFocus;
       // Same Tron-style core + faint halo as the floor grid.
+      float lineProf(float g) {
+        float core = 1.0 - smoothstep(0.0, 1.8, g);
+        float halo = 1.0 - smoothstep(0.0, 7.0, g);
+        return core + halo * halo * 0.22;
+      }
       float gridLine(vec2 p, float size) {
         vec2 r = p / size;
         vec2 g = abs(fract(r - 0.5) - 0.5) / fwidth(r);
-        float d = min(g.x, g.y);
-        float core = 1.0 - smoothstep(0.0, 1.8, d);
-        float halo = 1.0 - smoothstep(0.0, 7.0, d);
-        return core + halo * halo * 0.22;
+        return lineProf(min(g.x, g.y));
+      }
+      // Same line-by-line draw as the floor grid (see its comments).
+      vec2 drawLine(float id, float along, float t0, float spread, float dur, float maxLen) {
+        float jit = fract(sin(id * 127.1) * 43758.5453);
+        float grow = clamp((uReveal - t0 - jit * spread) / dur, 0.0, 1.0);
+        float len = grow * maxLen;
+        float a = abs(along);
+        float mask = 1.0 - smoothstep(len - 0.05, len, a);
+        float head = (1.0 - smoothstep(0.0, 0.35, len - a)) * mask
+                   * step(0.001, grow) * (1.0 - step(0.999, grow));
+        return vec2(mask, head);
       }
       void main() {
         // Wall surface coords: the in-plane horizontal world axis + height.
         float h = mix(vWorld.z, vWorld.x, uAlongX);
         vec2 p = vec2(h, vWorld.y);
         float cell = gridLine(p, uCell);
-        float section = gridLine(p, uSection);
+        // Horizontal axis shifted half a section to match the floor's odd
+        // lattice (vertical section lines meet the floor's at the base);
+        // the height axis keeps its base line at y = 0.
+        vec2 pSec = vec2(p.x + 0.5 * uSection, p.y);
+        float section = gridLine(pSec, uSection);
         float d = distance(vWorld.xz, uFocus.xz);
         float fade = pow(clamp(1.0 - d / uFadeDist, 0.0, 1.0), 1.6);
         float vert = 1.0 - clamp(vWorld.y / uWallH, 0.0, 1.0);
         vec3 col = mix(uCellColor, uSectionColor, clamp(section, 0.0, 1.0));
         float alpha = min(max(section * 0.9, cell * 0.6) * fade * (0.3 + 0.7 * vert), 1.0);
-        // Entrance draw-in: wall lines rise bottom-to-top with a per-tile
-        // stagger. Exactly the steady-state shader once uReveal hits 1.
+        // Entrance: section lines only - horizontals zip out from the
+        // wall's center, verticals rise from the ground, each with a
+        // hashed delay; the fine cells fade in over the reveal's second
+        // half. Same steady-state equivalence argument as the floor grid.
         if (uReveal < 1.0) {
-          float hN = clamp(vWorld.y / uWallH, 0.0, 1.0);
-          vec2 tile = floor(p / uSection);
-          float jit = fract(sin(dot(tile, vec2(127.1, 311.7))) * 43758.5453);
-          float at = hN * 0.76 + jit * 0.24;
-          // Same tail clamp as the floor: fully dark until reveal begins.
-          alpha *= smoothstep(at - 0.12, at, uReveal * 1.06) * step(1e-4, uReveal);
+          vec2 rs = pSec / uSection;
+          vec2 gs = abs(fract(rs - 0.5) - 0.5) / fwidth(rs);
+          // Const-height lines run along h (grow from center outward);
+          // const-h lines run along y (grow up from the ground).
+          vec2 sh = drawLine(floor(rs.y + 0.5), p.x, 0.00, 0.30, 0.40, 2.0);
+          vec2 sv = drawLine(floor(rs.x + 0.5) + 31.0, p.y, 0.30, 0.30, 0.30, uWallH);
+          float secR = max(lineProf(gs.y) * sh.x, lineProf(gs.x) * sv.x);
+          float cellR = cell * smoothstep(0.5, 1.0, uReveal);
+          float headGlow = max(lineProf(gs.y) * sh.y, lineProf(gs.x) * sv.y);
+          col = mix(uCellColor, uSectionColor, clamp(secR, 0.0, 1.0));
+          alpha = min(max(secR * 0.9, cellR * 0.6) * fade * (0.3 + 0.7 * vert), 1.0);
+          headGlow = clamp(headGlow, 0.0, 1.0);
+          col = mix(col, vec3(1.0, 0.86, 0.55), headGlow * 0.8);
+          alpha = min(alpha + headGlow * fade * 0.5, 1.0);
         }
         if (alpha < 0.004) discard;
         gl_FragColor = vec4(col, alpha);
@@ -904,27 +1158,25 @@ function activateLoco(name) {
   scene.add(rig.placer);
   document.body.classList.toggle("rollers", name === "rollers");
   resetSim();
-  refreshVelCmd(); // held keys re-map to the new variant's velocity limits
   if (uiReady) syncLocoHints();
 }
 
 // OSD line while the roller stack streams in, BIOS-style.
 let osdLoadEl = null;
 let locoSwitching = false;
-async function toggleLoco() {
-  // No switching mid one-shot (roll/kick/crouch end on their own and a
-  // teardown now would strand their timers), or while already switching.
-  if (locoSwitching || inputLocked || rollRun || kickRun || crouchRun || standTimer) return;
+async function setLoco(name, { force = false } = {}) {
+  if (name !== "legs" && name !== "rollers") return;
+  if (loco === name || locoSwitching) return;
+  if (!force && (inputLocked || rollRun || kickRun || crouchRun || standTimer)) return;
   locoSwitching = true;
   try {
-    const next = loco === "legs" ? "rollers" : "legs";
-    if (next === "rollers" && !locos.rollers) {
+    if (name === "rollers" && !locos.rollers) {
       osdLoadEl?.removeAttribute("hidden");
       await ensureRollers();
     }
-    activateLoco(next);
+    activateLoco(name);
   } catch (e) {
-    rollersLoading = null; // allow a retry on transient fetch failures
+    rollersLoading = null;
     console.error("[rl] roller switch failed", e);
   } finally {
     osdLoadEl?.setAttribute("hidden", "");
@@ -932,119 +1184,24 @@ async function toggleLoco() {
   }
 }
 
-// ── Sci-fi entrance: Tron grid draw-in + duck dissolve-in ───────────────
-// Plays once per page load, right as the BIOS overlay fades (playBios
-// calls startEntrance). Until then the world stays hidden (grids at
-// reveal 0, duck fully dissolved) and every robot input is gated by
-// inputLocked; the sim itself keeps running so the duck stands idle
-// underneath and is mid-stride the moment it finishes materializing.
-// The duck dissolve
-// swaps each rig mesh onto a TEMPORARY clone of its material (the shared
-// matFor cache and ghost cloning stay untouched) and restores the
-// originals when the effect completes, so variants/ghosts behave exactly
-// as before once the sequence is over.
-const dissolveP = { value: 1.0 }; // shared across all dissolve clones
-let dissolveSaved = null; // Array<[mesh, originalMaterial]> while active
-function applyDissolve() {
-  if (dissolveSaved) return;
-  dissolveSaved = [];
-  rig.placer.traverse((o) => {
-    if (!o.isMesh) return;
-    const orig = o.material;
-    const m = orig.clone();
-    m.onBeforeCompile = (shader) => {
-      shader.uniforms.uDissolveP = dissolveP;
-      shader.vertexShader = shader.vertexShader
-        .replace("#include <common>", "#include <common>\nvarying vec3 vDsvW;")
-        .replace(
-          "#include <worldpos_vertex>",
-          "#include <worldpos_vertex>\nvDsvW = (modelMatrix * vec4(transformed, 1.0)).xyz;",
-        );
-      shader.fragmentShader = shader.fragmentShader
-        .replace("#include <common>", /* glsl */ `#include <common>
-varying vec3 vDsvW;
-uniform float uDissolveP;
-float dsvHash(vec3 q) { return fract(sin(dot(q, vec3(127.1, 311.7, 74.7))) * 43758.5453); }
-float dsvNoise(vec3 x) {
-  vec3 i = floor(x), f = fract(x);
-  f = f * f * (3.0 - 2.0 * f);
-  return mix(
-    mix(mix(dsvHash(i), dsvHash(i + vec3(1, 0, 0)), f.x),
-        mix(dsvHash(i + vec3(0, 1, 0)), dsvHash(i + vec3(1, 1, 0)), f.x), f.y),
-    mix(mix(dsvHash(i + vec3(0, 0, 1)), dsvHash(i + vec3(1, 0, 1)), f.x),
-        mix(dsvHash(i + vec3(0, 1, 1)), dsvHash(i + vec3(1, 1, 1)), f.x), f.y), f.z);
-}`)
-        .replace("#include <clipping_planes_fragment>", /* glsl */ `#include <clipping_planes_fragment>
-float dsvEdge = 0.0;
-if (uDissolveP < 1.0) {
-  float dsvN = dsvNoise(vDsvW * 26.0);
-  float dsvThr = uDissolveP * 1.15;
-  if (dsvN > dsvThr) discard;
-  dsvEdge = 1.0 - smoothstep(0.015, 0.1, dsvThr - dsvN);
-}`)
-        .replace("#include <dithering_fragment>", /* glsl */ `#include <dithering_fragment>
-gl_FragColor.rgb += dsvEdge * vec3(0.5, 0.41, 0.12);`);
-    };
-    m.needsUpdate = true;
-    dissolveSaved.push([o, orig]);
-    o.material = m;
-  });
-}
-function restoreDissolve() {
-  if (!dissolveSaved) return;
-  for (const [mesh, orig] of dissolveSaved) {
-    mesh.material.dispose();
-    mesh.material = orig;
-  }
-  dissolveSaved = null;
-}
-// Boot hidden: the duck is fully dissolved from the first rendered frame
-// (the grids already start at uReveal 0), so nothing shows through the
-// welcome modal's blur or during the BIOS replay.
-dissolveP.value = 0;
-applyDissolve();
-
-const ENTRANCE_GRID_S = 1.5; // floor draw-in duration
-const ENTRANCE_WALL_DELAY_S = 0.4; // walls start after the floor
-const ENTRANCE_DISSOLVE_START_S = 0.9; // ~60% through the floor draw
-const ENTRANCE_DISSOLVE_S = 1.0;
-const clamp01 = (x) => Math.min(Math.max(x, 0), 1);
-const easeOutCubic = (x) => 1 - Math.pow(1 - clamp01(x), 3);
-let entranceT0 = null; // wall-clock start while the sequence is playing
-let entranceDone = false; // latches: once per page load
-// Resolved when the entrance completes; gates the ghosts join below so a
-// translucent peer can't float around in the still-hidden world.
-let entranceFinishedResolve;
-const entranceFinished = new Promise((r) => { entranceFinishedResolve = r; });
-function startEntrance() {
-  if (entranceT0 !== null || entranceDone) return;
-  entranceT0 = performance.now();
-  grid.material.uniforms.uReveal.value = 0;
-  for (const m of wallMats) m.uniforms.uReveal.value = 0;
-  dissolveP.value = 0; // duck fully dissolved until its cue
-  applyDissolve();
-}
-function updateEntrance() {
-  if (entranceT0 === null) return;
-  const t = (performance.now() - entranceT0) / 1000;
-  grid.material.uniforms.uReveal.value = easeOutCubic(t / ENTRANCE_GRID_S);
-  const wallR = easeOutCubic((t - ENTRANCE_WALL_DELAY_S) / ENTRANCE_GRID_S);
-  for (const m of wallMats) m.uniforms.uReveal.value = wallR;
-  const dp = clamp01((t - ENTRANCE_DISSOLVE_START_S) / ENTRANCE_DISSOLVE_S);
-  dissolveP.value = dp;
-  if (t >= ENTRANCE_WALL_DELAY_S + ENTRANCE_GRID_S && dp >= 1) {
-    // Park everything in exact steady state, drop the temp materials and
-    // hand control to the user.
-    entranceT0 = null;
-    entranceDone = true;
-    grid.material.uniforms.uReveal.value = 1;
-    for (const m of wallMats) m.uniforms.uReveal.value = 1;
-    restoreDissolve();
-    inputLocked = false;
-    entranceFinishedResolve();
-  }
+async function toggleLoco() {
+  await setLoco(loco === "legs" ? "rollers" : "legs");
 }
 
+// ── Cutscenes (entrance + respawn) ──────────────────────────────────────
+// Owned by ceremony.js. Physics reset stays in resetSim; this is the
+// camera + materialization layer. Boot-hidden: bind parks the duck clip
+// below the feet so nothing shows through the welcome modal / BIOS.
+const fx = await import(signed(`./fx/fx-wireframe.js?v=${SELF_V}`));
+const { createCeremony, CAM_RESET_S } = await import(signed(`./ceremony.js?v=${SELF_V}`));
+ceremony = createCeremony({
+  THREE, scene, camera, renderer, fx,
+  getRig: () => rig,
+  grid, wallMats,
+  syncRig, startCameraReset,
+  setLocked: (v) => { inputLocked = v; controller.setLocked(v); },
+  flashReset: () => { resetFlashAt = performance.now(); },
+});
 // Soccer-ball look computed per pixel on the sphere itself, so there is
 // no pole or seam special case by design. The truncated icosahedron is
 // reconstructed as a spherical Voronoi diagram over 32 sites: the 12
@@ -1178,11 +1335,25 @@ const ballMesh = new THREE.Mesh(
     clearcoatRoughness: 0.35,
   }),
 );
+ballMesh.userData.meshName = "ball";
 ballMesh.visible = false;
 ballGroup.add(ballMesh);
 scene.add(ballGroup);
 
+const { createBallActor } = await import(signed(`./ball-actor.js?v=${SELF_V}`));
+ball = createBallActor({
+  THREE, scene, camera, renderer, fxModule: fx, mesh: ballMesh, group: ballGroup,
+});
+
+// Comic sticker popups on game events (kick / quack / roll / ball spawn /
+// ghost join). Fully self-contained DOM overlay: delete this import to
+// remove the feature (the `stickers?.pop` hooks then no-op).
+// Stickers disabled for now - uncomment to re-enable.
+// stickers = (await import(signed(`./stickers.js?v=${SELF_V}`)))
+//   .initStickers({ signed, isLocked: () => inputLocked });
+
 const controls = new OrbitControls(camera, renderer.domElement);
+controls.target.set(SPAWN_X, 0, -SPAWN_Y); // orbit around the spawn cell
 controls.enableDamping = true;
 controls.dampingFactor = 0.08;
 controls.minDistance = 0.25;
@@ -1213,19 +1384,76 @@ const _chaseDir = new THREE.Vector3();
 // and the camera position lerp absorbs the small heading correction when
 // live tracking resumes (rolls end facing roughly the same way).
 let chaseHeldYaw = 0;
+// Heading hysteresis (Schmitt trigger): the walking gait wiggles the trunk
+// yaw substantially every step (measured ~±14 deg at full speed) and
+// tracking it 1:1 makes the camera sway left-right constantly. Two layers:
+//   1. chaseYawSmooth: slow EMA of the trunk yaw - the gait's oscillation
+//      is symmetric so this is the duck's MEAN heading, ~steady while
+//      walking straight, moving cleanly during a real sustained turn.
+//   2. chaseYawFollow: what the camera frames. Frozen until the smooth
+//      heading deviates beyond ENGAGE, then eases toward it and freezes
+//      again below RELEASE (classic Schmitt).
+// An intentional turn (non-zero wz command from keys or pad) bypasses the
+// deadband immediately and both layers track fast, so full-speed turns
+// stay responsive.
+let chaseYawSmooth = 0; // EMA of trunk yaw (spawn yaw = 0)
+let chaseYawFollow = 0; // heading the camera actually frames
+let chaseYawTracking = false;
+const CHASE_YAW_SMOOTH_EASE = 0.04; // per-frame EMA, ~0.4 s time constant
+const CHASE_YAW_ENGAGE = 0.17; // rad, ~10 deg: start re-tracking
+const CHASE_YAW_RELEASE = 0.03; // rad, ~1.7 deg: stop once realigned
+const CHASE_YAW_EASE = 0.10; // per-frame ease during hysteresis catch-up
+// During a commanded turn the heading chain must not stack lag on top of
+// the camera position lerp (rollers turn at ~70 deg/s): near-snap ease,
+// the position lerp alone provides the smoothing, like pre-hysteresis.
+const CHASE_YAW_EASE_TURN = 0.5;
+const wrapPi = (a) => Math.atan2(Math.sin(a), Math.cos(a));
 function updateChaseCam() {
+  // Reset glide: one clean tween from wherever the camera is back to the
+  // home framing (see startCameraReset). Runs instead of the chase logic
+  // and hands control back to it on landing - the destination IS the
+  // chase cam's ideal point, so the handoff is seamless.
+  if (camResetT0 !== null) {
+    // Any detach (drag, right stick, C/R3 toggle) cancels the glide and
+    // gives the camera straight back to the user.
+    if (!chaseCam) { camResetT0 = null; return; }
+    const t = (performance.now() - camResetT0) / 1000 / CAM_RESET_S;
+    const e = t >= 1 ? 1 : t < 0.5 ? 4 * t * t * t : 1 - Math.pow(-2 * t + 2, 3) / 2;
+    camera.position.lerpVectors(_camFrom, _camTo, e);
+    controls.target.lerpVectors(_tgtFrom, _tgtTo, e);
+    camera.lookAt(controls.target);
+    if (t >= 1) camResetT0 = null;
+    return;
+  }
   if (!chaseCam) return;
   const qpos = data.qpos;
-  let yaw;
+  let rawYaw;
   if (mode === "roll" || isKick()) {
-    yaw = chaseHeldYaw;
+    rawYaw = chaseHeldYaw;
   } else {
-    yaw = Math.atan2(
+    rawYaw = Math.atan2(
       2 * (qpos[3] * qpos[6] + qpos[4] * qpos[5]),
       1 - 2 * (qpos[5] * qpos[5] + qpos[6] * qpos[6]),
     );
-    chaseHeldYaw = yaw;
+    chaseHeldYaw = rawYaw;
+  }
+  // Schmitt heading follow (see constants above). "turning" reads the raw
+  // per-source wz commands (not the locked/merged view) so an intentional
+  // turn engages on the first frame.
+  const turning = controller.sources.some((s) => Math.abs(s.command[2]) > 0.05);
+  chaseYawSmooth = wrapPi(
+    chaseYawSmooth +
+      wrapPi(rawYaw - chaseYawSmooth) * (turning ? CHASE_YAW_EASE_TURN : CHASE_YAW_SMOOTH_EASE),
+  );
+  const yawErr = wrapPi(chaseYawSmooth - chaseYawFollow);
+  if (turning || Math.abs(yawErr) > CHASE_YAW_ENGAGE) chaseYawTracking = true;
+  if (chaseYawTracking) {
+    chaseYawFollow = wrapPi(
+      chaseYawFollow + yawErr * (turning ? CHASE_YAW_EASE_TURN : CHASE_YAW_EASE),
+    );
+    if (!turning && Math.abs(yawErr) < CHASE_YAW_RELEASE) chaseYawTracking = false;
   }
+  const yaw = chaseYawFollow;
   const dist = camera.position.distanceTo(controls.target);
   const horiz = dist * Math.cos(CHASE_PITCH);
   const vert = dist * Math.sin(CHASE_PITCH);
@@ -1247,6 +1475,49 @@ function updateChaseCam() {
 }
 renderer.domElement.addEventListener("pointerdown", () => { chaseCam = false; });
 
+// ── Camera reset (owned by the respawn ceremony) ────────────────────────
+// Glides back to the page-load framing: the chase cam's ideal point
+// behind the duck's spawn heading, at the boot orbit distance. The
+// distance is captured here, before any user input can zoom; the rest
+// of the destination is computed live at reset time from the freshly
+// reset qpos, so it lands correctly in both legs and roller modes.
+const CAM_HOME_DIST = camera.position.distanceTo(controls.target);
+let camResetT0 = null; // wall-clock start while the glide is playing
+const _camFrom = new THREE.Vector3(), _camTo = new THREE.Vector3();
+const _tgtFrom = new THREE.Vector3(), _tgtTo = new THREE.Vector3();
+function startCameraReset() {
+  const qpos = data.qpos;
+  const yaw = Math.atan2(
+    2 * (qpos[3] * qpos[6] + qpos[4] * qpos[5]),
+    1 - 2 * (qpos[5] * qpos[5] + qpos[6] * qpos[6]),
+  );
+  chaseHeldYaw = yaw; // keep the post-glide chase heading coherent
+  chaseYawSmooth = yaw; // hysteresis state lands with the glide
+  chaseYawFollow = yaw;
+  chaseYawTracking = false;
+  _tgtTo.set(qpos[0], qpos[2], -qpos[1]); // trunk at spawn, MJCF -> three
+  const horiz = CAM_HOME_DIST * Math.cos(CHASE_PITCH);
+  const vert = CAM_HOME_DIST * Math.sin(CHASE_PITCH);
+  _camTo.set(
+    _tgtTo.x - Math.cos(yaw) * horiz,
+    _tgtTo.y + vert,
+    _tgtTo.z + Math.sin(yaw) * horiz,
+  );
+  _camFrom.copy(camera.position);
+  _tgtFrom.copy(controls.target);
+  camResetT0 = performance.now();
+  chaseCam = true; // reset always re-attaches the chase cam
+}
+
+// Pause: while the menu is up over a live game, keys belong to the menu.
+const setInputLock = (v) => { inputLocked = v; controller.setLocked(v); };
+document.addEventListener("microduck:menu-open", () => {
+  if (ceremony.entranceDone) setInputLock(true);
+});
+document.addEventListener("microduck:menu-close", () => {
+  if (ceremony.entranceDone && !ceremony.respawnActive) setInputLock(false);
+});
+
 function resize() {
   const w = mount.clientWidth, h = mount.clientHeight;
   camera.aspect = w / h;
@@ -1267,22 +1538,26 @@ function syncRig() {
   for (let j = 0; j < NUM_JOINTS; j++) setJoint(rig, JOINT_NAMES[j], qpos[qposAdr[j]]);
   // Passive hinges (roller wheels): purely visual, driven straight from qpos.
   for (const ej of extraJoints) setJoint(rig, ej.name, qpos[ej.adr]);
-  // Ball: raw MJCF pose inside the Z-up group, hidden while parked.
-  ballMesh.visible = ballActive;
-  if (ballActive) {
-    ballMesh.position.set(qpos[ballQposAdr], qpos[ballQposAdr + 1], qpos[ballQposAdr + 2]);
-    ballMesh.quaternion.set(
-      qpos[ballQposAdr + 4], qpos[ballQposAdr + 5], qpos[ballQposAdr + 6], qpos[ballQposAdr + 3],
-    );
-  }
+  // Ball: live follows qpos; ghost freeze is owned by the ball actor
+  // (physics already parked, mesh holds last pose during reverse scan).
+  if (ball) ball.sync(qpos, ballQposAdr, ballActive);
   // Follow cam: ease the orbit target toward the trunk and translate the
   // camera by the same delta, so the camera-to-duck distance and viewing
   // angle stay constant while the duck walks. Mouse orbit/zoom still work:
-  // they only change the (preserved) camera-target offset.
-  _target.set(qpos[0], qpos[2], -qpos[1]);
-  _follow.copy(_target).sub(controls.target).multiplyScalar(0.06);
-  controls.target.add(_follow);
-  camera.position.add(_follow);
+  // they only change the (preserved) camera-target offset. Paused while
+  // the reset glide owns the camera (it tweens the target itself).
+  if (camResetT0 === null) {
+    _target.set(qpos[0], qpos[2], -qpos[1]);
+    _follow.copy(_target).sub(controls.target);
+    // Horizontal follow at the usual rate; vertical much slower so the
+    // per-step gait bob doesn't nod the frame (sit/crouch height changes
+    // still settle in, just over ~1 s instead of instantly).
+    _follow.x *= 0.06;
+    _follow.z *= 0.06;
+    _follow.y *= 0.015;
+    controls.target.add(_follow);
+    camera.position.add(_follow);
+  }
   // Keep the grid plane (and its fade center) under the action; the wall
   // grids share the same radial fade focus.
   grid.position.set(controls.target.x, 0, controls.target.z);
@@ -1326,6 +1601,7 @@ function playChirp() {
 const quackLoud = () => {
   quackAt = performance.now();
   playChirp();
+  stickers?.pop("quack");
 };
 function jawOpenNow() {
   const t = (performance.now() - quackAt) / QUACK_MS;
@@ -1364,10 +1640,17 @@ function syncLocoHints() {
   if (padXLabelEl) padXLabelEl.textContent = rollers ? "crouch" : "roll";
 }
 const STICK_R = 15; // px, max dot travel inside the 46px stick circle
-let resetFlashAt = -Infinity;
 let ballFlashAt = -Infinity;
 let padYFlashAt = -Infinity;
 
+// Bottom-right OSD extras: render rate (EMA over frame deltas), live ground
+// speed off the freejoint, and an odometer integrating horizontal trunk
+// travel. Teleport-sized jumps (resets, loco swaps) don't count as travel.
+let fpsEma = 60;
+let fpsLastT = performance.now();
+let odoM = 0;
+let odoX = null, odoY = null;
+
 function renderStats() {
   const [vx, , wz] = effectiveCmd();
   // The active policy lives in the big center label and the twist in the
@@ -1378,13 +1661,30 @@ function renderStats() {
   const p2 = (n) => String(n).padStart(2, "0");
   osdTimeEl.textContent =
     `\u25b6 ${p2(Math.floor(t / 60))}:${p2(Math.floor(t) % 60)}:${p2(Math.floor((t % 1) * 50))}`;
-  statsEl.textContent =
-    `CTRL ${ctrlHz.toFixed(0)}HZ` + (peers ? ` \u00b7 ${peers + 1} ONLINE` : "");
+
+  const now = performance.now();
+  const dtF = (now - fpsLastT) / 1000;
+  fpsLastT = now;
+  if (dtF > 0 && dtF < 0.5) fpsEma += (1 / dtF - fpsEma) * 0.05;
+  const stepD = (odoX === null) ? 0 : Math.hypot(data.qpos[0] - odoX, data.qpos[1] - odoY);
+  if (stepD < 0.05) odoM += stepD; // plausible per-frame travel only
+  odoX = data.qpos[0];
+  odoY = data.qpos[1];
+  const spd = Math.hypot(data.qvel[0], data.qvel[1]);
+
+  // Bottom-right telemetry stack, quietest line last: peers (only when
+  // someone else is around), then speed + odometer, then the loop rates.
+  const odo = odoM < 1000 ? `${odoM.toFixed(1)}M` : `${(odoM / 1000).toFixed(2)}KM`;
+  const lines = [];
+  if (peers) lines.push(`${peers + 1} ONLINE`);
+  lines.push(`${spd.toFixed(2)}M/S \u00b7 ODO ${odo}`);
+  lines.push(`FPS ${Math.round(fpsEma)} \u00b7 CTRL ${ctrlHz.toFixed(0)}HZ`);
+  ctrlHzEl.textContent = lines.join("\n");
 
   // Mini sticks: the dot mirrors the effective twist, lit yellow while the
   // user is actually driving. Normalized against the ACTIVE variant's
   // velocity limits so full deflection reads the same in both.
-  const manual = (padActive || held.size > 0) && mode !== "roll";
+  const manual = controller.anyActive() && mode !== "roll";
   const [limF, limB, limA] = velLims();
   const yN = vx >= 0 ? vx / limF : vx / -limB;
   // Move stick is vertical-only now that strafe is gone.
@@ -1394,10 +1694,11 @@ function renderStats() {
   boxTurn.classList.toggle("live", manual && Math.abs(wz) > 0.01);
 
   // Keycap highlighting: each individual key lights only while its own
-  // action is active, and only for its own input device.
+  // action is active, and only for its own input device (pressed-state
+  // snapshots come straight from the controller's sources).
   const sitting = mode === "sitstand" && sitFlag === 1;
   for (const k of ["fwd", "back", "turnl", "turnr"]) {
-    keyEls[k].classList.toggle("lit", held.has(k));
+    keyEls[k].classList.toggle("lit", kbSource.pressed[k]);
   }
   const trick = mode === "roll" || mode === "crouch"; // same R / pad-X slot
   keyEls.roll.classList.toggle("lit", trick && rollSource === "kb");
@@ -1412,89 +1713,101 @@ function renderStats() {
   keyEls.padRb.classList.toggle("lit", mode === "kickR" && kickSource === "pad");
   keyEls.padLb.classList.toggle("lit", mode === "kickL" && kickSource === "pad");
   keyEls.padSit.classList.toggle("lit", sitting);
-  keyEls.padRun.classList.toggle("lit", padPrev.dpadUp);
+  keyEls.padRun.classList.toggle("lit", padSource.pressed.dpadUp);
   keyEls.padRt.classList.toggle("lit", padJaw > 0.3);
   keyEls.padRs.classList.toggle("lit", padOrbitLive); // while deflected
   keyEls.padR3.classList.toggle("lit", chaseCam); // steady while chasing
-}
 
-// Real implementation assigned in the gamepad section below; the render
-// loop starts before that section has evaluated, hence the indirection.
-let pollPad = () => {};
-// Multiplayer ghosts, initialised asynchronously at the end of the module.
-let ghosts = null;
-
-function loop() {
-  requestAnimationFrame(loop);
-  pollPad();
-  syncRig();
-  syncJaw();
-  ghosts?.update();
-  controls.update();
-  updateChaseCam();
-  updateEntrance();
-  renderStats();
-  renderer.render(scene, camera);
+  drawMinimap();
 }
-// Boot complete: the sim/HUD go live immediately. The BIOS readout (if
-// the user already waddled in, or when they do) sees bootDone and closes
-// with READY. + fade on its own.
-bootDone = true;
-hudEl.hidden = false;
-loop();
 
-// ── Input: hold-to-command keys + HUD buttons ───────────────────────────
-function refreshVelCmd() {
-  const [limF, limB, limA] = velLims();
-  velCmd[0] = held.has("fwd") ? limF : held.has("back") ? limB : 0;
-  velCmd[2] = held.has("turnl") ? limA : held.has("turnr") ? -limA : 0;
+// ── Minimap (90s radar, top-right OSD) ──────────────────────────────────
+// Fixed top-down view of the 3x3 m arena. World +X (the spawn facing)
+// points UP on the map, so the spawn cell sits bottom-middle; world +Y
+// points LEFT (right-handed seen from above). Duck = oriented chevron,
+// ball = white dot while spawned, revealed ghosts = faint dots.
+const minimapEl = document.getElementById("minimap");
+const minimapCtx = minimapEl?.getContext("2d");
+const MINIMAP_HZ = 20;
+const MINIMAP_ORANGE = "#ff7a2f";
+let minimapLastDraw = 0;
+// Chevron heading: the minimap keeps its OWN yaw EMA, independent of the
+// camera's hysteresis state (chaseHeldYaw only updates while the chase
+// cam is attached, and the followed yaw freezes on purpose). The EMA
+// averages out the ±14 deg per-step gait wobble while tracking real
+// turns continuously; during roll/kick the trunk quaternion tumbles, so
+// the last sane value is held (same protection as the camera).
+let minimapYaw = 0; // spawn yaw = 0
+const MINIMAP_YAW_EASE = 0.15; // per 20 Hz tick, ~0.3 s to settle on a turn
+function drawMinimap() {
+  if (!minimapCtx) return;
+  const now = performance.now();
+  if (now - minimapLastDraw < 1000 / MINIMAP_HZ) return;
+  minimapLastDraw = now;
+  const ctx = minimapCtx;
+  const S = minimapEl.width; // square, drawn in device px
+  // World (MJCF, Z-up) -> map px: u right = -Y, v down = -X.
+  const u = (y) => (0.5 - y / (2 * ARENA_HALF)) * S;
+  const v = (x) => (0.5 - x / (2 * ARENA_HALF)) * S;
+  ctx.clearRect(0, 0, S, S);
+  // Section grid (0.6 m pitch): inner lines only, the CSS border frames it.
+  ctx.strokeStyle = "rgba(255, 122, 47, 0.18)";
+  ctx.lineWidth = 1;
+  ctx.beginPath();
+  for (let i = 1; i < 5; i++) {
+    const c = (i / 5) * S;
+    ctx.moveTo(c, 0); ctx.lineTo(c, S);
+    ctx.moveTo(0, c); ctx.lineTo(S, c);
+  }
+  ctx.stroke();
+  const qpos = data.qpos;
+  // Ghosts: revealed peers only, faint white dots.
+  ctx.fillStyle = "rgba(255, 255, 255, 0.4)";
+  for (const g of ghosts?.mapDots() ?? []) {
+    ctx.beginPath();
+    ctx.arc(u(g.y), v(g.x), S * 0.015, 0, Math.PI * 2);
+    ctx.fill();
+  }
+  // Ball: only while spawned (parked = 50 m away = hidden).
+  if (ballActive) {
+    const bx = qpos[ballQposAdr], by = qpos[ballQposAdr + 1];
+    if (Math.abs(bx) <= ARENA_HALF && Math.abs(by) <= ARENA_HALF) {
+      ctx.fillStyle = "rgba(255, 255, 255, 0.92)";
+      ctx.beginPath();
+      ctx.arc(u(by), v(bx), S * 0.019, 0, Math.PI * 2);
+      ctx.fill();
+    }
+  }
+  // Duck: chevron at the trunk position, nose along the smoothed live yaw
+  // (frozen during roll/kick where the trunk tumbles).
+  if (mode !== "roll" && !isKick()) {
+    const rawYaw = Math.atan2(
+      2 * (qpos[3] * qpos[6] + qpos[4] * qpos[5]),
+      1 - 2 * (qpos[5] * qpos[5] + qpos[6] * qpos[6]),
+    );
+    minimapYaw = wrapPi(minimapYaw + wrapPi(rawYaw - minimapYaw) * MINIMAP_YAW_EASE);
+  }
+  ctx.save();
+  ctx.translate(u(qpos[1]), v(qpos[0]));
+  // Forward (cos yaw, sin yaw) in world -> (-sin yaw, -cos yaw) on the
+  // map, i.e. a canvas rotation of -yaw applied to an up-pointing shape.
+  ctx.rotate(-minimapYaw);
+  const r = S * 0.032;
+  ctx.fillStyle = MINIMAP_ORANGE;
+  ctx.beginPath();
+  ctx.moveTo(0, -r * 1.35); // nose
+  ctx.lineTo(r * 0.85, r * 0.95);
+  ctx.lineTo(0, r * 0.45); // notched tail = chevron
+  ctx.lineTo(-r * 0.85, r * 0.95);
+  ctx.closePath();
+  ctx.fill();
+  ctx.restore();
 }
 
-// e.code is physical position, so one map covers QWERTY and AZERTY:
-// arrows / WASD (ZQSD) run + turn. No strafe.
-const KEYMAP = {
-  ArrowUp: "fwd", KeyW: "fwd",
-  ArrowDown: "back", KeyS: "back",
-  ArrowLeft: "turnl", KeyA: "turnl",
-  ArrowRight: "turnr", KeyD: "turnr",
-};
-
-window.addEventListener("keydown", (e) => {
-  if (e.repeat) return;
-  if (e.code === "Space") { e.preventDefault(); resetSim(); resetFlashAt = performance.now(); return; }
-  if (e.code === "KeyB") { spawnBall(); ballFlashAt = performance.now(); return; }
-  if (e.code === "KeyC") { chaseCam = !chaseCam; return; }
-  if (e.code === "KeyM") { toggleLoco(); return; }
-  if (e.code === "KeyR") { triggerRoll(); return; }
-  // Physical Q/E (A/E on AZERTY): explicit left / right kick, mirroring
-  // the pad's LB / RB.
-  if (e.code === "KeyQ") { triggerKick("left"); return; }
-  if (e.code === "KeyE") { triggerKick("right"); return; }
-  const act = KEYMAP[e.code];
-  if (!act) return;
-  e.preventDefault();
-  held.add(act);
-  refreshVelCmd();
-});
-window.addEventListener("keyup", (e) => {
-  const act = KEYMAP[e.code];
-  if (!act) return;
-  held.delete(act);
-  refreshVelCmd();
-});
-window.addEventListener("blur", () => { held.clear(); refreshVelCmd(); });
-
-// ── Gamepad: same mapping as the robot runtime (microduck_runtime) ──────
-// Left stick: vertical = vx (asymmetric fwd/back), horizontal = turn,
-// EMA-smoothed like the runtime's cmd_alpha. Right stick orbits the
-// camera (detaches the chase cam, R3 re-toggles it). X = roll, Y = ball,
-// RB/LB = kicks, DpadDown = sit/stand, DpadUp = back to run, RT = mouth.
-const PAD_DEADZONE = 0.15;
-const PAD_ALPHA = 0.12;
-const dz = (v) => (Math.abs(v) < PAD_DEADZONE ? 0 : v);
-
-// Right-stick camera orbit, in OrbitControls-compatible terms: rebuild
-// the camera-target offset as a spherical, nudge azimuth/elevation, and
+// ── Right-stick camera orbit (inertia downstream of the controller) ─────
+// The gamepad source reports the raw deflection (controller axes.orbitX/Y);
+// this step turns it into OrbitControls-compatible motion: rebuild the
+// camera-target offset as a spherical, nudge azimuth/elevation, and
 // re-place the camera. controls.update() then runs on the result, so the
 // damping bookkeeping never fights it (same trick as updateChaseCam).
 // The stick does not move the camera directly: it steers an angular
@@ -1528,109 +1841,94 @@ function padOrbitStep(rx, ry, dt) {
   camera.lookAt(controls.target);
 }
 
-let padPollT = performance.now();
-pollPad = function pollGamepad() {
-  const now = performance.now();
-  // Clamped so a background-tab stall can't slingshot the camera.
-  const dt = Math.min((now - padPollT) / 1000, 0.05);
-  padPollT = now;
-  const gp = [...(navigator.getGamepads?.() ?? [])].find((p) => p && p.connected);
-  document.body.classList.toggle("pad-connected", !!gp);
-  if (!gp) {
-    if (padActive) { padActive = false; padCmd.fill(0); padJaw = 0; }
+// Multiplayer ghosts, initialised asynchronously at the end of the module.
+let ghosts = null;
+
+let inputPollT = performance.now();
+function loop() {
+  requestAnimationFrame(loop);
+  // dt clamped so a background-tab stall can't slingshot the camera orbit.
+  const inputNow = performance.now();
+  const dt = Math.min((inputNow - inputPollT) / 1000, 0.05);
+  inputPollT = inputNow;
+  controller.update(dt);
+  padJaw = controller.getAxes().jaw;
+  document.body.classList.toggle("pad-connected", padSource.connected);
+  // Camera orbit runs every frame while a pad is present (the coasting
+  // needs the zero-deflection frames too); without a pad, park the state.
+  if (padSource.connected) {
+    padOrbitStep(controller.getAxes().orbitX, controller.getAxes().orbitY, dt);
+  } else {
     padOrbitLive = false;
     padOrbitVel.az = 0;
     padOrbitVel.el = 0;
-    return;
-  }
-  // Left stick only: vertical = forward/back, horizontal = turn.
-  // (No strafe; the right stick no longer drives movement.)
-  const lx = dz(gp.axes[0] ?? 0), ly = dz(gp.axes[1] ?? 0);
-  const up = -ly; // browser sticks report up as -1
-  const [limF, limB, limA] = velLims();
-  const target = [
-    up >= 0 ? up * limF : up * -limB,
-    0,
-    -lx * limA,
-  ];
-  for (let i = 0; i < 3; i++) padCmd[i] += PAD_ALPHA * (target[i] - padCmd[i]);
-  // Sticks grab command authority on first input, release when back at rest
-  // (then the keyboard takes over again).
-  const stickInput = lx !== 0 || ly !== 0;
-  if (stickInput) padActive = true;
-  else if (padActive && Math.abs(padCmd[0]) + Math.abs(padCmd[1]) + Math.abs(padCmd[2]) < 0.01) {
-    padActive = false;
-    padCmd.fill(0);
   }
+  syncRig();
+  syncJaw();
+  ghosts?.update();
+  controls.update();
+  updateChaseCam();
+  ceremony.drive();
+  ball.drive(() => spawnBall({ fromQueue: true }));
+  renderStats();
+  renderer.render(scene, camera);
+}
+// Boot complete: the sim/HUD go live immediately. The BIOS readout (if
+// the user already waddled in, or when they do) sees bootDone and closes
+// with READY. + fade on its own.
+bootDone = true;
+hudEl.hidden = false;
+loop();
 
-  // Right stick: camera orbit with velocity smoothing. Runs every frame
-  // (not just while deflected) so a released stick coasts to a stop.
-  padOrbitStep(dz(gp.axes[2] ?? 0), dz(gp.axes[3] ?? 0), dt);
-
-  // R3 (right stick click): toggle the chase cam, gamepad twin of KeyC.
-  const r3Btn = !!gp.buttons[11]?.pressed;
-  if (r3Btn && !padPrev.r3) chaseCam = !chaseCam;
-  padPrev.r3 = r3Btn;
-
-  // Standard mapping indices: X=2, Y=3, LB=4, RB=5, DpadDown=13, RT=7 (analog).
-  const x = !!gp.buttons[2]?.pressed;
-  if (x && !padPrev.x) triggerRoll("pad");
-  padPrev.x = x;
-
-  // Y: pop / respawn the ball, same rising-edge pattern as X.
-  const y = !!gp.buttons[3]?.pressed;
-  if (y && !padPrev.y) { spawnBall(); padYFlashAt = performance.now(); }
-  padPrev.y = y;
-
-  // RB / LB: right / left kick, same buttons as the robot runtime.
-  const rb = !!gp.buttons[5]?.pressed;
-  if (rb && !padPrev.rb) triggerKick("right", "pad");
-  padPrev.rb = rb;
-  const lb = !!gp.buttons[4]?.pressed;
-  if (lb && !padPrev.lb) triggerKick("left", "pad");
-  padPrev.lb = lb;
-
-  const dpadDown = !!gp.buttons[13]?.pressed;
-  if (dpadDown && !padPrev.dpadDown && loco === "legs") {
-    const sitting = mode === "sitstand" && sitFlag === 1;
-    setMode(sitting ? "walk" : "sit");
-  }
-  padPrev.dpadDown = dpadDown;
-
-  // DpadUp: short press = straight back to running (ignored mid-roll: it
-  // hands back to walk on its own, and switching on a tipped duck would
-  // floor it). HOLD ~1 s = legs <-> rollers switch, like the robot's 3 s
-  // hold on the real controller (shortened for the web).
-  const dpadUp = !!gp.buttons[12]?.pressed;
-  if (dpadUp && !padPrev.dpadUp) {
-    padPrev.dpadUpAt = now;
-    padPrev.dpadUpFired = false;
-    if (mode !== "walk" && mode !== "roll" && mode !== "crouch") setMode("walk");
-  }
-  if (dpadUp && !padPrev.dpadUpFired && now - padPrev.dpadUpAt >= 1000) {
-    padPrev.dpadUpFired = true; // latch: one switch per hold
-    toggleLoco();
+// ── Input wiring: arm the controller sources, bind actions to triggers ──
+// Key/button mappings live in controls/keyboard.js and controls/gamepad.js;
+// this section is pure game-side wiring. Arming the listeners HERE (not at
+// source construction) keeps the boot behavior identical to when the raw
+// keydown/gamepad handlers attached at this point in the module.
+controller.init();
+
+// Keyboard F alternates kicking feet; only advance the alternation on
+// kicks that actually launched (triggerKick reports that).
+let kbKickFoot = "left";
+// Action meta.source ("keyboard"/"gamepad") -> the trigger functions'
+// historical source tags, which the HUD keycap lighting keys off.
+const srcTag = (source) => (source === "gamepad" ? "pad" : "kb");
+
+controller.on("reset", () => resetSim());
+controller.on("spawnBall", ({ source }) => {
+  spawnBall();
+  if (source === "gamepad") padYFlashAt = performance.now();
+  else ballFlashAt = performance.now();
+});
+controller.on("chaseToggle", () => { chaseCam = !chaseCam; });
+controller.on("locoToggle", () => toggleLoco());
+controller.on("roll", ({ source }) => triggerRoll(srcTag(source)));
+controller.on("kickL", ({ source }) => triggerKick("left", srcTag(source)));
+controller.on("kickR", ({ source }) => triggerKick("right", srcTag(source)));
+controller.on("alternateKick", ({ source }) => {
+  if (triggerKick(kbKickFoot, srcTag(source))) {
+    kbKickFoot = kbKickFoot === "left" ? "right" : "left";
   }
-  padPrev.dpadUp = dpadUp;
-
-  // Triggers drive the mouth like the runtime (max of both), and the right
-  // one quacks on its rising edge — same as the robot's chirp.
-  // Schmitt trigger on the analog RT value: fire at 0.35, re-arm only once
-  // it drops below 0.2. A single threshold re-fires on every jitter around
-  // it, which is how one squeeze used to quack several times.
-  const rt = gp.buttons[7]?.value ?? 0;
-  const lt = gp.buttons[6]?.value ?? 0;
-  padJaw = Math.max(rt, lt);
-  if (padPrev.rtArmed && rt >= 0.35) { quackLoud(); padPrev.rtArmed = false; }
-  else if (!padPrev.rtArmed && rt < 0.2) padPrev.rtArmed = true;
-};
+});
+controller.on("sitToggle", () => {
+  if (loco !== "legs") return; // sitting is a legs-only skill
+  const sitting = mode === "sitstand" && sitFlag === 1;
+  setMode(sitting ? "walk" : "sit");
+});
+// Pad DpadUp short press: straight back to running (ignored mid-roll /
+// mid-crouch: those hand back to walk on their own, and switching on a
+// tipped duck would floor it).
+controller.on("walk", () => {
+  if (mode !== "walk" && mode !== "roll" && mode !== "crouch") setMode("walk");
+});
+controller.on("quack", () => quackLoud());
 
 // Read-only state label (bottom-left): reflects the active policy,
 // switching happens via keyboard/gamepad only.
 const modeLabel = document.getElementById("mode-label");
 
-function setMode(next) {
-  if (inputLocked) return;
+function setMode(next, { force = false } = {}) {
+  if (!force && inputLocked) return;
   // No policy switching mid-roll or mid-kick: both end on their own and
   // return to walk - switching now would floor the duck. Sitting is a
   // legs-only skill (the roller stance has no sitstand policy).
@@ -1685,6 +1983,7 @@ function triggerRoll(source = "kb") {
   sitFlag = 0;
   rollRun = { steps: 0, tipped: false };
   syncButtons();
+  stickers?.pop("roll");
 }
 
 // Roller-only one-shot: crouch, glide low, stand back up (phase-driven,
@@ -1696,6 +1995,7 @@ function triggerCrouch(source = "kb") {
   mode = "crouch";
   crouchRun = { phase: 0 };
   syncButtons();
+  stickers?.pop("roll"); // same WHEE - the crouch-glide is the roller "roll"
 }
 
 // One blind kick (the duck can't see any ball - it's a scripted boot),
@@ -1712,23 +2012,39 @@ function triggerKick(foot, source = "kb") {
   sitFlag = 0;
   kickRun = { steps: 0 };
   syncButtons();
+  stickers?.pop("kick");
   return true;
 }
-// Slot-machine roll: the old text slides up and out while the new one
-// rises in from below the (overflow-hidden) label box.
+// Matrix-style letter scramble: on change every glyph flips through random
+// charset entries, then locks to its target left-to-right over ~0.45s.
+// One interval for the whole run; monospace keeps the width stable.
+const SCRAMBLE_GLYPHS = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789#$%&*<>/=+";
+let scrambleTimer = null;
 function setModeLabel(text) {
-  const cur = modeLabel.lastElementChild;
-  if (cur && cur.textContent === text) return;
-  const next = document.createElement("span");
-  next.className = "mode-text in";
-  next.textContent = text;
-  modeLabel.appendChild(next);
-  void next.offsetWidth; // flush layout so the transition actually plays
-  if (cur) {
-    cur.classList.add("out");
-    setTimeout(() => cur.remove(), 350);
-  }
-  next.classList.remove("in");
+  // Guard on the intended target, not the displayed text (which is mid-
+  // scramble noise while the interval runs).
+  if (modeLabel.dataset.target === text) return;
+  modeLabel.dataset.target = text;
+  if (scrambleTimer) { clearInterval(scrambleTimer); scrambleTimer = null; }
+  const span = modeLabel.firstElementChild;
+  const target = text.toUpperCase();
+  const n = target.length;
+  const DUR = 450; // ms until the last letter locks
+  const rnd = () => SCRAMBLE_GLYPHS[(Math.random() * SCRAMBLE_GLYPHS.length) | 0];
+  const t0 = performance.now();
+  scrambleTimer = setInterval(() => {
+    // Letters 0..k-1 are locked; the rest keep boiling.
+    const k = Math.floor(((performance.now() - t0) / DUR) * n);
+    if (k >= n) {
+      clearInterval(scrambleTimer);
+      scrambleTimer = null;
+      span.textContent = target;
+      return;
+    }
+    let out = target.slice(0, k);
+    for (let i = k; i < n; i++) out += rnd();
+    span.textContent = out;
+  }, 40);
 }
 
 function syncButtons() {
@@ -1781,11 +2097,15 @@ window.rl = {
   get mode() { return mode; },
   get sitFlag() { return sitFlag; },
   buildObs, cmd,
-  velCmd, lastAction, resetSim,
-  spawnBall, triggerKick, sessions, ort,
+  // velCmd is the keyboard source's live command array: writing to it
+  // still drives the duck when no other source is active (the controller
+  // falls back to it), same as before the controls/ refactor.
+  velCmd: kbSource.command, lastAction, resetSim,
+  controller, kbSource, padSource,
+  spawnBall, triggerKick, triggerRoll, sessions, ort,
   get loco() { return loco; },
   get locoSwitching() { return locoSwitching; },
-  toggleLoco, ensureRollers,
+  toggleLoco, setLoco, ensureRollers,
   triggerCrouch,
   get crouchPhase() { return crouchRun?.phase ?? null; },
   get kickSteps() { return KICK_STEPS; },
@@ -1794,30 +2114,31 @@ window.rl = {
   get ballQposAdr() { return ballQposAdr; },
   get chaseCam() { return chaseCam; },
   set chaseCam(v) { chaseCam = !!v; },
+  get camResetActive() { return camResetT0 !== null; },
+  get respawnActive() { return ceremony?.respawnActive ?? false; },
+  get camPose() {
+    return {
+      pos: camera.position.toArray(),
+      target: controls.target.toArray(),
+    };
+  },
+  get chaseYaw() { return { follow: chaseYawFollow, smooth: chaseYawSmooth, held: chaseHeldYaw, tracking: chaseYawTracking, map: minimapYaw }; },
   padOrbitStep,
   jawOpenNow,
   step: async (n = 1) => { for (let i = 0; i < n; i++) await controlStep(); },
   render: () => { syncRig(); renderer.render(scene, camera); },
   // One full render-loop iteration, for tests driving frames manually.
-  frame: () => { syncRig(); syncJaw(); controls.update(); updateChaseCam(); updateEntrance(); renderStats(); renderer.render(scene, camera); },
+  frame: () => { syncRig(); syncJaw(); controls.update(); updateChaseCam(); ceremony.drive(); renderStats(); renderer.render(scene, camera); },
   get ghosts() { return ghosts; },
   get inputLocked() { return inputLocked; },
   // Deterministic entrance controls for screenshots/tests: setting values
-  // detaches the time-based driver; setDissolve(1) also restores the
-  // original materials and releases the input lock (same cleanup as the
-  // real sequence).
+  // detaches the time-based driver; setFx(1) also runs the FX through its
+  // finish path (materials restored) and releases the input lock (same
+  // cleanup as the real sequence).
   entrance: {
-    start: startEntrance,
-    setReveal: (floor, wall = floor) => {
-      entranceT0 = null;
-      grid.material.uniforms.uReveal.value = floor;
-      for (const m of wallMats) m.uniforms.uReveal.value = wall;
-    },
-    setDissolve: (p) => {
-      entranceT0 = null;
-      if (p >= 1) { dissolveP.value = 1; restoreDissolve(); inputLocked = false; entranceFinishedResolve(); }
-      else { applyDissolve(); dissolveP.value = p; }
-    },
+    start: () => ceremony.startEntrance(),
+    setReveal: (floor, wall) => ceremony.setReveal(floor, wall),
+    setFx: (p) => ceremony.setFx(p),
   },
 };
 
@@ -1828,7 +2149,7 @@ const r3 = (x) => Math.round(x * 1000) / 1000;
 try {
   // Ghosts only join once the entrance has fully played: the world (and
   // this duck) must stay hidden until then, translucent peers included.
-  await entranceFinished;
+  await ceremony.entranceFinished;
   const { initGhosts } = await import(signed(`./ghosts.js?v=${SELF_V}`));
   ghosts = await initGhosts({
     scene, rig, cloneRig, setJoint, setJawOpen, applyVariant,
@@ -1851,6 +2172,9 @@ try {
       };
     },
   });
+  // "HI!" sticker when another visitor joins (setter-style registration,
+  // same trystero build quirk as onPeerLeave inside ghosts.js).
+  if (ghosts.room) ghosts.room.onPeerJoin = () => stickers?.pop("hi");
 } catch (e) {
   window.__ghostErr = String((e && e.stack) || e);
   console.warn("ghosts disabled:", e);

stickers.js

@@ -0,0 +1,222 @@
+// Comic sticker popups: on notable game events (kick, quack, roll, ball
+// spawn, ghost peer joining) a die-cut sticker or a comic onomatopoeia pops
+// at a semi-random spot on screen, overshoots in, then fades out. Pure
+// CSS animations, no dependencies.
+//
+// Fully self-contained and OPTIONAL: this module owns its DOM layer and its
+// <style> tag, and imports nothing from the rest of the game. rl.js keeps a
+// nullable `stickers` slot and calls `stickers?.pop("kick")` at each event
+// site, so deleting the single import line in rl.js removes the feature
+// without breaking anything.
+//
+// Image assets are the pre-cut Pollen showcase stickers (assets/stickers/,
+// webp with transparency). Their URLs go through the injected `signed()`
+// helper so they load on the private HF Space (?__sign JWT) as well as
+// locally, where signed() is a no-op.
+//
+//   const stickers = initStickers({ signed, isLocked });
+//   stickers.pop("quack");   // one of: kick, quack, roll, spawn, hi
+//   stickers.dispose();      // remove layer + styles (tests/teardown)
+
+// Bump when the webp files change; python http.server sends no
+// Cache-Control, same convention as the mesh/module ?v= busters.
+const ASSET_V = "1";
+const DIR = "./assets/stickers";
+
+// Comic palette sampled from the sticker sheet itself.
+const C = {
+  red: "#ff3b30",
+  teal: "#1fb6a8",
+  yellow: "#ffd23f",
+  blue: "#2f8bff",
+  pink: "#ff2d78",
+};
+
+// Per-event pools: each pop picks one variant at random. `img` is a die-cut
+// webp sticker (w = on-screen width in px before jitter), `text` a pure
+// CSS onomatopoeia; both together = text overlaid on the image (POP! burst).
+// `cool` is the per-event rate limit in ms - repeated quacks/kicks reuse
+// the sticker on screen instead of stacking a new one per press.
+const EVENTS = {
+  kick: {
+    cool: 900,
+    pool: [
+      { img: "bang-red", w: 170 },
+      { img: "boom", w: 175 },
+      { img: "star-yellow", w: 120 },
+      { text: "BAM!", color: C.red },
+    ],
+  },
+  quack: {
+    cool: 700,
+    pool: [
+      { img: "quack", w: 180 },
+      { img: "quack-quack", w: 170 },
+      { text: "QUACK!", color: C.teal },
+    ],
+  },
+  roll: {
+    cool: 1600,
+    pool: [
+      { text: "WHEE!", color: C.pink },
+      { img: "ziouuu", w: 200 },
+      { img: "shooting-star", w: 150 },
+    ],
+  },
+  spawn: {
+    cool: 900,
+    pool: [
+      { img: "burst-yellow", w: 140, text: "POP!", color: C.pink },
+      { text: "POP!", color: C.yellow },
+    ],
+  },
+  hi: {
+    cool: 2500,
+    pool: [
+      { text: "HI!", color: C.blue },
+      { img: "wave", w: 150 },
+    ],
+  },
+};
+
+const MAX_LIVE = 4; // concurrent stickers, all events combined
+const LIFE_MS = 1250; // matches the CSS animation duration below
+
+// Safe zone (viewport %): keeps stickers off the HUD corners - mode label
+// top-left, REC/stats top-right (+ colour stack below it), hint keycaps
+// along the bottom. The middle band is all playground.
+const ZONE = { x0: 16, x1: 78, y0: 20, y1: 68 };
+
+const CSS = `
+#sticker-layer {
+  position: fixed;
+  inset: 0;
+  z-index: 9; /* above the CRT overlay (5), below the HUD (10) */
+  pointer-events: none;
+  overflow: hidden;
+}
+#sticker-layer .sticker {
+  position: absolute;
+  will-change: transform, opacity;
+  animation: sticker-pop ${LIFE_MS}ms cubic-bezier(0.22, 1, 0.36, 1) forwards;
+}
+#sticker-layer .sticker img {
+  display: block;
+  filter: drop-shadow(0 4px 10px rgba(0, 0, 0, 0.35));
+}
+#sticker-layer .sticker-text {
+  font-family: "Arial Black", "Avenir-Black", "Helvetica Neue", sans-serif;
+  font-weight: 900;
+  font-style: italic;
+  font-size: clamp(2.4rem, 5.5vw, 4.2rem);
+  letter-spacing: 0.02em;
+  white-space: nowrap;
+  -webkit-text-stroke: 0.24em #fff;
+  paint-order: stroke fill;
+  text-shadow: 0.07em 0.1em 0 rgba(20, 10, 40, 0.85);
+  filter: drop-shadow(0 4px 10px rgba(0, 0, 0, 0.35));
+}
+/* Text overlaid on a die-cut sticker (e.g. POP! on the blank burst). */
+#sticker-layer .sticker-overlay {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  font-size: clamp(1.6rem, 3.2vw, 2.4rem);
+  transform: rotate(-8deg);
+}
+/* Pop-in with scale overshoot + a small rotation settle, short hold, then
+   shrink/fade. --rot / --s carry the per-pop random jitter. */
+@keyframes sticker-pop {
+  0%   { transform: translate(-50%, -50%) rotate(calc(var(--rot) - 12deg)) scale(0); opacity: 0; }
+  14%  { transform: translate(-50%, -50%) rotate(calc(var(--rot) + 3deg)) scale(calc(var(--s) * 1.22)); opacity: 1; }
+  26%  { transform: translate(-50%, -50%) rotate(var(--rot)) scale(calc(var(--s) * 0.96)); }
+  36%  { transform: translate(-50%, -50%) rotate(var(--rot)) scale(var(--s)); }
+  78%  { transform: translate(-50%, -50%) rotate(var(--rot)) scale(var(--s)); opacity: 1; }
+  100% { transform: translate(-50%, -50%) rotate(var(--rot)) scale(calc(var(--s) * 0.5)); opacity: 0; }
+}
+@media (prefers-reduced-motion: reduce) {
+  #sticker-layer .sticker { animation-duration: 1ms; }
+}
+`;
+
+const rand = (a, b) => a + Math.random() * (b - a);
+
+export function initStickers({ signed = (u) => u, isLocked = () => false } = {}) {
+  const url = (name) => signed(`${DIR}/${name}.webp?v=${ASSET_V}`);
+
+  const style = document.createElement("style");
+  style.textContent = CSS;
+  document.head.appendChild(style);
+
+  const layer = document.createElement("div");
+  layer.id = "sticker-layer";
+  layer.setAttribute("aria-hidden", "true");
+  document.body.appendChild(layer);
+
+  // Warm the image cache so the first pop of each sticker isn't a blank
+  // frame while the webp downloads.
+  for (const { pool } of Object.values(EVENTS))
+    for (const v of pool) if (v.img) new Image().src = url(v.img);
+
+  const lastAt = new Map(); // event -> last pop timestamp
+  // Avoid showing the same variant twice in a row per event.
+  const lastPick = new Map();
+
+  const pop = (event) => {
+    const cfg = EVENTS[event];
+    if (!cfg) return;
+    if (isLocked()) return; // no stickers during the entrance/reset ceremony
+    const now = performance.now();
+    if (now - (lastAt.get(event) ?? -Infinity) < cfg.cool) return;
+    if (layer.childElementCount >= MAX_LIVE) return;
+    lastAt.set(event, now);
+
+    let i = (Math.random() * cfg.pool.length) | 0;
+    if (cfg.pool.length > 1 && i === lastPick.get(event)) i = (i + 1) % cfg.pool.length;
+    lastPick.set(event, i);
+    const v = cfg.pool[i];
+
+    const el = document.createElement("div");
+    el.className = "sticker";
+    el.style.left = `${rand(ZONE.x0, ZONE.x1)}%`;
+    el.style.top = `${rand(ZONE.y0, ZONE.y1)}%`;
+    el.style.setProperty("--rot", `${rand(-14, 14)}deg`);
+    el.style.setProperty("--s", rand(0.88, 1.12).toFixed(2));
+
+    if (v.img) {
+      const img = document.createElement("img");
+      img.src = url(v.img);
+      img.width = v.w;
+      img.alt = "";
+      el.appendChild(img);
+      if (v.text) {
+        const t = document.createElement("span");
+        t.className = "sticker-text sticker-overlay";
+        t.style.color = v.color;
+        t.textContent = v.text;
+        el.appendChild(t);
+      }
+    } else {
+      const t = document.createElement("span");
+      t.className = "sticker-text";
+      t.style.color = v.color;
+      t.textContent = v.text;
+      el.appendChild(t);
+    }
+
+    el.addEventListener("animationend", () => el.remove(), { once: true });
+    // Fallback sweep in case the animation never fires (hidden tab).
+    setTimeout(() => el.remove(), LIFE_MS + 500);
+    layer.appendChild(el);
+  };
+
+  return {
+    pop,
+    dispose() {
+      layer.remove();
+      style.remove();
+    },
+  };
+}

variants.js

@@ -228,13 +228,89 @@ function matFor(spec) {
   return m;
 }
 
+// ── Smooth colourway fades ──────────────────────────────────────────────
+// applyVariant on a rig that is live in a scene tweens every mesh's
+// colour/roughness/metalness toward the new spec (same feel as the
+// showcase site: ~0.35 s, ease in-out) instead of snapping. Off-scene
+// rigs (first paint, the locomotion rig swap before scene.add, freshly
+// cloned ghosts) keep the instant path, so hidden repaints stay exact.
+//
+// Each fading mesh gets a transient material (clone of the target cache
+// entry, rewound to the current look) so the shared matCache instances
+// are never mutated. The per-frame driver writes to that transient
+// material AND to whatever the mesh currently carries: systems that swap
+// materials mid-fade (ghostify's transparent clones, the wireframe FX's
+// clip clones) keep receiving colour updates and still land on the exact
+// target values. When nothing intervened, the mesh settles back on the
+// shared cache material, so the at-rest state is byte-identical to a
+// snap (the wireframe FX caches clip clones per material uuid, which
+// must stay stable across colour changes). Driven by a self-contained
+// rAF ticker that only runs while fades are active - no render-loop hook
+// needed, and rapid re-clicks simply retarget from the current colours.
+const FADE_S = 0.35;
+const easeInOut = (x) => (x < 0.5 ? 4 * x * x * x : 1 - Math.pow(-2 * x + 2, 3) / 2);
+const fades = new Map(); // mesh -> fade record
+let fadeRaf = 0;
+
+function driveFades() {
+  const t = performance.now() / 1000;
+  for (const [mesh, f] of fades) {
+    const x = Math.min(1, (t - f.start) / FADE_S);
+    const e = easeInOut(x);
+    f.mat.color.lerpColors(f.fromColor, f.toColor, e);
+    f.mat.roughness = f.fromRough + (f.toRough - f.fromRough) * e;
+    f.mat.metalness = f.fromMetal + (f.toMetal - f.fromMetal) * e;
+    const cur = mesh.material;
+    if (cur !== f.mat && cur?.color) {
+      cur.color.copy(f.mat.color);
+      cur.roughness = f.mat.roughness;
+      cur.metalness = f.mat.metalness;
+    }
+    if (x >= 1) {
+      fades.delete(mesh);
+      if (cur === f.mat) {
+        mesh.material = matFor(f.spec);
+        f.mat.dispose();
+      }
+    }
+  }
+  fadeRaf = fades.size ? requestAnimationFrame(driveFades) : 0;
+}
+
 export function applyVariant(rig, variant) {
   const v = typeof variant === "string" ? VARIANTS[variant] : variant;
   const map = meshMaterialsFor(v);
+  const fade = !!rig.placer?.parent;
   rig.root.traverse((o) => {
     if (!o.isMesh || !o.userData.meshName) return;
-    o.material = matFor(map[o.userData.meshName] ?? v.mechGray);
+    const spec = map[o.userData.meshName] ?? v.mechGray;
+    const target = matFor(spec);
+    if (!fade) {
+      fades.delete(o);
+      o.material = target;
+      return;
+    }
+    // Already resting on the target material and not mid-fade: no-op.
+    if (o.material === target && !fades.has(o)) return;
+    const from = o.material;
+    const m = target.clone();
+    m.color.copy(from.color);
+    m.roughness = from.roughness;
+    m.metalness = from.metalness;
+    fades.set(o, {
+      mat: m,
+      spec,
+      fromColor: from.color.clone(),
+      toColor: target.color.clone(),
+      fromRough: from.roughness,
+      toRough: target.roughness,
+      fromMetal: from.metalness,
+      toMetal: target.metalness,
+      start: performance.now() / 1000,
+    });
+    o.material = m;
   });
+  if (fades.size && !fadeRaf) fadeRaf = requestAnimationFrame(driveFades);
 }
 
 // Linear-space spec colour -> sRGB CSS hex, for swatch UI elements.