@volter/editor-game 0.5.65

package/src/game-document/InstanceInspectorPicker.tsx

@@ -0,0 +1,183 @@
+import {
+  getInspectedNetworking,
+  inspectedInstanceId,
+  inspectedInstanceVersion,
+  setInspectedInstance,
+  subscribeInspectedInstance,
+} from '@volter/editor-core/authoring/active-systems';
+import { useEditorStore } from '@volter/editor-core/editor-runtime';
+import { gameRealmDiagnostics } from '../host/gated-globals';
+import { faEye } from '@fortawesome/free-solid-svg-icons';
+import {
+  AnchoredMenu,
+  Button,
+  DisclosureIcon,
+  EditorIcon,
+  MenuItem,
+  MenuSeparator,
+  Text,
+  themeVars,
+} from '@volter/editor-sdk/widgets';
+import { useEffect, useRef, useState, useSyncExternalStore } from 'react';
+import {
+  focusedInstanceId,
+  instanceEntries,
+  subscribeFocusedInstance,
+  subscribeGameSession,
+} from '../play/play-mode';
+
+function instancesSnapshot(): string {
+  return instanceEntries()
+    .map(({ id, name }) => `${id}\u0000${name}`)
+    .join('\u0001');
+}
+
+function Diagnostics({ instanceId }: { instanceId: string }) {
+  const store = useEditorStore();
+  useSyncExternalStore(store.subscribe, store.getSnapshot, store.getSnapshot);
+  const focused = useSyncExternalStore(
+    subscribeFocusedInstance,
+    focusedInstanceId,
+    focusedInstanceId,
+  );
+  const [, refresh] = useState(0);
+  useEffect(() => {
+    const timer = window.setInterval(() => refresh((value) => value + 1), 250);
+    return () => window.clearInterval(timer);
+  }, []);
+
+  const realm = gameRealmDiagnostics(instanceId);
+  const networking = getInspectedNetworking();
+  const timers = realm
+    ? (realm.loop.activeTimeouts ?? 0) +
+      (realm.loop.activeIntervals ?? 0) +
+      (realm.loop.activeAnimationFrames ?? 0) +
+      realm.loop.pending
+    : 0;
+  const listeners = realm ? realm.listeners.window + realm.listeners.document : 0;
+  const rows: [string, string][] = [
+    ['Mount', instanceId],
+    ['Simulation', store.playState === 'paused' ? 'Paused' : 'Running'],
+    ['Input', focused === instanceId ? 'Keyboard focus' : 'Inactive'],
+    [
+      'Input events',
+      realm
+        ? `${realm.loop.input ?? 0} observed · ${realm.loop.inputBlocked ?? 0} blocked`
+        : 'Not measured',
+    ],
+    // Two different nothings: no adapter at all, and an adapter that cannot
+    // read connection state. Neither is "disconnected".
+    [
+      'Network',
+      !networking
+        ? 'Not registered'
+        : (networking.getConnectionState?.() ?? 'Not reported by this adapter'),
+    ],
+    ['Owned callbacks', String(timers)],
+    ['Owned listeners', String(listeners)],
+    ['Realm globals', String(realm?.globals ?? 0)],
+    // Same-origin browser storage is intentionally disclosed rather than
+    // presented as isolated. A durable virtual profile would require a stable
+    // project-owned identity beyond the transient mount id.
+    [
+      'Browser storage',
+      realm
+        ? `Shared origin · ${realm.storage.local.reads + realm.storage.session.reads} reads · ${realm.storage.local.writes + realm.storage.session.writes} writes`
+        : 'Shared origin',
+    ],
+  ];
+
+  return (
+    <div
+      role="none"
+      style={{
+        display: 'grid',
+        gridTemplateColumns: '112px minmax(120px, 1fr)',
+        gap: '4px 12px',
+        padding: '8px 10px',
+        fontSize: 10,
+        lineHeight: '15px',
+      }}
+    >
+      {rows.map(([label, value]) => (
+        <div key={label} style={{ display: 'contents' }}>
+          <span style={{ color: themeVars.content.dim }}>{label}</span>
+          <span
+            style={{
+              color: themeVars.content.primary,
+              fontFamily: label === 'Mount' ? themeVars.typography.mono : undefined,
+              overflow: 'hidden',
+              textOverflow: 'ellipsis',
+            }}
+          >
+            {value}
+          </span>
+        </div>
+      ))}
+    </div>
+  );
+}
+
+/** Runtime context selector for a split Game document. This changes only
+ * editor instruments; it never retargets scene authoring or agent commands. */
+export function InstanceInspectorPicker() {
+  useSyncExternalStore(subscribeGameSession, instancesSnapshot, instancesSnapshot);
+  useSyncExternalStore(
+    subscribeInspectedInstance,
+    inspectedInstanceVersion,
+    inspectedInstanceVersion,
+  );
+  const entries = instanceEntries();
+  const inspectedId = inspectedInstanceId();
+  const selected = entries.find((entry) => entry.id === inspectedId) ?? entries[0];
+  const [open, setOpen] = useState(false);
+  const ref = useRef<HTMLButtonElement>(null);
+
+  if (entries.length < 2 || !selected) return null;
+  const diagnostics = gameRealmDiagnostics(selected.id);
+  const warning = (diagnostics?.loop.firedWhileHeld ?? 0) > 0;
+
+  return (
+    <div className="vgai-playbar-popover-anchor">
+      <Button
+        ref={ref}
+        variant="ghost"
+        size="compact"
+        aria-haspopup="menu"
+        aria-expanded={open}
+        onClick={() => setOpen((value) => !value)}
+        title={`Runtime instruments inspect ${selected.name}; agent-addressed commands are unchanged`}
+      >
+        <EditorIcon
+          icon={faEye}
+          size="sm"
+          style={{ color: warning ? themeVars.semantic.warning : undefined }}
+        />
+        <Text variant="code">Inspect {selected.name}</Text>
+        <DisclosureIcon direction="down" />
+      </Button>
+      {open && (
+        <AnchoredMenu
+          anchorRef={ref}
+          gap={3}
+          onDismiss={() => setOpen(false)}
+          style={{ minWidth: 270 }}
+        >
+          {entries.map((entry) => (
+            <MenuItem
+              key={entry.id}
+              role="menuitemradio"
+              aria-checked={entry.id === selected.id}
+              onSelect={() => setInspectedInstance(entry.id)}
+            >
+              {entry.id === selected.id ? '✓ ' : '  '}
+              {entry.name}
+            </MenuItem>
+          ))}
+          <MenuSeparator />
+          <Diagnostics instanceId={selected.id} />
+        </AnchoredMenu>
+      )}
+    </div>
+  );
+}

package/src/game-document/crowd-debug.ts

@@ -0,0 +1,183 @@
+/**
+ * Play-mode crowd debug draw (W1a) — agent-clearance cylinders + velocity
+ * arrows for every live crowd agent, drawn INTO the running game's scene so
+ * the Game tab shows them over the actual gameplay.
+ *
+ * Reads only the `NavigationAdapter.crowdAgents()` capability off the active
+ * game's `SystemAdapters` (installed by play-mode's `setActiveSystems`) — the
+ * editor never touches recast's `Crowd` directly. A game whose navigation
+ * adapter omits `crowdAgents` simply draws nothing (capability-absence
+ * degradation, same doctrine as the rest of the seam).
+ *
+ * Toggled from the Game tab's Debug menu (`CenterDocuments.tsx`), mirroring
+ * the active-document debug-control pattern there.
+ */
+
+import { getActiveSystems } from '@volter/editor-core/authoring/active-systems';
+import type { NavCrowdAgentState } from '@volter/editor-project/adapter';
+import { setUserData } from '@volter/threejs-runtime/ecs/user-data';
+import * as THREE from 'three';
+import { getGameScene } from '../play/play-mode';
+
+let _enabled = false;
+let _raf = 0;
+let _group: THREE.Group | null = null;
+let _attachedScene: THREE.Scene | null = null;
+
+/** Unit cylinder scaled per-agent to (radius, height, radius). */
+const _cylGeo = new THREE.CylinderGeometry(1, 1, 1, 16, 1, true);
+const _cylMat = new THREE.MeshBasicMaterial({
+  color: 0x22ccee,
+  transparent: true,
+  opacity: 0.45,
+  side: THREE.DoubleSide,
+  depthWrite: false,
+});
+
+interface AgentVisual {
+  root: THREE.Group;
+  cylinder: THREE.Mesh;
+  /** Per-visual material clone, so a FAILED agent can flush red without
+   *  repainting the whole crowd. */
+  cylinderMaterial: THREE.MeshBasicMaterial;
+  arrow: THREE.ArrowHelper;
+  /** The agent's REQUESTED PATH — its local corridor corners, drawn in scene
+   *  space (not under `root`, which follows the agent). */
+  path: THREE.Line;
+  /** The move target, a small marker at the corridor's end. */
+  target: THREE.Mesh;
+}
+
+const _pathMat = new THREE.LineBasicMaterial({ color: 0xffaa00, transparent: true, opacity: 0.9 });
+const _targetGeo = new THREE.SphereGeometry(0.12, 12, 8);
+const _targetMat = new THREE.MeshBasicMaterial({ color: 0xffaa00, depthWrite: false });
+const FAILED_COLOR = 0xff3344;
+const OK_COLOR = 0x22ccee;
+
+let _visuals: AgentVisual[] = [];
+
+export function crowdDebugEnabled(): boolean {
+  return _enabled;
+}
+
+export function setCrowdDebugEnabled(enabled: boolean): void {
+  if (enabled === _enabled) return;
+  _enabled = enabled;
+  if (enabled) {
+    _raf = requestAnimationFrame(_tick);
+  } else {
+    cancelAnimationFrame(_raf);
+    _teardown();
+  }
+}
+
+function _tick(): void {
+  if (!_enabled) return;
+  _raf = requestAnimationFrame(_tick);
+  const scene = getGameScene();
+  const agents = scene ? (getActiveSystems().navigation?.crowdAgents?.() ?? []) : [];
+
+  // (Re)attach the group to whatever game scene is currently live — play
+  // restarts swap scenes out from under a long-lived toggle.
+  if (scene !== _attachedScene) {
+    if (_attachedScene && _group) _attachedScene.remove(_group);
+    _attachedScene = scene;
+    if (scene) {
+      if (!_group) {
+        _group = new THREE.Group();
+        _group.name = 'crowd-debug-draw';
+        setUserData(_group, 'editorHelper', true);
+      }
+      scene.add(_group);
+    }
+  }
+  if (!_group || !scene) return;
+
+  _syncVisualCount(_group, agents.length);
+  for (let i = 0; i < agents.length; i++) {
+    _updateAgentVisual(_visuals[i]!, agents[i]!);
+  }
+}
+
+/** Grow/shrink the pooled per-agent visuals to match the live agent count. */
+function _syncVisualCount(group: THREE.Group, count: number): void {
+  while (_visuals.length < count) {
+    const root = new THREE.Group();
+    const cylinderMaterial = _cylMat.clone();
+    const cylinder = new THREE.Mesh(_cylGeo, cylinderMaterial);
+    const arrow = new THREE.ArrowHelper(
+      new THREE.Vector3(1, 0, 0),
+      new THREE.Vector3(),
+      1,
+      0xffaa00,
+    );
+    const path = new THREE.Line(new THREE.BufferGeometry(), _pathMat);
+    const target = new THREE.Mesh(_targetGeo, _targetMat);
+    root.add(cylinder);
+    root.add(arrow);
+    group.add(root);
+    group.add(path);
+    group.add(target);
+    _visuals.push({ root, cylinder, cylinderMaterial, arrow, path, target });
+  }
+  while (_visuals.length > count) {
+    const v = _visuals.pop()!;
+    group.remove(v.root);
+    group.remove(v.path);
+    group.remove(v.target);
+    v.arrow.dispose();
+    v.path.geometry.dispose();
+    v.cylinderMaterial.dispose();
+  }
+}
+
+function _updateAgentVisual(v: AgentVisual, a: NavCrowdAgentState): void {
+  v.root.position.set(a.position.x, a.position.y, a.position.z);
+  v.cylinder.scale.set(a.radius, a.height, a.radius);
+  v.cylinder.position.y = a.height / 2;
+  // A FAILED agent — off the navmesh, going nowhere — flushes red; everything
+  // else keeps the crowd colour. An adapter that predates `state` reports
+  // undefined and draws as walking.
+  v.cylinderMaterial.color.setHex(a.state === 'invalid' ? FAILED_COLOR : OK_COLOR);
+  // The REQUESTED PATH: the agent's local corridor, drawn from its own feet
+  // through the corners, with the move target marked at its own position.
+  const corners = a.corners ?? [];
+  if (corners.length > 0) {
+    v.path.visible = true;
+    v.path.geometry.setFromPoints([
+      new THREE.Vector3(a.position.x, a.position.y + 0.05, a.position.z),
+      ...corners.map((c) => new THREE.Vector3(c.x, c.y + 0.05, c.z)),
+    ]);
+  } else {
+    v.path.visible = false;
+  }
+  if (a.target && corners.length > 0) {
+    v.target.visible = true;
+    v.target.position.set(a.target.x, a.target.y + 0.05, a.target.z);
+  } else {
+    v.target.visible = false;
+  }
+  const speed = Math.hypot(a.velocity.x, a.velocity.y, a.velocity.z);
+  if (speed > 0.01) {
+    v.arrow.visible = true;
+    v.arrow.position.y = a.height / 2;
+    v.arrow.setDirection(
+      new THREE.Vector3(a.velocity.x / speed, a.velocity.y / speed, a.velocity.z / speed),
+    );
+    // Arrow length = half a second of travel, min 0.2 so it stays legible.
+    v.arrow.setLength(Math.max(speed * 0.5, 0.2));
+  } else {
+    v.arrow.visible = false;
+  }
+}
+
+function _teardown(): void {
+  if (_group) {
+    _attachedScene?.remove(_group);
+    for (const v of _visuals) v.arrow.dispose();
+    _group.clear();
+  }
+  _visuals = [];
+  _group = null;
+  _attachedScene = null;
+}

package/src/game-document/device-preview.ts

@@ -0,0 +1,336 @@
+/**
+ * Device preview (W2c, F13 — critique O4). Chrome-device-mode-style presets
+ * for the Game tab: a preset constrains the game mount to a device's CSS
+ * resolution (letterboxed/centered in the panel, scaled down to fit — the
+ * scale/letterbox math is `GamePanel`'s existing device-resolution path in
+ * `CenterDocuments.tsx`), applies the device's DPR to the running renderers
+ * (`resizeGame(w, h, dpr)` → `GameSession.resize`'s optional third arg), and
+ * for phone/tablet presets:
+ *
+ *  - SAFE AREA — the preset carries notch/home-indicator insets. `GamePanel`
+ *    draws a visual overlay (`data-testid="device-safe-area-overlay"`) and
+ *    sets CSS custom properties on the game mount container
+ *    (`data-testid="game-runtime-container"`), the element game canvases and
+ *    react-world DOM layers mount into:
+ *      --vgai-safe-area-inset-top / -right / -bottom / -left   (CSS px)
+ *    Game UI reads them with `var(--vgai-safe-area-inset-top, 0px)`.
+ *    Recorded choice: real `env(safe-area-inset-*)` injection is NOT
+ *    possible from a same-document host (env() values come from the UA for
+ *    the top-level viewport only), so the overlay + CSS vars ARE the
+ *    contract here.
+ *
+ *  - POINTER-AS-TOUCH — mouse input reaches the game as pointer events with
+ *    `pointerType: 'touch'`, emulated at the game-mount DOM boundary
+ *    (`attachDeviceTouchTarget` below): a capture-phase listener on the
+ *    mount container swallows mouse-typed pointer events and re-dispatches a
+ *    clone with `pointerType: 'touch'` on the same target — so anything the
+ *    game registered (raw canvas listeners, gated `window`/`document`
+ *    listeners via `gated-globals.ts` — the clone bubbles to the real window
+ *    exactly like the original would, so the T6.3 input gate still applies)
+ *    sees touch. The engine `InputManager` is untouched: it listens for
+ *    compatibility `mouse*` events on `window`, which the browser still
+ *    fires (we never `preventDefault()` the pointer event). Fidelity limits,
+ *    recorded: real mobile fires compat mousedown/up AFTER a tap completes
+ *    and never streams hover mousemove — here the InputManager sees
+ *    desktop-timed mouse events alongside the touch clones, so games mixing
+ *    pointer handlers with InputManager mouse state get simultaneous rather
+ *    than sequenced input, and hover-dependent logic that breaks on device
+ *    still works in emulation. No `TouchEvent` (`touchstart`/`touchmove`)
+ *    synthesis (Chrome device mode does synthesize these) — raw-touch-event
+ *    games see nothing. A game capture-phase window/document pointer
+ *    listener registers ahead of this seam and sees the original mouse
+ *    event before the clone.
+ *
+ * Persistence: preset + touch override are the PROJECT settings layer's
+ * `devicePreview` (`settings-store.ts` → `.vgai/settings.json`, committed):
+ * the frame a game is designed for is a fact about the project, shared by
+ * everyone who opens it.
+ */
+
+import { projectSettings, updateProjectSettings } from '@volter/editor-core/settings-store';
+
+export type DevicePresetKind = 'fit' | 'phone' | 'tablet' | 'desktop';
+
+export interface SafeAreaInsets {
+  readonly top: number;
+  readonly right: number;
+  readonly bottom: number;
+  readonly left: number;
+}
+
+export interface DevicePreset {
+  readonly id: string;
+  readonly label: string;
+  readonly kind: DevicePresetKind;
+  /** CSS resolution; null for the default fit-panel preset. */
+  readonly width: number | null;
+  readonly height: number | null;
+  /** Device pixel ratio applied to the game renderers; null → host default. */
+  readonly dpr: number | null;
+  /** Notch/home-indicator insets in CSS px; null → no safe-area treatment. */
+  readonly safeArea: SafeAreaInsets | null;
+}
+
+export const FIT_PRESET_ID = 'fit';
+
+/** Chrome-device-mode-class presets. Insets are the real devices' values
+ *  (iPhone 14: 47pt notch + 34pt home indicator; landscape rotates the notch
+ *  to the sides; Android: 24dp status bar + 24dp gesture bar; iPad: 24pt
+ *  status bar + 20pt home indicator). */
+export const DEVICE_PRESETS: readonly DevicePreset[] = [
+  {
+    id: FIT_PRESET_ID,
+    label: 'Fit panel',
+    kind: 'fit',
+    width: null,
+    height: null,
+    dpr: null,
+    safeArea: null,
+  },
+  {
+    id: 'iphone-portrait',
+    label: 'iPhone 14 — 390×844 @3x',
+    kind: 'phone',
+    width: 390,
+    height: 844,
+    dpr: 3,
+    safeArea: { top: 47, right: 0, bottom: 34, left: 0 },
+  },
+  {
+    id: 'iphone-landscape',
+    label: 'iPhone 14 landscape — 844×390 @3x',
+    kind: 'phone',
+    width: 844,
+    height: 390,
+    dpr: 3,
+    safeArea: { top: 0, right: 47, bottom: 21, left: 47 },
+  },
+  {
+    id: 'android-portrait',
+    label: 'Android — 412×915 @2.6x',
+    kind: 'phone',
+    width: 412,
+    height: 915,
+    dpr: 2.6,
+    safeArea: { top: 24, right: 0, bottom: 24, left: 0 },
+  },
+  {
+    id: 'ipad-portrait',
+    label: 'iPad — 820×1180 @2x',
+    kind: 'tablet',
+    width: 820,
+    height: 1180,
+    dpr: 2,
+    safeArea: { top: 24, right: 0, bottom: 20, left: 0 },
+  },
+  {
+    id: 'desktop-1080p',
+    label: 'Desktop — 1920×1080 @1x',
+    kind: 'desktop',
+    width: 1920,
+    height: 1080,
+    dpr: 1,
+    safeArea: null,
+  },
+];
+
+const FIT_PRESET = DEVICE_PRESETS[0] as DevicePreset;
+
+function presetById(id: string): DevicePreset {
+  return DEVICE_PRESETS.find((p) => p.id === id) ?? FIT_PRESET;
+}
+
+// --- store (house module-scope useSyncExternalStore shape) ------------------
+
+let _preset: DevicePreset = FIT_PRESET;
+/** null → auto (on for phone/tablet presets); boolean → explicit override. */
+let _touchOverride: boolean | null = null;
+let _version = 0;
+const _listeners = new Set<() => void>();
+
+function notify(): void {
+  _version++;
+  for (const fn of _listeners) fn();
+}
+
+export function subscribeDevicePreview(fn: () => void): () => void {
+  _listeners.add(fn);
+  return () => {
+    _listeners.delete(fn);
+  };
+}
+
+export const devicePreviewVersion = (): number => _version;
+
+export function devicePreset(): DevicePreset {
+  return _preset;
+}
+
+/** Effective pointer-as-touch state: explicit override, else auto-on for
+ *  phone/tablet presets. */
+export function touchEmulationActive(): boolean {
+  return _touchOverride ?? (_preset.kind === 'phone' || _preset.kind === 'tablet');
+}
+
+export function touchEmulationOverride(): boolean | null {
+  return _touchOverride;
+}
+
+export function setDevicePreset(id: string): void {
+  const next = presetById(id);
+  if (next === _preset) return;
+  _preset = next;
+  // A new device's auto touch policy takes over; the override was a choice
+  // about the PREVIOUS preset.
+  _touchOverride = null;
+  persist();
+  notify();
+}
+
+export function setTouchEmulationOverride(enabled: boolean | null): void {
+  if (enabled === _touchOverride) return;
+  _touchOverride = enabled;
+  persist();
+  notify();
+}
+
+/** The renderer pixel ratio the active preset emulates, or `null` for the
+ *  host default (`min(devicePixelRatio, 2)` — `create-runtime.ts`'s mount
+ *  policy). `play-mode.ts` consults this on session boot so a preset chosen
+ *  BEFORE Play still lands its DPR. */
+export function deviceEmulatedPixelRatio(): number | null {
+  return _preset.dpr;
+}
+
+/** The host-default pixel ratio `GamePanel` passes to restore after a preset
+ *  is cleared — the same formula the runtime mounts with. */
+export function hostDefaultPixelRatio(): number {
+  return Math.min(typeof window !== 'undefined' ? window.devicePixelRatio || 1 : 1, 2);
+}
+
+// --- project persistence (the PROJECT settings layer) ----------------------
+
+function persist(): void {
+  updateProjectSettings({ devicePreview: { preset: _preset.id, touch: _touchOverride } });
+}
+
+/** Load the active project's declared preset into the store (no persist
+ *  write-back) and return it — `GamePanel` calls this on mount and applies
+ *  the returned preset's resolution to the shared game-resolution store. */
+export function restoreDevicePresetForProject(): DevicePreset {
+  const stored = projectSettings().devicePreview;
+  if (stored?.preset) {
+    _preset = presetById(stored.preset);
+    _touchOverride = typeof stored.touch === 'boolean' ? stored.touch : null;
+  } else {
+    // Nothing declared for THIS project: reset module state, or a preset
+    // carried over from a previously-open project would silently apply here
+    // (and a later toggle would persist it under this project).
+    _preset = FIT_PRESET;
+    _touchOverride = null;
+  }
+  notify();
+  return _preset;
+}
+
+// --- pointer-as-touch emulation at the game-mount DOM boundary --------------
+
+const EMULATED_TYPES = ['pointerdown', 'pointermove', 'pointerup', 'pointercancel'] as const;
+
+/** Clones this module dispatched — never re-intercept our own events. */
+const _synthetic = new WeakSet<Event>();
+
+let _touchTarget: HTMLElement | null = null;
+let _detach: (() => void) | null = null;
+
+function interceptPointer(e: Event): void {
+  if (!touchEmulationActive()) return;
+  if (_synthetic.has(e)) return;
+  if (!(e instanceof PointerEvent) || e.pointerType !== 'mouse') return;
+  const target = e.target;
+  if (!target) return;
+  // Swallow the mouse-typed pointer event before it reaches the game (canvas
+  // listeners, gated window/document listeners) …
+  e.stopImmediatePropagation();
+  // … and deliver the identical gesture as touch. Compat mouse events are
+  // deliberately NOT suppressed (no preventDefault): the engine InputManager
+  // listens for window `mouse*` and keeps working, exactly as on a real
+  // mobile browser where compat mouse events accompany touches.
+  const clone = new PointerEvent(e.type, {
+    bubbles: true,
+    cancelable: e.cancelable,
+    composed: true,
+    view: e.view,
+    detail: e.detail,
+    clientX: e.clientX,
+    clientY: e.clientY,
+    screenX: e.screenX,
+    screenY: e.screenY,
+    button: e.button,
+    buttons: e.buttons,
+    ctrlKey: e.ctrlKey,
+    shiftKey: e.shiftKey,
+    altKey: e.altKey,
+    metaKey: e.metaKey,
+    pointerId: e.pointerId,
+    pointerType: 'touch',
+    isPrimary: true,
+    pressure: e.type === 'pointerup' || e.type === 'pointercancel' ? 0 : Math.max(e.pressure, 0.5),
+    width: 20,
+    height: 20,
+  });
+  _synthetic.add(clone);
+  target.dispatchEvent(clone);
+  if (clone.defaultPrevented) e.preventDefault();
+}
+
+/**
+ * (Re)bind the emulation seam to the game mount container. `GamePanel`'s
+ * container callback ref calls this alongside `setGameContainer`; `null`
+ * detaches. Listeners are capture-phase so they run before the canvas (the
+ * event target) and before any bubble listener the game installed; they
+ * no-op unless {@link touchEmulationActive}.
+ */
+export function attachDeviceTouchTarget(el: HTMLElement | null): void {
+  if (el === _touchTarget) return;
+  _detach?.();
+  _detach = null;
+  _touchTarget = el;
+  if (!el) return;
+  for (const type of EMULATED_TYPES) {
+    el.addEventListener(type, interceptPointer, { capture: true });
+  }
+  _detach = () => {
+    for (const type of EMULATED_TYPES) {
+      el.removeEventListener(type, interceptPointer, { capture: true });
+    }
+  };
+}
+
+/**
+ * The detach half, keyed by the element letting go — the same ownership rule
+ * as `play-mode.ts`'s `releaseGameContainer`, for the same overlap: two
+ * GamePanels coexist across a close/reopen gesture, and a STALE panel's
+ * cleanup calling `attachDeviceTouchTarget(null)` after the new panel
+ * attached would strip the CURRENT element's listeners.
+ */
+export function detachDeviceTouchTarget(el: HTMLElement): void {
+  if (_touchTarget !== el) return;
+  attachDeviceTouchTarget(null);
+}
+
+// --- e2e state hook (house rule: assert state, never screenshot-diff) -------
+
+function _stateForE2E() {
+  return {
+    presetId: _preset.id,
+    presetLabel: _preset.label,
+    dpr: _preset.dpr,
+    safeArea: _preset.safeArea,
+    touchActive: touchEmulationActive(),
+  };
+}
+
+if (typeof window !== 'undefined') {
+  (window as unknown as Record<string, unknown>)['__vgaiDevicePreview'] = _stateForE2E;
+}