@nano133/nanoterra 0.7.0 → 0.8.0

package/dist/friends/panel/mount.js

@@ -22,7 +22,6 @@ export function mountFriends(root, options) {
         return NOTHING;
     const n = ++mounts;
     const origin = (options.origin ?? "https://nano133.com").replace(/\/+$/, "");
-    const ask = options.confirm ?? ((q) => window.confirm(q));
     let where = options.where === undefined ? null : whereText(options.where);
     let isOpen = false;
     let destroyed = false;
@@ -34,7 +33,12 @@ export function mountFriends(root, options) {
     const title = h("h2", { class: "n133f-title", id: `n133f-title-${n}` }, "Friends");
     const closeKey = h("button", { class: "n133f-close", type: "button", "aria-label": "Close friends" }, icon("close", 20));
     const body = h("div", { class: "n133f-body" });
-    const panel = h("section", { class: `n133f-panel n133f-${options.mode}`, id: `n133f-panel-${n}`, role: "dialog", "aria-labelledby": `n133f-title-${n}`, "data-open": "false" }, h("header", { class: "n133f-head" }, title, closeKey), body);
+    const question = h("p", { class: "n133f-ask-q", id: `n133f-ask-${n}` });
+    const yesKey = h("button", { class: "n133f-btn n133f-primary", type: "button" });
+    const noKey = h("button", { class: "n133f-btn", type: "button" }, "Cancel");
+    const askBox = h("div", { class: "n133f-ask", role: "alertdialog", "aria-labelledby": `n133f-ask-${n}` }, question, h("div", { class: "n133f-ask-keys" }, yesKey, noKey));
+    askBox.hidden = true;
+    const panel = h("section", { class: `n133f-panel n133f-${options.mode}`, id: `n133f-panel-${n}`, role: "dialog", "aria-labelledby": `n133f-title-${n}`, "data-open": "false" }, h("header", { class: "n133f-head" }, title, closeKey), askBox, body);
     const wrap = h("div", { class: "n133-friends" }, key, panel);
     root.append(wrap);
     /** The requests (the thing to do) when there are any, else the friends online (another colour). The key's name says both. */
@@ -60,6 +64,7 @@ export function mountFriends(root, options) {
     const close = () => {
         if (destroyed || !isOpen)
             return;
+        answer?.(false);
         isOpen = false;
         panel.dataset.open = "false";
         key.setAttribute("aria-expanded", "false");
@@ -68,8 +73,34 @@ export function mountFriends(root, options) {
     };
     key.addEventListener("click", () => (isOpen ? close() : open()));
     closeKey.addEventListener("click", close);
+    /** The question in the panel: one at a time (a new one answers the old with no), and closing the panel answers no. */
+    let answer = null;
+    const askInPanel = (q, yesWord) => new Promise((resolve) => {
+        answer?.(false);
+        question.textContent = q;
+        yesKey.textContent = yesWord;
+        askBox.hidden = false;
+        answer = (yes) => {
+            answer = null;
+            askBox.hidden = true;
+            resolve(yes);
+            if (isOpen && !destroyed)
+                closeKey.focus();
+        };
+        open();
+        yesKey.focus();
+    });
+    yesKey.addEventListener("click", () => answer?.(true));
+    noKey.addEventListener("click", () => answer?.(false));
+    const ask = (q, yesWord) => (options.confirm ? Promise.resolve(options.confirm(q)) : askInPanel(q, yesWord));
+    cleanup.push(() => answer?.(false));
     const onKey = (e) => {
-        if (e.key === "Escape" && isOpen)
+        if (e.key !== "Escape" || !isOpen)
+            return;
+        // Escape answers an open question first, then closes the panel.
+        if (answer)
+            answer(false);
+        else
             close();
     };
     document.addEventListener("keydown", onKey);
@@ -132,12 +163,15 @@ export function mountFriends(root, options) {
             else if (m.type === "badge")
                 setBadge(m);
             else if (m.type === "join") {
-                if (!ask("Leave this game to join your friend?"))
-                    return;
-                if (options.onJoin)
-                    options.onJoin(m.url);
-                else
-                    window.location.assign(m.url);
+                const url = m.url;
+                void ask("Leave this game to join your friend?", "Join").then((yes) => {
+                    if (!yes || destroyed)
+                        return;
+                    if (options.onJoin)
+                        options.onJoin(url);
+                    else
+                        window.location.assign(url);
+                });
             }
             // "signin": the window needs a tap (Storage Access) inside itself. The panel stays as it is; the kit does nothing else.
         };
@@ -228,10 +262,10 @@ function ownList(body, options, whereNow, setBadge, ask) {
             if (p.invite && options.onJoin)
                 keys.push(btn("Join", () => options.onJoin(p.invite.where, { name: p.name }), "n133f-primary"));
             const here = whereNow();
-            if (here)
+            if (here && options.onJoin)
                 keys.push(btn("Invite", () => void act({ op: "invite", edge: p.edge, where: here }, `Invited ${p.name}.`)));
-            keys.push(btn("Remove", () => ask(`Remove ${p.name} from your friends?`) && void act({ op: "remove", edge: p.edge })));
-            keys.push(btn("Block", () => ask(`Block ${p.name}? They will not see you or be able to ask you again.`) && void act({ op: "block", edge: p.edge }), "n133f-quiet"));
+            keys.push(btn("Remove", () => void ask(`Remove ${p.name} from your friends?`, "Remove").then((yes) => (yes ? act({ op: "remove", edge: p.edge }) : undefined))));
+            keys.push(btn("Block", () => void ask(`Block ${p.name}? They will not see you or be able to ask you again.`, "Block").then((yes) => (yes ? act({ op: "block", edge: p.edge }) : undefined)), "n133f-quiet"));
         }
         if (p.state === "outgoing")
             keys.push(btn("Cancel", () => void act({ op: "decline", edge: p.edge })));

package/dist/options/common.d.ts

@@ -0,0 +1,88 @@
+import type { OptionDef, RangeDef } from "./core.js";
+export declare const COMMON_OPTIONS: {
+    /** 0 to 100 (%), every sound. A game multiplies it into the others; the square of it is a fair loudness curve (`level ** 2`). */
+    masterVolume: RangeDef;
+    /** 0 to 100 (%), the music only. */
+    musicVolume: RangeDef;
+    /** 0 to 100 (%), every sound but the music. */
+    effectsVolume: RangeDef;
+    /** 10 to 100, how fast a drag or the mouse turns the camera; 50 is the game's own speed. */
+    cameraSensitivity: {
+        kind: "range";
+        key: string;
+        label: string;
+        tab: "basic";
+        group: string;
+        min: number;
+        max: number;
+        step: number;
+        default: number;
+    };
+    /** Up and down of the camera swapped. */
+    invertLook: {
+        kind: "toggle";
+        key: string;
+        label: string;
+        help: string;
+        tab: "advanced";
+        group: string;
+        default: false;
+    };
+    /** "left" or "right": the side of a touch screen the move stick is on (the camera drag is on the other). Shown on a phone and a tablet only. */
+    stickSide: {
+        kind: "choice";
+        key: string;
+        label: string;
+        help: string;
+        tab: "basic";
+        group: string;
+        choices: {
+            value: string;
+            label: string;
+        }[];
+        default: string;
+        devices: ("phone" | "tablet")[];
+    };
+    /** Fewer shakes, swings and flashes. On by default when the device asks for less motion. */
+    reducedMotion: {
+        kind: "toggle";
+        key: string;
+        label: string;
+        help: string;
+        tab: "advanced";
+        group: string;
+        default: {
+            default: false;
+            reducedMotion: true;
+        };
+    };
+    /** "low", "medium" or "high": the game decides what each draws. Medium on a phone. */
+    quality: {
+        kind: "choice";
+        key: string;
+        label: string;
+        tab: "advanced";
+        group: string;
+        choices: {
+            value: string;
+            label: string;
+        }[];
+        default: {
+            phone: string;
+            default: string;
+        };
+    };
+    /** A small frames-a-second counter on the screen. */
+    showFps: {
+        kind: "toggle";
+        key: string;
+        label: string;
+        tab: "advanced";
+        group: string;
+        default: false;
+    };
+};
+export type CommonKey = keyof typeof COMMON_OPTIONS;
+export declare const COMMON_KEYS: CommonKey[];
+/** The common defs for these keys, in the order given (a copy: change it freely). */
+export declare function common(...keys: CommonKey[]): OptionDef[];

package/dist/options/common.js

@@ -0,0 +1,59 @@
+// The settings most games have, ready to opt into by key: `common("masterVolume", "musicVolume", "quality")`. They are plain defs: the game reads them and
+// does what they say (the kit plays no sound and draws no frame). A game changes one by spreading it: `{ ...COMMON_OPTIONS.quality, default: "low" }`.
+// The words and ranges follow nano133's island and Echo Island (Wes, 2026-10-30: Sound effects and Music sliders; the island's Settings rows).
+const volume = (key, label, help) => ({ kind: "range", key, label, ...(help ? { help } : {}), tab: "basic", group: "Sound", min: 0, max: 100, step: 5, unit: "%", default: 100 });
+export const COMMON_OPTIONS = {
+    /** 0 to 100 (%), every sound. A game multiplies it into the others; the square of it is a fair loudness curve (`level ** 2`). */
+    masterVolume: volume("masterVolume", "Volume"),
+    /** 0 to 100 (%), the music only. */
+    musicVolume: volume("musicVolume", "Music"),
+    /** 0 to 100 (%), every sound but the music. */
+    effectsVolume: volume("effectsVolume", "Sound effects"),
+    /** 10 to 100, how fast a drag or the mouse turns the camera; 50 is the game's own speed. */
+    cameraSensitivity: { kind: "range", key: "cameraSensitivity", label: "Camera speed", tab: "basic", group: "Camera", min: 10, max: 100, step: 5, default: 50 },
+    /** Up and down of the camera swapped. */
+    invertLook: { kind: "toggle", key: "invertLook", label: "Invert look", help: "Up and down are swapped", tab: "advanced", group: "Camera", default: false },
+    /** "left" or "right": the side of a touch screen the move stick is on (the camera drag is on the other). Shown on a phone and a tablet only. */
+    stickSide: {
+        kind: "choice",
+        key: "stickSide",
+        label: "Move stick",
+        help: "The side of the screen that moves you",
+        tab: "basic",
+        group: "Controls",
+        choices: [
+            { value: "left", label: "Left" },
+            { value: "right", label: "Right" },
+        ],
+        default: "left",
+        devices: ["phone", "tablet"],
+    },
+    /** Fewer shakes, swings and flashes. On by default when the device asks for less motion. */
+    reducedMotion: { kind: "toggle", key: "reducedMotion", label: "Less motion", help: "Fewer shakes, swings and flashes", tab: "advanced", group: "Comfort", default: { default: false, reducedMotion: true } },
+    /** "low", "medium" or "high": the game decides what each draws. Medium on a phone. */
+    quality: {
+        kind: "choice",
+        key: "quality",
+        label: "Quality",
+        tab: "advanced",
+        group: "Graphics",
+        choices: [
+            { value: "low", label: "Low" },
+            { value: "medium", label: "Medium" },
+            { value: "high", label: "High" },
+        ],
+        default: { phone: "medium", default: "high" },
+    },
+    /** A small frames-a-second counter on the screen. */
+    showFps: { kind: "toggle", key: "showFps", label: "Show frame rate", tab: "advanced", group: "Graphics", default: false },
+};
+export const COMMON_KEYS = Object.keys(COMMON_OPTIONS);
+/** The common defs for these keys, in the order given (a copy: change it freely). */
+export function common(...keys) {
+    return keys.map((k) => {
+        const def = COMMON_OPTIONS[k];
+        if (!def)
+            throw new TypeError(`common: "${String(k)}" is not a common setting (${COMMON_KEYS.join(", ")})`);
+        return { ...def };
+    });
+}

package/dist/options/core.d.ts

@@ -0,0 +1,130 @@
+export type Tab = "basic" | "advanced";
+export type DeviceClass = "phone" | "tablet" | "desktop";
+export declare const DEVICE_CLASSES: readonly DeviceClass[];
+/** A default for each device class. `default` is for a class left out; `reducedMotion` wins while the device asks for less motion. */
+export type DeviceDefault<V> = {
+    phone?: V;
+    tablet?: V;
+    desktop?: V;
+    reducedMotion?: V;
+    default: V;
+};
+type DefBase<V> = {
+    /** The key the game reads. Letters, digits, "_" and "-", in parts joined by dots; a module's section starts with its own name ("emotes.show"). */
+    key: string;
+    /** The words on the row: short, the player reads them ("Music", "Invert look"). */
+    label: string;
+    /** One short line under the label. */
+    help?: string;
+    tab: Tab;
+    /** The heading the row goes under, in the order the groups first appear. Rows with no group come first. */
+    group?: string;
+    default: V | DeviceDefault<V>;
+    /** Show the row only on these device classes (a stick's side means nothing with a mouse). The store keeps the value on every device. */
+    devices?: readonly DeviceClass[];
+};
+export type ToggleDef = DefBase<boolean> & {
+    kind: "toggle";
+};
+export type ChoiceValue = string | number;
+export type ChoiceDef = DefBase<ChoiceValue> & {
+    kind: "choice";
+    /** At least two, each value once. */
+    choices: readonly {
+        value: ChoiceValue;
+        label: string;
+    }[];
+    /** "buttons": a row of keys; "list": a drop-down. Left out: buttons for at most 4 short labels (10 characters), else a list. */
+    display?: "buttons" | "list";
+};
+export type RangeDef = DefBase<number> & {
+    kind: "range";
+    min: number;
+    max: number;
+    step: number;
+    /** Put after the number as written: "%" gives "80%", " s" gives "3 s". */
+    unit?: string;
+};
+/** A key binding: the value is a `KeyboardEvent.code` ("KeyE", "Space", "ArrowUp"): the key's place, the same on every keyboard layout. */
+export type KeyDef = DefBase<string> & {
+    kind: "key";
+};
+export type OptionDef = ToggleDef | ChoiceDef | RangeDef | KeyDef;
+export type OptionValue = boolean | ChoiceValue;
+type Kept = Pick<Storage, "getItem" | "setItem" | "removeItem">;
+export type OptionsInit = {
+    /** The game's id: the storage key is `n133-options:<game>`. */
+    game: string;
+    defs: readonly OptionDef[];
+    /** The device class (default: `detectDevice`). */
+    device?: () => DeviceClass;
+    /** Whether the device asks for less motion (default: `prefers-reduced-motion: reduce`, followed live). A game's own function is read at start and on `redetect()`. */
+    reducedMotion?: () => boolean;
+    /** Where the choices are kept (default: the page's localStorage). null keeps them for the life of the page only. */
+    storage?: Kept | null;
+    /**
+     * Changes what was kept before it is read: a renamed key, a new scale, or a game's old save under another key (read it from `storage` when `stored` is
+     * empty, and remove it). Gets a copy of the stored object ({} when there is none); returns the object to read. What it returns is checked like any kept value.
+     */
+    migrate?: (stored: Record<string, unknown>, storage: Kept | null) => Record<string, unknown> | null | undefined;
+};
+export type OptionsStore = {
+    readonly game: string;
+    /** The device class the defaults are resolved for. */
+    readonly device: DeviceClass;
+    /** The value now. Throws for a key no def has. */
+    get<T extends OptionValue = OptionValue>(key: string): T;
+    /**
+     * Sets a value, keeps it (only if it differs from the default) and tells the listeners. A range's number is put on its nearest step inside min and max;
+     * a key binding that another binding has swaps with it. Throws a TypeError for an unknown key, a value of the wrong type, a number that is not finite,
+     * an unknown choice and a key binding that is not a `KeyboardEvent.code`.
+     */
+    set(key: string, value: OptionValue): void;
+    /** One setting back to its default; with no key, every setting. */
+    reset(key?: string): void;
+    /** Every value now, by key (a copy). */
+    values(): Record<string, OptionValue>;
+    /** The defs, in order (the game's first, then each section in the order it was added). */
+    defs(): readonly OptionDef[];
+    /** The def of a key, or undefined. */
+    def(key: string): OptionDef | undefined;
+    /** This device's default for a key now. Throws for a key no def has. */
+    defaultOf(key: string): OptionValue;
+    /** True when the key (or, with no key, every setting) is at its default. */
+    isDefault(key?: string): boolean;
+    /** Hears each change of a value (set, reset, a default that moved): the key and the new value. Returns the call that stops it. */
+    subscribe(fn: (key: string, value: OptionValue) => void): () => void;
+    /** Hears each add(): a panel draws the new rows. Returns the call that stops it. */
+    subscribeDefs(fn: () => void): () => void;
+    /** Adds defs later (a module's section). A key that is already there throws, and nothing is added. */
+    add(defs: readonly OptionDef[]): void;
+    /** Reads the device class and reduced motion again and moves the defaults: a setting the player never changed follows, and its listeners hear it. */
+    redetect(): void;
+};
+export declare const OPTIONS_PREFIX = "n133-options:";
+/** The localStorage key of a game's choices. */
+export declare const optionsKey: (game: string) => string;
+/**
+ * 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 declare function detectDevice(): DeviceClass;
+/** `prefers-reduced-motion: reduce`; false where it cannot be read. */
+export declare const prefersReducedMotion: () => boolean;
+/** The default a def has on a device class (and with reduced motion asked for or not). */
+export declare function resolveDefault<V extends OptionValue>(def: {
+    default: V | DeviceDefault<V>;
+}, device: DeviceClass, reducedMotion?: boolean): V;
+/** A number on a range's nearest step from min, inside min and max. */
+export declare function snapToRange(def: Pick<RangeDef, "min" | "max" | "step">, v: number): number;
+/** The words for a `KeyboardEvent.code` on a key cap: "KeyE" is "E", "Digit1" is "1", "ArrowUp" is "↑", "ShiftLeft" is "Shift". */
+export declare function keyLabel(code: string): string;
+/** The first thing wrong with a def, as a sentence, or null. `createOptions` and `add` throw it. */
+export declare function defProblem(def: OptionDef): string | 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 declare function createOptions(init: OptionsInit): OptionsStore;
+/** 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 declare function optionSection(name: string, defs: readonly OptionDef[], group?: string): OptionDef[];
+/** 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 declare function keyBinding(action: string, label: string, code: string, over?: Partial<Omit<KeyDef, "kind">>): KeyDef;
+export {};