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

package/dist/react/reactAddon.d.ts

@@ -0,0 +1,37 @@
+/**
+ * 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 type { ReactNode } from 'react';
+import { Addon, type AddonMeta } from '../runtime/addon.js';
+import { HotkeyManager } from '../runtime/input.js';
+export type ReactAddonMeta = AddonMeta & {
+    /** Host element id. Defaults to a slug of the add-on name. */
+    overlayId?: string;
+    /** Stylesheet for the shadow tree. */
+    styles?: string;
+};
+export declare abstract class ReactAddon extends Addon {
+    private overlay?;
+    private root?;
+    /** Global shortcuts, bound ahead of the game's own handlers. */
+    protected readonly hotkeys: HotkeyManager;
+    private readonly reactMeta;
+    constructor(meta: ReactAddonMeta);
+    /** The add-on's root component. Re-rendered only when {@link refresh} is called. */
+    protected abstract render(): ReactNode;
+    protected onMount(): Promise<void>;
+    /** Hook for work that needs the overlay to exist (shortcuts, data loading). */
+    protected onReady(): void | Promise<void>;
+    /** Re-render the tree - for state the add-on holds outside React. */
+    protected refresh(): void;
+    protected onUnmount(): Promise<void>;
+}
+//# sourceMappingURL=reactAddon.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"reactAddon.d.ts","sourceRoot":"","sources":["../../src/react/reactAddon.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC,OAAO,EAAE,KAAK,EAAE,KAAK,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAC5D,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAGpD,MAAM,MAAM,cAAc,GAAG,SAAS,GAAG;IACxC,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,sCAAsC;IACtC,MAAM,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAEF,8BAAsB,UAAW,SAAQ,KAAK;IAE7C,OAAO,CAAC,OAAO,CAAC,CAAU;IAC1B,OAAO,CAAC,IAAI,CAAC,CAAO;IAEpB,gEAAgE;IAChE,SAAS,CAAC,QAAQ,CAAC,OAAO,gBAAuB;IAEjD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAiB;gBAE/B,IAAI,EAAE,cAAc;IAKhC,oFAAoF;IACpF,SAAS,CAAC,QAAQ,CAAC,MAAM,IAAI,SAAS;cAEb,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAYjD,+EAA+E;IAC/E,SAAS,CAAC,OAAO,IAAI,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAEzC,qEAAqE;IACrE,SAAS,CAAC,OAAO,IAAI,IAAI;cAIA,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;CASnD"}

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,94 @@
+/**
+ * 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. `mount` is handed the game's
+ * host (its React, the editor for add-ons of the Editor type: {@link host});
+ * the rest (the game's database, its beatmap store, the DOM) an add-on 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 { type AddonHost, type EditorApi } from './host.js';
+/** 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(host?: AddonHost): Promise<void>;
+    private handed?;
+    /** The game's host: React, the editor. Undefined on a game too old to hand one. */
+    protected get host(): AddonHost | undefined;
+    /**
+     * Work with the editor while it is open (an add-on of the Editor type):
+     * `onOpen` runs each time it opens, with its API. What is registered through
+     * that API goes when the editor closes or this add-on unmounts.
+     */
+    protected editor(onOpen: (editor: EditorApi) => void, onClose?: () => void): 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;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,EAEN,KAAK,SAAS,EACd,KAAK,SAAS,EACd,MAAM,WAAW,CAAC;AAEnB,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,CAAC,IAAI,CAAC,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAO7C,OAAO,CAAC,MAAM,CAAC,CAAY;IAE3B,mFAAmF;IACnF,SAAS,KAAK,IAAI,IAAI,SAAS,GAAG,SAAS,CAE1C;IAED;;;;OAIG;IACH,SAAS,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,IAAI,EAAE,OAAO,CAAC,EAAE,MAAM,IAAI,GAAG,IAAI;IASjF;;;;;;OAMG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAkB/B"}

package/dist/runtime/addon.js

@@ -0,0 +1,129 @@
+/**
+ * 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. `mount` is handed the game's
+ * host (its React, the editor for add-ons of the Editor type: {@link host});
+ * the rest (the game's database, its beatmap store, the DOM) an add-on 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';
+import { gameHost, } from './host.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(host) {
+        if (this.mounted)
+            return;
+        this.mounted = true;
+        this.handed = host;
+        await this.onMount();
+    }
+    handed;
+    /** The game's host: React, the editor. Undefined on a game too old to hand one. */
+    get host() {
+        return this.handed ?? gameHost();
+    }
+    /**
+     * Work with the editor while it is open (an add-on of the Editor type):
+     * `onOpen` runs each time it opens, with its API. What is registered through
+     * that API goes when the editor closes or this add-on unmounts.
+     */
+    editor(onOpen, onClose) {
+        const host = this.host;
+        if (!host) {
+            this.log.warn('this game hands add-ons no editor: update oss!idle');
+            return;
+        }
+        this.own(host.editor.watch(onOpen, onClose));
+    }
+    /**
+     * 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,26 @@
+import { Addon } from './addon.js';
+import type { AddonHost } from './host.js';
+/** The module shape oss!idle's add-on runtime imports and drives. */
+export type AddonModule = {
+    mount: (meta?: unknown, host?: AddonHost) => void;
+    unmount: () => Promise<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 `mount` synchronously and ignores what it returns, 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.
+ * `unmount` returns its teardown, which the runtime awaits before mounting an
+ * updated version.
+ *
+ * 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;AACnC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAE3C,qEAAqE;AACrE,MAAM,MAAM,WAAW,GAAG;IACzB,KAAK,EAAE,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,IAAI,CAAC,EAAE,SAAS,KAAK,IAAI,CAAC;IAClD,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;CAC7B,CAAC;AAEF;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,WAAW,GAAI,QAAQ,MAAM,KAAK,KAAG,WAsBjD,CAAC"}

package/dist/runtime/define.js

@@ -0,0 +1,40 @@
+/**
+ * Turn an {@link Addon} subclass into the `mount` / `unmount` pair the runtime
+ * expects:
+ *
+ * ```ts
+ * export const { mount, unmount } = defineAddon(() => new MyAddon());
+ * ```
+ *
+ * The runtime calls `mount` synchronously and ignores what it returns, 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.
+ * `unmount` returns its teardown, which the runtime awaits before mounting an
+ * updated version.
+ *
+ * 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: (_meta, host) => {
+            instance = create();
+            const addon = instance;
+            settling = addon._mount(host).catch((e) => {
+                console.error('[addon] mount failed', e);
+            });
+        },
+        unmount: () => {
+            const addon = instance;
+            if (!addon)
+                return settling;
+            instance = undefined;
+            settling = settling
+                .then(() => addon._unmount())
+                .catch((e) => console.error('[addon] unmount failed', e));
+            return settling;
+        },
+    };
+};

package/dist/runtime/host.d.ts

@@ -0,0 +1,113 @@
+/**
+ * What the game hands an add-on: `mount(meta, host)`, and the same object on
+ * `globalThis.ossIdle` for code that runs before `mount` (the `sharedReact`
+ * build reads React there). Mirrors the game's `addons/host.ts` and
+ * `editor/editorApi.ts`; an older game hands none.
+ */
+/** A teardown; running it undoes what returned it. */
+type Disposer = () => void;
+/** A note as the editor holds it; `end` makes it a long note. */
+export type EditorNote = {
+    time: number;
+    column: number;
+    end?: number;
+    /** the .osu hitSound bits, as written */
+    hitSound: string;
+    /** the .osu sample fields, as written */
+    sample: string;
+};
+export type EditorTimingPoint = {
+    time: number;
+    /** ms per beat for a BPM point; -100 / the multiplier for a scroll speed one */
+    beatLength: number;
+    meter: number;
+    sound: string;
+    effects: string;
+};
+export type EditorMetadata = {
+    title: string;
+    titleUnicode: string;
+    artist: string;
+    artistUnicode: string;
+    creator: string;
+    version: string;
+    source: string;
+    tags: string;
+    previewTime: number;
+};
+/** Draws into `container`; what it returns runs when it goes. */
+export type EditorRender = (container: HTMLElement) => void | (() => void);
+/**
+ * The open editor. Notes and points are the editor's own objects: read them,
+ * never change them, and hand new ones to `edit`. Everything registered here
+ * goes when the editor closes or the add-on stops.
+ */
+export type EditorApi = {
+    readonly keys: number;
+    notes(): readonly EditorNote[];
+    timing(): readonly EditorTimingPoint[];
+    scroll(): readonly EditorTimingPoint[];
+    metadata(): Readonly<EditorMetadata>;
+    bookmarks(): readonly number[];
+    text(): string;
+    edit(change: {
+        notes?: EditorNote[];
+        timing?: EditorTimingPoint[];
+        scroll?: EditorTimingPoint[];
+        bookmarks?: number[];
+        metadata?: Partial<EditorMetadata>;
+    }, select?: EditorNote[]): void;
+    undo(): void;
+    redo(): void;
+    save(): void;
+    selection(): EditorNote[];
+    select(notes: EditorNote[]): void;
+    now(): number;
+    seek(ms: number): void;
+    play(): void;
+    pause(): void;
+    isPlaying(): boolean;
+    snap(ms: number): number;
+    divisor(): number;
+    setDivisor(divisor: number): void;
+    onChange(callback: () => void): Disposer;
+    addAction(action: {
+        id: string;
+        label: string;
+        keys?: string[];
+        run: () => void;
+    }): Disposer;
+    addTab(tab: {
+        id: string;
+        label: string;
+        render: EditorRender;
+    }): Disposer;
+    addPanel(panel: {
+        id: string;
+        title?: string;
+        render: EditorRender;
+    }): Disposer;
+    openWindow(window: {
+        title: string;
+        width?: number;
+        height?: number;
+        render: EditorRender;
+        onClose?: () => void;
+    }): {
+        close(): void;
+    };
+};
+export type AddonHost = {
+    /** the game's version */
+    version: string;
+    /** the game's React modules by import path */
+    react: Record<string, unknown>;
+    editor: {
+        /** `onOpen` runs whenever the editor opens (now, if it is open), `onClose` when it closes. */
+        watch(onOpen: (editor: EditorApi) => void, onClose?: () => void): Disposer;
+    };
+};
+/** The game's host, if it hands one out (older games do not). */
+export declare const gameHost: () => AddonHost | undefined;
+export {};
+//# sourceMappingURL=host.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../../src/runtime/host.ts"],"names":[],"mappings":"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"}

package/dist/runtime/host.js

@@ -0,0 +1,8 @@
+/**
+ * What the game hands an add-on: `mount(meta, host)`, and the same object on
+ * `globalThis.ossIdle` for code that runs before `mount` (the `sharedReact`
+ * build reads React there). Mirrors the game's `addons/host.ts` and
+ * `editor/editorApi.ts`; an older game hands none.
+ */
+/** The game's host, if it hands one out (older games do not). */
+export const gameHost = () => globalThis.ossIdle;

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"}