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

package/dist/runtime/settings.js

@@ -0,0 +1,74 @@
+/**
+ * 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.
+ */
+const PREFIX = 'oss-idle-addon:';
+/** {@link PREFIX} before the rename to oss!idle: still read, so saved settings carry over. */
+const LEGACY_PREFIX = 'osu-idle-addon:';
+/**
+ * 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 const createSettings = (namespace, defaults) => {
+    const key = `${PREFIX}${namespace}`;
+    return {
+        key,
+        load() {
+            try {
+                const raw = localStorage.getItem(key) ?? localStorage.getItem(`${LEGACY_PREFIX}${namespace}`);
+                if (!raw)
+                    return { ...defaults };
+                const stored = JSON.parse(raw);
+                if (!stored || typeof stored !== 'object')
+                    return { ...defaults };
+                // Take only keys the defaults still declare, and only when the
+                // stored value has the same shape - a hand-edited or stale entry
+                // must not put a string where a number is expected.
+                const merged = { ...defaults };
+                for (const name of Object.keys(defaults)) {
+                    const value = stored[name];
+                    if (value === undefined)
+                        continue;
+                    if (typeof value !== typeof defaults[name])
+                        continue;
+                    merged[name] = value;
+                }
+                return merged;
+            }
+            catch {
+                return { ...defaults };
+            }
+        },
+        save(value) {
+            try {
+                localStorage.setItem(key, JSON.stringify(value));
+            }
+            catch {
+                // Full or unavailable storage: the add-on still works, it just
+                // will not remember. Not worth interrupting the player over.
+            }
+        },
+        clear() {
+            try {
+                localStorage.removeItem(key);
+            }
+            catch { /* nothing to do */ }
+        },
+    };
+};

package/package.json

@@ -1,6 +1,85 @@
 {
   "name": "@oss-idle/addon-sdk",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.5.0",
+  "type": "module",
+  "license": "AGPL-3.0-only",
+  "description": "oss!idle Addon SDK - build oss!idle add-ons in TypeScript. An Addon base class with automatic teardown, shadow-root React overlays, bridges to the game's database and beatmap store, and a bundler that emits the single-file ES module the add-on runtime loads.",
+  "keywords": [
+    "osu",
+    "oss-idle",
+    "addon",
+    "sdk",
+    "plugin",
+    "typescript",
+    "esbuild"
+  ],
+  "homepage": "https://github.com/oss-idle/addon-sdk#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/oss-idle/addon-sdk.git",
+    "directory": "packages/addon-sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/oss-idle/addon-sdk/issues"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "default": "./dist/react/index.js"
+    },
+    "./build": {
+      "types": "./dist/build/index.d.ts",
+      "default": "./dist/build/index.js"
+    },
+    "./package.json": "./package.json",
+    "./scaffold": "./bin/scaffold.mjs"
+  },
+  "bin": {
+    "oss-idle-addon": "bin/cli.mjs"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "esbuild": "^0.24.0"
+  },
+  "peerDependencies": {
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "react-dom": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^26.4.1",
+    "@types/react": "^18.3.12",
+    "@types/react-dom": "^18.3.1",
+    "typescript": "^5.6.3"
+  }
+}

package/templates/common/README.md

@@ -0,0 +1,31 @@
+# __ADDON_NAME__
+
+An add-on for [oss!idle](https://github.com/oss-idle/oss-idle), built with the
+[oss!idle Addon SDK](https://github.com/oss-idle/addon-sdk).
+
+## Build
+
+```sh
+npm install
+npm run build
+```
+
+That emits `__OUTFILE__` - a single self-contained ES module. Paste its contents
+into the in-game add-on editor (Options → Add-ons → Manage) and enable it.
+
+`npm run dev` rebuilds on save; re-paste to see changes.
+
+## How an add-on runs
+
+The game imports your built file as an ES module from a Blob URL and calls its
+`mount` / `unmount` exports. Nothing is injected and nothing resolves at load
+time, so every dependency is bundled into that one file.
+
+`unmount` has to genuinely undo everything, because add-ons are enabled,
+disabled, updated and removed without a page reload. The SDK's `Addon` base
+class records teardown for every listener, timer and overlay it hands you and
+reverses it for you.
+
+## Licence
+
+__LICENSE__

package/templates/common/addon.config.json

@@ -0,0 +1,6 @@
+{
+  "name": "__ADDON_NAME__",
+  "license": "__LICENSE__",
+  "entry": "src/index.ts",
+  "outfile": "dist/__SLUG__.js"
+}

package/templates/common/gitignore

@@ -0,0 +1,3 @@
+node_modules/
+dist/
+*.tsbuildinfo

package/templates/common/src/env.d.ts

@@ -0,0 +1,17 @@
+/** Stylesheets are inlined as strings and injected into the overlay's shadow root. */
+declare module '*.css' {
+	const css: string;
+	export default css;
+}
+
+/** Workers are inlined into the single-file bundle and spawned from a Blob URL. */
+declare module 'worker:*' {
+	const createWorker: () => Worker;
+	export default createWorker;
+}
+
+/** Binary assets inlined as base64 (e.g. `import wasm from './x.wasm?base64'`). */
+declare module '*?base64' {
+	const base64: string;
+	export default base64;
+}

package/templates/common/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable", "WebWorker"],
+    "module": "ES2022",
+    "moduleResolution": "bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "skipLibCheck": true,
+    "noEmit": true
+  },
+  "include": ["src"]
+}

package/templates/plain/src/index.ts

@@ -0,0 +1,32 @@
+/**
+ * __ADDON_NAME__
+ *
+ * oss!idle loads an add-on by importing its built source as an ES module and
+ * calling `mount` / `unmount`. That pair is the whole contract - `defineAddon`
+ * produces it from the class below.
+ */
+
+import { Addon, defineAddon, gameDb } from '@oss-idle/addon-sdk';
+
+class __CLASS__ extends Addon {
+
+	constructor() {
+		super({ name: '__ADDON_NAME__' });
+	}
+
+	protected async onMount(): Promise<void> {
+		// The client opens its database lazily, so wait before querying it.
+		await gameDb.ready();
+
+		const played = await gameDb.value<number>('SELECT COUNT(*) FROM score');
+		this.log.info(`hello! you have ${played ?? 0} scores stored locally`);
+
+		// Anything registered through `this.on` / `this.interval` / `this.own`
+		// is torn down automatically when the add-on is disabled or updated.
+		this.on(window, 'keydown', event => {
+			if (event.key === 'F9') this.log.info('F9');
+		});
+	}
+}
+
+export const { mount, unmount } = defineAddon(() => new __CLASS__());

package/templates/react/src/Addon.tsx

@@ -0,0 +1,44 @@
+/**
+ * __ADDON_NAME__
+ *
+ * The panel is mounted for the add-on's whole life and only *hidden* when
+ * closed. Returning `null` instead would unmount the React tree, discarding its
+ * state and running cleanup - so anything the overlay had started would be
+ * thrown away the moment the player closed it.
+ */
+
+import type { ReactNode } from 'react';
+import { ReactAddon } from '@oss-idle/addon-sdk/react';
+import Panel from './Panel.js';
+import styles from './styles.css';
+
+const TOGGLE = 'Ctrl+Shift+__KEY__';
+
+export class __CLASS__ extends ReactAddon {
+
+	private open = false;
+
+	constructor() {
+		super({ name: '__ADDON_NAME__', overlayId: '__SLUG__', styles });
+	}
+
+	protected override async onReady(): Promise<void> {
+		// Registered in the capture phase, ahead of the game's own handlers, so
+		// the combo never reaches gameplay.
+		this.own(this.hotkeys.register(TOGGLE, () => this.toggle(), { allowInText: true }));
+		this.own(this.hotkeys.register('Escape', () => {
+			if (this.open) this.toggle();
+		}, { allowInText: true }));
+
+		this.log.info(`ready - press ${TOGGLE} to open`);
+	}
+
+	private toggle(): void {
+		this.open = !this.open;
+		this.refresh();
+	}
+
+	protected render(): ReactNode {
+		return <Panel open={this.open} version={this.meta.version ?? ''} onClose={() => this.toggle()} />;
+	}
+}

package/templates/react/src/Panel.tsx

@@ -0,0 +1,41 @@
+import { useEffect, useState } from 'react';
+import { gameCharacter, type CharacterRow } from '@oss-idle/addon-sdk';
+
+export default function Panel({
+	open,
+	version,
+	onClose,
+}: {
+	open: boolean;
+	version: string;
+	onClose: () => void;
+}) {
+	const [character, setCharacter] = useState<CharacterRow>();
+
+	// Re-read when opened: the client writes skill levels back to this row after
+	// every play, so a value read once at boot goes stale.
+	useEffect(() => {
+		if (open) void gameCharacter.live().then(setCharacter);
+	}, [open]);
+
+	return (
+		<div style={{ display: open ? 'contents' : 'none' }} aria-hidden={!open}>
+			<div className="backdrop" onClick={onClose} />
+			<div className="panel" role="dialog" aria-label="__ADDON_NAME__">
+				<header>
+					<h1>__ADDON_NAME__</h1>
+					<span className="spacer" />
+					<span className="hint">v{version}</span>
+					<button onClick={onClose}>Close</button>
+				</header>
+
+				<div className="body">
+					{character
+						? <p>Playing as <strong>{character.name}</strong> (level {character.overallLevel}).</p>
+						: <p>Looking for your character...</p>}
+					<p>Edit <code>src/Panel.tsx</code> to build your add-on.</p>
+				</div>
+			</div>
+		</div>
+	);
+}

package/templates/react/src/index.ts

@@ -0,0 +1,12 @@
+/**
+ * __ADDON_NAME__
+ *
+ * oss!idle loads an add-on by importing its built source as an ES module and
+ * calling `mount` / `unmount`. That pair is the whole contract - `defineAddon`
+ * produces it from the class in `Addon.tsx`.
+ */
+
+import { defineAddon } from '@oss-idle/addon-sdk';
+import { __CLASS__ } from './Addon.js';
+
+export const { mount, unmount } = defineAddon(() => new __CLASS__());

package/templates/react/src/styles.css

@@ -0,0 +1,61 @@
+/*
+ * Rendered inside a shadow root, so these selectors cannot reach the game and
+ * the game's stylesheet cannot reach them.
+ */
+
+:host, * { box-sizing: border-box; }
+
+.backdrop {
+	position: absolute;
+	inset: 0;
+	background: rgb(8 6 12 / 55%);
+	pointer-events: auto;
+}
+
+.panel {
+	position: absolute;
+	top: 50%;
+	left: 50%;
+	transform: translate(-50%, -50%);
+	width: min(720px, 92vw);
+	max-height: 80vh;
+	display: flex;
+	flex-direction: column;
+	pointer-events: auto;
+
+	font-family: ui-sans-serif, system-ui, "Segoe UI", Roboto, sans-serif;
+	font-size: 13px;
+	color: #eceaf2;
+	background: #16141c;
+	border: 1px solid #322c40;
+	border-radius: 12px;
+	box-shadow: 0 24px 80px rgb(0 0 0 / 60%);
+	overflow: hidden;
+}
+
+header {
+	display: flex;
+	align-items: center;
+	gap: 12px;
+	padding: 14px 18px;
+	background: #1e1a28;
+	border-bottom: 1px solid #322c40;
+}
+
+header h1 { margin: 0; font-size: 15px; font-weight: 600; }
+header .spacer { flex: 1; }
+header .hint { color: #8b83a0; font-size: 11px; }
+
+button {
+	font: inherit;
+	color: #eceaf2;
+	background: #2b2438;
+	border: 1px solid #3d3550;
+	border-radius: 6px;
+	padding: 6px 12px;
+	cursor: pointer;
+}
+button:hover { background: #362d47; }
+
+.body { padding: 18px; overflow: auto; line-height: 1.7; }
+code { background: #221d2e; border-radius: 4px; padding: 1px 5px; }