minimojs 1.0.0-alpha.33 → 1.0.0-alpha.35

package/dist/minimo-leaderboard.d.ts

@@ -0,0 +1,199 @@
+import { Game } from "./minimo.js";
+/**
+ * When a leaderboard starts again. Every period is a UTC calendar unit, and a
+ * week is an ISO week, starting on Monday, so every player sees the table
+ * reset at the same moment. Past periods stay readable.
+ */
+export type LeaderboardCycle = "never" | "daily" | "weekly" | "monthly" | "yearly";
+/** Which score is better: `higher`, for points, or `lower`, for times. */
+export type LeaderboardOrder = "higher" | "lower";
+/**
+ * What a leaderboard's table calls each player: `player`, the name the player
+ * wrote, or `noname`; `hidden`, no names; or `assigned`, a name such as
+ * `Blue Fox 42`, given to each player.
+ */
+export type LeaderboardNames = "player" | "hidden" | "assigned";
+/**
+ * Who can be in a leaderboard. `account`: players signed in to Minimo Games,
+ * in one table every player sees. `local`: light users, whose scores stay on
+ * their own device, so each player sees only their own.
+ */
+export type LeaderboardPlayer = "account" | "local";
+/**
+ * How a leaderboard works. On Minimo Games the creator sets these on the
+ * game's Edit leaderboards page, or an AI agent sets them with the
+ * `saveGameLeaderboard` tool, and the game reads them; the settings passed to
+ * {@link Leaderboard} are used only when the game runs anywhere else.
+ */
+export interface LeaderboardSettings {
+    /** The title its table shows. */
+    title: string;
+    cycle: LeaderboardCycle;
+    order: LeaderboardOrder;
+    names: LeaderboardNames;
+    player: LeaderboardPlayer;
+}
+/**
+ * Which period of a leaderboard to read: `"current"` (the default),
+ * `"previous"`, such as yesterday's table of a daily leaderboard, or a period
+ * written out: `"2026-10-17"`, `"2026-W42"`, `"2026-10"`, or `"2026"`.
+ */
+export type LeaderboardPeriod = "current" | "previous" | string;
+/** One row of a leaderboard's table. */
+export interface LeaderboardEntry {
+    /** 1 for the best score. Equal scores share a rank. */
+    rank: number;
+    /** The player's name, or `null` when the leaderboard shows no names. */
+    name: string | null;
+    score: number;
+    /** Whether this is the player playing now. */
+    mine: boolean;
+}
+/** One period of a leaderboard, best score first. */
+export interface LeaderboardTable {
+    key: string;
+    settings: LeaderboardSettings;
+    /** The period read, or `null` for the period before a leaderboard that never resets. */
+    period: string | null;
+    entries: LeaderboardEntry[];
+    /** The player's own entry in the period, wherever it ranks, or `null`. */
+    mine: LeaderboardEntry | null;
+    /**
+     * `false` when the leaderboard does not exist, such as a key no leaderboard
+     * of the game has. The table is then empty.
+     */
+    available: boolean;
+    /** Whether the scores are kept on this device rather than by Minimo Games. */
+    local: boolean;
+}
+/**
+ * What became of a score:
+ *
+ * - `saved`: it is the player's best in the period, and the table shows it.
+ * - `not_better`: the player already has a better score in the period.
+ * - `pending_sign_in`: the leaderboard takes Minimo Games accounts and the
+ *   player is not signed in. Minimo Games asks them to sign in, keeps the
+ *   score, and saves it when they come back.
+ * - `unavailable`: the leaderboard does not exist, or the game is not taking
+ *   new records now.
+ */
+export type LeaderboardSubmitStatus = "saved" | "not_better" | "pending_sign_in" | "unavailable";
+export interface LeaderboardSubmitResult {
+    status: LeaderboardSubmitStatus;
+    /** The player's best score in the period, or `null` when nothing was saved. */
+    best: number | null;
+    /** The rank of that best score, or `null` when nothing was saved. */
+    rank: number | null;
+    period: string | null;
+}
+/** Options for {@link Leaderboard.top}. */
+export interface LeaderboardTopOptions {
+    /** Which period to read. Default `"current"`. */
+    period?: LeaderboardPeriod;
+}
+/** Options for {@link Leaderboard.show}. Every field is optional. */
+export interface LeaderboardShowOptions {
+    /** How many of the best scores the table shows. Default `10`, at most `100`. */
+    top?: number;
+    /** Which period the table opens on. Default `"current"`; the player can switch to the previous one. */
+    period?: LeaderboardPeriod;
+    /** A title instead of the leaderboard's own. */
+    title?: string;
+    /** How a score is written, such as `(s) => s.toFixed(2) + " s"`. Default: the number, with digit grouping. */
+    format?: (score: number) => string;
+    /** CSS font family, such as one of the game's fonts. Default: the system font. */
+    font?: string;
+    /** Background color of the table. Default `"#15151d"`. */
+    background?: string;
+    /** Text color. Default `"#ffffff"`. */
+    color?: string;
+    /** Color of the title and of the player's own row. Default `"#ffcc33"`. */
+    accent?: string;
+}
+/**
+ * A leaderboard of the game: a table of each player's best score, per period.
+ *
+ * On Minimo Games, the creator sets up a game's leaderboards, up to 5, on the
+ * game's Edit leaderboards page, or an AI agent with the `saveGameLeaderboard`
+ * tool; the game names one by its key. Their settings come from there, and a
+ * key that no leaderboard of the game has is unavailable. Leaderboards are part
+ * of Minimo Games Pro: while the creator is not on it, the game shows its
+ * tables but saves no new records.
+ *
+ * Scores of a leaderboard that takes Minimo Games accounts go to one table
+ * that every player sees. Minimo Games posts them for the signed-in player, and
+ * asks a player who is not signed in to sign in, keeping the score until they
+ * do. Scores of a leaderboard for light users stay on the device, and a game
+ * preview keeps every score on the device, so a working version never changes
+ * the published game's tables.
+ *
+ * Anywhere else, every leaderboard keeps its scores on the device, with the
+ * settings passed here.
+ *
+ * Nothing here pauses the game. Await {@link Leaderboard.show} to continue
+ * after the player closes the table.
+ *
+ * ```js
+ * import { Leaderboard } from "https://cdn.jsdelivr.net/npm/minimojs@<version>/dist/minimo-leaderboard.js";
+ *
+ * const best = new Leaderboard(game, "best-score");
+ * // When a run ends:
+ * await best.submit(score);
+ * await best.show({ top: 10 });
+ * ```
+ */
+export declare class Leaderboard {
+    /** The key the game names this leaderboard by. */
+    readonly key: string;
+    /**
+     * @param game - The game.
+     * @param key - The leaderboard's key, as set up on Minimo Games.
+     * @param settings - Used only when the game runs outside Minimo Games.
+     *   Default: a leaderboard on the device that never resets, where higher is
+     *   better and players are named by their own name.
+     */
+    constructor(game: Game, key: string, settings?: Partial<LeaderboardSettings>);
+    /** Whether the table is showing. */
+    get isShowing(): boolean;
+    /**
+     * This leaderboard's settings, and whether it exists and keeps its scores on
+     * the device.
+     */
+    info(): Promise<{
+        settings: LeaderboardSettings;
+        available: boolean;
+        local: boolean;
+    }>;
+    /**
+     * Posts a score. Only the player's best score in the current period is
+     * kept, so posting every finished run is right.
+     *
+     * @param score - A finite number. Which is better, higher or lower, is the
+     *   leaderboard's setting.
+     */
+    submit(score: number): Promise<LeaderboardSubmitResult>;
+    /**
+     * Reads one period of the table, best score first.
+     *
+     * @param limit - How many of the best scores. Default `10`, at most `100`.
+     */
+    top(limit?: number, options?: LeaderboardTopOptions): Promise<LeaderboardTable>;
+    /**
+     * The light user's name on this device, shared by every Minimo Games game,
+     * or `null` before the player writes one. The table asks for it on its own
+     * when a leaderboard for light users shows names.
+     */
+    playerName(): Promise<string | null>;
+    /** Sets the light user's name on this device. Returns it cleaned, or `null` when it is empty or too long. */
+    setPlayerName(name: string): Promise<string | null>;
+    /**
+     * Shows the table over the game, in HTML: the best scores of a period, the
+     * player's own entry, and, for a leaderboard that resets, a switch to the
+     * previous period. Resolves when the player closes it.
+     */
+    show(options?: LeaderboardShowOptions): Promise<void>;
+    /** Closes the table, if it is showing. */
+    close(): void;
+    /** Closes the table. The leaderboard's scores are kept. */
+    destroy(): void;
+}

package/dist/minimo-leaderboard.js

@@ -0,0 +1,566 @@
+const DEFAULT_SETTINGS = {
+    title: "Leaderboard",
+    cycle: "never",
+    order: "higher",
+    names: "player",
+    player: "local",
+};
+const NO_NAME = "noname";
+const MAX_NAME_CHARS = 24;
+const MAX_LOCAL_ENTRIES = 100;
+const MAX_LOCAL_PERIODS = 60;
+const MAX_READ = 100;
+// ---------------------------------------------------------------------------
+// Periods: the same as Minimo Games computes for the leaderboards it keeps.
+function pad(value) {
+    return String(value).padStart(2, "0");
+}
+function isoWeek(date) {
+    const day = new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate()));
+    const weekday = day.getUTCDay() || 7;
+    day.setUTCDate(day.getUTCDate() + 4 - weekday);
+    const yearStart = Date.UTC(day.getUTCFullYear(), 0, 1);
+    return { year: day.getUTCFullYear(), week: Math.ceil(((day.getTime() - yearStart) / 86400000 + 1) / 7) };
+}
+/** @internal */
+export function leaderboardPeriod(cycle, at) {
+    switch (cycle) {
+        case "daily":
+            return `${at.getUTCFullYear()}-${pad(at.getUTCMonth() + 1)}-${pad(at.getUTCDate())}`;
+        case "weekly": {
+            const { year, week } = isoWeek(at);
+            return `${year}-W${pad(week)}`;
+        }
+        case "monthly":
+            return `${at.getUTCFullYear()}-${pad(at.getUTCMonth() + 1)}`;
+        case "yearly":
+            return String(at.getUTCFullYear());
+        default:
+            return "all";
+    }
+}
+/** @internal */
+export function resolveLeaderboardPeriod(cycle, requested, now) {
+    const value = (requested ?? "current").trim();
+    if (value === "" || value === "current")
+        return leaderboardPeriod(cycle, now);
+    if (value !== "previous")
+        return value;
+    const day = Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate());
+    switch (cycle) {
+        case "daily":
+            return leaderboardPeriod(cycle, new Date(day - 86400000));
+        case "weekly":
+            return leaderboardPeriod(cycle, new Date(day - 7 * 86400000));
+        case "monthly":
+            return leaderboardPeriod(cycle, new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), 0)));
+        case "yearly":
+            return String(now.getUTCFullYear() - 1);
+        default:
+            return null;
+    }
+}
+const HOST_TIMEOUT_MS = 1500;
+const REQUEST_TIMEOUT_MS = 15000;
+const pendingRequests = new Map();
+let nextRequestId = 1;
+let listening = false;
+let hostPromise = null;
+function parentWindow() {
+    try {
+        return typeof window !== "undefined" && window.parent && window.parent !== window ? window.parent : null;
+    }
+    catch {
+        return null;
+    }
+}
+function listen() {
+    if (listening || typeof window === "undefined")
+        return;
+    listening = true;
+    window.addEventListener("message", (event) => {
+        if (event.source !== parentWindow())
+            return;
+        const message = event.data;
+        if (!message || message.type !== "minimo:leaderboard-response" || typeof message.id !== "string")
+            return;
+        const pending = pendingRequests.get(message.id);
+        if (!pending)
+            return;
+        pendingRequests.delete(message.id);
+        if (message.ok)
+            pending.resolve(message.result);
+        else
+            pending.reject(new Error(message.error || "Leaderboard request failed"));
+    });
+}
+function request(action, payload, timeoutMs = REQUEST_TIMEOUT_MS) {
+    const parent = parentWindow();
+    if (!parent)
+        return Promise.reject(new Error("No leaderboard host"));
+    listen();
+    const id = `leaderboard-${nextRequestId++}`;
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            pendingRequests.delete(id);
+            reject(new Error("The leaderboard did not answer"));
+        }, timeoutMs);
+        pendingRequests.set(id, {
+            resolve: (value) => { clearTimeout(timer); resolve(value); },
+            reject: (error) => { clearTimeout(timer); reject(error); },
+        });
+        parent.postMessage({ type: "minimo:leaderboard-request", id, action, ...payload }, "*");
+    });
+}
+function connectHost() {
+    hostPromise ?? (hostPromise = request("hello", {}, HOST_TIMEOUT_MS)
+        .then((info) => (info && info.host === "minimo-games" ? info : null))
+        .catch(() => null));
+    return hostPromise;
+}
+const memoryStorage = new Map();
+function readStored(key) {
+    try {
+        const value = window.localStorage.getItem(key);
+        if (value !== null)
+            return value;
+    }
+    catch {
+        // Fall back to memory.
+    }
+    return memoryStorage.get(key) ?? null;
+}
+function writeStored(key, value) {
+    memoryStorage.set(key, value);
+    try {
+        window.localStorage.setItem(key, value);
+    }
+    catch {
+        // Kept in memory for this visit.
+    }
+}
+function cleanName(value) {
+    if (typeof value !== "string")
+        return null;
+    const name = value.replace(/\s+/g, " ").trim();
+    return name && Array.from(name).length <= MAX_NAME_CHARS ? name : null;
+}
+const ADJECTIVES = ["Blue", "Brave", "Bright", "Calm", "Clever", "Cosmic", "Golden", "Happy", "Jolly", "Lucky", "Mighty", "Quick",
+    "Quiet", "Red", "Silver", "Sleepy", "Sly", "Sunny", "Swift", "Tiny", "Wild", "Wise", "Witty", "Zesty"];
+const ANIMALS = ["Badger", "Bear", "Cat", "Crab", "Deer", "Duck", "Eagle", "Fox", "Frog", "Gecko", "Goat", "Hare",
+    "Koala", "Lion", "Llama", "Mole", "Otter", "Owl", "Panda", "Seal", "Shark", "Tiger", "Turtle", "Wolf"];
+function assignedLocalName() {
+    const key = "minimo-leaderboard-assigned-name";
+    const stored = cleanName(readStored(key));
+    if (stored)
+        return stored;
+    const pick = (list) => list[Math.floor(Math.random() * list.length)];
+    const name = `${pick(ADJECTIVES)} ${pick(ANIMALS)} ${Math.floor(Math.random() * 100)}`;
+    writeStored(key, name);
+    return name;
+}
+function isBetter(order, candidate, current) {
+    return order === "higher" ? candidate > current : candidate < current;
+}
+function rankEntries(scores) {
+    const ranks = [];
+    scores.forEach((score, index) => {
+        ranks.push(index > 0 && scores[index - 1] === score ? ranks[index - 1] : index + 1);
+    });
+    return ranks;
+}
+// ---------------------------------------------------------------------------
+// The table drawn over the game, in HTML.
+const STYLE_ID = "minimo-leaderboard-style";
+const STYLE = `
+.minimo-leaderboard{position:fixed;z-index:2147483000;display:flex;align-items:center;justify-content:center;
+  box-sizing:border-box;background:rgba(0,0,0,.55);-webkit-user-select:none;user-select:none;touch-action:manipulation}
+.minimo-leaderboard *{box-sizing:border-box}
+.minimo-leaderboard-panel{display:flex;flex-direction:column;width:min(92%,30em);max-height:92%;padding:1em;border-radius:.9em;
+  background:var(--mlb-bg);color:var(--mlb-fg);font-family:var(--mlb-font);box-shadow:0 .6em 2em rgba(0,0,0,.5)}
+.minimo-leaderboard-title{margin:0 0 .15em;color:var(--mlb-accent);font-size:1.35em;font-weight:700;text-align:center}
+.minimo-leaderboard-period{margin:0 0 .7em;opacity:.7;font-size:.8em;text-align:center}
+.minimo-leaderboard-tabs{display:flex;gap:.4em;justify-content:center;margin:0 0 .7em}
+.minimo-leaderboard button{padding:.45em .9em;border:.08em solid currentColor;border-radius:999px;background:none;color:inherit;
+  font:inherit;font-size:.85em;cursor:pointer}
+.minimo-leaderboard button[aria-pressed="true"],.minimo-leaderboard .minimo-leaderboard-primary{border-color:var(--mlb-accent);
+  background:var(--mlb-accent);color:var(--mlb-bg);font-weight:700}
+.minimo-leaderboard-rows{flex:1 1 auto;min-height:0;margin:0;padding:0;overflow-y:auto;list-style:none}
+.minimo-leaderboard-row{display:flex;align-items:baseline;gap:.6em;padding:.35em .5em;border-radius:.4em}
+.minimo-leaderboard-row:nth-child(odd){background:rgba(255,255,255,.06)}
+.minimo-leaderboard-row.is-mine{color:var(--mlb-accent);font-weight:700}
+.minimo-leaderboard-rank{flex:0 0 2.2em;text-align:right;opacity:.8}
+.minimo-leaderboard-name{flex:1 1 auto;min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+.minimo-leaderboard-score{flex:0 0 auto;font-variant-numeric:tabular-nums}
+.minimo-leaderboard-gap{padding:.1em .5em;opacity:.5;text-align:center;list-style:none}
+.minimo-leaderboard-empty{margin:.8em 0;opacity:.75;text-align:center}
+.minimo-leaderboard-name-form{display:flex;gap:.4em;margin:0 0 .7em}
+.minimo-leaderboard-name-form input{flex:1 1 auto;min-width:0;padding:.45em .6em;border:.08em solid currentColor;border-radius:.4em;
+  background:rgba(255,255,255,.08);color:inherit;font:inherit;font-size:max(16px,.9em)}
+.minimo-leaderboard-note{margin:.6em 0 0;opacity:.6;font-size:.75em;text-align:center}
+.minimo-leaderboard-actions{display:flex;justify-content:center;gap:.5em;margin-top:.8em}
+`;
+function escapeHtml(value) {
+    return value.replace(/[&<>"']/g, (char) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[char]);
+}
+function defaultFormat(score) {
+    return Number.isInteger(score) ? score.toLocaleString() : score.toLocaleString(undefined, { maximumFractionDigits: 3 });
+}
+const CURRENT_LABELS = {
+    never: "All time", daily: "Today", weekly: "This week", monthly: "This month", yearly: "This year",
+};
+const PREVIOUS_LABELS = {
+    never: "", daily: "Yesterday", weekly: "Last week", monthly: "Last month", yearly: "Last year",
+};
+/** @internal The table's HTML, apart from the page, so it can be checked without a browser. */
+export function renderLeaderboardHtml(table, view) {
+    const cycle = table.settings.cycle;
+    const parts = [];
+    parts.push(`<div class="minimo-leaderboard-panel" role="dialog" aria-modal="true" aria-label="${escapeHtml(view.title)}">`);
+    parts.push(`<h2 class="minimo-leaderboard-title">${escapeHtml(view.title)}</h2>`);
+    if (cycle !== "never") {
+        parts.push('<div class="minimo-leaderboard-tabs" role="group">');
+        parts.push(`<button type="button" data-period="current" aria-pressed="${view.previous ? "false" : "true"}">${CURRENT_LABELS[cycle]}</button>`);
+        parts.push(`<button type="button" data-period="previous" aria-pressed="${view.previous ? "true" : "false"}">${PREVIOUS_LABELS[cycle]}</button>`);
+        parts.push("</div>");
+    }
+    else {
+        parts.push(`<p class="minimo-leaderboard-period">${CURRENT_LABELS.never}</p>`);
+    }
+    if (view.askName) {
+        // Not a <form>: a game's frame on Minimo Games is sandboxed without forms.
+        parts.push('<div class="minimo-leaderboard-name-form" data-name-form>');
+        parts.push(`<input name="name" maxlength="${MAX_NAME_CHARS}" placeholder="Your name" aria-label="Your name" autocomplete="nickname" value="${escapeHtml(view.playerName ?? "")}">`);
+        parts.push('<button type="button" class="minimo-leaderboard-primary" data-save-name>Save</button></div>');
+    }
+    if (!table.available) {
+        parts.push('<p class="minimo-leaderboard-empty">This leaderboard is not available.</p>');
+    }
+    else if (table.entries.length === 0) {
+        parts.push('<p class="minimo-leaderboard-empty">No scores yet.</p>');
+    }
+    else {
+        parts.push('<ol class="minimo-leaderboard-rows">');
+        const row = (entry) => parts.push(`<li class="minimo-leaderboard-row${entry.mine ? " is-mine" : ""}">`
+            + `<span class="minimo-leaderboard-rank">${entry.rank}</span>`
+            + `<span class="minimo-leaderboard-name">${entry.name === null ? "" : escapeHtml(entry.name)}</span>`
+            + `<span class="minimo-leaderboard-score">${escapeHtml(view.format(entry.score))}</span></li>`);
+        table.entries.forEach(row);
+        if (table.mine && !table.entries.some((entry) => entry.mine)) {
+            parts.push('<li class="minimo-leaderboard-gap" aria-hidden="true">…</li>');
+            row(table.mine);
+        }
+        parts.push("</ol>");
+    }
+    if (table.local && table.available) {
+        parts.push('<p class="minimo-leaderboard-note">Scores on this device</p>');
+    }
+    parts.push('<div class="minimo-leaderboard-actions"><button type="button" class="minimo-leaderboard-primary" data-close>Close</button></div>');
+    parts.push("</div>");
+    return parts.join("");
+}
+/**
+ * A leaderboard of the game: a table of each player's best score, per period.
+ *
+ * On Minimo Games, the creator sets up a game's leaderboards, up to 5, on the
+ * game's Edit leaderboards page, or an AI agent with the `saveGameLeaderboard`
+ * tool; the game names one by its key. Their settings come from there, and a
+ * key that no leaderboard of the game has is unavailable. Leaderboards are part
+ * of Minimo Games Pro: while the creator is not on it, the game shows its
+ * tables but saves no new records.
+ *
+ * Scores of a leaderboard that takes Minimo Games accounts go to one table
+ * that every player sees. Minimo Games posts them for the signed-in player, and
+ * asks a player who is not signed in to sign in, keeping the score until they
+ * do. Scores of a leaderboard for light users stay on the device, and a game
+ * preview keeps every score on the device, so a working version never changes
+ * the published game's tables.
+ *
+ * Anywhere else, every leaderboard keeps its scores on the device, with the
+ * settings passed here.
+ *
+ * Nothing here pauses the game. Await {@link Leaderboard.show} to continue
+ * after the player closes the table.
+ *
+ * ```js
+ * import { Leaderboard } from "https://cdn.jsdelivr.net/npm/minimojs@<version>/dist/minimo-leaderboard.js";
+ *
+ * const best = new Leaderboard(game, "best-score");
+ * // When a run ends:
+ * await best.submit(score);
+ * await best.show({ top: 10 });
+ * ```
+ */
+export class Leaderboard {
+    /**
+     * @param game - The game.
+     * @param key - The leaderboard's key, as set up on Minimo Games.
+     * @param settings - Used only when the game runs outside Minimo Games.
+     *   Default: a leaderboard on the device that never resets, where higher is
+     *   better and players are named by their own name.
+     */
+    constructor(game, key, settings = {}) {
+        /** @internal */ this._overlay = null;
+        /** @internal */ this._closeOverlay = null;
+        this._game = game;
+        this.key = String(key);
+        this._fallback = { ...DEFAULT_SETTINGS, title: this.key, ...settings };
+    }
+    /** Whether the table is showing. */
+    get isShowing() {
+        return this._overlay !== null;
+    }
+    /** @internal */
+    async _resolve() {
+        const host = await connectHost();
+        if (!host) {
+            return { settings: this._fallback, available: true, local: true, accepting: true, preview: false, host: false };
+        }
+        const settings = host.leaderboards[this.key];
+        if (!settings) {
+            return { settings: { ...this._fallback, title: this.key }, available: false, local: true, accepting: false, preview: host.preview, host: true };
+        }
+        return {
+            settings,
+            available: true,
+            local: settings.player === "local" || host.preview,
+            accepting: host.accepting,
+            preview: host.preview,
+            host: true,
+        };
+    }
+    /**
+     * This leaderboard's settings, and whether it exists and keeps its scores on
+     * the device.
+     */
+    async info() {
+        const { settings, available, local } = await this._resolve();
+        return { settings, available, local };
+    }
+    /** @internal */
+    _storageKey(preview) {
+        return `${preview ? "minimo-leaderboard-preview:" : "minimo-leaderboard:"}${this.key}`;
+    }
+    /** @internal */
+    _readLocal(preview) {
+        try {
+            const parsed = JSON.parse(readStored(this._storageKey(preview)) ?? "null");
+            if (parsed && parsed.v === 1 && parsed.periods && typeof parsed.periods === "object")
+                return parsed;
+        }
+        catch {
+            // A damaged board starts again.
+        }
+        return { v: 1, periods: {} };
+    }
+    /** @internal */
+    _writeLocal(preview, board) {
+        const periods = Object.keys(board.periods);
+        // The oldest periods go first when there are too many to keep on a device.
+        for (const period of periods.sort().slice(0, Math.max(0, periods.length - MAX_LOCAL_PERIODS))) {
+            delete board.periods[period];
+        }
+        writeStored(this._storageKey(preview), JSON.stringify(board));
+    }
+    /** @internal */
+    async _localName(settings) {
+        if (settings.names === "hidden")
+            return null;
+        if (settings.names === "assigned")
+            return assignedLocalName();
+        return (await this.playerName()) ?? NO_NAME;
+    }
+    /**
+     * Posts a score. Only the player's best score in the current period is
+     * kept, so posting every finished run is right.
+     *
+     * @param score - A finite number. Which is better, higher or lower, is the
+     *   leaderboard's setting.
+     */
+    async submit(score) {
+        const value = Number(score);
+        if (!Number.isFinite(value))
+            throw new Error("Leaderboard.submit needs a finite number");
+        const resolved = await this._resolve();
+        if (!resolved.available || !resolved.accepting) {
+            return { status: "unavailable", best: null, rank: null, period: null };
+        }
+        if (!resolved.local) {
+            const result = await request("submit", { key: this.key, score: value });
+            return { status: result.status, best: result.best ?? null, rank: result.rank ?? null, period: result.period ?? null };
+        }
+        const period = leaderboardPeriod(resolved.settings.cycle, new Date());
+        const board = this._readLocal(resolved.preview);
+        const entries = board.periods[period] ?? [];
+        const order = resolved.settings.order;
+        const previousBest = entries.length > 0 ? entries[0].score : null;
+        entries.push({ score: value, at: new Date().toISOString() });
+        entries.sort((a, b) => (order === "higher" ? b.score - a.score : a.score - b.score));
+        board.periods[period] = entries.slice(0, MAX_LOCAL_ENTRIES);
+        this._writeLocal(resolved.preview, board);
+        const best = board.periods[period][0].score;
+        const improved = previousBest === null || isBetter(order, value, previousBest);
+        const rank = rankEntries(board.periods[period].map((entry) => entry.score))[board.periods[period].findIndex((entry) => entry.score === value)] ?? null;
+        return { status: improved ? "saved" : "not_better", best, rank: improved ? 1 : rank, period };
+    }
+    /**
+     * Reads one period of the table, best score first.
+     *
+     * @param limit - How many of the best scores. Default `10`, at most `100`.
+     */
+    async top(limit = 10, options = {}) {
+        const count = Math.min(Math.max(Math.trunc(Number(limit) || 10), 1), MAX_READ);
+        const resolved = await this._resolve();
+        const base = { key: this.key, settings: resolved.settings, available: resolved.available, local: resolved.local };
+        if (!resolved.available) {
+            return { ...base, period: null, entries: [], mine: null };
+        }
+        if (!resolved.local) {
+            const table = await request("top", { key: this.key, limit: count, period: options.period ?? "current" });
+            return { ...base, period: table.period, entries: table.entries, mine: table.mine };
+        }
+        const period = resolveLeaderboardPeriod(resolved.settings.cycle, options.period, new Date());
+        if (period === null)
+            return { ...base, period: null, entries: [], mine: null };
+        const scores = (this._readLocal(resolved.preview).periods[period] ?? []).map((entry) => entry.score);
+        const ranks = rankEntries(scores);
+        const name = await this._localName(resolved.settings);
+        const entries = scores.slice(0, count).map((score, index) => ({ rank: ranks[index], name, score, mine: true }));
+        return { ...base, period, entries, mine: entries[0] ?? null };
+    }
+    /**
+     * The light user's name on this device, shared by every Minimo Games game,
+     * or `null` before the player writes one. The table asks for it on its own
+     * when a leaderboard for light users shows names.
+     */
+    async playerName() {
+        if (await connectHost()) {
+            try {
+                return cleanName((await request("getPlayerName", {})).name);
+            }
+            catch {
+                return null;
+            }
+        }
+        return cleanName(readStored("minimo-leaderboard-player-name"));
+    }
+    /** Sets the light user's name on this device. Returns it cleaned, or `null` when it is empty or too long. */
+    async setPlayerName(name) {
+        const clean = cleanName(name);
+        if (!clean)
+            return null;
+        if (await connectHost()) {
+            return cleanName((await request("setPlayerName", { name: clean })).name);
+        }
+        writeStored("minimo-leaderboard-player-name", clean);
+        return clean;
+    }
+    /**
+     * Shows the table over the game, in HTML: the best scores of a period, the
+     * player's own entry, and, for a leaderboard that resets, a switch to the
+     * previous period. Resolves when the player closes it.
+     */
+    async show(options = {}) {
+        if (typeof document === "undefined" || !document.body)
+            return;
+        this.close();
+        const resolved = await this._resolve();
+        const format = options.format ?? defaultFormat;
+        const title = options.title ?? resolved.settings.title;
+        let previous = options.period === "previous";
+        const askName = resolved.available && resolved.local && resolved.settings.names === "player";
+        let playerName = askName ? await this.playerName() : null;
+        if (!document.getElementById(STYLE_ID)) {
+            const style = document.createElement("style");
+            style.id = STYLE_ID;
+            style.textContent = STYLE;
+            document.head.appendChild(style);
+        }
+        const root = document.createElement("div");
+        root.className = "minimo-leaderboard";
+        root.style.setProperty("--mlb-bg", options.background ?? "#15151d");
+        root.style.setProperty("--mlb-fg", options.color ?? "#ffffff");
+        root.style.setProperty("--mlb-accent", options.accent ?? "#ffcc33");
+        root.style.setProperty("--mlb-font", options.font ?? 'system-ui, -apple-system, "Segoe UI", Roboto, sans-serif');
+        const canvas = this._game.getCanvasElement();
+        const place = () => {
+            const rect = canvas.getBoundingClientRect();
+            root.style.left = `${rect.left}px`;
+            root.style.top = `${rect.top}px`;
+            root.style.width = `${rect.width}px`;
+            root.style.height = `${rect.height}px`;
+            root.style.fontSize = `${Math.max(12, Math.min(22, rect.width / 22))}px`;
+        };
+        place();
+        let token = 0;
+        const render = async () => {
+            const mine = ++token;
+            const table = await this.top(options.top ?? 10, { period: previous ? "previous" : options.period && options.period !== "previous" ? options.period : "current" })
+                .catch(() => ({ key: this.key, settings: resolved.settings, period: null, entries: [], mine: null, available: false, local: resolved.local }));
+            if (mine !== token || this._overlay !== root)
+                return;
+            root.innerHTML = renderLeaderboardHtml(table, { title, previous, format, askName: askName && !previous, playerName });
+        };
+        // Keys typed into the table, such as a name, must not reach the game.
+        const stopKeys = (event) => event.stopPropagation();
+        return new Promise((resolve) => {
+            const finish = () => {
+                window.removeEventListener("resize", place);
+                root.removeEventListener("keydown", stopKeys);
+                root.removeEventListener("keyup", stopKeys);
+                root.remove();
+                if (this._overlay === root) {
+                    this._overlay = null;
+                    this._closeOverlay = null;
+                }
+                resolve();
+            };
+            const saveName = () => {
+                const input = root.querySelector("[data-name-form] input");
+                void this.setPlayerName(input?.value ?? "").then((name) => {
+                    if (name) {
+                        playerName = name;
+                        void render();
+                    }
+                });
+            };
+            root.addEventListener("keydown", (event) => {
+                if (event.key === "Escape")
+                    finish();
+                else if (event.key === "Enter" && event.target?.closest?.("[data-name-form]"))
+                    saveName();
+            });
+            root.addEventListener("keydown", stopKeys);
+            root.addEventListener("keyup", stopKeys);
+            root.addEventListener("click", (event) => {
+                const target = event.target;
+                if (target === root || target?.closest("[data-close]")) {
+                    finish();
+                    return;
+                }
+                if (target?.closest("[data-save-name]")) {
+                    saveName();
+                    return;
+                }
+                const tab = target?.closest("[data-period]");
+                if (tab) {
+                    previous = tab.getAttribute("data-period") === "previous";
+                    void render();
+                }
+            });
+            window.addEventListener("resize", place);
+            this._overlay = root;
+            this._closeOverlay = finish;
+            document.body.appendChild(root);
+            void render();
+        });
+    }
+    /** Closes the table, if it is showing. */
+    close() {
+        this._closeOverlay?.();
+    }
+    /** Closes the table. The leaderboard's scores are kept. */
+    destroy() {
+        this.close();
+    }
+}

package/dist/minimo.d.ts

@@ -2072,9 +2072,12 @@ export declare class Game {
     /**
      * Plays a square-wave beep using the Web Audio API.
      *
-     * **Square wave only.** This synthesizes a tone and needs no file. To play
-     * a recorded sound, load it with {@link Game.loadSound} and play it with
-     * {@link Game.playSound}.
+     * **Retro tone, not a game's sound.** This synthesizes a square-wave tone and
+     * needs no file, so it sounds like an old arcade machine. A game's music and
+     * sound effects are audio files: declare them as `sound` entries in an asset
+     * file, or load them with {@link Game.loadSound}, and play them with
+     * {@link Game.playSound}. Use tones only for a deliberately retro game, or
+     * when no audio file can be obtained.
      *
      * The AudioContext is created lazily on first call. Browsers require a user
      * gesture (click, keypress) before audio can play — always call `sound()` in
@@ -2092,13 +2095,16 @@ export declare class Game {
      * ```ts
      * game.sound(440, 100);   // 440 Hz beep for 100ms
      * game.sound(261, 500);   // middle C for 500ms
-     * game.sound(880, 50);    // high beep for 50ms (jump sound)
+     * game.sound(880, 50);    // high beep for 50ms
      * ```
      */
     sound(freq: number, durationMs: number): void;
     /**
      * Plays multiple square-wave tones in strict sequence.
      *
+     * Like {@link Game.sound}, this is a retro tone, not a game's sound: for
+     * music and sound effects, play audio files with {@link Game.playSound}.
+     *
      * Each tuple is `[frequencyHz, durationMs]`. The next tone starts when the
      * previous one ends.
      *

package/dist/minimo.js

@@ -2216,6 +2216,15 @@ export class Game {
     isPointerCancelled() {
         return this._inputSystem.isPointerCancelled();
     }
+    /**
+     * The canvas the game draws on, for a module in this package that lays HTML
+     * over it, as `leaderboard` does with its table. Games never need it.
+     *
+     * @internal
+     */
+    getCanvasElement() {
+        return this._canvas;
+    }
     /**
      * Returns `true` while any active pointer is held down over the target sprite.
      * Works with both mouse input and multiple simultaneous touches.
@@ -2400,9 +2409,12 @@ export class Game {
     /**
      * Plays a square-wave beep using the Web Audio API.
      *
-     * **Square wave only.** This synthesizes a tone and needs no file. To play
-     * a recorded sound, load it with {@link Game.loadSound} and play it with
-     * {@link Game.playSound}.
+     * **Retro tone, not a game's sound.** This synthesizes a square-wave tone and
+     * needs no file, so it sounds like an old arcade machine. A game's music and
+     * sound effects are audio files: declare them as `sound` entries in an asset
+     * file, or load them with {@link Game.loadSound}, and play them with
+     * {@link Game.playSound}. Use tones only for a deliberately retro game, or
+     * when no audio file can be obtained.
      *
      * The AudioContext is created lazily on first call. Browsers require a user
      * gesture (click, keypress) before audio can play — always call `sound()` in
@@ -2420,7 +2432,7 @@ export class Game {
      * ```ts
      * game.sound(440, 100);   // 440 Hz beep for 100ms
      * game.sound(261, 500);   // middle C for 500ms
-     * game.sound(880, 50);    // high beep for 50ms (jump sound)
+     * game.sound(880, 50);    // high beep for 50ms
      * ```
      */
     sound(freq, durationMs) {
@@ -2429,6 +2441,9 @@ export class Game {
     /**
      * Plays multiple square-wave tones in strict sequence.
      *
+     * Like {@link Game.sound}, this is a retro tone, not a game's sound: for
+     * music and sound effects, play audio files with {@link Game.playSound}.
+     *
      * Each tuple is `[frequencyHz, durationMs]`. The next tone starts when the
      * previous one ends.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minimojs",
-  "version": "1.0.0-alpha.33",
+  "version": "1.0.0-alpha.35",
   "description": "MinimoJS v1 — ultra-minimal, flat, deterministic 2D web game engine. Image-first sprites with emoji as a zero-asset alternative, rAF loop, TypeScript-first, LLM-friendly.",
   "type": "module",
   "main": "dist/minimo.js",