@nano133/nanoterra 0.7.1 → 0.8.1

package/dist/emotes/wheel.d.ts

@@ -0,0 +1,42 @@
+export declare const WHEEL_SLOTS = 8;
+/** The localStorage key of a game's wheel. */
+export declare const wheelKey: (game: string) => string;
+/** A wheel: eight places, each an emote's id once, or null (empty). */
+export type Slots = readonly (string | null)[];
+/** Nanoterra's wheel before the player changes it (the island's): the eight most social emotes. Bow, Shrug and Facepalm wait in Edit. */
+export declare const DEFAULT_WHEEL: Slots;
+/** What the player is told when they put a ninth emote on the wheel. */
+export declare const WHEEL_FULL = "Your wheel is full. Take one off first.";
+/** The first wheel for a list of emotes: `defaults` when given (each id of the list once), else the island's wheel for Nanoterra's list, else the list's first eight. */
+export declare function defaultWheel(ids: readonly string[], defaults?: readonly (string | null)[]): Slots;
+/** A kept wheel: eight places, each an emote of `ids` once or empty. Anything else (no key, broken text, another length) is `fallback`. */
+export declare function readWheel(raw: string | null | undefined, ids: readonly string[], fallback: Slots): Slots;
+/** The emote put on (in the first empty place), taken off, or refused because all eight places are full. */
+export declare function toggleSlot(slots: Slots, id: string): {
+    slots: Slots;
+    did: "added" | "removed" | "full";
+};
+type Store = Pick<Storage, "getItem" | "setItem">;
+export type WheelOptions = {
+    /** The game's id: each game keeps its own wheel. */
+    game: string;
+    /** Every emote the player may put on the wheel, by id. Default: Nanoterra's eleven. */
+    ids?: readonly string[];
+    /** The eight places before the player changes them. Default: see `defaultWheel`. */
+    defaults?: readonly (string | null)[];
+    /** Where the wheel is kept (default: the page's localStorage). null keeps it only for the life of the page. */
+    storage?: Store | null;
+};
+export type Wheel = {
+    /** The eight places now. */
+    readonly slots: Slots;
+    /** Puts an emote on (its first empty place) or takes it off; "full" changes nothing. */
+    toggle(id: string): "added" | "removed" | "full";
+    /** Takes the emote off a place. */
+    clear(slot: number): void;
+    /** Hears every change. Returns the call that stops it. */
+    subscribe(listen: (slots: Slots) => void): () => void;
+};
+/** A game's wheel, read from this browser (or the default), and kept there on each change. */
+export declare function createWheel(options: WheelOptions): Wheel;
+export {};

package/dist/emotes/wheel.js

@@ -0,0 +1,110 @@
+// The player's emote wheel: eight places round the wheel, slot 1 at the top and on clockwise, each an emote or empty. The player picks which emotes sit
+// there from every emote the game offers (Edit in the panel), so the list can grow past eight. Kept in this browser per game, under `n133-emotes:<game>`;
+// a browser with nothing kept, or a storage that is refused (some private windows), has the game's default wheel and keeps changes for the page's life.
+// No DOM and no Three.js here: the panel (./panel) draws it.
+import { EMOTES } from "./list.js";
+export const WHEEL_SLOTS = 8;
+/** The localStorage key of a game's wheel. */
+export const wheelKey = (game) => `n133-emotes:${game}`;
+/** Nanoterra's wheel before the player changes it (the island's): the eight most social emotes. Bow, Shrug and Facepalm wait in Edit. */
+export const DEFAULT_WHEEL = ["wave", "cheer", "clap", "dance", "laugh", "point", "sit", "spin"];
+/** What the player is told when they put a ninth emote on the wheel. */
+export const WHEEL_FULL = "Your wheel is full. Take one off first.";
+/** Eight places from a list (cut, or filled with empty places), each id of `known` once. */
+function fit(list, known) {
+    const seen = new Set();
+    return Array.from({ length: WHEEL_SLOTS }, (_, i) => {
+        const x = list[i];
+        if (typeof x !== "string" || !known.has(x) || seen.has(x))
+            return null;
+        seen.add(x);
+        return x;
+    });
+}
+/** The first wheel for a list of emotes: `defaults` when given (each id of the list once), else the island's wheel for Nanoterra's list, else the list's first eight. */
+export function defaultWheel(ids, defaults) {
+    const known = new Set(ids);
+    if (defaults)
+        return fit(defaults, known);
+    const island = fit(DEFAULT_WHEEL, known);
+    return island.some((x) => x !== null) ? island : fit(ids, known);
+}
+/** A kept wheel: eight places, each an emote of `ids` once or empty. Anything else (no key, broken text, another length) is `fallback`. */
+export function readWheel(raw, ids, fallback) {
+    if (!raw)
+        return fallback;
+    try {
+        const v = JSON.parse(raw);
+        if (!Array.isArray(v) || v.length !== WHEEL_SLOTS)
+            return fallback;
+        return fit(v, new Set(ids));
+    }
+    catch {
+        return fallback;
+    }
+}
+/** The emote put on (in the first empty place), taken off, or refused because all eight places are full. */
+export function toggleSlot(slots, id) {
+    const at = slots.indexOf(id);
+    if (at >= 0)
+        return { slots: slots.map((x, i) => (i === at ? null : x)), did: "removed" };
+    const free = slots.indexOf(null);
+    if (free < 0)
+        return { slots, did: "full" };
+    return { slots: slots.map((x, i) => (i === free ? id : x)), did: "added" };
+}
+/** The page's localStorage, or null where reading it throws. */
+function pageStorage() {
+    try {
+        return globalThis.localStorage ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/** A game's wheel, read from this browser (or the default), and kept there on each change. */
+export function createWheel(options) {
+    const ids = options.ids ?? EMOTES.map((e) => e.id);
+    const storage = options.storage === undefined ? pageStorage() : options.storage;
+    const key = wheelKey(options.game);
+    let raw = null;
+    try {
+        raw = storage?.getItem(key) ?? null;
+    }
+    catch {
+        raw = null;
+    }
+    let slots = readWheel(raw, ids, defaultWheel(ids, options.defaults));
+    const listeners = new Set();
+    const set = (next) => {
+        slots = next;
+        try {
+            storage?.setItem(key, JSON.stringify(next));
+        }
+        catch {
+            // A full or refused storage: the wheel still works for this page.
+        }
+        for (const l of listeners)
+            l(slots);
+    };
+    return {
+        get slots() {
+            return slots;
+        },
+        toggle(id) {
+            const r = toggleSlot(slots, id);
+            if (r.did !== "full")
+                set(r.slots);
+            return r.did;
+        },
+        clear(slot) {
+            if (slots[slot] == null)
+                return;
+            set(slots.map((x, i) => (i === slot ? null : x)));
+        },
+        subscribe(listen) {
+            listeners.add(listen);
+            return () => listeners.delete(listen);
+        },
+    };
+}

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

@@ -21,6 +21,11 @@ export type FriendsMountOptions = {
     fetch?: typeof fetch;
     /** 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>;
+    /**
+     * Where the keyboard focus goes when the panel closes. "game" (the default): out of the key and the panel, to the page, so Space and the game's
+     * other keys reach the game again (a focused key would take Space and open the panel again). "key": back to the key, for a page with no keys of its own.
+     */
+    focusAfterClose?: "game" | "key";
 };
 export type MountedFriends = {
     /** Sets where the player is (friends see it). Null: no place. */

package/dist/friends/panel/mount.js

@@ -11,7 +11,7 @@
 //
 // The panel is phone first: a sheet from the bottom on a phone held upright, from the side on a wide or sideways screen; every key is 44 px.
 import { ApiError, createApi } from "../../admin/panel/api.js";
-import { h } from "../../admin/panel/dom.js";
+import { h, releaseFocus } from "../../admin/panel/dom.js";
 import { icon } from "../../admin/panel/icons.js";
 import { readWindowMessage, toWindow, whereText, windowUrl } from "./window.js";
 export const FRIENDS_TIMING = { viewOpenMs: 20_000, viewClosedMs: 60_000, pulseMs: 45_000 };
@@ -69,7 +69,10 @@ export function mountFriends(root, options) {
         panel.dataset.open = "false";
         key.setAttribute("aria-expanded", "false");
         onClose();
-        key.focus();
+        if (options.focusAfterClose === "key")
+            key.focus();
+        else
+            releaseFocus(wrap);
     };
     key.addEventListener("click", () => (isOpen ? close() : open()));
     closeKey.addEventListener("click", close);

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 {};