@jgengine/core 0.6.0 → 0.8.0

package/dist/game/social.js

@@ -1,3 +1,4 @@
+export const DEFAULT_EMOTE_RADIUS = 20;
 const DEFAULT_INVITE_TTL_MS = 60_000;
 export function createSocial(deps) {
     const now = deps.now ?? Date.now;
@@ -71,12 +72,25 @@ export function createSocial(deps) {
                     friendRequests.delete(requestId);
             }
         },
+        decline(userId, requestId) {
+            const request = friendRequests.get(requestId);
+            if (request !== undefined && request.to === userId)
+                friendRequests.delete(requestId);
+        },
         list(userId) {
             return Array.from(friendships.get(userId) ?? [], (friendUserId) => ({
                 userId: friendUserId,
                 online: deps.presence?.(friendUserId).online ?? false,
             }));
         },
+        requestsFor(userId) {
+            const entries = [];
+            for (const [requestId, request] of friendRequests) {
+                if (request.to === userId)
+                    entries.push({ requestId, fromUserId: request.from });
+            }
+            return entries;
+        },
         snapshot(userId) {
             return {
                 friends: Array.from(friendships.get(userId) ?? []),
@@ -211,9 +225,131 @@ export function createSocial(deps) {
                 role: member === current.leader ? "leader" : "member",
             }));
         },
+        decline(userId, inviteId) {
+            const invite = partyInvites.get(inviteId);
+            if (invite !== undefined && invite.to === userId)
+                partyInvites.delete(inviteId);
+        },
         membersOf(userId) {
             return partyOf(userId)?.members.slice() ?? [];
         },
+        invitesFor(userId) {
+            const ttlMs = partyConfig?.inviteTtlMs ?? DEFAULT_INVITE_TTL_MS;
+            const cutoff = now() - ttlMs;
+            const entries = [];
+            for (const [inviteId, invite] of partyInvites) {
+                if (invite.createdAt < cutoff) {
+                    partyInvites.delete(inviteId);
+                    continue;
+                }
+                if (invite.to === userId) {
+                    entries.push({ inviteId, fromUserId: invite.from, createdAt: invite.createdAt });
+                }
+            }
+            return entries;
+        },
+    };
+    const worldInviteTtlMs = deps.worldInviteTtlMs ?? DEFAULT_INVITE_TTL_MS;
+    const worldInviteEntries = new Map();
+    let worldInviteCounter = 0;
+    function pruneWorldInvites() {
+        const cutoff = now() - worldInviteTtlMs;
+        for (const [id, entry] of worldInviteEntries) {
+            if (entry.createdAt < cutoff)
+                worldInviteEntries.delete(id);
+        }
+    }
+    function canWorldInvite(fromUserId, toUserId) {
+        if (fromUserId === toUserId)
+            return { reason: "cannot invite yourself" };
+        if (blocked.get(toUserId)?.has(fromUserId) || blocked.get(fromUserId)?.has(toUserId)) {
+            return { reason: "blocked" };
+        }
+        pruneWorldInvites();
+        for (const entry of worldInviteEntries.values()) {
+            if (entry.fromUserId === fromUserId && entry.toUserId === toUserId) {
+                return { reason: "invite already pending" };
+            }
+        }
+        return null;
+    }
+    const worldInvites = {
+        canInvite: canWorldInvite,
+        invite(fromUserId, toUserId, target) {
+            const denied = canWorldInvite(fromUserId, toUserId);
+            if (denied !== null)
+                return denied;
+            worldInviteCounter += 1;
+            const inviteId = `winv_${worldInviteCounter}`;
+            const entry = {
+                id: inviteId,
+                fromUserId,
+                toUserId,
+                serverId: target.serverId,
+                createdAt: now(),
+            };
+            if (target.joinCode !== undefined)
+                entry.joinCode = target.joinCode;
+            worldInviteEntries.set(inviteId, entry);
+            const invited = {
+                inviteId,
+                fromUserId,
+                toUserId,
+                serverId: target.serverId,
+            };
+            if (target.joinCode !== undefined)
+                invited.joinCode = target.joinCode;
+            events.emit("social.world.invited", invited);
+            return { inviteId };
+        },
+        accept(userId, inviteId) {
+            const entry = worldInviteEntries.get(inviteId);
+            if (entry === undefined)
+                return { reason: `unknown invite "${inviteId}"` };
+            if (entry.toUserId !== userId)
+                return { reason: "invite is not addressed to this user" };
+            if (now() - entry.createdAt > worldInviteTtlMs) {
+                worldInviteEntries.delete(inviteId);
+                return { reason: "invite expired" };
+            }
+            worldInviteEntries.delete(inviteId);
+            const target = { serverId: entry.serverId };
+            if (entry.joinCode !== undefined)
+                target.joinCode = entry.joinCode;
+            const accepted = {
+                inviteId,
+                userId,
+                fromUserId: entry.fromUserId,
+                serverId: entry.serverId,
+            };
+            if (entry.joinCode !== undefined)
+                accepted.joinCode = entry.joinCode;
+            events.emit("social.world.accepted", accepted);
+            return { target };
+        },
+        decline(userId, inviteId) {
+            const entry = worldInviteEntries.get(inviteId);
+            if (entry !== undefined && entry.toUserId === userId)
+                worldInviteEntries.delete(inviteId);
+        },
+        listFor(userId) {
+            pruneWorldInvites();
+            return Array.from(worldInviteEntries.values()).filter((entry) => entry.toUserId === userId);
+        },
+    };
+    const emotes = {
+        play(fromUserId, emoteId, radius) {
+            const emoteDeps = deps.emotes;
+            if (emoteDeps === undefined)
+                return { reason: "emotes not configured" };
+            const origin = emoteDeps.entities.get(fromUserId);
+            if (origin === null)
+                return { reason: `entity "${fromUserId}" is not spawned` };
+            const recipients = emoteDeps.spatial.inRadius(origin.position, radius ?? DEFAULT_EMOTE_RADIUS, (id) => id !== fromUserId && emoteDeps.entities.get(id)?.role === "player");
+            const result = { from: fromUserId, emoteId, at: origin.position, recipients };
+            events.emit("emote.played", result);
+            return result;
+        },
     };
     return {
         friends,
@@ -223,5 +359,7 @@ export function createSocial(deps) {
                 return deps.presence?.(userId) ?? { online: false };
             },
         },
+        emotes,
+        worldInvites,
     };
 }

package/dist/game/spawnPoints.d.ts

@@ -0,0 +1,19 @@
+import type { EntityPose } from "../scene/entityStore.js";
+export interface SpawnPointPose {
+    x: number;
+    y: number;
+    z: number;
+    rotationY?: number;
+}
+export interface RespawnTarget {
+    setPose(id: string, pose: EntityPose): boolean;
+}
+export interface SpawnPoints {
+    record(id: string, pose: SpawnPointPose): void;
+    get(id: string): SpawnPointPose | undefined;
+    list(): readonly (SpawnPointPose & {
+        id: string;
+    })[];
+    respawn(entities: RespawnTarget, entityId: string, spawnId: string): boolean;
+}
+export declare function createSpawnPoints(): SpawnPoints;

package/dist/game/spawnPoints.js

@@ -0,0 +1,23 @@
+export function createSpawnPoints() {
+    const points = new Map();
+    return {
+        record(id, pose) {
+            points.set(id, { ...pose });
+        },
+        get(id) {
+            return points.get(id);
+        },
+        list() {
+            return Array.from(points, ([id, pose]) => ({ id, ...pose }));
+        },
+        respawn(entities, entityId, spawnId) {
+            const pose = points.get(spawnId);
+            if (pose === undefined)
+                return false;
+            return entities.setPose(entityId, {
+                position: { x: pose.x, y: pose.y, z: pose.z },
+                ...(pose.rotationY === undefined ? {} : { rotationY: pose.rotationY }),
+            });
+        },
+    };
+}

package/dist/game/worldItem.d.ts

@@ -0,0 +1,95 @@
+import type { EntityPosition } from "../scene/entityStore.js";
+import { type LootFilterItem, type LootFilterRule } from "./lootFilter.js";
+import type { Drop } from "./lootTable.js";
+/** Scene-entity catalog name every dropped-item instance spawns under (see the three buckets: worldItem is an entity, never an inventory item or object). */
+export declare const WORLD_ITEM_ENTITY_NAME = "world_item";
+export declare const DEFAULT_RARITY = "common";
+export declare const DEFAULT_PICKUP_RADIUS = 2;
+export interface ScatterOptions {
+    radius: number;
+    minRadius?: number;
+    height?: number;
+}
+export declare const DEFAULT_SCATTER: ScatterOptions;
+/** Random offset within an annulus `[minRadius, radius]` around the origin — the on-death scatter impulse. */
+export declare function scatterOffset(rng: () => number, options?: ScatterOptions): EntityPosition;
+export declare function scatterPosition(origin: EntityPosition, rng: () => number, options?: ScatterOptions): EntityPosition;
+export interface WorldItemRecord {
+    instanceId: string;
+    itemId: string;
+    rarity: string;
+    baseType: string;
+    count: number;
+    affixTier?: number;
+    source?: string;
+    droppedAt: number;
+}
+export interface WorldItemSpawnInput {
+    itemId: string;
+    position: EntityPosition;
+    rarity?: string;
+    baseType?: string;
+    count?: number;
+    affixTier?: number;
+    source?: string;
+}
+export interface WorldItemStoreDeps {
+    spawnEntity(position: EntityPosition): string;
+    despawnEntity(instanceId: string): boolean;
+    resolvePosition(instanceId: string): EntityPosition | undefined;
+    now?(): number;
+}
+export interface WorldItemStore {
+    spawn(input: WorldItemSpawnInput): WorldItemRecord;
+    get(instanceId: string): WorldItemRecord | null;
+    list(): readonly WorldItemRecord[];
+    nearestInRadius(from: EntityPosition, radius: number, filter?: (record: WorldItemRecord) => boolean): string | null;
+    /** Detaches the record for a pickup: caller is expected to grant its contents (e.g. `loot.grantToPlayer`) itself. */
+    take(instanceId: string): WorldItemRecord | null;
+    /** Consumes/destroys the record with no grant implied (decay, an explosion, a cleanup sweep) — same despawn path as `take`, leaves no orphaned record. */
+    remove(instanceId: string): WorldItemRecord | null;
+}
+/** Pure pickup-radius + nearest-item selection, usable without a live store (click-to-grab, proximity prompts). */
+export declare function selectNearestWorldItem(candidates: readonly {
+    instanceId: string;
+    position: EntityPosition;
+}[], from: EntityPosition, radius: number): string | null;
+export declare function createWorldItemStore(deps: WorldItemStoreDeps): WorldItemStore;
+export interface ResolveDeathDropsOptions {
+    mode: "grant" | "world";
+    origin: EntityPosition;
+    resolveRarity(itemId: string): string;
+    resolveBaseType?(itemId: string): string;
+    scatter?: ScatterOptions;
+    rng?(): number;
+    source?: string;
+}
+export interface ResolvedDeathDrops {
+    worldSpawns: WorldItemSpawnInput[];
+    grants: Drop[];
+}
+/**
+ * Splits rolled death drops between direct grants and scattered ground items.
+ * `mode: "grant"` is the legacy behavior (loot straight to inventory); `mode:
+ * "world"` routes item drops through a scatter impulse and leaves currency
+ * drops granting directly (coins fly to the killer, gear hits the ground).
+ */
+export declare function resolveDeathDrops(drops: readonly Drop[], options: ResolveDeathDropsOptions): ResolvedDeathDrops;
+export interface RarityStyle {
+    color?: string;
+    beam?: boolean;
+    label?: string;
+}
+export interface WorldItemPresentation {
+    hidden: boolean;
+    color?: string;
+    beam: boolean;
+    label?: string;
+}
+/**
+ * Composes the baseline rarity→beam/color/label render binding (#32, catalog
+ * data the game supplies) with the loot-filter rule overrides (#33). A
+ * matching rule wins field-by-field; unmatched fields fall back to the
+ * rarity's baseline style.
+ */
+export declare function resolveWorldItemPresentation(item: LootFilterItem, rarityStyle: Record<string, RarityStyle> | undefined, rules: readonly LootFilterRule[] | undefined): WorldItemPresentation;

package/dist/game/worldItem.js

@@ -0,0 +1,138 @@
+import { distanceBetween } from "../scene/spatial.js";
+import { evaluateLootFilter } from "./lootFilter.js";
+/** Scene-entity catalog name every dropped-item instance spawns under (see the three buckets: worldItem is an entity, never an inventory item or object). */
+export const WORLD_ITEM_ENTITY_NAME = "world_item";
+export const DEFAULT_RARITY = "common";
+export const DEFAULT_PICKUP_RADIUS = 2;
+export const DEFAULT_SCATTER = { radius: 1.5, minRadius: 0.4, height: 0 };
+/** Random offset within an annulus `[minRadius, radius]` around the origin — the on-death scatter impulse. */
+export function scatterOffset(rng, options = DEFAULT_SCATTER) {
+    const angle = rng() * Math.PI * 2;
+    const min = options.minRadius ?? 0;
+    const span = Math.max(options.radius - min, 0);
+    const distance = min + rng() * span;
+    return [Math.cos(angle) * distance, options.height ?? 0, Math.sin(angle) * distance];
+}
+export function scatterPosition(origin, rng, options = DEFAULT_SCATTER) {
+    const offset = scatterOffset(rng, options);
+    return [origin[0] + offset[0], origin[1] + offset[1], origin[2] + offset[2]];
+}
+/** Pure pickup-radius + nearest-item selection, usable without a live store (click-to-grab, proximity prompts). */
+export function selectNearestWorldItem(candidates, from, radius) {
+    let bestId = null;
+    let bestDistance = Number.POSITIVE_INFINITY;
+    for (const candidate of candidates) {
+        const distance = distanceBetween(from, candidate.position);
+        if (distance <= radius && distance < bestDistance) {
+            bestDistance = distance;
+            bestId = candidate.instanceId;
+        }
+    }
+    return bestId;
+}
+export function createWorldItemStore(deps) {
+    const records = new Map();
+    const now = deps.now ?? Date.now;
+    function removeRecord(instanceId) {
+        const record = records.get(instanceId);
+        if (record === undefined)
+            return null;
+        records.delete(instanceId);
+        deps.despawnEntity(instanceId);
+        return record;
+    }
+    return {
+        spawn(input) {
+            const instanceId = deps.spawnEntity(input.position);
+            const record = {
+                instanceId,
+                itemId: input.itemId,
+                rarity: input.rarity ?? DEFAULT_RARITY,
+                baseType: input.baseType ?? input.itemId,
+                count: input.count ?? 1,
+                droppedAt: now(),
+            };
+            if (input.affixTier !== undefined)
+                record.affixTier = input.affixTier;
+            if (input.source !== undefined)
+                record.source = input.source;
+            records.set(instanceId, record);
+            return record;
+        },
+        get(instanceId) {
+            return records.get(instanceId) ?? null;
+        },
+        list() {
+            return [...records.values()];
+        },
+        nearestInRadius(from, radius, filter) {
+            const candidates = [];
+            for (const record of records.values()) {
+                if (filter !== undefined && !filter(record))
+                    continue;
+                const position = deps.resolvePosition(record.instanceId);
+                if (position !== undefined)
+                    candidates.push({ instanceId: record.instanceId, position });
+            }
+            return selectNearestWorldItem(candidates, from, radius);
+        },
+        take(instanceId) {
+            return removeRecord(instanceId);
+        },
+        remove(instanceId) {
+            return removeRecord(instanceId);
+        },
+    };
+}
+/**
+ * Splits rolled death drops between direct grants and scattered ground items.
+ * `mode: "grant"` is the legacy behavior (loot straight to inventory); `mode:
+ * "world"` routes item drops through a scatter impulse and leaves currency
+ * drops granting directly (coins fly to the killer, gear hits the ground).
+ */
+export function resolveDeathDrops(drops, options) {
+    if (options.mode !== "world")
+        return { worldSpawns: [], grants: [...drops] };
+    const rng = options.rng ?? Math.random;
+    const worldSpawns = [];
+    const grants = [];
+    for (const drop of drops) {
+        if (drop.item === undefined) {
+            grants.push(drop);
+            continue;
+        }
+        const spawn = {
+            itemId: drop.item,
+            count: drop.count,
+            rarity: options.resolveRarity(drop.item),
+            position: scatterPosition(options.origin, rng, options.scatter),
+        };
+        if (options.resolveBaseType !== undefined)
+            spawn.baseType = options.resolveBaseType(drop.item);
+        if (options.source !== undefined)
+            spawn.source = options.source;
+        worldSpawns.push(spawn);
+    }
+    return { worldSpawns, grants };
+}
+/**
+ * Composes the baseline rarity→beam/color/label render binding (#32, catalog
+ * data the game supplies) with the loot-filter rule overrides (#33). A
+ * matching rule wins field-by-field; unmatched fields fall back to the
+ * rarity's baseline style.
+ */
+export function resolveWorldItemPresentation(item, rarityStyle, rules) {
+    const base = rarityStyle?.[item.rarity];
+    const override = rules === undefined || rules.length === 0 ? {} : evaluateLootFilter(rules, item);
+    const presentation = {
+        hidden: override.hidden ?? false,
+        beam: override.beam ?? base?.beam ?? false,
+    };
+    const color = override.color ?? base?.color;
+    if (color !== undefined)
+        presentation.color = color;
+    const label = override.label ?? base?.label;
+    if (label !== undefined)
+        presentation.label = label;
+    return presentation;
+}

package/dist/input/actionBindings.d.ts

@@ -27,8 +27,18 @@ export type ActionStateBindingMap<TAction extends string, TCode extends string =
 export type ActionCodes<TCode extends string = string> = readonly TCode[] | {
     hold?: readonly TCode[];
     toggle?: readonly TCode[];
+    repeatMs?: number;
 };
 export type ActionCodesMap<TAction extends string = string, TCode extends string = string> = Record<TAction, ActionCodes<TCode>>;
+export declare function actionRepeatMs(codes: ActionCodes | undefined): number | undefined;
+export interface ShouldDispatchActionInput {
+    pressed: boolean;
+    down: boolean;
+    repeatMs: number | undefined;
+    lastFiredAt: number | null;
+    now: number;
+}
+export declare function shouldDispatchAction({ pressed, down, repeatMs, lastFiredAt, now }: ShouldDispatchActionInput): boolean;
 export declare function toActionStateBindingMap<TAction extends string, TCode extends string>(map: ActionCodesMap<TAction, TCode>): ActionStateBindingMap<TAction, TCode>;
 export declare function hotbarSlotBindings(count: number, options?: {
     action?: (slot: number) => string;

package/dist/input/actionBindings.js

@@ -27,6 +27,20 @@ export function normalizeKeyCode(code) {
         return "Control";
     return code;
 }
+export function actionRepeatMs(codes) {
+    if (codes === undefined || Array.isArray(codes))
+        return undefined;
+    return codes.repeatMs;
+}
+export function shouldDispatchAction({ pressed, down, repeatMs, lastFiredAt, now }) {
+    if (pressed)
+        return true;
+    if (repeatMs === undefined || repeatMs <= 0)
+        return false;
+    if (!down || lastFiredAt === null)
+        return false;
+    return now - lastFiredAt >= repeatMs;
+}
 function toBindings(codes) {
     return codes.map((code) => ({ primary: code, secondary: null }));
 }

package/dist/input/axisInput.d.ts

@@ -0,0 +1,43 @@
+export interface AxisInput {
+    throttle: number;
+    brake: number;
+    steer: number;
+    handbrake: number;
+}
+export declare const NEUTRAL_AXIS: AxisInput;
+export type AxisName = keyof AxisInput;
+export interface AxisBinding {
+    positive: readonly string[];
+    negative?: readonly string[];
+}
+export type AxisBindingMap = Record<AxisName, AxisBinding>;
+export interface AxisChannelConfig {
+    bindings: AxisBindingMap;
+    smoothing?: number;
+}
+export interface AxisRange {
+    min: number;
+    max: number;
+}
+export declare const AXIS_RANGE: Record<AxisName, AxisRange>;
+export declare function clampAxis(value: number, range: AxisRange): number;
+export declare function rampToward(current: number, target: number, rate: number, dt: number): number;
+/**
+ * Analog control channel — distinct from the digital action bindings. Throttle/brake/steer/handbrake
+ * are continuous values ramped from held keys (a keyboard feels like a pedal) or driven directly from
+ * a gamepad axis via `setAnalog`. `sample(dt, isDown)` folds the current held-key state into the
+ * smoothed value; a `setAnalog` override replaces the digital target for that axis until cleared.
+ */
+export declare class AxisChannel {
+    private readonly bindings;
+    private readonly smoothing;
+    private readonly current;
+    private readonly overrides;
+    constructor(config: AxisChannelConfig);
+    setAnalog(axis: AxisName, value: number): void;
+    clearAnalog(axis: AxisName): void;
+    reset(): void;
+    get value(): AxisInput;
+    sample(dt: number, isDown: (code: string) => boolean): AxisInput;
+}
+export declare const DRIVE_AXIS_BINDINGS: AxisBindingMap;

package/dist/input/axisInput.js

@@ -0,0 +1,70 @@
+export const NEUTRAL_AXIS = { throttle: 0, brake: 0, steer: 0, handbrake: 0 };
+export const AXIS_RANGE = {
+    throttle: { min: 0, max: 1 },
+    brake: { min: 0, max: 1 },
+    steer: { min: -1, max: 1 },
+    handbrake: { min: 0, max: 1 },
+};
+export function clampAxis(value, range) {
+    return value < range.min ? range.min : value > range.max ? range.max : value;
+}
+export function rampToward(current, target, rate, dt) {
+    if (!Number.isFinite(rate))
+        return target;
+    const delta = target - current;
+    const step = rate * dt;
+    if (Math.abs(delta) <= step)
+        return target;
+    return current + Math.sign(delta) * step;
+}
+function digitalTarget(binding, isDown) {
+    const positive = binding.positive.some(isDown) ? 1 : 0;
+    const negative = binding.negative !== undefined && binding.negative.some(isDown) ? 1 : 0;
+    return positive - negative;
+}
+/**
+ * Analog control channel — distinct from the digital action bindings. Throttle/brake/steer/handbrake
+ * are continuous values ramped from held keys (a keyboard feels like a pedal) or driven directly from
+ * a gamepad axis via `setAnalog`. `sample(dt, isDown)` folds the current held-key state into the
+ * smoothed value; a `setAnalog` override replaces the digital target for that axis until cleared.
+ */
+export class AxisChannel {
+    bindings;
+    smoothing;
+    current = { ...NEUTRAL_AXIS };
+    overrides = {};
+    constructor(config) {
+        this.bindings = config.bindings;
+        this.smoothing = config.smoothing ?? 6;
+    }
+    setAnalog(axis, value) {
+        this.overrides[axis] = clampAxis(value, AXIS_RANGE[axis]);
+    }
+    clearAnalog(axis) {
+        delete this.overrides[axis];
+    }
+    reset() {
+        this.current.throttle = 0;
+        this.current.brake = 0;
+        this.current.steer = 0;
+        this.current.handbrake = 0;
+    }
+    get value() {
+        return this.current;
+    }
+    sample(dt, isDown) {
+        for (const axis of Object.keys(this.bindings)) {
+            const range = AXIS_RANGE[axis];
+            const override = this.overrides[axis];
+            const target = override !== undefined ? override : clampAxis(digitalTarget(this.bindings[axis], isDown), range);
+            this.current[axis] = clampAxis(rampToward(this.current[axis], target, this.smoothing, dt), range);
+        }
+        return this.current;
+    }
+}
+export const DRIVE_AXIS_BINDINGS = {
+    throttle: { positive: ["KeyW", "ArrowUp"] },
+    brake: { positive: ["KeyS", "ArrowDown"] },
+    steer: { positive: ["KeyD", "ArrowRight"], negative: ["KeyA", "ArrowLeft"] },
+    handbrake: { positive: ["Space"] },
+};

package/dist/input/gestureSurface.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Single-finger play-surface gesture recognizer for touch controls: taps,
+ * directional flick swipes, and continuous step drags all resolve to action
+ * names from a TouchGestureBindings declaration. Drag steps stream out of
+ * move() as the finger travels; taps and swipes resolve on end(). Timestamps
+ * are injected so the state machine stays pure; the capture layer owns touch
+ * identifiers and pointer capture.
+ */
+import type { TouchGestureBindings } from "./touchScheme.js";
+export interface GestureSurfaceTuning {
+    /** A finger that moves less than this (px) and lifts quickly is a tap. */
+    tapMoveThresholdPx: number;
+    tapMaxMs: number;
+    /** Minimum travel (px) for a lift to register as a swipe. */
+    swipeMinPx: number;
+    /** Minimum lift velocity (px/ms) for a swipe; slower travel is a drag that ends quietly. */
+    swipeMinVelocity: number;
+    /** Default travel (px) per repeated drag action when the binding sets none. */
+    dragStepPx: number;
+}
+export declare const DEFAULT_GESTURE_TUNING: GestureSurfaceTuning;
+export interface GestureSurfaceTracker {
+    begin(x: number, y: number, nowMs: number): void;
+    /** Drag-step actions fired by this movement, in travel order. */
+    move(x: number, y: number): readonly string[];
+    /** Tap or swipe action resolved by lifting the finger, if any. */
+    end(x: number, y: number, nowMs: number): readonly string[];
+    cancel(): void;
+    isActive(): boolean;
+}
+export declare function createGestureSurfaceTracker(bindings: TouchGestureBindings, tuning?: GestureSurfaceTuning): GestureSurfaceTracker;