@oss-idle/addon-sdk 0.0.0-stage → 0.5.0

package/dist/react/reactAddon.js

@@ -0,0 +1,51 @@
+/**
+ * A React add-on.
+ *
+ * Bundles the two things a React overlay always needs - a shadow-rooted host
+ * and a React 18 root - and ties both to the add-on lifecycle, so disabling the
+ * add-on unmounts the tree and removes the host in one step.
+ *
+ * React itself is bundled into the add-on's single emitted file. Two add-ons
+ * each carrying their own React is fine: they render into separate roots inside
+ * separate shadow trees and never share a reconciler.
+ */
+import { createRoot } from 'react-dom/client';
+import { Addon } from '../runtime/addon.js';
+import { HotkeyManager } from '../runtime/input.js';
+import { createOverlay } from './overlay.js';
+export class ReactAddon extends Addon {
+    overlay;
+    root;
+    /** Global shortcuts, bound ahead of the game's own handlers. */
+    hotkeys = new HotkeyManager();
+    reactMeta;
+    constructor(meta) {
+        super(meta);
+        this.reactMeta = meta;
+    }
+    async onMount() {
+        const id = this.reactMeta.overlayId
+            ?? `addon-${this.reactMeta.name.toLowerCase().replace(/[^a-z0-9]+/g, '-')}`;
+        this.overlay = createOverlay({ id, styles: this.reactMeta.styles });
+        this.root = createRoot(this.overlay.container);
+        this.root.render(this.render());
+        this.own(() => this.hotkeys.dispose());
+        await this.onReady();
+    }
+    /** Hook for work that needs the overlay to exist (shortcuts, data loading). */
+    onReady() { }
+    /** Re-render the tree - for state the add-on holds outside React. */
+    refresh() {
+        this.root?.render(this.render());
+    }
+    async onUnmount() {
+        // React 18 warns if a root is unmounted while it is rendering, which is
+        // possible here because the runtime can disable an add-on at any moment.
+        const root = this.root;
+        this.root = undefined;
+        if (root)
+            await Promise.resolve().then(() => root.unmount());
+        this.overlay?.dispose();
+        this.overlay = undefined;
+    }
+}

package/dist/react/useSettings.d.ts

@@ -0,0 +1,16 @@
+/**
+ * React binding for a {@link SettingsStore}.
+ *
+ * Loads once on mount and writes back whenever a setting changes, so the values
+ * a player picked are there the next time the overlay opens.
+ */
+import type { SettingsStore } from '../runtime/settings.js';
+export type SettingsHandle<T extends object> = [
+    settings: T,
+    /** Merge a patch into the settings and persist. */
+    update: (patch: Partial<T>) => void,
+    /** Restore the defaults. */
+    reset: () => void
+];
+export declare const usePersistedSettings: <T extends object>(store: SettingsStore<T>, defaults: T) => SettingsHandle<T>;
+//# sourceMappingURL=useSettings.d.ts.map

package/dist/react/useSettings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useSettings.d.ts","sourceRoot":"","sources":["../../src/react/useSettings.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAE5D,MAAM,MAAM,cAAc,CAAC,CAAC,SAAS,MAAM,IAAI;IAC9C,QAAQ,EAAE,CAAC;IACX,mDAAmD;IACnD,MAAM,EAAE,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC,KAAK,IAAI;IACnC,4BAA4B;IAC5B,KAAK,EAAE,MAAM,IAAI;CACjB,CAAC;AAEF,eAAO,MAAM,oBAAoB,GAAI,CAAC,SAAS,MAAM,EACpD,OAAO,aAAa,CAAC,CAAC,CAAC,EACvB,UAAU,CAAC,KACT,cAAc,CAAC,CAAC,CA2BlB,CAAC"}

package/dist/react/useSettings.js

@@ -0,0 +1,30 @@
+/**
+ * React binding for a {@link SettingsStore}.
+ *
+ * Loads once on mount and writes back whenever a setting changes, so the values
+ * a player picked are there the next time the overlay opens.
+ */
+import { useCallback, useEffect, useRef, useState } from 'react';
+export const usePersistedSettings = (store, defaults) => {
+    // Loaded in the initialiser so the first render already has the stored
+    // values - a later effect would flash the defaults first.
+    const [settings, setSettings] = useState(() => store.load());
+    const latest = useRef(settings);
+    latest.current = settings;
+    const update = useCallback((patch) => {
+        const next = { ...latest.current, ...patch };
+        latest.current = next;
+        setSettings(next);
+        store.save(next);
+    }, [store]);
+    const reset = useCallback(() => {
+        const next = { ...defaults };
+        latest.current = next;
+        setSettings(next);
+        store.clear();
+    }, [store, defaults]);
+    // Persist whatever the component settled on when it goes away, covering a
+    // value changed through some path other than `update`.
+    useEffect(() => () => store.save(latest.current), [store]);
+    return [settings, update, reset];
+};

package/dist/runtime/addon.d.ts

@@ -0,0 +1,83 @@
+/**
+ * The add-on contract.
+ *
+ * oss!idle loads an add-on by turning its `source` into a Blob URL and
+ * `import()`ing it in the page realm, then calling the module's `mount` /
+ * `unmount` exports - that pair *is* the contract, and nothing else is passed
+ * in. Everything a useful add-on needs (the game's database, its beatmap store,
+ * the DOM) it reaches for itself, because it runs unsandboxed on the page.
+ *
+ * Two consequences shape this class:
+ *
+ * - **Nothing resolves at load time.** The module is a Blob, so it has no base
+ *   URL and no import map: every dependency, React included, must already be
+ *   inside the single emitted file. That is the bundler's job (`./build`).
+ * - **`unmount` must actually undo everything.** Add-ons are enabled, disabled,
+ *   updated and uninstalled without a page reload, so a listener or timer left
+ *   behind leaks into a game the player keeps playing. {@link Addon} therefore
+ *   hands out registration helpers that record their own teardown, and reverses
+ *   them for you.
+ */
+/** A teardown returned by a registration; running it undoes that registration. */
+export type Disposer = () => void;
+export type AddonMeta = {
+    /** Human name, used in log lines and error surfaces. */
+    name: string;
+    /** The add-on's own semver. Defaults to the version the bundler stamped in. */
+    version?: string;
+};
+/**
+ * Base class for an add-on. Subclass it, implement {@link onMount}, and export
+ * the pair the runtime wants with {@link defineAddon}.
+ *
+ * Anything registered through `this.own`, `this.on`, `this.interval` or
+ * `this.timeout` is torn down in reverse order on unmount, so `onUnmount` is
+ * only for work those helpers cannot express.
+ */
+export declare abstract class Addon {
+    protected readonly meta: AddonMeta;
+    /** Registered teardowns, newest first when reversed at unmount. */
+    private disposers;
+    private mounted;
+    constructor(meta: AddonMeta);
+    /** Runs when the player enables the add-on (and once per boot thereafter). */
+    protected abstract onMount(): void | Promise<void>;
+    /** Optional extra teardown, run *before* the registered disposers unwind. */
+    protected onUnmount(): void | Promise<void>;
+    /** Record a teardown to run at unmount. Returns it, so it can also be run early. */
+    protected own<T extends Disposer>(dispose: T): T;
+    /**
+     * Add a DOM listener that is removed at unmount. Defaults to the capture
+     * phase, which is what an overlay wants: the game binds its own handlers on
+     * `window` in the bubble phase, so capturing lets an overlay claim an event
+     * before gameplay ever sees it.
+     */
+    protected on<K extends keyof WindowEventMap>(target: Window, type: K, handler: (event: WindowEventMap[K]) => void, options?: AddEventListenerOptions): Disposer;
+    protected on(target: EventTarget, type: string, handler: EventListenerOrEventListenerObject, options?: AddEventListenerOptions): Disposer;
+    /** `setInterval` that is cleared at unmount. */
+    protected interval(handler: () => void, ms: number): Disposer;
+    /** `setTimeout` that is cleared at unmount if it has not fired yet. */
+    protected timeout(handler: () => void, ms: number): Disposer;
+    /** Prefixed console logger, so a player's console says which add-on spoke. */
+    protected get log(): {
+        info: (...args: unknown[]) => void;
+        warn: (...args: unknown[]) => void;
+        error: (...args: unknown[]) => void;
+    };
+    /**
+     * Internal: called by {@link defineAddon}, not by add-on code.
+     *
+     * Public only because `defineAddon` lives outside the class and TypeScript
+     * has no package-private visibility; the underscore marks it as off-limits.
+     */
+    _mount(): Promise<void>;
+    /**
+     * Internal: called by {@link defineAddon}, not by add-on code.
+     *
+     * Every teardown runs even if an earlier one throws - a half-unmounted
+     * add-on that keeps a key handler alive would break the game far more
+     * visibly than a logged error here.
+     */
+    _unmount(): Promise<void>;
+}
+//# sourceMappingURL=addon.d.ts.map

package/dist/runtime/addon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"addon.d.ts","sourceRoot":"","sources":["../../src/runtime/addon.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAIH,kFAAkF;AAClF,MAAM,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC;AAElC,MAAM,MAAM,SAAS,GAAG;IACvB,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,+EAA+E;IAC/E,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF;;;;;;;GAOG;AACH,8BAAsB,KAAK;IAE1B,SAAS,CAAC,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAEnC,mEAAmE;IACnE,OAAO,CAAC,SAAS,CAAkB;IAEnC,OAAO,CAAC,OAAO,CAAS;gBAEZ,IAAI,EAAE,SAAS;IAI3B,8EAA8E;IAC9E,SAAS,CAAC,QAAQ,CAAC,OAAO,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAElD,6EAA6E;IAC7E,SAAS,CAAC,SAAS,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAE3C,oFAAoF;IACpF,SAAS,CAAC,GAAG,CAAC,CAAC,SAAS,QAAQ,EAAE,OAAO,EAAE,CAAC,GAAG,CAAC;IAKhD;;;;;OAKG;IACH,SAAS,CAAC,EAAE,CAAC,CAAC,SAAS,MAAM,cAAc,EAC1C,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,CAAC,EACP,OAAO,EAAE,CAAC,KAAK,EAAE,cAAc,CAAC,CAAC,CAAC,KAAK,IAAI,EAC3C,OAAO,CAAC,EAAE,uBAAuB,GAC/B,QAAQ;IACX,SAAS,CAAC,EAAE,CACX,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,kCAAkC,EAC3C,OAAO,CAAC,EAAE,uBAAuB,GAC/B,QAAQ;IAWX,gDAAgD;IAChD,SAAS,CAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,QAAQ;IAK7D,uEAAuE;IACvE,SAAS,CAAC,OAAO,CAAC,OAAO,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,GAAG,QAAQ;IAK5D,8EAA8E;IAC9E,SAAS,KAAK,GAAG;wBAGC,OAAO,EAAE;wBACT,OAAO,EAAE;yBACR,OAAO,EAAE;MAE3B;IAED;;;;;OAKG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IAM7B;;;;;;OAMG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAkB/B"}

package/dist/runtime/addon.js

@@ -0,0 +1,108 @@
+/**
+ * The add-on contract.
+ *
+ * oss!idle loads an add-on by turning its `source` into a Blob URL and
+ * `import()`ing it in the page realm, then calling the module's `mount` /
+ * `unmount` exports - that pair *is* the contract, and nothing else is passed
+ * in. Everything a useful add-on needs (the game's database, its beatmap store,
+ * the DOM) it reaches for itself, because it runs unsandboxed on the page.
+ *
+ * Two consequences shape this class:
+ *
+ * - **Nothing resolves at load time.** The module is a Blob, so it has no base
+ *   URL and no import map: every dependency, React included, must already be
+ *   inside the single emitted file. That is the bundler's job (`./build`).
+ * - **`unmount` must actually undo everything.** Add-ons are enabled, disabled,
+ *   updated and uninstalled without a page reload, so a listener or timer left
+ *   behind leaks into a game the player keeps playing. {@link Addon} therefore
+ *   hands out registration helpers that record their own teardown, and reverses
+ *   them for you.
+ */
+import { buildMeta } from './buildMeta.js';
+/**
+ * Base class for an add-on. Subclass it, implement {@link onMount}, and export
+ * the pair the runtime wants with {@link defineAddon}.
+ *
+ * Anything registered through `this.own`, `this.on`, `this.interval` or
+ * `this.timeout` is torn down in reverse order on unmount, so `onUnmount` is
+ * only for work those helpers cannot express.
+ */
+export class Addon {
+    meta;
+    /** Registered teardowns, newest first when reversed at unmount. */
+    disposers = [];
+    mounted = false;
+    constructor(meta) {
+        this.meta = { ...meta, version: meta.version ?? buildMeta().version };
+    }
+    /** Optional extra teardown, run *before* the registered disposers unwind. */
+    onUnmount() { }
+    /** Record a teardown to run at unmount. Returns it, so it can also be run early. */
+    own(dispose) {
+        this.disposers.push(dispose);
+        return dispose;
+    }
+    on(target, type, handler, options = { capture: true }) {
+        target.addEventListener(type, handler, options);
+        return this.own(() => target.removeEventListener(type, handler, options));
+    }
+    /** `setInterval` that is cleared at unmount. */
+    interval(handler, ms) {
+        const id = window.setInterval(handler, ms);
+        return this.own(() => window.clearInterval(id));
+    }
+    /** `setTimeout` that is cleared at unmount if it has not fired yet. */
+    timeout(handler, ms) {
+        const id = window.setTimeout(handler, ms);
+        return this.own(() => window.clearTimeout(id));
+    }
+    /** Prefixed console logger, so a player's console says which add-on spoke. */
+    get log() {
+        const tag = `[${this.meta.name}]`;
+        return {
+            info: (...args) => console.log(tag, ...args),
+            warn: (...args) => console.warn(tag, ...args),
+            error: (...args) => console.error(tag, ...args),
+        };
+    }
+    /**
+     * Internal: called by {@link defineAddon}, not by add-on code.
+     *
+     * Public only because `defineAddon` lives outside the class and TypeScript
+     * has no package-private visibility; the underscore marks it as off-limits.
+     */
+    async _mount() {
+        if (this.mounted)
+            return;
+        this.mounted = true;
+        await this.onMount();
+    }
+    /**
+     * Internal: called by {@link defineAddon}, not by add-on code.
+     *
+     * Every teardown runs even if an earlier one throws - a half-unmounted
+     * add-on that keeps a key handler alive would break the game far more
+     * visibly than a logged error here.
+     */
+    async _unmount() {
+        if (!this.mounted)
+            return;
+        this.mounted = false;
+        try {
+            await this.onUnmount();
+        }
+        catch (e) {
+            this.log.error('onUnmount failed', e);
+        }
+        const pending = this.disposers.reverse();
+        this.disposers = [];
+        for (const dispose of pending) {
+            try {
+                dispose();
+            }
+            catch (e) {
+                this.log.error('teardown failed', e);
+            }
+        }
+    }
+}

package/dist/runtime/buildMeta.d.ts

@@ -0,0 +1,11 @@
+export type BuildMeta = {
+    name?: string;
+    version?: string;
+    /** The oss!idle release the bundle was built against. */
+    gameVersion?: string;
+    /** The @oss-idle/addon-sdk that built it. */
+    sdkVersion?: string;
+    license?: string;
+};
+export declare const buildMeta: () => BuildMeta;
+//# sourceMappingURL=buildMeta.d.ts.map

package/dist/runtime/buildMeta.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildMeta.d.ts","sourceRoot":"","sources":["../../src/runtime/buildMeta.ts"],"names":[],"mappings":"AASA,MAAM,MAAM,SAAS,GAAG;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yDAAyD;IACzD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6CAA6C;IAC7C,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,eAAO,MAAM,SAAS,QAAO,SACuC,CAAC"}

package/dist/runtime/buildMeta.js

@@ -0,0 +1 @@
+export const buildMeta = () => typeof __OSS_IDLE_ADDON__ === 'undefined' ? {} : __OSS_IDLE_ADDON__;

package/dist/runtime/define.d.ts

@@ -0,0 +1,23 @@
+import { Addon } from './addon.js';
+/** The module shape oss!idle's add-on runtime imports and drives. */
+export type AddonModule = {
+    mount: () => void;
+    unmount: () => void;
+};
+/**
+ * Turn an {@link Addon} subclass into the `mount` / `unmount` pair the runtime
+ * expects:
+ *
+ * ```ts
+ * export const { mount, unmount } = defineAddon(() => new MyAddon());
+ * ```
+ *
+ * The runtime calls both synchronously and ignores what they return, so an
+ * async `onMount` is started and left to run - its failure is reported here
+ * rather than surfacing as an unhandled rejection in the player's console.
+ *
+ * A mount still settling when `unmount` arrives (disable clicked mid-boot) is
+ * awaited first, so teardown never races a half-built overlay.
+ */
+export declare const defineAddon: (create: () => Addon) => AddonModule;
+//# sourceMappingURL=define.d.ts.map

package/dist/runtime/define.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../../src/runtime/define.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnC,qEAAqE;AACrE,MAAM,MAAM,WAAW,GAAG;IACzB,KAAK,EAAE,MAAM,IAAI,CAAC;IAClB,OAAO,EAAE,MAAM,IAAI,CAAC;CACpB,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,WAAW,GAAI,QAAQ,MAAM,KAAK,KAAG,WAqBjD,CAAC"}

package/dist/runtime/define.js

@@ -0,0 +1,37 @@
+/**
+ * Turn an {@link Addon} subclass into the `mount` / `unmount` pair the runtime
+ * expects:
+ *
+ * ```ts
+ * export const { mount, unmount } = defineAddon(() => new MyAddon());
+ * ```
+ *
+ * The runtime calls both synchronously and ignores what they return, so an
+ * async `onMount` is started and left to run - its failure is reported here
+ * rather than surfacing as an unhandled rejection in the player's console.
+ *
+ * A mount still settling when `unmount` arrives (disable clicked mid-boot) is
+ * awaited first, so teardown never races a half-built overlay.
+ */
+export const defineAddon = (create) => {
+    let instance;
+    let settling = Promise.resolve();
+    return {
+        mount: () => {
+            instance = create();
+            const addon = instance;
+            settling = addon._mount().catch((e) => {
+                console.error('[addon] mount failed', e);
+            });
+        },
+        unmount: () => {
+            const addon = instance;
+            if (!addon)
+                return;
+            instance = undefined;
+            settling = settling
+                .then(() => addon._unmount())
+                .catch((e) => console.error('[addon] unmount failed', e));
+        },
+    };
+};

package/dist/runtime/input.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Keeping an overlay's input out of the game.
+ *
+ * The client binds its gameplay controls as **bubble-phase listeners on
+ * `window`** (`input/Controls.ts`), and the same is true of the scene-level
+ * shortcuts and the wheel handlers that drive volume and the song carousel.
+ * Nothing is bound in the capture phase, which is what makes an overlay able to
+ * coexist with it:
+ *
+ * - **Inside the overlay**, {@link isolateInput} stops these events at the
+ *   overlay's root while they bubble. The event still reached its target, so a
+ *   text field types normally, but it never continues up to `window` - so typing
+ *   "speed" into a filter box cannot press four gameplay keys, and scrolling a
+ *   results list cannot change the game's volume.
+ * - **Outside the overlay**, {@link HotkeyManager} listens in the capture phase,
+ *   ahead of every game handler, so a shortcut can claim its combo before
+ *   gameplay interprets it.
+ */
+import type { Disposer } from './addon.js';
+/**
+ * Stop the game from seeing input that belongs to `root`.
+ *
+ * Bubble phase on purpose: the event has already done its job inside the
+ * overlay by the time it is stopped here. Capturing instead would take the
+ * keystroke away from the very field the player is typing into.
+ */
+export declare const isolateInput: (root: HTMLElement) => Disposer;
+export type Hotkey = {
+    /** `KeyboardEvent.key`, compared case-insensitively. */
+    key: string;
+    ctrl: boolean;
+    shift: boolean;
+    alt: boolean;
+    meta: boolean;
+};
+/** Parse `"Ctrl+Shift+F"` into a {@link Hotkey}. Order and case do not matter. */
+export declare const parseHotkey: (combo: string) => Hotkey;
+/**
+ * Global shortcuts that win against the game.
+ *
+ * One capture-phase listener on `window` serves every binding. A claimed combo
+ * is stopped with `stopImmediatePropagation` and `preventDefault`, so neither
+ * the game's handlers nor the browser's own act on it.
+ */
+export declare class HotkeyManager {
+    private readonly bindings;
+    private readonly onKeyDown;
+    constructor();
+    /**
+     * Bind a combo. `allowInText` lets it fire even from a focused field, which
+     * is what a close/escape shortcut wants.
+     */
+    register(combo: string, handler: (event: KeyboardEvent) => void, { allowInText }?: {
+        allowInText?: boolean;
+    }): Disposer;
+    dispose(): void;
+}
+//# sourceMappingURL=input.d.ts.map

package/dist/runtime/input.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"input.d.ts","sourceRoot":"","sources":["../../src/runtime/input.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAS3C;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,GAAI,MAAM,WAAW,KAAG,QAUhD,CAAC;AAEF,MAAM,MAAM,MAAM,GAAG;IACpB,wDAAwD;IACxD,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,OAAO,CAAC;IACd,KAAK,EAAE,OAAO,CAAC;IACf,GAAG,EAAE,OAAO,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;CACd,CAAC;AAEF,kFAAkF;AAClF,eAAO,MAAM,WAAW,GAAI,OAAO,MAAM,KAAG,MAY3C,CAAC;AAqBF;;;;;;GAMG;AACH,qBAAa,aAAa;IAEzB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAsB;IAE/C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAYxB;;IAMF;;;OAGG;IACH,QAAQ,CACP,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,EACvC,EAAE,WAAmB,EAAE,GAAE;QAAE,WAAW,CAAC,EAAE,OAAO,CAAA;KAAO,GACrD,QAAQ;IAMX,OAAO,IAAI,IAAI;CAIf"}

package/dist/runtime/input.js

@@ -0,0 +1,119 @@
+/**
+ * Keeping an overlay's input out of the game.
+ *
+ * The client binds its gameplay controls as **bubble-phase listeners on
+ * `window`** (`input/Controls.ts`), and the same is true of the scene-level
+ * shortcuts and the wheel handlers that drive volume and the song carousel.
+ * Nothing is bound in the capture phase, which is what makes an overlay able to
+ * coexist with it:
+ *
+ * - **Inside the overlay**, {@link isolateInput} stops these events at the
+ *   overlay's root while they bubble. The event still reached its target, so a
+ *   text field types normally, but it never continues up to `window` - so typing
+ *   "speed" into a filter box cannot press four gameplay keys, and scrolling a
+ *   results list cannot change the game's volume.
+ * - **Outside the overlay**, {@link HotkeyManager} listens in the capture phase,
+ *   ahead of every game handler, so a shortcut can claim its combo before
+ *   gameplay interprets it.
+ */
+/** Events the game acts on globally, which an overlay must not leak upward. */
+const ISOLATED_EVENTS = [
+    'keydown', 'keyup', 'keypress',
+    'wheel',
+    'pointerdown', 'pointerup', 'mousedown', 'mouseup', 'click', 'dblclick',
+];
+/**
+ * Stop the game from seeing input that belongs to `root`.
+ *
+ * Bubble phase on purpose: the event has already done its job inside the
+ * overlay by the time it is stopped here. Capturing instead would take the
+ * keystroke away from the very field the player is typing into.
+ */
+export const isolateInput = (root) => {
+    const stop = (event) => event.stopPropagation();
+    for (const type of ISOLATED_EVENTS) {
+        root.addEventListener(type, stop, { capture: false });
+    }
+    return () => {
+        for (const type of ISOLATED_EVENTS) {
+            root.removeEventListener(type, stop, { capture: false });
+        }
+    };
+};
+/** Parse `"Ctrl+Shift+F"` into a {@link Hotkey}. Order and case do not matter. */
+export const parseHotkey = (combo) => {
+    const parts = combo.split('+').map(p => p.trim().toLowerCase()).filter(Boolean);
+    const hotkey = { key: '', ctrl: false, shift: false, alt: false, meta: false };
+    for (const part of parts) {
+        if (part === 'ctrl' || part === 'control')
+            hotkey.ctrl = true;
+        else if (part === 'shift')
+            hotkey.shift = true;
+        else if (part === 'alt' || part === 'option')
+            hotkey.alt = true;
+        else if (part === 'meta' || part === 'cmd' || part === 'super')
+            hotkey.meta = true;
+        else
+            hotkey.key = part;
+    }
+    if (!hotkey.key)
+        throw new Error(`Hotkey "${combo}" names no key`);
+    return hotkey;
+};
+const matches = (hotkey, event) => event.key.toLowerCase() === hotkey.key
+    && event.ctrlKey === hotkey.ctrl
+    && event.shiftKey === hotkey.shift
+    && event.altKey === hotkey.alt
+    && event.metaKey === hotkey.meta;
+/** Whether the event is going somewhere the player is typing. */
+const isTextEntry = (target) => {
+    const el = target;
+    if (!el?.tagName)
+        return false;
+    return el.tagName === 'INPUT'
+        || el.tagName === 'TEXTAREA'
+        || el.tagName === 'SELECT'
+        || el.isContentEditable;
+};
+/**
+ * Global shortcuts that win against the game.
+ *
+ * One capture-phase listener on `window` serves every binding. A claimed combo
+ * is stopped with `stopImmediatePropagation` and `preventDefault`, so neither
+ * the game's handlers nor the browser's own act on it.
+ */
+export class HotkeyManager {
+    bindings = new Set();
+    onKeyDown = (event) => {
+        if (event.repeat)
+            return;
+        for (const binding of this.bindings) {
+            if (!matches(binding.hotkey, event))
+                continue;
+            // A shortcut must not fire while the player is typing - unless it is
+            // the combo that closes the overlay they are typing in.
+            if (!binding.allowInText && isTextEntry(event.target))
+                continue;
+            event.preventDefault();
+            event.stopImmediatePropagation();
+            binding.handler(event);
+            return;
+        }
+    };
+    constructor() {
+        window.addEventListener('keydown', this.onKeyDown, { capture: true });
+    }
+    /**
+     * Bind a combo. `allowInText` lets it fire even from a focused field, which
+     * is what a close/escape shortcut wants.
+     */
+    register(combo, handler, { allowInText = false } = {}) {
+        const binding = { hotkey: parseHotkey(combo), handler, allowInText };
+        this.bindings.add(binding);
+        return () => this.bindings.delete(binding);
+    }
+    dispose() {
+        this.bindings.clear();
+        window.removeEventListener('keydown', this.onKeyDown, { capture: true });
+    }
+}

package/dist/runtime/settings.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Persisted add-on settings.
+ *
+ * An add-on is remounted on every boot and on every enable/disable, so anything
+ * held only in component state is re-entered by the player each time. Settings
+ * belong in `localStorage`, which is the same store the client keeps its own
+ * options in and survives reloads without touching the game's database.
+ *
+ * **Keys are namespaced deliberately.** The client writes its settings under
+ * bare, unprefixed keys (`db/settings.ts`), and reads them back with a bare
+ * `JSON.parse`. An add-on writing a colliding key would corrupt a game setting,
+ * so everything here lives under `oss-idle-addon:<namespace>`.
+ *
+ * Stored values are merged **over** the defaults on load, so adding a setting in
+ * a later version does not invalidate what a player already saved, and only keys
+ * the defaults still declare are kept - a removed setting cleans itself up.
+ */
+export type SettingsStore<T extends object> = {
+    /** The full storage key, for debugging. */
+    readonly key: string;
+    /** Stored settings merged over the defaults. Never throws. */
+    load(): T;
+    /** Persist the whole settings object. Never throws. */
+    save(value: T): void;
+    /** Forget the stored settings. */
+    clear(): void;
+};
+/**
+ * A namespaced settings store.
+ *
+ * Every operation is guarded: `localStorage` can be unavailable (private
+ * browsing, storage disabled) or full, and losing settings must never take the
+ * add-on - or the game - down with it.
+ */
+export declare const createSettings: <T extends object>(namespace: string, defaults: T) => SettingsStore<T>;
+//# sourceMappingURL=settings.d.ts.map

package/dist/runtime/settings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings.d.ts","sourceRoot":"","sources":["../../src/runtime/settings.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAMH,MAAM,MAAM,aAAa,CAAC,CAAC,SAAS,MAAM,IAAI;IAC7C,2CAA2C;IAC3C,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,8DAA8D;IAC9D,IAAI,IAAI,CAAC,CAAC;IACV,uDAAuD;IACvD,IAAI,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI,CAAC;IACrB,kCAAkC;IAClC,KAAK,IAAI,IAAI,CAAC;CACd,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,cAAc,GAAI,CAAC,SAAS,MAAM,EAC9C,WAAW,MAAM,EACjB,UAAU,CAAC,KACT,aAAa,CAAC,CAAC,CA6CjB,CAAC"}