@jgengine/shell 0.31.0 → 0.33.0

package/dist/audio/emitterTracking.js

@@ -0,0 +1,153 @@
+/**
+ * Track one sound map's positional loops.
+ *
+ * Membership is reconciled only when `sources.ids()` returns a new array, and each frame then reads
+ * just the tracked emitters — so a game with hundreds of props and a handful of sounding ones pays
+ * for the handful, and a still frame allocates nothing. An emitter that gains a sounding key through
+ * a rename is picked up on the next membership change, not per frame; catalog ids never change, and a
+ * spawned entity already carries the name its sound map is keyed by.
+ * @internal
+ */
+export function createEmitterTracker(options) {
+    const entries = [];
+    const byId = new Map();
+    const pose = { key: "", position: [0, 0, 0] };
+    const target = { x: 0, y: 0, z: 0 };
+    let soundsRef;
+    let idsRef = null;
+    let reconcileNext = false;
+    function stopEntry(entry) {
+        entry.handle?.stop();
+        entry.handle = null;
+    }
+    function removeAt(index) {
+        const entry = entries[index];
+        stopEntry(entry);
+        byId.delete(entry.id);
+        const last = entries.pop();
+        if (index < entries.length) {
+            entries[index] = last;
+            last.index = index;
+        }
+    }
+    function clear() {
+        for (let index = 0; index < entries.length; index += 1)
+            stopEntry(entries[index]);
+        entries.length = 0;
+        byId.clear();
+    }
+    function playAt(sound, x, y, z) {
+        target.x = x;
+        target.y = y;
+        target.z = z;
+        return options.play(sound, target);
+    }
+    function start(id, key, sound) {
+        const position = pose.position;
+        const entry = {
+            id,
+            key,
+            sound,
+            handle: playAt(sound, position[0], position[1], position[2]),
+            index: entries.length,
+            x: position[0],
+            y: position[1],
+            z: position[2],
+        };
+        entries.push(entry);
+        byId.set(id, entry);
+    }
+    function retune(entry, sound) {
+        if (sound === undefined) {
+            removeAt(entry.index);
+            return false;
+        }
+        entry.key = pose.key;
+        if (sound !== entry.sound) {
+            stopEntry(entry);
+            entry.sound = sound;
+            entry.handle = playAt(sound, pose.position[0], pose.position[1], pose.position[2]);
+        }
+        applyPose(entry);
+        return true;
+    }
+    function applyPose(entry) {
+        const position = pose.position;
+        if (position[0] === entry.x && position[1] === entry.y && position[2] === entry.z)
+            return;
+        entry.x = position[0];
+        entry.y = position[1];
+        entry.z = position[2];
+        if (entry.handle !== null) {
+            target.x = entry.x;
+            target.y = entry.y;
+            target.z = entry.z;
+            entry.handle.setPosition(target);
+        }
+    }
+    function reconcile(sounds) {
+        for (let index = entries.length - 1; index >= 0; index -= 1) {
+            const entry = entries[index];
+            if (!options.sources.read(entry.id, pose))
+                removeAt(index);
+        }
+        for (const id of options.sources.ids()) {
+            if (byId.has(id) || !options.sources.read(id, pose))
+                continue;
+            const sound = sounds[pose.key];
+            if (sound !== undefined)
+                start(id, pose.key, sound);
+        }
+    }
+    return {
+        step() {
+            const sounds = options.sounds();
+            if (sounds === undefined) {
+                if (entries.length > 0)
+                    clear();
+                soundsRef = undefined;
+                idsRef = null;
+                return;
+            }
+            if (sounds !== soundsRef) {
+                soundsRef = sounds;
+                reconcileNext = true;
+            }
+            const ids = options.sources.ids();
+            if (ids !== idsRef) {
+                idsRef = ids;
+                reconcileNext = true;
+            }
+            if (reconcileNext) {
+                reconcileNext = false;
+                reconcile(sounds);
+            }
+            // Backwards so a retune that drops an entry does not shift the ones still to visit.
+            for (let index = entries.length - 1; index >= 0; index -= 1) {
+                const entry = entries[index];
+                if (!options.sources.read(entry.id, pose)) {
+                    removeAt(index);
+                    continue;
+                }
+                if (pose.key !== entry.key) {
+                    if (!retune(entry, sounds[pose.key]))
+                        continue;
+                }
+                else {
+                    applyPose(entry);
+                }
+                // A stolen or failed voice is retried while its emitter lives, as the per-frame rebuild did.
+                if (entry.handle === null)
+                    entry.handle = playAt(entry.sound, entry.x, entry.y, entry.z);
+            }
+        },
+        count() {
+            return entries.length;
+        },
+        dispose() {
+            clear();
+            soundsRef = undefined;
+            idsRef = null;
+        },
+    };
+}

package/dist/audio/eventFeedback.d.ts

@@ -0,0 +1,137 @@
+import type { FeedbackCue } from "@jgengine/core/audio/feedbackCues";
+import type { GameEventMap, GameEvents } from "@jgengine/core/game/events";
+import type { HapticPulse } from "@jgengine/core/input/haptics";
+import type { WaveRunner } from "@jgengine/core/ai/waveRunner";
+/** One cue's reaction: what plays, what the hand feels, what the screen does, and what a caption says. */
+export interface FeedbackReaction {
+    /** Catalog id played for the cue. Defaults to `feel.<cue>`; a game sound with that id replaces it. */
+    sound: string;
+    /** Gamepad pulse, `0..1` per motor. Omitted cues do not rumble. */
+    haptics?: HapticPulse;
+    /** Camera trauma `0..1`, scaled by the player's motion setting (`0` under reduced motion). */
+    shake?: number;
+    /** Caption text when the accessibility captions setting is on. */
+    caption?: string;
+    /** Minimum ms between two plays of this cue, so a burst of hits reads as one impact. Default 40. */
+    cooldownMs?: number;
+}
+/**
+ * The default reactions. They are data: a game overrides one through `audio.feedbackCues` (sound) or
+ * `createEventFeedback({ reactions })` (haptics, shake, caption), and replaces the mapping through
+ * `bindings` without touching the shell.
+ */
+export declare const DEFAULT_FEEDBACK_REACTIONS: Readonly<Record<FeedbackCue, FeedbackReaction>>;
+/** Which side of an event a binding reacts to: the local player's, someone else's, or either. */
+export type FeedbackScope = "local" | "remote" | "any";
+/** Event names the default mapping listens to; a game may add its own through `bindings`. */
+export type FeedbackEventName = "combat.damage" | "entity.died" | "worldItem.picked_up" | "quest.completed" | "stat.levelUp" | "command.refused";
+/** One row of the event mapping: `event` announces, `cue` reacts. */
+export type FeedbackBinding<Name extends FeedbackEventName = FeedbackEventName> = {
+    event: Name;
+    cue: FeedbackCue;
+    /** Default `"any"`. `"local"` only fires for the local player's own target/user/refusal. */
+    scope?: FeedbackScope;
+    /** Overrides the cue's caption for this event, e.g. "You died". */
+    caption?: string;
+    /** Reads extra caption detail out of the payload, e.g. the damage amount. */
+    detail?: (payload: GameEventMap[Name]) => string | undefined;
+};
+/** Any row of the event mapping, whichever event it binds. */
+export type AnyFeedbackBinding = {
+    [Name in FeedbackEventName]: FeedbackBinding<Name>;
+}[FeedbackEventName];
+/**
+ * The default mapping: each engine-announced gameplay event to the cue it raises. Damage to the
+ * local player reads as hurt, damage anywhere else as a hit; an event that carries a `position`
+ * (damage, death) pans and attenuates its cue, and one without still plays centred. A wave start has
+ * no event of its own, so a game announces it through `notify("wave")` or `attachWaveFeedback`.
+ */
+export declare const DEFAULT_FEEDBACK_BINDINGS: readonly AnyFeedbackBinding[];
+/** A resolved trigger: pooled per binding, so a busy event stream allocates nothing to decide. */
+export interface ResolvedFeedback {
+    event: FeedbackEventName;
+    cue: FeedbackCue;
+    sound: string;
+    caption: string | undefined;
+    haptics: HapticPulse | undefined;
+    shake: number;
+    cooldownMs: number;
+}
+/** Everything the feedback seam reaches outside itself. Injected so it runs headless. */
+export interface FeedbackDeps {
+    /**
+     * Play one catalog sound through the game's audio seam. `position` is the event's own position
+     * when it carries one, so the engine pans and attenuates the cue; omit it and the cue plays
+     * centred at full gain.
+     */
+    play(sound: string, position?: readonly [number, number, number]): void;
+    /** Add camera trauma `0..1`; called with `shake x motionScale`. */
+    shake?(amount: number): void;
+    /**
+     * One-shot rumble for the local player. Wire it to `createHapticsRoute` so a gamepad takes the
+     * pulse when one is connected and a phone feels it through vibration otherwise.
+     */
+    haptics?(pulse: HapticPulse): void;
+    /** Show a caption line for `cue`; only called when captions are on. */
+    caption?(text: string, cue: FeedbackCue): void;
+    /** The local player, for `scope: "local"`. */
+    localUserId(): string | null;
+    /** The entity the local player currently controls, for damage/death scope. */
+    localEntityId(): string | null;
+    /** Engine motion scale: `0` under reduced motion, `1` normally. Default `1`. */
+    motionScale?(): number;
+    now?(): number;
+}
+/** Options a game or host may override. */
+export interface EventFeedbackOptions {
+    reactions?: Partial<Record<FeedbackCue, FeedbackReaction>>;
+    bindings?: readonly AnyFeedbackBinding[];
+    /** Whether captions reach `deps.caption` at all. Default true. */
+    captions?: boolean;
+}
+/** The event-to-reaction seam. One instance per running world. */
+export interface EventFeedback {
+    /** React to one announced event. Returns the cue fired, or null when nothing mapped or it was muted by cooldown. */
+    handle<Name extends FeedbackEventName>(event: Name, payload: GameEventMap[Name]): FeedbackCue | null;
+    /** Fire a cue the game announces itself (a wave starting, a custom moment); `caption` overrides the cue's text. */
+    notify(cue: FeedbackCue, caption?: string): boolean;
+    /** Map without firing - the pooled reaction for an event, for devtools and tests. */
+    resolve<Name extends FeedbackEventName>(event: Name, payload: GameEventMap[Name]): ResolvedFeedback | null;
+    /** How many triggers a cue's cooldown folded away since the last reset. */
+    suppressed(cue: FeedbackCue): number;
+    /** Replace reactions or bindings at runtime. */
+    retune(options: Partial<EventFeedbackOptions>): void;
+    /** Clear cooldowns and suppressed counters. */
+    reset(): void;
+}
+/**
+ * Build the event-to-sound/haptic/shake/caption seam. The mapping is data
+ * ({@link DEFAULT_FEEDBACK_BINDINGS}), reactions are data ({@link DEFAULT_FEEDBACK_REACTIONS}), and the
+ * resolved trigger for each binding is allocated once - handling an event allocates only the caption
+ * string it actually shows, never per frame.
+ *
+ * @capability event-feedback map announced gameplay events (damage, kill, pickup, objective, wave, refusal) to a sound, gamepad pulse, camera shake and caption through one data mapping
+ */
+export declare function createEventFeedback(deps: FeedbackDeps, options?: EventFeedbackOptions): EventFeedback;
+/**
+ * Subscribe the feedback seam to a game's event bus, including `feedback.cue` for moments the game
+ * announces itself. Returns the detach function; the mapping and reactions stay override-able
+ * through the seam's `retune`.
+ *
+ * @capability attach-event-feedback one call wires every announced combat/loot/objective/refusal event to its reaction
+ */
+export declare function attachEventFeedback(events: Pick<GameEvents, "on">, feedback: EventFeedback, eventsToBind?: readonly FeedbackEventName[]): () => void;
+/** The slice of `ctx.game.feedback` a wave runner needs, so this runs headless in a test. */
+export interface FeedbackAnnouncer {
+    cue(cue: FeedbackCue, caption?: string): void;
+}
+/**
+ * Announce each new wave a {@link WaveRunner} starts as the `wave` cue, once per boundary. A wave
+ * has no event of its own, so this is the engine-side hookup for tower defense and wave survival
+ * games: `attachWaveFeedback(runner, ctx.game.feedback)`. Nothing is polled, the runner's own
+ * notification drives it, and one `update` that crosses two waves still fires once - the cue has a
+ * cooldown and the next boundary is announced by the next crossing.
+ *
+ * @capability attach-wave-feedback fire the wave cue once whenever a wave runner crosses into a new wave
+ */
+export declare function attachWaveFeedback(runner: Pick<WaveRunner, "state" | "subscribe">, announce: FeedbackAnnouncer): () => void;

package/dist/audio/eventFeedback.js

@@ -0,0 +1,273 @@
+import { feedbackCueSoundId } from "@jgengine/core/audio/feedbackCues";
+/**
+ * The default reactions. They are data: a game overrides one through `audio.feedbackCues` (sound) or
+ * `createEventFeedback({ reactions })` (haptics, shake, caption), and replaces the mapping through
+ * `bindings` without touching the shell.
+ */
+export const DEFAULT_FEEDBACK_REACTIONS = {
+    hit: {
+        sound: feedbackCueSoundId("hit"),
+        haptics: { strong: 0.18, weak: 0.3, ms: 70 },
+        shake: 0.14,
+        caption: "Hit",
+        cooldownMs: 55,
+    },
+    hurt: {
+        sound: feedbackCueSoundId("hurt"),
+        haptics: { strong: 0.45, weak: 0.35, ms: 140 },
+        shake: 0.4,
+        caption: "Hurt",
+        cooldownMs: 140,
+    },
+    kill: {
+        sound: feedbackCueSoundId("kill"),
+        haptics: { strong: 0.3, weak: 0.45, ms: 110 },
+        shake: 0.22,
+        caption: "Enemy down",
+        cooldownMs: 90,
+    },
+    pickup: {
+        sound: feedbackCueSoundId("pickup"),
+        haptics: { strong: 0.06, weak: 0.14, ms: 45 },
+        caption: "Picked up",
+        cooldownMs: 80,
+    },
+    objective: {
+        sound: feedbackCueSoundId("objective"),
+        haptics: { strong: 0.12, weak: 0.2, ms: 120 },
+        caption: "Objective complete",
+        cooldownMs: 500,
+    },
+    wave: {
+        sound: feedbackCueSoundId("wave"),
+        haptics: { strong: 0.2, weak: 0.1, ms: 180 },
+        shake: 0.1,
+        caption: "Wave incoming",
+        cooldownMs: 1500,
+    },
+    deny: {
+        sound: feedbackCueSoundId("deny"),
+        haptics: { strong: 0.1, weak: 0.25, ms: 60 },
+        caption: "Not possible",
+        cooldownMs: 350,
+    },
+};
+/**
+ * The default mapping: each engine-announced gameplay event to the cue it raises. Damage to the
+ * local player reads as hurt, damage anywhere else as a hit; an event that carries a `position`
+ * (damage, death) pans and attenuates its cue, and one without still plays centred. A wave start has
+ * no event of its own, so a game announces it through `notify("wave")` or `attachWaveFeedback`.
+ */
+export const DEFAULT_FEEDBACK_BINDINGS = [
+    { event: "combat.damage", cue: "hurt", scope: "local", detail: (event) => `${Math.round(event.amount)}` },
+    { event: "combat.damage", cue: "hit", scope: "remote", detail: (event) => `${Math.round(event.amount)}` },
+    { event: "entity.died", cue: "hurt", scope: "local", caption: "You died" },
+    { event: "entity.died", cue: "kill", scope: "remote", detail: (event) => event.displayName ?? event.catalogId },
+    { event: "worldItem.picked_up", cue: "pickup", scope: "local", detail: (event) => (event.count > 1 ? `${event.itemId} x${event.count}` : event.itemId) },
+    { event: "quest.completed", cue: "objective", scope: "local", detail: (event) => event.questId },
+    { event: "stat.levelUp", cue: "objective", scope: "local", detail: (event) => `${event.stat} ${event.level}` },
+    { event: "command.refused", cue: "deny", scope: "local", detail: (event) => event.message ?? event.reason },
+];
+const DEFAULT_COOLDOWN_MS = 40;
+/**
+ * Build the event-to-sound/haptic/shake/caption seam. The mapping is data
+ * ({@link DEFAULT_FEEDBACK_BINDINGS}), reactions are data ({@link DEFAULT_FEEDBACK_REACTIONS}), and the
+ * resolved trigger for each binding is allocated once - handling an event allocates only the caption
+ * string it actually shows, never per frame.
+ *
+ * @capability event-feedback map announced gameplay events (damage, kill, pickup, objective, wave, refusal) to a sound, gamepad pulse, camera shake and caption through one data mapping
+ */
+export function createEventFeedback(deps, options = {}) {
+    const reactions = { ...DEFAULT_FEEDBACK_REACTIONS };
+    let bindings = options.bindings ?? DEFAULT_FEEDBACK_BINDINGS;
+    let captionsOn = options.captions ?? true;
+    for (const [cue, reaction] of Object.entries(options.reactions ?? {})) {
+        if (reaction !== undefined)
+            reactions[cue] = reaction;
+    }
+    const now = deps.now ?? Date.now;
+    const lastPlayed = { hit: -Infinity, hurt: -Infinity, kill: -Infinity, pickup: -Infinity, objective: -Infinity, wave: -Infinity, deny: -Infinity };
+    const suppressed = { hit: 0, hurt: 0, kill: 0, pickup: 0, objective: 0, wave: 0, deny: 0 };
+    function triggerFor(binding) {
+        const reaction = reactions[binding.cue];
+        return {
+            event: binding.event,
+            cue: binding.cue,
+            sound: reaction.sound,
+            caption: undefined,
+            haptics: reaction.haptics,
+            shake: reaction.shake ?? 0,
+            cooldownMs: reaction.cooldownMs ?? DEFAULT_COOLDOWN_MS,
+        };
+    }
+    // One pooled resolution per binding row plus one per cue (for `notify`), so a busy event stream
+    // allocates nothing to decide what to play.
+    let resolved = bindings.map(triggerFor);
+    const cueTriggers = Object.fromEntries(["hit", "hurt", "kill", "pickup", "objective", "wave", "deny"].map((cue) => [cue, triggerFor({ event: "combat.damage", cue })]));
+    function rebuild() {
+        resolved = bindings.map(triggerFor);
+        for (const cue of Object.keys(cueTriggers)) {
+            const reaction = reactions[cue];
+            const trigger = cueTriggers[cue];
+            trigger.sound = reaction.sound;
+            trigger.haptics = reaction.haptics;
+            trigger.shake = reaction.shake ?? 0;
+            trigger.cooldownMs = reaction.cooldownMs ?? DEFAULT_COOLDOWN_MS;
+        }
+    }
+    function isLocal(event, payload) {
+        switch (event) {
+            case "combat.damage":
+                return payload.target === deps.localEntityId();
+            case "entity.died": {
+                const died = payload;
+                const userId = deps.localUserId();
+                return (userId !== null && died.userId === userId) || died.instanceId === deps.localEntityId();
+            }
+            case "worldItem.picked_up":
+                return payload.userId === deps.localUserId();
+            case "quest.completed":
+            case "stat.levelUp": {
+                const userId = deps.localUserId();
+                return userId !== null && payload.userId === userId;
+            }
+            case "command.refused": {
+                const actor = payload.actor;
+                return actor === null || actor === deps.localUserId();
+            }
+            default:
+                return true;
+        }
+    }
+    function fire(trigger, captionText, position) {
+        if (position === undefined)
+            deps.play(trigger.sound);
+        else
+            deps.play(trigger.sound, position);
+        if (trigger.haptics !== undefined)
+            deps.haptics?.(trigger.haptics);
+        if (trigger.shake > 0) {
+            const scale = deps.motionScale?.() ?? 1;
+            if (scale > 0)
+                deps.shake?.(trigger.shake * scale);
+        }
+        if (captionsOn && captionText !== undefined)
+            deps.caption?.(captionText, trigger.cue);
+    }
+    function react(cue, captionText, position) {
+        const reaction = reactions[cue];
+        const trigger = cueTriggers[cue];
+        const time = now();
+        const cooldown = trigger.cooldownMs;
+        if (time - lastPlayed[cue] < cooldown) {
+            suppressed[cue] += 1;
+            return false;
+        }
+        lastPlayed[cue] = time;
+        const text = captionText ?? trigger.caption ?? reaction.caption;
+        fire(trigger, text, position);
+        return true;
+    }
+    return {
+        handle(event, payload) {
+            for (let index = 0; index < bindings.length; index += 1) {
+                const binding = bindings[index];
+                if (binding.event !== event)
+                    continue;
+                const scope = binding.scope ?? "any";
+                if (scope !== "any" && isLocal(event, payload) !== (scope === "local"))
+                    continue;
+                const detail = binding.detail?.(payload);
+                const base = binding.caption ?? reactions[binding.cue].caption;
+                const captionText = base === undefined ? detail : detail === undefined ? base : `${base} ${detail}`;
+                const position = payload.position;
+                return react(binding.cue, captionText, position) ? binding.cue : null;
+            }
+            return null;
+        },
+        notify(cue, caption) {
+            return react(cue, caption);
+        },
+        resolve(event, payload) {
+            for (let index = 0; index < bindings.length; index += 1) {
+                const binding = bindings[index];
+                if (binding.event !== event)
+                    continue;
+                const scope = binding.scope ?? "any";
+                if (scope !== "any" && isLocal(event, payload) !== (scope === "local"))
+                    continue;
+                const trigger = resolved[index];
+                const detail = binding.detail?.(payload);
+                const base = binding.caption ?? reactions[binding.cue].caption;
+                trigger.caption = base === undefined ? detail : detail === undefined ? base : `${base} ${detail}`;
+                return trigger;
+            }
+            return null;
+        },
+        suppressed(cue) {
+            return suppressed[cue];
+        },
+        retune(next) {
+            if (next.captions !== undefined)
+                captionsOn = next.captions;
+            if (next.bindings !== undefined) {
+                bindings = next.bindings;
+                rebuild();
+            }
+            if (next.reactions !== undefined) {
+                for (const [cue, reaction] of Object.entries(next.reactions)) {
+                    if (reaction !== undefined)
+                        reactions[cue] = reaction;
+                }
+                rebuild();
+            }
+        },
+        reset() {
+            for (const cue of Object.keys(lastPlayed)) {
+                lastPlayed[cue] = -Infinity;
+                suppressed[cue] = 0;
+            }
+        },
+    };
+}
+/**
+ * Subscribe the feedback seam to a game's event bus, including `feedback.cue` for moments the game
+ * announces itself. Returns the detach function; the mapping and reactions stay override-able
+ * through the seam's `retune`.
+ *
+ * @capability attach-event-feedback one call wires every announced combat/loot/objective/refusal event to its reaction
+ */
+export function attachEventFeedback(events, feedback, eventsToBind = Object.keys(DEFAULT_FEEDBACK_BINDINGS.reduce((names, binding) => {
+    names[binding.event] = true;
+    return names;
+}, {}))) {
+    const offs = eventsToBind.map((name) => events.on(name, (payload) => {
+        feedback.handle(name, payload);
+    }));
+    offs.push(events.on("feedback.cue", ({ cue, caption }) => {
+        feedback.notify(cue, caption);
+    }));
+    return () => {
+        for (const off of offs)
+            off();
+    };
+}
+/**
+ * Announce each new wave a {@link WaveRunner} starts as the `wave` cue, once per boundary. A wave
+ * has no event of its own, so this is the engine-side hookup for tower defense and wave survival
+ * games: `attachWaveFeedback(runner, ctx.game.feedback)`. Nothing is polled, the runner's own
+ * notification drives it, and one `update` that crosses two waves still fires once - the cue has a
+ * cooldown and the next boundary is announced by the next crossing.
+ *
+ * @capability attach-wave-feedback fire the wave cue once whenever a wave runner crosses into a new wave
+ */
+export function attachWaveFeedback(runner, announce) {
+    let lastWave = runner.state().wave;
+    return runner.subscribe(() => {
+        const wave = runner.state().wave;
+        if (wave === lastWave)
+            return;
+        lastWave = wave;
+        announce.cue("wave", `Wave ${wave + 1}`);
+    });
+}

package/dist/audio/gestureResume.d.ts

@@ -0,0 +1,10 @@
+import type { AudioEngine } from "./audioEngine.js";
+/**
+ * Resume the audio context on the first real user gesture. Chrome keeps a freshly created
+ * `AudioContext` suspended until the page sees a trusted input, so pressing a key, tapping or clicking
+ * is the only moment sound may start; the engine then flushes any cue it held. One listener set per
+ * game, removed on unmount.
+ *
+ * @capability gesture-resume unlock the audio context on the first pointer/key/touch gesture, so pre-gesture cues play instead of vanishing
+ */
+export declare function installGestureResume(engine: Pick<AudioEngine, "resume">, target?: Pick<Document, "addEventListener" | "removeEventListener"> | null): () => void;

package/dist/audio/gestureResume.js

@@ -0,0 +1,25 @@
+/**
+ * Resume the audio context on the first real user gesture. Chrome keeps a freshly created
+ * `AudioContext` suspended until the page sees a trusted input, so pressing a key, tapping or clicking
+ * is the only moment sound may start; the engine then flushes any cue it held. One listener set per
+ * game, removed on unmount.
+ *
+ * @capability gesture-resume unlock the audio context on the first pointer/key/touch gesture, so pre-gesture cues play instead of vanishing
+ */
+export function installGestureResume(engine, target = typeof document === "undefined" ? null : document) {
+    if (target === null)
+        return () => undefined;
+    const resume = () => {
+        engine.resume();
+        detach();
+    };
+    const detach = () => {
+        target.removeEventListener("pointerdown", resume, true);
+        target.removeEventListener("keydown", resume, true);
+        target.removeEventListener("touchstart", resume, true);
+    };
+    target.addEventListener("pointerdown", resume, true);
+    target.addEventListener("keydown", resume, true);
+    target.addEventListener("touchstart", resume, true);
+    return detach;
+}

package/dist/audio/hapticsRoute.d.ts

@@ -0,0 +1,28 @@
+import type { HapticPulse } from "@jgengine/core/input/haptics";
+/** Where a pulse actually landed: a gamepad, the device's own motor, or nowhere. */
+export type HapticsSink = "gamepad" | "vibration" | "none";
+/** The browser reach of {@link createHapticsRoute}; injected so the route runs headless. */
+export interface HapticsRouteOptions {
+    /** Connected pads. Default `navigator.getGamepads`. */
+    gamepads?(): ArrayLike<Gamepad | null>;
+    /** Device vibration, called with the pulse length in ms. Default `navigator.vibrate`; `null` for a device without one. */
+    vibrate?: ((ms: number) => void) | null;
+    /** Where `gamepadconnected`/`gamepaddisconnected` arrive. Default `window`; `null` reads pads per pulse. */
+    events?: Pick<Window, "addEventListener" | "removeEventListener"> | null;
+}
+/** Route haptic pulses to whatever the player can feel them on. */
+export interface HapticsRoute {
+    /** Send one pulse: the gamepad if a pad is connected, else the phone's motor, else nothing. */
+    deliver(pulse: HapticPulse): HapticsSink;
+    /** Drop the connection listeners. Safe twice. */
+    dispose(): void;
+}
+/**
+ * One pulse in, whichever motor the player has: a connected gamepad takes it through the haptic
+ * channels the gamepad loop already drives, and a phone with no pad falls back to
+ * `navigator.vibrate`. Pad presence is cached and refreshed on connection events, so a hit never
+ * asks the browser for its pad list. Reduced motion does not silence this: see `eventFeedback`.
+ *
+ * @capability haptics-route send a feedback pulse to the gamepad when one is connected, else to the phone's vibration motor
+ */
+export declare function createHapticsRoute(pad: (pulse: HapticPulse) => void, options?: HapticsRouteOptions): HapticsRoute;