@nano133/nanoterra 0.7.0 → 0.8.0

package/dist/options/core.js

@@ -0,0 +1,420 @@
+// The options store: a game's settings as data, their defaults for this device, and the player's choices, kept in this browser. No DOM: a game with its own
+// menu reads, writes and hears the store; the kit's panel (./panel) is one view of it.
+//
+//   - A setting is a def: a toggle (on or off), a choice (one of a list), a range (a number from min to max in steps) or a key (a key binding: a
+//     `KeyboardEvent.code`). Each has a key, a label the player reads, an optional help line, a tab ("basic" or "advanced"), an optional group heading and
+//     a default.
+//   - A default is one value, or one for each device class: { phone?, tablet?, desktop?, reducedMotion?, default }. The class comes from the pointer and the
+//     screen (`detectDevice`); `reducedMotion` wins while the device asks for less motion. The device's reduced-motion setting is followed LIVE: a player
+//     who never set the option follows the device when it changes (Echo Island's draft, 2026-11-01).
+//   - Only the choices that DIFFER from this device's default are kept (localStorage, `n133-options:<game>`), so a better default later reaches every
+//     player who never touched that setting. A value that does not fit its def any more (the wrong type, out of range, an unknown choice) is dropped on
+//     read, and so is a key that no def has, unless it has a dot: a key like "emotes.show" belongs to a module's section that may be added later, so it waits.
+//   - Two key bindings never share a key: setting one to a key that another has gives the other this one's old key (a swap).
+//   - A refused storage (some private windows, a full disk) works in memory for the life of the page.
+export const DEVICE_CLASSES = ["phone", "tablet", "desktop"];
+export const OPTIONS_PREFIX = "n133-options:";
+/** The localStorage key of a game's choices. */
+export const optionsKey = (game) => `${OPTIONS_PREFIX}${game}`;
+const KEY_RE = /^[A-Za-z][A-Za-z0-9_-]*(\.[A-Za-z][A-Za-z0-9_-]*)*$/;
+const KEY_MAX = 64;
+/** A `KeyboardEvent.code`: "KeyE", "Digit1", "Space", "ArrowUp", "F5". */
+const CODE_RE = /^[A-Za-z][A-Za-z0-9]{0,23}$/;
+const REDUCE_QUERY = "(prefers-reduced-motion: reduce)";
+/** A media query; null when there is none (Node, a test). */
+function mediaQuery(query) {
+    try {
+        return typeof globalThis.matchMedia === "function" ? globalThis.matchMedia(query) : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The device class: a coarse pointer (a finger) and a short side under 600 px is a phone; a coarse pointer otherwise is a tablet; anything else is a
+ * desktop. The short side is the screen's, so turning a phone does not change it. With no matchMedia (Node), a desktop.
+ */
+export function detectDevice() {
+    if (mediaQuery("(pointer: coarse)")?.matches !== true)
+        return "desktop";
+    const g = globalThis;
+    const short = Math.min(g.screen?.width || g.innerWidth || 0, g.screen?.height || g.innerHeight || 0);
+    return short > 0 && short < 600 ? "phone" : "tablet";
+}
+/** `prefers-reduced-motion: reduce`; false where it cannot be read. */
+export const prefersReducedMotion = () => mediaQuery(REDUCE_QUERY)?.matches === true;
+const isDeviceDefault = (d) => typeof d === "object" && d !== null;
+/** The default a def has on a device class (and with reduced motion asked for or not). */
+export function resolveDefault(def, device, reducedMotion = false) {
+    const d = def.default;
+    if (!isDeviceDefault(d))
+        return d;
+    if (reducedMotion && d.reducedMotion !== undefined)
+        return d.reducedMotion;
+    return d[device] !== undefined ? d[device] : d.default;
+}
+/** The number of decimals of a number, so a snapped value is 0.3 and not 0.30000000000000004. */
+const decimals = (n) => {
+    const s = String(n);
+    const e = s.match(/e-(\d+)$/);
+    if (e)
+        return Number(e[1]);
+    const dot = s.indexOf(".");
+    return dot < 0 ? 0 : s.length - dot - 1;
+};
+/** A number on a range's nearest step from min, inside min and max. */
+export function snapToRange(def, v) {
+    const places = Math.max(decimals(def.step), decimals(def.min));
+    const steps = Math.round((Math.min(def.max, Math.max(def.min, v)) - def.min) / def.step);
+    const out = Number((def.min + steps * def.step).toFixed(places));
+    return out > def.max ? Number((out - def.step).toFixed(places)) : out;
+}
+/** The words for a `KeyboardEvent.code` on a key cap: "KeyE" is "E", "Digit1" is "1", "ArrowUp" is "↑", "ShiftLeft" is "Shift". */
+export function keyLabel(code) {
+    if (/^Key[A-Z]$/.test(code))
+        return code.slice(3);
+    if (/^Digit\d$/.test(code))
+        return code.slice(5);
+    if (/^Numpad\d$/.test(code))
+        return `Num ${code.slice(6)}`;
+    const named = {
+        ArrowUp: "↑", ArrowDown: "↓", ArrowLeft: "←", ArrowRight: "→", Escape: "Esc", Backquote: "`", Minus: "-", Equal: "=", BracketLeft: "[", BracketRight: "]",
+        Semicolon: ";", Quote: "'", Comma: ",", Period: ".", Slash: "/", Backslash: "\\", ShiftLeft: "Shift", ShiftRight: "Right Shift", ControlLeft: "Ctrl",
+        ControlRight: "Right Ctrl", AltLeft: "Alt", AltRight: "Right Alt", MetaLeft: "Cmd", MetaRight: "Right Cmd", Enter: "Enter", Space: "Space", Backspace: "Backspace", CapsLock: "Caps Lock",
+    };
+    return named[code] ?? code;
+}
+/** Whether a value fits a def as it is (a range's number must be in range; it is not snapped here). */
+function fits(def, v) {
+    if (def.kind === "toggle")
+        return typeof v === "boolean";
+    if (def.kind === "choice")
+        return (typeof v === "string" || typeof v === "number") && def.choices.some((c) => c.value === v);
+    if (def.kind === "key")
+        return typeof v === "string" && CODE_RE.test(v);
+    return typeof v === "number" && Number.isFinite(v) && v >= def.min && v <= def.max;
+}
+/** The first thing wrong with a def, as a sentence, or null. `createOptions` and `add` throw it. */
+export function defProblem(def) {
+    const d = def;
+    if (!d || typeof d !== "object")
+        return "a def must be an object";
+    const name = typeof d.key === "string" ? `"${d.key}"` : "a def";
+    if (typeof d.key !== "string" || !KEY_RE.test(d.key) || d.key.length > KEY_MAX)
+        return `${name}: the key must be letters, digits, "_" and "-", in parts joined by dots, at most ${KEY_MAX} characters`;
+    if (d.kind !== "toggle" && d.kind !== "choice" && d.kind !== "range" && d.kind !== "key")
+        return `${name}: kind must be "toggle", "choice", "range" or "key"`;
+    if (typeof d.label !== "string" || !d.label.trim())
+        return `${name}: the label is empty`;
+    if (d.help !== undefined && typeof d.help !== "string")
+        return `${name}: help must be text`;
+    if (d.tab !== "basic" && d.tab !== "advanced")
+        return `${name}: tab must be "basic" or "advanced"`;
+    if (d.group !== undefined && (typeof d.group !== "string" || !d.group.trim()))
+        return `${name}: the group is empty`;
+    if (d.devices !== undefined && (!Array.isArray(d.devices) || !d.devices.length || d.devices.some((c) => !DEVICE_CLASSES.includes(c))))
+        return `${name}: devices must list "phone", "tablet" or "desktop"`;
+    if (def.kind === "choice") {
+        if (!Array.isArray(def.choices) || def.choices.length < 2)
+            return `${name}: a choice needs two choices or more`;
+        const seen = new Set();
+        for (const c of def.choices) {
+            if (!c || (typeof c.value !== "string" && typeof c.value !== "number") || typeof c.label !== "string" || !c.label.trim())
+                return `${name}: each choice needs a value (text or a number) and a label`;
+            if (seen.has(c.value))
+                return `${name}: the choice ${JSON.stringify(c.value)} is there twice`;
+            seen.add(c.value);
+        }
+        if (def.display !== undefined && def.display !== "buttons" && def.display !== "list")
+            return `${name}: display must be "buttons" or "list"`;
+    }
+    if (def.kind === "range") {
+        if (![def.min, def.max, def.step].every((n) => typeof n === "number" && Number.isFinite(n)))
+            return `${name}: min, max and step must be numbers`;
+        if (!(def.min < def.max))
+            return `${name}: min must be under max`;
+        if (!(def.step > 0) || def.step > def.max - def.min)
+            return `${name}: the step must be above 0 and at most max - min`;
+        if (def.unit !== undefined && typeof def.unit !== "string")
+            return `${name}: the unit must be text`;
+    }
+    const dflt = d.default;
+    if (dflt === undefined)
+        return `${name}: there is no default`;
+    let values = [["default", dflt]];
+    if (isDeviceDefault(dflt)) {
+        values = Object.entries(dflt);
+        const odd = values.find(([k]) => k !== "default" && k !== "reducedMotion" && !DEVICE_CLASSES.includes(k));
+        if (odd)
+            return `${name}: a default for each device takes phone, tablet, desktop, reducedMotion and default, not "${odd[0]}"`;
+        if (!values.some(([k, v]) => k === "default" && v !== undefined))
+            return `${name}: a default for each device needs "default" too`;
+    }
+    for (const [k, v] of values) {
+        if (v === undefined)
+            continue;
+        if (!fits(def, v))
+            return `${name}: the default${k === "default" ? "" : ` for ${k}`} (${JSON.stringify(v)}) does not fit the def`;
+    }
+    return null;
+}
+/** The page's localStorage, or null where reading it throws. */
+function pageStorage() {
+    try {
+        return globalThis.localStorage ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Makes the store, reads what this browser kept for the game, and drops what does not fit. Throws for a bad def or a key that is there twice. */
+export function createOptions(init) {
+    if (typeof init?.game !== "string" || !init.game.trim())
+        throw new TypeError("createOptions: game must be the game's id");
+    const game = init.game;
+    const storage = init.storage === undefined ? pageStorage() : init.storage;
+    const detect = () => {
+        let device = "desktop";
+        let reduce = false;
+        try {
+            const d = (init.device ?? detectDevice)();
+            if (DEVICE_CLASSES.includes(d))
+                device = d;
+        }
+        catch {
+            // The detection failed: a desktop.
+        }
+        try {
+            reduce = (init.reducedMotion ?? prefersReducedMotion)() === true;
+        }
+        catch {
+            // Not known: full motion.
+        }
+        return { device, reduce };
+    };
+    let env = detect();
+    const list = [];
+    const byKey = new Map();
+    const dflt = new Map();
+    /** The player's choices that differ from the default, by key. */
+    const diff = new Map();
+    /** Kept keys with a dot whose section has not been added yet: written back as they were, and read when the section comes. */
+    let waiting = {};
+    const listeners = new Set();
+    const defListeners = new Set();
+    const defaultFor = (def) => resolveDefault(def, env.device, env.reduce);
+    const read = () => {
+        let kept = {};
+        try {
+            const raw = storage?.getItem(optionsKey(game));
+            const v = raw ? JSON.parse(raw) : null;
+            if (v && typeof v === "object" && !Array.isArray(v))
+                kept = v;
+        }
+        catch {
+            // Unreadable or not JSON: nothing was kept.
+        }
+        if (!init.migrate)
+            return kept;
+        try {
+            const out = init.migrate({ ...kept }, storage);
+            return out && typeof out === "object" && !Array.isArray(out) ? out : {};
+        }
+        catch {
+            // The migration threw: what was kept, as it was.
+            return kept;
+        }
+    };
+    const write = () => {
+        if (!storage)
+            return;
+        const out = { ...waiting };
+        for (const [k, v] of diff)
+            out[k] = v;
+        try {
+            if (Object.keys(out).length)
+                storage.setItem(optionsKey(game), JSON.stringify(out));
+            else
+                storage.removeItem(optionsKey(game));
+        }
+        catch {
+            // A full or refused storage: the choices hold for this page only.
+        }
+    };
+    /** Checks the defs (all of them, and against the store) before any is taken, so a bad one adds nothing. */
+    const take = (defs) => {
+        if (!Array.isArray(defs))
+            throw new TypeError("options: defs must be a list");
+        const fresh = new Set();
+        for (const def of defs) {
+            const p = defProblem(def);
+            if (p)
+                throw new TypeError(`options: ${p}`);
+            if (byKey.has(def.key) || fresh.has(def.key))
+                throw new Error(`options: the key "${def.key}" is there twice`);
+            fresh.add(def.key);
+        }
+        for (const def of defs) {
+            list.push(def);
+            byKey.set(def.key, def);
+            dflt.set(def.key, defaultFor(def));
+        }
+    };
+    /** Reads kept values for these keys: a value that fits and is not the default is a choice; the rest is dropped. */
+    const adopt = (kept, keys) => {
+        for (const key of keys) {
+            if (!Object.prototype.hasOwnProperty.call(kept, key))
+                continue;
+            const def = byKey.get(key);
+            let v = kept[key];
+            if (def.kind === "range" && typeof v === "number" && Number.isFinite(v) && v >= def.min && v <= def.max)
+                v = snapToRange(def, v);
+            if (fits(def, v) && v !== dflt.get(key))
+                diff.set(key, v);
+        }
+    };
+    take(init.defs ?? []);
+    const kept = read();
+    adopt(kept, byKey.keys());
+    for (const [k, v] of Object.entries(kept))
+        if (!byKey.has(k) && k.includes(".") && KEY_RE.test(k))
+            waiting[k] = v;
+    // A migration's result is written at once (the old save may be gone), and a store with values dropped on read writes the cleaner object.
+    if (init.migrate || Object.keys(kept).length !== diff.size + Object.keys(waiting).length)
+        write();
+    const need = (key) => {
+        const def = byKey.get(key);
+        if (!def)
+            throw new TypeError(`options: no setting has the key "${key}"`);
+        return def;
+    };
+    const now = (key) => (diff.has(key) ? diff.get(key) : dflt.get(key));
+    const tell = (key, value) => {
+        for (const fn of [...listeners]) {
+            try {
+                fn(key, value);
+            }
+            catch (e) {
+                // One listener's fault must not stop the others or the change: it is thrown on its own.
+                queueMicrotask(() => {
+                    throw e;
+                });
+            }
+        }
+    };
+    /** Sets the value in memory; the caller writes. */
+    const put = (key, value) => {
+        const was = now(key);
+        if (value === dflt.get(key))
+            diff.delete(key);
+        else
+            diff.set(key, value);
+        if (was !== value)
+            tell(key, value);
+    };
+    const store = {
+        game,
+        get device() {
+            return env.device;
+        },
+        get(key) {
+            need(key);
+            return now(key);
+        },
+        set(key, value) {
+            const def = need(key);
+            let v = value;
+            if (def.kind === "range") {
+                if (typeof v !== "number" || !Number.isFinite(v))
+                    throw new TypeError(`options: "${key}" takes a number`);
+                v = snapToRange(def, v);
+            }
+            if (!fits(def, v))
+                throw new TypeError(`options: ${JSON.stringify(value)} does not fit "${key}"`);
+            if (def.kind === "key") {
+                // The binding that had this key gets this one's old key, so two actions never share a key.
+                const old = now(key);
+                if (old !== v)
+                    for (const other of list)
+                        if (other.kind === "key" && other.key !== key && now(other.key) === v)
+                            put(other.key, old);
+            }
+            put(key, v);
+            write();
+        },
+        reset(key) {
+            const keys = key === undefined ? [...byKey.keys()] : [need(key).key];
+            for (const k of keys)
+                put(k, dflt.get(k));
+            write();
+        },
+        values() {
+            const out = {};
+            for (const k of byKey.keys())
+                out[k] = now(k);
+            return out;
+        },
+        defs: () => list.slice(),
+        def: (key) => byKey.get(key),
+        defaultOf(key) {
+            need(key);
+            return dflt.get(key);
+        },
+        isDefault(key) {
+            if (key === undefined)
+                return diff.size === 0;
+            need(key);
+            return !diff.has(key);
+        },
+        subscribe(fn) {
+            listeners.add(fn);
+            return () => void listeners.delete(fn);
+        },
+        subscribeDefs(fn) {
+            defListeners.add(fn);
+            return () => void defListeners.delete(fn);
+        },
+        add(defs) {
+            take(defs);
+            adopt(waiting, defs.map((d) => d.key));
+            const rest = {};
+            for (const [k, v] of Object.entries(waiting))
+                if (!byKey.has(k))
+                    rest[k] = v;
+            waiting = rest;
+            for (const fn of [...defListeners])
+                fn();
+        },
+        redetect() {
+            env = detect();
+            let wrote = false;
+            for (const def of list) {
+                const was = now(def.key);
+                dflt.set(def.key, defaultFor(def));
+                // A choice that now equals the default follows the default again.
+                if (diff.get(def.key) === dflt.get(def.key)) {
+                    diff.delete(def.key);
+                    wrote = true;
+                }
+                if (now(def.key) !== was)
+                    tell(def.key, now(def.key));
+            }
+            if (wrote)
+                write();
+        },
+    };
+    // The device's reduced-motion setting, followed live (only the kit's own reading: a game's function is read on redetect()).
+    if (!init.reducedMotion)
+        mediaQuery(REDUCE_QUERY)?.addEventListener?.("change", () => store.redetect());
+    return store;
+}
+/** A module's section: its defs with the module's name before each key ("show" in "emotes" is "emotes.show"), and its group when a def has none. */
+export function optionSection(name, defs, group) {
+    if (!KEY_RE.test(name) || name.includes("."))
+        throw new TypeError(`optionSection: "${name}" must be one part of a key (letters, digits, "_" and "-")`);
+    return defs.map((d) => ({ ...d, key: `${name}.${d.key}`, ...(group && !d.group ? { group } : {}) }));
+}
+/** A key binding def: the key `keys.<action>`, in Advanced under "Keys", shown on a desktop only (a touch screen has no keys to bind). */
+export function keyBinding(action, label, code, over = {}) {
+    return { kind: "key", key: `keys.${action}`, label, tab: "advanced", group: "Keys", default: code, devices: ["desktop"], ...over };
+}

package/dist/options/index.d.ts

@@ -0,0 +1,7 @@
+export { createOptions, defProblem, detectDevice, DEVICE_CLASSES, keyBinding, keyLabel, optionsKey, OPTIONS_PREFIX, optionSection, prefersReducedMotion, resolveDefault, snapToRange, } from "./core.js";
+export type { ChoiceDef, ChoiceValue, DeviceClass, DeviceDefault, KeyDef, OptionDef, OptionsInit, OptionsStore, OptionValue, RangeDef, Tab, ToggleDef } from "./core.js";
+export { common, COMMON_KEYS, COMMON_OPTIONS } from "./common.js";
+export type { CommonKey } from "./common.js";
+export { optionAttribute, reflectOptions } from "./reflect.js";
+export { mountOptions } from "./panel/mount.js";
+export type { MountedOptions, OptionsMountOptions } from "./panel/mount.js";

package/dist/options/index.js

@@ -0,0 +1,24 @@
+// "@nano133/nanoterra/options": a game's options (settings) as data, with their defaults for each device, kept in this browser; the common settings a game
+// opts into; and the ready panel.
+//
+//   import { createOptions, common, mountOptions } from "@nano133/nanoterra/options";
+//   import "@nano133/nanoterra/options/style.css";
+//
+//   const options = createOptions({
+//     game: "my-game",
+//     defs: [
+//       ...common("masterVolume", "musicVolume", "effectsVolume", "cameraSensitivity", "invertLook", "quality"),
+//       { kind: "toggle", key: "hints", label: "Show hints", tab: "basic", group: "Game", default: true },
+//     ],
+//   });
+//   options.get<number>("musicVolume");                         // 0 to 100
+//   options.subscribe((key, value) => apply(key, value));       // every change, from the panel or the game
+//   mountOptions(document.getElementById("options")!, options);  // the gear key and the panel
+//
+// reflectOptions(options, ["reducedMotion"]) keeps <html data-n133-opt-reduced-motion="true|false"> for the page's CSS.
+// A kit module adds its own section later: `options.add(optionSection("emotes", emoteDefs, "Emotes"))` gives the keys "emotes.<key>".
+// The store has no DOM and touches nothing at import. The panel (also on "@nano133/nanoterra/options/panel") builds its elements only when it is mounted.
+export { createOptions, defProblem, detectDevice, DEVICE_CLASSES, keyBinding, keyLabel, optionsKey, OPTIONS_PREFIX, optionSection, prefersReducedMotion, resolveDefault, snapToRange, } from "./core.js";
+export { common, COMMON_KEYS, COMMON_OPTIONS } from "./common.js";
+export { optionAttribute, reflectOptions } from "./reflect.js";
+export { mountOptions } from "./panel/mount.js";

package/dist/options/panel/index.d.ts

@@ -0,0 +1,2 @@
+export { choiceDisplay, mountOptions, PRESS_A_KEY, rangeText, RESET_QUESTION, TAB_WORDS } from "./mount.js";
+export type { MountedOptions, OptionsMountOptions } from "./mount.js";

package/dist/options/panel/index.js

@@ -0,0 +1,10 @@
+// "@nano133/nanoterra/options/panel": the Options key and panel of a game, drawn in the browser. Plain DOM, no framework, no Three.js.
+//
+//   import { createOptions, common } from "@nano133/nanoterra/options";
+//   import { mountOptions } from "@nano133/nanoterra/options/panel";
+//   import "@nano133/nanoterra/options/style.css";
+//   const options = createOptions({ game: "my-game", defs: [...common("masterVolume", "musicVolume", "quality"), myOwnDef] });
+//   const panel = mountOptions(document.getElementById("options")!, options);
+//
+// The store (../core.ts) has no DOM: a game with its own menu reads, writes and hears it without this panel.
+export { choiceDisplay, mountOptions, PRESS_A_KEY, rangeText, RESET_QUESTION, TAB_WORDS } from "./mount.js";

package/dist/options/panel/mount.d.ts

@@ -0,0 +1,30 @@
+import { type ChoiceDef, type OptionsStore, type RangeDef, type Tab } from "../core.js";
+export type OptionsMountOptions = {
+    /** The panel's heading and the key's word. Default "Options". */
+    title?: string;
+    /** Draw the Options key (a gear and the word). Default true; false for a game that calls `open()` from its own menu. */
+    key?: boolean;
+    /** Called when the panel opens and closes (a game may pause under it). */
+    onOpen?: () => void;
+    onClose?: () => void;
+    /** A slider was let go (a game plays a sound at the new level). */
+    onRangeDone?: (key: string, value: number) => void;
+    /** Asks the player a yes or no question (default: a question in the panel, with a key for each answer; never a browser dialog). */
+    confirm?: (question: string) => boolean | Promise<boolean>;
+};
+export type MountedOptions = {
+    open(): void;
+    close(): void;
+    readonly isOpen: boolean;
+    /** Removes the key and the panel and stops hearing the store. */
+    destroy(): void;
+};
+export declare const TAB_WORDS: Record<Tab, string>;
+export declare const RESET_QUESTION = "Put every option back to its default?";
+/** On a key binding while it waits for its key. */
+export declare const PRESS_A_KEY = "Press a key";
+/** "80%", "3 s", "50". */
+export declare const rangeText: (def: Pick<RangeDef, "unit">, v: number) => string;
+/** Buttons for at most 4 choices of at most 10 characters, else a list; the def's `display` wins. */
+export declare const choiceDisplay: (def: ChoiceDef) => "buttons" | "list";
+export declare function mountOptions(root: HTMLElement, store: OptionsStore, options?: OptionsMountOptions): MountedOptions;