@crowdedkingdoms/construct 0.0.0 → 0.2.1-dev.1

package/src/platform/studio/instanceStore.test.ts

@@ -0,0 +1,97 @@
+import { describe, expect, it } from 'vitest';
+import type { EventRouter, StateCodec, TypedEvent } from '@crowdedkingdoms/crowdyjs/stores';
+import {
+  EVENT_CATALOG,
+  EVENT_POSES,
+  bytesToBase64,
+  encodeCatalogChunks,
+  encodePosePacket,
+  parseSceneCatalog,
+  type SceneNode,
+} from './instanceSchema';
+import { InstanceStore } from './instanceStore';
+
+function fakeEvents(): EventRouter & { emit: (type: number, bytes: Uint8Array) => void } {
+  const handlers = new Map<number, (event: { value: string }) => void>();
+  return {
+    on<T>(eventType: number, codec: StateCodec<T>, handler: (event: TypedEvent<T>) => void) {
+      handlers.set(eventType, (event) =>
+        handler({ ...event, value: codec.decode(event.value) } as TypedEvent<T>),
+      );
+      return () => handlers.delete(eventType);
+    },
+    emit(type: number, bytes: Uint8Array) {
+      handlers.get(type)?.({ value: bytesToBase64(bytes) });
+    },
+  } as unknown as EventRouter & { emit: (type: number, bytes: Uint8Array) => void };
+}
+
+describe('InstanceStore', () => {
+  it('renders SERVER catalog plus packed poses without CLIENT overlay', () => {
+    const events = fakeEvents();
+    const store = new InstanceStore(events);
+    const catalog = {
+      v: 1,
+      revision: 3,
+      meshes: [],
+      nodes: [
+        { id: 'table', kind: 'box', x: 8, y: 0.8, z: 8, sx: 2, sy: 0.2, sz: 1 },
+        { id: 'cue', kind: 'box', x: 8, y: 1, z: 8, qx: 0, qy: 0, qz: 0, qw: 1 },
+      ],
+    };
+    const utf8 = new TextEncoder().encode(JSON.stringify(catalog));
+    for (const chunk of encodeCatalogChunks(3, utf8)) events.emit(EVENT_CATALOG, chunk);
+    const parsed = parseSceneCatalog(catalog)!;
+    const posed: SceneNode[] = parsed.nodes.map((n) =>
+      n.id === 'cue' ? { ...n, qy: 0.7071, qw: 0.7071 } : n,
+    );
+    events.emit(EVENT_POSES, encodePosePacket(3, posed));
+    const snap = store.snapshot();
+    const cue = snap.instances.find((i) => i.id === 'cue');
+    expect(cue?.qy).toBeCloseTo(0.7071, 2);
+    expect(snap.instances.some((i) => i.id === 'table')).toBe(true);
+
+    for (const chunk of encodeCatalogChunks(3, utf8)) events.emit(EVENT_CATALOG, chunk);
+    const afterKeepalive = store.snapshot();
+    expect(afterKeepalive.instances.find((i) => i.id === 'cue')?.qy).toBeCloseTo(0.7071, 2);
+    store.dispose();
+  });
+
+  it('lets local overlay ids replace replicated ones in this tab only', () => {
+    const events = fakeEvents();
+    const store = new InstanceStore(events);
+    const catalog = {
+      v: 1,
+      revision: 1,
+      nodes: [{ id: 'marker', kind: 'box', x: 0, y: 1, z: 0 }],
+    };
+    for (const chunk of encodeCatalogChunks(1, new TextEncoder().encode(JSON.stringify(catalog)))) {
+      events.emit(EVENT_CATALOG, chunk);
+    }
+    const snap = store.snapshot({
+      overlay: [
+        {
+          id: 'marker',
+          shape: 'sphere',
+          kind: 'sphere',
+          x: 4,
+          y: 1,
+          z: 4,
+          qx: 0,
+          qy: 0,
+          qz: 0,
+          qw: 1,
+          sx: 0.3,
+          sy: 0.3,
+          sz: 0.3,
+          color: 0xff0000,
+          visible: true,
+        },
+      ],
+    });
+    expect(snap.instances).toHaveLength(1);
+    expect(snap.instances[0]?.kind).toBe('sphere');
+    expect(snap.instances[0]?.x).toBe(4);
+    store.dispose();
+  });
+});

package/src/platform/studio/instanceStore.ts

@@ -0,0 +1,120 @@
+/**
+ * SERVER-authoritative instances: catalog + packed poses arriving on the
+ * World Stores EventRouter. Overlay nodes from CLIENT mods merge on top for
+ * the local tab only.
+ */
+import { rawCodec, type EventRouter } from '@crowdedkingdoms/crowdyjs/stores';
+import type { PlayerCodeGridBounds } from '@crowdedkingdoms/crowdyjs';
+
+import {
+  CatalogAssembler,
+  EVENT_CATALOG,
+  EVENT_POSES,
+  applyPoses,
+  bytesFromBase64,
+  composeScene,
+  decodePosePacket,
+  parseSceneCatalog,
+  type ActorXform,
+  type ComposedInstance,
+  type SceneCatalog,
+  type SceneNode,
+} from './instanceSchema';
+import type { ModOverlayObject } from './modOverlay';
+
+export interface InstanceSnapshot {
+  revision: number;
+  instances: readonly ComposedInstance[];
+}
+
+export interface InstanceSnapshotInput {
+  overlay?: readonly ModOverlayObject[];
+  actors?: readonly ActorXform[];
+  grid?: PlayerCodeGridBounds;
+}
+
+export class InstanceStore {
+  private catalog: SceneCatalog | null = null;
+  private poses = new Map<string, SceneNode>();
+  private revisionValue = 0;
+  private readonly assembler = new CatalogAssembler();
+  private readonly offs: Array<() => void> = [];
+
+  constructor(private readonly events: EventRouter) {
+    this.offs.push(
+      events.on(EVENT_CATALOG, rawCodec, (event) => {
+        this.ingestCatalog(event.value);
+      }),
+      events.on(EVENT_POSES, rawCodec, (event) => {
+        this.ingestPoses(event.value);
+      }),
+    );
+  }
+
+  get revision(): number {
+    return this.revisionValue;
+  }
+
+  get catalogRevision(): number {
+    return this.catalog?.revision ?? 0;
+  }
+
+  dispose(): void {
+    for (const off of this.offs) off();
+    this.offs.length = 0;
+    this.catalog = null;
+    this.poses.clear();
+  }
+
+  snapshot(input: InstanceSnapshotInput = {}): InstanceSnapshot {
+    const catalogNodes = this.catalog ? applyPoses(this.catalog.nodes, this.poses) : [];
+    const overlay = input.overlay ?? [];
+    const overlayIds = new Set(overlay.map((n) => n.id));
+    const nodes: SceneNode[] = [...catalogNodes.filter((n) => !overlayIds.has(n.id)), ...overlay];
+    const meshes = this.catalog?.meshes ?? [];
+    return {
+      revision: this.revisionValue,
+      instances: composeScene(nodes, meshes, input.actors ?? [], input.grid),
+    };
+  }
+
+  private ingestCatalog(stateBase64: string): void {
+    let bytes: Uint8Array;
+    try {
+      bytes = bytesFromBase64(stateBase64);
+    } catch {
+      return;
+    }
+    const joined = this.assembler.push(bytes);
+    if (!joined) return;
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(new TextDecoder().decode(joined));
+    } catch {
+      return;
+    }
+    const catalog = parseSceneCatalog(parsed);
+    if (!catalog) return;
+    if (this.catalog && this.catalog.revision === catalog.revision) return;
+    this.catalog = catalog;
+    this.poses.clear();
+    this.revisionValue += 1;
+  }
+
+  private ingestPoses(stateBase64: string): void {
+    if (!this.catalog) return;
+    let bytes: Uint8Array;
+    try {
+      bytes = bytesFromBase64(stateBase64);
+    } catch {
+      return;
+    }
+    const decoded = decodePosePacket(
+      bytes,
+      this.catalog.nodes.map((n) => n.id),
+    );
+    if (!decoded || decoded.catalogRev !== this.catalog.revision) return;
+    this.poses = decoded.poses;
+    this.revisionValue += 1;
+  }
+}

package/src/platform/studio/modOverlay.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it } from 'vitest';
+
+import { MAX_OVERLAY_OBJECTS, ModOverlayStore, parseOverlayPayload } from './modOverlay';
+
+const grid = { low: { x: 3n, y: 0n, z: 3n }, high: { x: 3n, y: 0n, z: 3n } };
+
+describe('parseOverlayPayload', () => {
+  it('reads an objects list and clamps to the grid AABB', () => {
+    const rows = parseOverlayPayload(
+      {
+        objects: [
+          { id: 'cue', shape: 'sphere', x: 56, y: 0.5, z: 56, r: 0.08, color: '#f8fafc' },
+          { id: 'far', x: 0, y: 0, z: 0 },
+        ],
+      },
+      grid,
+    );
+    expect(rows).toHaveLength(2);
+    expect(rows[0]).toMatchObject({ id: 'cue', shape: 'sphere', x: 56, z: 56 });
+    expect(rows[0]?.sx).toBeCloseTo(0.08);
+    expect(rows[1]?.x).toBe(48); // 3 * 16
+    expect(rows[1]?.z).toBe(48);
+  });
+
+  it('caps the list and ignores duplicates', () => {
+    const objects = Array.from({ length: MAX_OVERLAY_OBJECTS + 5 }, (_, i) => ({
+      id: i < 2 ? 'same' : `b${i}`,
+      x: 50,
+      z: 50,
+    }));
+    expect(parseOverlayPayload({ objects })).toHaveLength(MAX_OVERLAY_OBJECTS);
+  });
+
+  it('never treats a string as HTML', () => {
+    expect(parseOverlayPayload('<div id="x">nope</div>')).toEqual([]);
+    expect(parseOverlayPayload({ objects: [{ x: 1, z: 1, color: '<script>' }] })[0]?.color).toBe(
+      0xf8fafc,
+    );
+  });
+});
+
+describe('ModOverlayStore', () => {
+  it('merges sources and drops one on remove', () => {
+    const store = new ModOverlayStore();
+    store.apply('a', { objects: [{ id: 'one', x: 1, z: 1 }] });
+    store.apply('b', { objects: [{ id: 'two', x: 2, z: 2 }] });
+    expect(
+      store
+        .snapshot()
+        .objects.map((o) => o.id)
+        .sort(),
+    ).toEqual(['one', 'two']);
+    store.remove('a');
+    expect(store.snapshot().objects.map((o) => o.id)).toEqual(['two']);
+  });
+});

package/src/platform/studio/modOverlay.ts

@@ -0,0 +1,51 @@
+/**
+ * CLIENT `overlay_draw` is local presentation on the same construct.scene.v1
+ * nodes the replicated instance layer uses. The mod never touches the DOM.
+ */
+import type { PlayerCodeGridBounds } from '@crowdedkingdoms/crowdyjs';
+
+import {
+  MAX_OVERLAY_OBJECTS,
+  parseOverlayPayload,
+  type ModOverlayObject,
+  type ModOverlayShape,
+} from './instanceSchema';
+
+export { MAX_OVERLAY_OBJECTS, parseOverlayPayload, type ModOverlayObject, type ModOverlayShape };
+
+export interface ModOverlaySnapshot {
+  revision: number;
+  objects: readonly ModOverlayObject[];
+}
+
+/** Latest overlay from every running CLIENT source, keyed by source id. */
+export class ModOverlayStore {
+  private readonly bySource = new Map<string, ModOverlayObject[]>();
+  private revisionValue = 0;
+
+  get revision(): number {
+    return this.revisionValue;
+  }
+
+  snapshot(): ModOverlaySnapshot {
+    const objects: ModOverlayObject[] = [];
+    for (const rows of this.bySource.values()) objects.push(...rows);
+    return { revision: this.revisionValue, objects };
+  }
+
+  apply(source: string, payload: unknown, grid?: PlayerCodeGridBounds): void {
+    this.bySource.set(source, parseOverlayPayload(payload, grid));
+    this.revisionValue += 1;
+  }
+
+  remove(source: string): void {
+    if (!this.bySource.delete(source)) return;
+    this.revisionValue += 1;
+  }
+
+  clear(): void {
+    if (this.bySource.size === 0) return;
+    this.bySource.clear();
+    this.revisionValue += 1;
+  }
+}

package/src/platform/studio/permissions.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+  gridBoundsContain,
+  gridBoundsFrom,
+  hasAnyStudioPermission,
+  singleChunkBounds,
+  studioPermissions,
+  toBrokerBounds,
+} from './permissions';
+
+describe('studioPermissions', () => {
+  it('derives SERVER and CLIENT gates independently from the exact keys', () => {
+    const p = studioPermissions(['write_server_code', 'run_client_code', 'access', 'bogus']);
+    expect(p.effectiveKeys).toEqual(['write_server_code', 'run_client_code']);
+    expect(p.server).toEqual({ canWrite: true, canRun: false });
+    expect(p.client).toEqual({ canWrite: false, canRun: true });
+  });
+
+  it('never inflates a missing or empty key list', () => {
+    expect(hasAnyStudioPermission(studioPermissions(undefined))).toBe(false);
+    expect(hasAnyStudioPermission(studioPermissions([]))).toBe(false);
+    expect(hasAnyStudioPermission(studioPermissions(['run_server_code']))).toBe(true);
+  });
+});
+
+describe('grid bounds', () => {
+  it('parses authoritative bounds from strings, numbers and bigints', () => {
+    expect(gridBoundsFrom({ x: '-1', y: 0, z: 2n }, { x: '3', y: '0', z: '2' })).toEqual({
+      low: { x: '-1', y: '0', z: '2' },
+      high: { x: '3', y: '0', z: '2' },
+    });
+  });
+
+  it('rejects malformed or inverted bounds', () => {
+    expect(gridBoundsFrom(null, { x: '1', y: '1', z: '1' })).toBeNull();
+    expect(gridBoundsFrom({ x: '2', y: '0', z: '0' }, { x: '1', y: '0', z: '0' })).toBeNull();
+    expect(gridBoundsFrom({ x: '1.5', y: '0', z: '0' }, { x: '1', y: '0', z: '0' })).toBeNull();
+  });
+
+  it('tests containment inclusively and converts for the broker', () => {
+    const bounds = gridBoundsFrom({ x: '-1', y: '0', z: '-1' }, { x: '1', y: '0', z: '1' })!;
+    expect(gridBoundsContain(bounds, { x: 1, y: 0, z: -1 })).toBe(true);
+    expect(gridBoundsContain(bounds, { x: 2, y: 0, z: 0 })).toBe(false);
+    expect(gridBoundsContain(bounds, { x: 0, y: 1, z: 0 })).toBe(false);
+    expect(toBrokerBounds(singleChunkBounds({ x: 5, y: 0, z: -3 }))).toEqual({
+      low: { x: 5n, y: 0n, z: -3n },
+      high: { x: 5n, y: 0n, z: -3n },
+    });
+  });
+});

package/src/platform/studio/permissions.ts

@@ -0,0 +1,134 @@
+/**
+ * Crowdy Studio permissions and grid bounds, derived from what the platform
+ * says and nothing else.
+ *
+ * A claim (or a nearby-grid read) returns the caller's EFFECTIVE permission
+ * keys on that grid. SERVER and CLIENT write/run gates come from those exact
+ * keys, independently; nothing here infers one target from the other or
+ * inflates a partial key list.
+ */
+export const PLAYER_CODE_PERMISSION_KEYS = [
+  'write_server_code',
+  'run_server_code',
+  'write_client_code',
+  'run_client_code',
+] as const;
+
+export type PlayerCodePermissionKey = (typeof PLAYER_CODE_PERMISSION_KEYS)[number];
+
+export interface TargetPermission {
+  canWrite: boolean;
+  canRun: boolean;
+}
+
+export interface StudioPermissions {
+  effectiveKeys: PlayerCodePermissionKey[];
+  server: TargetPermission;
+  client: TargetPermission;
+}
+
+export const NO_STUDIO_PERMISSIONS: StudioPermissions = {
+  effectiveKeys: [],
+  server: { canWrite: false, canRun: false },
+  client: { canWrite: false, canRun: false },
+};
+
+function isPlayerCodeKey(value: string): value is PlayerCodePermissionKey {
+  return (PLAYER_CODE_PERMISSION_KEYS as readonly string[]).includes(value);
+}
+
+export function studioPermissions(
+  effectiveKeys: readonly unknown[] | null | undefined,
+): StudioPermissions {
+  const keys = new Set((effectiveKeys ?? []).map(String).filter(isPlayerCodeKey));
+  return {
+    effectiveKeys: PLAYER_CODE_PERMISSION_KEYS.filter((key) => keys.has(key)),
+    server: { canWrite: keys.has('write_server_code'), canRun: keys.has('run_server_code') },
+    client: { canWrite: keys.has('write_client_code'), canRun: keys.has('run_client_code') },
+  };
+}
+
+export function hasAnyStudioPermission(permissions: StudioPermissions | null | undefined): boolean {
+  return Boolean(
+    permissions &&
+    (permissions.server.canWrite ||
+      permissions.server.canRun ||
+      permissions.client.canWrite ||
+      permissions.client.canRun),
+  );
+}
+
+/** A grid's chunk AABB, as decimal strings (int64 on the wire). */
+export interface GridBounds {
+  low: { x: string; y: string; z: string };
+  high: { x: string; y: string; z: string };
+}
+
+function decimalInteger(value: unknown): string | null {
+  if (typeof value === 'bigint') return value.toString();
+  if (typeof value === 'number') return Number.isInteger(value) ? String(value) : null;
+  if (typeof value !== 'string' || !/^-?\d+$/u.test(value)) return null;
+  return BigInt(value).toString();
+}
+
+function parseCorner(value: unknown): { x: string; y: string; z: string } | null {
+  if (!value || typeof value !== 'object') return null;
+  const record = value as Record<string, unknown>;
+  const x = decimalInteger(record.x);
+  const y = decimalInteger(record.y);
+  const z = decimalInteger(record.z);
+  return x !== null && y !== null && z !== null ? { x, y, z } : null;
+}
+
+/** Authoritative bounds from a claim/nearby response; null when malformed. */
+export function gridBoundsFrom(low: unknown, high: unknown): GridBounds | null {
+  const l = parseCorner(low);
+  const h = parseCorner(high);
+  if (!l || !h) return null;
+  if (BigInt(l.x) > BigInt(h.x) || BigInt(l.y) > BigInt(h.y) || BigInt(l.z) > BigInt(h.z))
+    return null;
+  return { low: l, high: h };
+}
+
+export function singleChunkBounds(chunk: {
+  x: number | string;
+  y: number | string;
+  z: number | string;
+}): GridBounds {
+  const corner = { x: String(chunk.x), y: String(chunk.y), z: String(chunk.z) };
+  return { low: corner, high: { ...corner } };
+}
+
+export function gridBoundsContain(
+  bounds: GridBounds,
+  chunk: { x: number | string; y: number | string; z: number | string },
+): boolean {
+  const x = BigInt(chunk.x);
+  const y = BigInt(chunk.y);
+  const z = BigInt(chunk.z);
+  return (
+    x >= BigInt(bounds.low.x) &&
+    x <= BigInt(bounds.high.x) &&
+    y >= BigInt(bounds.low.y) &&
+    y <= BigInt(bounds.high.y) &&
+    z >= BigInt(bounds.low.z) &&
+    z <= BigInt(bounds.high.z)
+  );
+}
+
+/** The bigint form the SDK's broker and embed expect. */
+export function toBrokerBounds(
+  bounds: GridBounds,
+  gridId?: string,
+): {
+  low: { x: bigint; y: bigint; z: bigint };
+  high: { x: bigint; y: bigint; z: bigint };
+  gridId?: string;
+} {
+  return {
+    low: { x: BigInt(bounds.low.x), y: BigInt(bounds.low.y), z: BigInt(bounds.low.z) },
+    high: { x: BigInt(bounds.high.x), y: BigInt(bounds.high.y), z: BigInt(bounds.high.z) },
+    // With the id the broker joins the page-local grid event bus (DN-10).
+    ...(gridId ? { gridId } : {}),
+  };
+}

package/src/platform/studio/pointerClicks.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it } from 'vitest';
+
+import { PointerClickBuffer } from './pointerClicks';
+
+describe('PointerClickBuffer', () => {
+  it('drains queued clicks and reports live hold time', () => {
+    let now = 1_000;
+    const buf = new PointerClickBuffer(() => now);
+    buf.push({ t: 'down', button: 0, atMs: 1_000, nx: 0.2, ny: -0.1 }, 1);
+    now = 1_080;
+    const held = buf.drainPointerClicks();
+    expect(held.clicks).toEqual([{ t: 'down', button: 0, atMs: 1_000, nx: 0.2, ny: -0.1 }]);
+    expect(held.buttons).toBe(1);
+    expect(held.holdingMs).toEqual({ '0': 80 });
+    now = 1_200;
+    buf.push({ t: 'up', button: 0, atMs: 1_200, heldMs: 200, nx: 0.2, ny: -0.1 }, 0);
+    const released = buf.drainPointerClicks();
+    expect(released.clicks[0]?.heldMs).toBe(200);
+    expect(released.buttons).toBe(0);
+    expect(released.holdingMs).toEqual({});
+    expect(buf.drainPointerClicks().clicks).toEqual([]);
+  });
+});

package/src/platform/studio/pointerClicks.ts

@@ -0,0 +1,132 @@
+/**
+ * Holodeck mouse clicks for CLIENT mods. DSH builds click-to-charge from
+ * `host_call("pointer_clicks")` / `crowdy::api::pointer_clicks()`: drain the
+ * queue every tick, read `holdingMs["0"]` while LMB is down, fire on `up`.
+ *
+ * Only `.scene-canvas` counts. Studio chrome, text fields, and Monaco are
+ * omitted even while Studio is open, so authors can click the world to test.
+ */
+import { isTextEntry } from '../../engine/Input';
+
+export interface PointerClickEvent {
+  t: 'down' | 'up';
+  button: number;
+  atMs: number;
+  heldMs?: number;
+  nx: number;
+  ny: number;
+}
+
+export interface PointerClicksSnapshot {
+  nowMs: number;
+  buttons: number;
+  holdingMs: Record<string, number>;
+  clicks: PointerClickEvent[];
+}
+
+const MAX_QUEUE = 32;
+const CANVAS_SELECTOR = '.scene-canvas';
+
+function canvasOf(target: EventTarget | null): HTMLCanvasElement | null {
+  if (!(target instanceof Element)) return null;
+  return target.closest(CANVAS_SELECTOR);
+}
+
+function ndcFor(event: PointerEvent, canvas: HTMLCanvasElement | null): { nx: number; ny: number } {
+  if (typeof document !== 'undefined' && document.pointerLockElement) {
+    return { nx: 0, ny: 0 };
+  }
+  if (!canvas) return { nx: 0, ny: 0 };
+  const rect = canvas.getBoundingClientRect();
+  const w = rect.width || 1;
+  const h = rect.height || 1;
+  return {
+    nx: ((event.clientX - rect.left) / w) * 2 - 1,
+    ny: -(((event.clientY - rect.top) / h) * 2 - 1),
+  };
+}
+
+export class PointerClickBuffer {
+  private clicks: PointerClickEvent[] = [];
+  private buttons = 0;
+  private readonly downAt = new Map<number, number>();
+  private lastCanvas: HTMLCanvasElement | null = null;
+  private detach: (() => void) | null = null;
+  private readonly now: () => number;
+
+  constructor(now: () => number = () => Date.now()) {
+    this.now = now;
+  }
+
+  /** Listen on `window` (capture). Safe to call twice. */
+  attach(target: Window | null = typeof window === 'undefined' ? null : window): void {
+    if (this.detach || !target) return;
+    const onDown = (event: PointerEvent) => this.onPointer(event, 'down');
+    const onUp = (event: PointerEvent) => this.onPointer(event, 'up');
+    target.addEventListener('pointerdown', onDown, true);
+    target.addEventListener('pointerup', onUp, true);
+    this.detach = () => {
+      target.removeEventListener('pointerdown', onDown, true);
+      target.removeEventListener('pointerup', onUp, true);
+      this.detach = null;
+    };
+  }
+
+  dispose(): void {
+    this.detach?.();
+    this.clicks = [];
+    this.buttons = 0;
+    this.downAt.clear();
+    this.lastCanvas = null;
+  }
+
+  /** Test helper: enqueue as if the holodeck canvas saw the event. */
+  push(event: PointerClickEvent, buttons = this.buttons): void {
+    if (event.t === 'down') this.downAt.set(event.button, event.atMs);
+    if (event.t === 'up') this.downAt.delete(event.button);
+    this.buttons = buttons;
+    this.clicks.push(event);
+    if (this.clicks.length > MAX_QUEUE) this.clicks.splice(0, this.clicks.length - MAX_QUEUE);
+  }
+
+  drainPointerClicks(): PointerClicksSnapshot {
+    const nowMs = this.now();
+    const clicks = this.clicks;
+    this.clicks = [];
+    const holdingMs: Record<string, number> = {};
+    for (const [button, started] of this.downAt) {
+      holdingMs[String(button)] = Math.max(0, nowMs - started);
+    }
+    return { nowMs, buttons: this.buttons, holdingMs, clicks };
+  }
+
+  private onPointer(event: PointerEvent, phase: 'down' | 'up'): void {
+    if (isTextEntry(event.target)) return;
+    const canvas =
+      canvasOf(event.target) ??
+      (phase === 'up' && this.downAt.has(event.button) ? this.lastCanvas : null);
+    if (phase === 'down') {
+      if (!canvas) return;
+      this.lastCanvas = canvas;
+    } else if (!this.downAt.has(event.button)) {
+      return;
+    }
+    const atMs = this.now();
+    const { nx, ny } = ndcFor(event, canvas);
+    const heldMs =
+      phase === 'up' && this.downAt.has(event.button)
+        ? Math.max(0, atMs - (this.downAt.get(event.button) ?? atMs))
+        : undefined;
+    this.push(
+      {
+        t: phase,
+        button: event.button,
+        atMs,
+        ...(heldMs !== undefined ? { heldMs } : {}),
+        nx,
+        ny,
+      },
+      event.buttons,
+    );
+  }
+}