@waica/engine 0.21.0 → 0.23.0

package/dist/index.js

@@ -15,6 +15,7 @@ export { authoringDefaults } from './authoring-defaults.js';
 export { collectModuleComponents, mergeRegistryComponents } from './component-registry.js';
 export { resolveComponentUpdateSchedule } from './component-update-schedule.js';
 export { Input, DEFAULT_BINDINGS } from './input.js';
+export { ACTION_HELD_THRESHOLD, firstStandardPadValues, GAMEPAD_CODE_PREFIX, gamepadControl, } from './gamepad.js';
 export { Pointer } from './pointer.js';
 export { RUNTIME_BRIDGE_CAPABILITIES, RUNTIME_BRIDGE_PROTOCOL_VERSION, RUNTIME_BRIDGE_SYMBOL, RuntimeBridgeOperationError, } from './runtime-bridge.js';
 export { RUNTIME_PROJECTION_LIMITS } from './runtime-inspection.js';

package/dist/input.d.ts

@@ -1,41 +1,89 @@
 export type ActionName = string;
 export type InjectedActionOperation = 'press' | 'hold' | 'release';
-/** Action → KeyboardEvent.code list. */
+/** Action → source codes: `KeyboardEvent.code` values and `Gamepad:<control>` codes (ADR 0023). */
 export type InputBindings = Record<string, string[]>;
 /** Neutral engine baseline; archetypes own their action vocabulary. */
 export declare const DEFAULT_BINDINGS: Readonly<InputBindings>;
+/** An injection's checked `value`, or why it is rejected. */
+export type InjectedValueCheck = {
+    value: number | undefined;
+} | {
+    error: string;
+};
 /**
- * Action-based input with archetype default bindings.
- * v0: keyboard. TODO(H1): gamepad and touch.
+ * The injection value rule Input and the Runtime Bridge share: only `hold`
+ * takes a value, a finite number in (0, 1]; an absent value always passes.
+ */
+export declare function checkInjectedValue(operation: InjectedActionOperation, value: unknown): InjectedValueCheck;
+export interface InputOptions {
+    /** Radial stick dead zone in [0, 1); absent or invalid means 0.2. */
+    gamepadDeadZone?: number;
+}
+/**
+ * Action-based input with archetype default bindings. Sources are keys and
+ * player 1's standard gamepad (ADR 0023); every Action has a 0..1 value, the
+ * max across its sources, and is held at 0.5 or above. Touch is still TODO.
  */
 export declare class Input {
     private readonly bindings;
     private readonly down;
     private readonly justDown;
-    private readonly injectedDown;
+    private readonly injectedHolds;
     private readonly injectedJustDown;
     private readonly injectedPresses;
     private readonly used;
+    private readonly deadZone;
+    private readonly padSlot;
+    /** Live pad values by code, after the last poll; disarmed codes read 0. */
+    private padValues;
+    /** Pad codes released while held: they count again only after dropping below the threshold. */
+    private readonly disarmed;
+    /** Actions held when the last step closed: a press is a step that starts from none of them (CA-5). */
+    private heldAtStepEnd;
     /** Installs exactly the action map supplied by the active archetype/project. */
-    constructor(bindings?: Readonly<InputBindings>);
-    /** Is the action held this frame? */
+    constructor(bindings?: Readonly<InputBindings>, options?: InputOptions);
+    /** Is the action held this frame (some source at 0.5 or above)? */
     held(action: ActionName): boolean;
-    /** Was the action pressed exactly this frame? */
+    /**
+     * Was the action pressed exactly this frame? True when no source held it
+     * as the last step closed and some source holds it now — or a key or an
+     * injection held it since, even if already released (a tap between steps).
+     */
     justPressed(action: ActionName): boolean;
+    /**
+     * The action's 0..1 value: the max across its sources — 1 for a key that
+     * is down, a pad button's value, a stick half's dead-zoned component, an
+     * injected hold's value. 0 for an unknown or unbound action.
+     */
+    value(action: ActionName): number;
     /** Installed semantic action names in deterministic order. */
     availableActions(): ActionName[];
     /**
-     * The key codes bound to the action, in their declared order (e.g.
+     * The source codes bound to the action, in their declared order (e.g.
      * `['KeyE', 'Space']`); `[]` for an unknown or unbound action. A new
      * array every call: mutating it never changes the bindings.
      */
     bindingsFor(action: ActionName): string[];
     /** Currently held semantic action names in deterministic order. */
     heldActions(): ActionName[];
-    /** Injects an action by semantic name; false means the action is not installed. */
-    injectAction(action: ActionName, operation: InjectedActionOperation): boolean;
-    /** -1..1 axis from two actions (left/right by default). */
+    /** The value of every held action, keyed in the same order as heldActions(). */
+    actionValues(): Record<ActionName, number>;
+    /**
+     * Injects an action by semantic name; false means the action is not
+     * installed. `hold` takes an optional value in (0, 1] (default 1) and is
+     * one more source of the action: below 0.5 it moves it without holding it.
+     * A value outside (0, 1], or any value on `press`/`release`, throws a
+     * RangeError before anything changes (checkInjectedValue, the Runtime
+     * Bridge's rule).
+     */
+    injectAction(action: ActionName, operation: InjectedActionOperation, value?: number): boolean;
+    /** -1..1 axis from two actions (left/right by default): value(positive) − value(negative). */
     axis(negative?: ActionName, positive?: ActionName): number;
+    /**
+     * Reads player 1's pad. The Game calls this once per Simulation Step,
+     * before component updates.
+     */
+    pollGamepad(): void;
     /**
      * Marks this frame's press of the action as spent, so consumers that
      * honor consumption (state-machine 'input:' triggers) ignore it. One
@@ -49,6 +97,8 @@ export declare class Input {
     endFrame(): void;
     dispose(): void;
     private isActive;
+    /** Every pad source reads 0; the ones that were held stay released until they drop below the threshold. */
+    private releasePad;
     private releaseAll;
     private onVisibilityChange;
     private onKeyDown;

package/dist/input.js

@@ -1,41 +1,96 @@
+import { ACTION_HELD_THRESHOLD, connectedGamepads, GAMEPAD_CODE_PREFIX, gamepadControl, gamepadValues, GamepadSlot, resolveGamepadDeadZone, } from './gamepad.js';
 /** Neutral engine baseline; archetypes own their action vocabulary. */
 export const DEFAULT_BINDINGS = {};
 /**
- * Action-based input with archetype default bindings.
- * v0: keyboard. TODO(H1): gamepad and touch.
+ * The injection value rule Input and the Runtime Bridge share: only `hold`
+ * takes a value, a finite number in (0, 1]; an absent value always passes.
+ */
+export function checkInjectedValue(operation, value) {
+    if (value === undefined)
+        return { value };
+    if (operation !== 'hold')
+        return { error: `${operation} does not accept a value; only hold does.` };
+    if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0 || value > 1) {
+        return { error: 'value must be a finite number greater than 0 and at most 1.' };
+    }
+    return { value };
+}
+/**
+ * Action-based input with archetype default bindings. Sources are keys and
+ * player 1's standard gamepad (ADR 0023); every Action has a 0..1 value, the
+ * max across its sources, and is held at 0.5 or above. Touch is still TODO.
  */
 export class Input {
     bindings = new Map();
     down = new Set();
     justDown = new Set();
-    injectedDown = new Set();
+    injectedHolds = new Map();
     injectedJustDown = new Set();
     injectedPresses = new Set();
     used = new Set();
+    deadZone;
+    padSlot = new GamepadSlot();
+    /** Live pad values by code, after the last poll; disarmed codes read 0. */
+    padValues = new Map();
+    /** Pad codes released while held: they count again only after dropping below the threshold. */
+    disarmed = new Set();
+    /** Actions held when the last step closed: a press is a step that starts from none of them (CA-5). */
+    heldAtStepEnd = new Set();
     /** Installs exactly the action map supplied by the active archetype/project. */
-    constructor(bindings = DEFAULT_BINDINGS) {
+    constructor(bindings = DEFAULT_BINDINGS, options = {}) {
+        const warned = new Set();
         for (const [action, codes] of Object.entries(bindings)) {
             this.bindings.set(action, new Set(codes));
+            for (const code of codes)
+                warnUnknownPadCode(code, warned);
         }
+        this.deadZone = resolveGamepadDeadZone(options.gamepadDeadZone, (message) => {
+            console.warn(message);
+        });
         window.addEventListener('keydown', this.onKeyDown);
         window.addEventListener('keyup', this.onKeyUp);
         window.addEventListener('blur', this.releaseAll);
         document.addEventListener('visibilitychange', this.onVisibilityChange);
     }
-    /** Is the action held this frame? */
+    /** Is the action held this frame (some source at 0.5 or above)? */
     held(action) {
-        return this.injectedDown.has(action) || this.isActive(action, this.down);
+        return this.value(action) >= ACTION_HELD_THRESHOLD;
     }
-    /** Was the action pressed exactly this frame? */
+    /**
+     * Was the action pressed exactly this frame? True when no source held it
+     * as the last step closed and some source holds it now — or a key or an
+     * injection held it since, even if already released (a tap between steps).
+     */
     justPressed(action) {
-        return this.injectedJustDown.has(action) || this.isActive(action, this.justDown);
+        if (this.heldAtStepEnd.has(action))
+            return false;
+        return (this.held(action) ||
+            this.injectedJustDown.has(action) ||
+            this.isActive(action, this.justDown));
+    }
+    /**
+     * The action's 0..1 value: the max across its sources — 1 for a key that
+     * is down, a pad button's value, a stick half's dead-zoned component, an
+     * injected hold's value. 0 for an unknown or unbound action.
+     */
+    value(action) {
+        const codes = this.bindings.get(action);
+        if (!codes)
+            return 0;
+        let value = this.injectedPresses.has(action) ? 1 : (this.injectedHolds.get(action) ?? 0);
+        for (const code of codes) {
+            if (this.down.has(code))
+                return 1;
+            value = Math.max(value, this.padValues.get(code) ?? 0);
+        }
+        return value;
     }
     /** Installed semantic action names in deterministic order. */
     availableActions() {
         return [...this.bindings.keys()].sort();
     }
     /**
-     * The key codes bound to the action, in their declared order (e.g.
+     * The source codes bound to the action, in their declared order (e.g.
      * `['KeyE', 'Space']`); `[]` for an unknown or unbound action. A new
      * array every call: mutating it never changes the bindings.
      */
@@ -46,29 +101,65 @@ export class Input {
     heldActions() {
         return this.availableActions().filter((action) => this.held(action));
     }
-    /** Injects an action by semantic name; false means the action is not installed. */
-    injectAction(action, operation) {
+    /** The value of every held action, keyed in the same order as heldActions(). */
+    actionValues() {
+        return Object.fromEntries(this.heldActions().map((action) => [action, this.value(action)]));
+    }
+    /**
+     * Injects an action by semantic name; false means the action is not
+     * installed. `hold` takes an optional value in (0, 1] (default 1) and is
+     * one more source of the action: below 0.5 it moves it without holding it.
+     * A value outside (0, 1], or any value on `press`/`release`, throws a
+     * RangeError before anything changes (checkInjectedValue, the Runtime
+     * Bridge's rule).
+     */
+    injectAction(action, operation, value) {
+        const checked = checkInjectedValue(operation, value);
+        if ('error' in checked)
+            throw new RangeError(checked.error);
         if (!this.bindings.has(action))
             return false;
         if (operation === 'release') {
-            this.injectedDown.delete(action);
+            this.injectedHolds.delete(action);
             this.injectedPresses.delete(action);
             return true;
         }
-        if (this.held(action)) {
-            if (operation === 'hold')
-                this.injectedPresses.delete(action);
-            return true;
+        const wasHeld = this.held(action);
+        if (operation === 'hold') {
+            // A queued press becomes this persistent hold rather than a second edge.
+            this.injectedPresses.delete(action);
+            this.injectedHolds.set(action, checked.value ?? 1);
         }
-        this.injectedDown.add(action);
-        this.injectedJustDown.add(action);
-        if (operation === 'press')
+        else if (!wasHeld) {
             this.injectedPresses.add(action);
+        }
+        if (!wasHeld && this.held(action))
+            this.injectedJustDown.add(action);
         return true;
     }
-    /** -1..1 axis from two actions (left/right by default). */
+    /** -1..1 axis from two actions (left/right by default): value(positive) − value(negative). */
     axis(negative = 'left', positive = 'right') {
-        return (this.held(positive) ? 1 : 0) - (this.held(negative) ? 1 : 0);
+        return this.value(positive) - this.value(negative);
+    }
+    /**
+     * Reads player 1's pad. The Game calls this once per Simulation Step,
+     * before component updates.
+     */
+    pollGamepad() {
+        const { pad, lostActive } = this.padSlot.poll(connectedGamepads());
+        // No pad, none lost and no pad values: nothing can change (the common keyboard-only case).
+        if (!pad && !lostActive && this.padValues.size === 0)
+            return;
+        if (lostActive)
+            this.releasePad();
+        const raw = pad ? gamepadValues(pad, this.deadZone) : new Map();
+        for (const [code, value] of raw) {
+            if (value < ACTION_HELD_THRESHOLD)
+                this.disarmed.delete(code);
+            else if (this.disarmed.has(code))
+                raw.set(code, 0);
+        }
+        this.padValues = raw;
     }
     /**
      * Marks this frame's press of the action as spent, so consumers that
@@ -87,13 +178,12 @@ export class Input {
     endFrame() {
         this.justDown.clear();
         this.injectedJustDown.clear();
-        for (const action of this.injectedPresses)
-            this.injectedDown.delete(action);
         this.injectedPresses.clear();
         this.used.clear();
+        this.heldAtStepEnd = new Set(this.heldActions());
     }
     dispose() {
-        this.injectedDown.clear();
+        this.injectedHolds.clear();
         this.injectedJustDown.clear();
         this.injectedPresses.clear();
         window.removeEventListener('keydown', this.onKeyDown);
@@ -110,9 +200,18 @@ export class Input {
                 return true;
         return false;
     }
+    /** Every pad source reads 0; the ones that were held stay released until they drop below the threshold. */
+    releasePad() {
+        for (const [code, value] of this.padValues) {
+            if (value >= ACTION_HELD_THRESHOLD)
+                this.disarmed.add(code);
+        }
+        this.padValues = new Map();
+    }
     releaseAll = () => {
         this.down.clear();
         this.justDown.clear();
+        this.releasePad();
     };
     onVisibilityChange = () => {
         if (document.visibilityState === 'hidden')
@@ -128,3 +227,10 @@ export class Input {
         this.down.delete(e.code);
     };
 }
+/** An unknown `Gamepad:` code never matches; it is reported once per code per Input. */
+function warnUnknownPadCode(code, warned) {
+    if (!code.startsWith(GAMEPAD_CODE_PREFIX) || warned.has(code) || gamepadControl(code))
+        return;
+    warned.add(code);
+    console.warn(`[waica] unknown gamepad binding "${code}": it never matches.`);
+}

package/dist/runtime-bridge.d.ts

@@ -18,8 +18,11 @@ export type RuntimeMode = 'paused' | 'real-time';
  * operation and before a screenshot. `camera-effects` (issue #74, ADR 0020)
  * announces that every snapshot carries `camera: { shake, fade, flash }`
  * from `game.cameraEffects`; the `scene` operation stays a hard cut.
+ * `analog-actions` (issue #75, ADR 0023) announces that `hold` takes an
+ * optional `value` in (0, 1] and that every control result carries
+ * `actionValues` beside `heldActions`.
  */
-export declare const RUNTIME_BRIDGE_CAPABILITIES: readonly ['click', 'scene', 'fixed-step', 'assets', 'camera-effects'];
+export declare const RUNTIME_BRIDGE_CAPABILITIES: readonly ['click', 'scene', 'fixed-step', 'assets', 'camera-effects', 'analog-actions'];
 export interface RuntimeMetadata {
     bridgeVersion: typeof RUNTIME_BRIDGE_PROTOCOL_VERSION;
     engineVersion: string;
@@ -31,8 +34,14 @@ export interface RuntimeMetadata {
     assets: AssetStatus;
 }
 export type RuntimeControlRequest = {
-    operation: 'press' | 'hold' | 'release';
+    operation: 'press' | 'release';
     action: string;
+}
+/** Holds at `value` in (0, 1]; without one, at 1. */
+ | {
+    operation: 'hold';
+    action: string;
+    value?: number;
 } | {
     operation: 'pause' | 'resume';
 }
@@ -50,6 +59,8 @@ export type RuntimeControlRequest = {
 };
 export interface RuntimeControlResult extends RuntimeMetadata {
     heldActions: string[];
+    /** The value of each held action, in the same order as `heldActions`. */
+    actionValues: Record<string, number>;
 }
 export declare class RuntimeBridgeOperationError extends Error {
     readonly code: 'runtime-invalid-state' | 'runtime-operation-failed';
@@ -82,9 +93,10 @@ export interface RuntimeBridgeHost {
     /** Starts clock-driven playback; `onStep` is told after every Simulation Step. */
     resume(onStep: () => void): void;
     pause(): void;
-    injectAction(action: string, operation: 'press' | 'hold' | 'release'): boolean;
+    injectAction(action: string, operation: 'press' | 'hold' | 'release', value?: number): boolean;
     availableActions(): string[];
     heldActions(): string[];
+    actionValues(): Record<string, number>;
     inspect(metadata: RuntimeMetadata, filters?: RuntimeSnapshotFilters): RuntimeSnapshot;
     click(x: number, y: number): void;
     /** Resolves `name` through the registered catalog and loads it. */

package/dist/runtime-bridge.js

@@ -1,5 +1,6 @@
 import enginePackage from '../package.json' with { type: 'json' };
 import { SIMULATION_STEP } from './fixed-step.js';
+import { checkInjectedValue } from './input.js';
 export const RUNTIME_BRIDGE_PROTOCOL_VERSION = 1;
 export const RUNTIME_BRIDGE_SYMBOL = Symbol.for('@waica/runtime-bridge/v1');
 /**
@@ -17,6 +18,9 @@ export const RUNTIME_BRIDGE_SYMBOL = Symbol.for('@waica/runtime-bridge/v1');
  * operation and before a screenshot. `camera-effects` (issue #74, ADR 0020)
  * announces that every snapshot carries `camera: { shake, fade, flash }`
  * from `game.cameraEffects`; the `scene` operation stays a hard cut.
+ * `analog-actions` (issue #75, ADR 0023) announces that `hold` takes an
+ * optional `value` in (0, 1] and that every control result carries
+ * `actionValues` beside `heldActions`.
  */
 export const RUNTIME_BRIDGE_CAPABILITIES = [
     'click',
@@ -24,6 +28,7 @@ export const RUNTIME_BRIDGE_CAPABILITIES = [
     'fixed-step',
     'assets',
     'camera-effects',
+    'analog-actions',
 ];
 export class RuntimeBridgeOperationError extends Error {
     code;
@@ -116,10 +121,17 @@ export class EngineRuntimeBridge {
                 throw new RuntimeBridgeOperationError('runtime-operation-failed', `Unsupported runtime control operation "${unsupported.operation}".`);
             }
         }
-        return { ...this.metadata(), heldActions: this.host.heldActions() };
+        return {
+            ...this.metadata(),
+            heldActions: this.host.heldActions(),
+            actionValues: this.host.actionValues(),
+        };
     }
     injectAction(request) {
-        if (this.host.injectAction(request.action, request.operation))
+        const checked = checkInjectedValue(request.operation, 'value' in request ? request.value : undefined);
+        if ('error' in checked)
+            throw new RuntimeBridgeOperationError('runtime-operation-failed', checked.error);
+        if (this.host.injectAction(request.action, request.operation, checked.value))
             return;
         const available = this.host.availableActions();
         throw new RuntimeBridgeOperationError('runtime-operation-failed', `Unknown action "${request.action}". Available actions: ${available.join(', ') || '(none)'}.`, available);

package/dist/scene.d.ts

@@ -37,6 +37,16 @@ export interface SceneRenderJson {
     sort?: 'y';
     /** Logical positions are projected to the fixed 2:1 render lattice. */
     projection?: 'isometric';
+    /**
+     * Sprite Batches (ADR 0024). Absent or true: sprites that share art —
+     * same texture (an AnimatedSprite's current sheet), pixel-art filtering and
+     * shape — and sit next to each other in draw order are drawn together in
+     * one call, each one an instance with its own placement, color and frame;
+     * what is drawn in front of what never changes. false: one mesh, one
+     * material and one draw call per sprite, the pre-batching path — set it to
+     * rule batching out of a visual difference or while debugging draw order.
+     */
+    batch?: boolean;
 }
 export interface SceneJson {
     waicaScene: 1 | 2 | 3;

package/dist/spatial-broadphase.d.ts

@@ -15,7 +15,13 @@ export interface SpatialBroadphaseStats {
 export interface SpatialBroadphase<T> {
     readonly stats: SpatialBroadphaseStats;
     candidates(bounds: CollisionBounds): T[];
-    pairs(): Array<readonly [T, T]>;
+    /**
+     * Visits every distinct pair sharing a cell, or involving an overflow
+     * entry, once, in ascending query order. The grid is frozen at creation,
+     * so callbacks that move, spawn or destroy entities do not change which
+     * pairs are visited.
+     */
+    forEachPair(visit: (first: T, second: T) => void): void;
 }
 /**
  * Package-internal fresh uniform grid. Bodies above the fixed occupancy cap

package/dist/spatial-broadphase.js

@@ -4,6 +4,7 @@ import { Hitbox } from './components/hitbox.js';
 import { Solid } from './components/solid.js';
 import { Tilemap } from './components/tilemap.js';
 import { sceneSolids } from './scene-solids.js';
+import { forEachCandidatePair } from './spatial-pairs.js';
 import { usableCollisionBody } from './spatial-query-geometry.js';
 const CELL_OCCUPANCY_CAP = 256;
 function rangeSize(range) {
@@ -54,13 +55,6 @@ function entryValue(entries, index) {
         throw new Error(`Spatial broadphase has no entry at index ${index}`);
     return entry.value;
 }
-/** The entry index stored at `position` of a bucket that is iterated within its bounds. */
-function indexAt(bucket, position) {
-    const index = bucket[position];
-    if (index === undefined)
-        throw new Error(`Spatial broadphase bucket has no index at position ${position}`);
-    return index;
-}
 /** The indexable sources in query order, each with the cell range it covers. */
 function spatialEntries(sources, cellSize, isIndexable) {
     return sources
@@ -79,47 +73,25 @@ function spatialEntries(sources, cellSize, isIndexable) {
 function spatialGrid(entries) {
     const buckets = new Map();
     const overflow = [];
+    const entryBuckets = [];
     for (const [index, entry] of entries.entries()) {
+        const own = [];
+        entryBuckets.push(own);
         if (!entry.range) {
             overflow.push(index);
             continue;
         }
         eachCell(entry.range, (key) => {
-            const bucket = buckets.get(key);
-            if (bucket)
-                bucket.push(index);
-            else
-                buckets.set(key, [index]);
-        });
-    }
-    return { buckets, overflow };
-}
-/** Distinct index pairs sharing a cell, or involving an overflow entry, in ascending order. */
-function candidatePairIndices(grid, entryCount) {
-    const pairKeys = new Set();
-    const width = entryCount;
-    const addPair = (left, right) => {
-        if (left === right)
-            return;
-        const first = Math.min(left, right);
-        const second = Math.max(left, right);
-        pairKeys.add(first * width + second);
-    };
-    for (const bucket of grid.buckets.values()) {
-        for (let left = 0; left < bucket.length; left += 1) {
-            for (let right = left + 1; right < bucket.length; right += 1) {
-                addPair(indexAt(bucket, left), indexAt(bucket, right));
+            let bucket = buckets.get(key);
+            if (!bucket) {
+                bucket = [];
+                buckets.set(key, bucket);
             }
-        }
-    }
-    for (const overflowIndex of grid.overflow) {
-        for (let index = 0; index < entryCount; index += 1) {
-            addPair(overflowIndex, index);
-        }
+            bucket.push(index);
+            own.push(bucket);
+        });
     }
-    return [...pairKeys]
-        .map((key) => [Math.floor(key / width), key % width])
-        .sort(([a1, a2], [b1, b2]) => a1 - b1 || a2 - b2);
+    return { buckets, overflow, entryBuckets };
 }
 /**
  * Package-internal fresh uniform grid. Bodies above the fixed occupancy cap
@@ -144,11 +116,10 @@ export function createSpatialBroadphase(sources, cellSize, isIndexable = usableC
                 .sort((a, b) => a - b)
                 .map((index) => entryValue(entries, index));
         },
-        pairs() {
-            return candidatePairIndices(grid, entries.length).map(([first, second]) => [
-                entryValue(entries, first),
-                entryValue(entries, second),
-            ]);
+        forEachPair(visit) {
+            forEachCandidatePair(grid, (first, second) => {
+                visit(entryValue(entries, first), entryValue(entries, second));
+            });
         },
     };
 }

package/dist/spatial-pairs.d.ts

@@ -0,0 +1,17 @@
+/** The grid shape the pair walk needs: which buckets each entry is in, and the overflow. */
+export interface PairGrid {
+    /** Entries too large to bucket, ascending; they pair with every other entry. */
+    readonly overflow: readonly number[];
+    /** Per entry, the buckets it was added to, each ascending by entry index (empty for overflow entries). */
+    readonly entryBuckets: readonly (readonly (readonly number[])[])[];
+}
+type PairVisitor = (first: number, second: number) => void;
+/**
+ * Visits every distinct index pair sharing a cell, or involving an overflow
+ * entry, in ascending (first, second) order. Buckets fill in index order, so
+ * each one is already ascending: a body in one cell, with no overflow after
+ * it, needs no deduplication or sort. Equivalent to collecting all pairs,
+ * deduplicating and sorting them, without allocating per pair.
+ */
+export declare function forEachCandidatePair(grid: PairGrid, visit: PairVisitor): void;
+export {};