@nano133/nanoterra 0.7.0 → 0.8.0

package/dist/emotes/panel/mount.js

@@ -0,0 +1,360 @@
+// The Emotes key and the emote wheel of a game: `mountEmotes(element, options)`. Plain DOM, no framework, no Three.js: nano133.com's EmoteKeys.tsx and
+// EmoteWheel.tsx (Nano Island), for any game. The key goes into `element`; it opens the wheel in the middle of the screen over a dim page: eight round
+// places on a ring, slot 1 at the top and on clockwise, each the emote's picture and name, and a middle disc with the name of the place under the
+// finger and Edit. Two ways with a finger or a mouse: a tap on the key opens the wheel and a tap on a place plays it; or a hold on the key opens it at
+// once, and sliding onto a place and letting go plays that one (a slide under 14 px is a tap, a let-go in the middle leaves the wheel open). A press
+// beside the wheel, Escape or the key closes it. On a keyboard B opens and closes it (not while a field has the keys, or when the game's `keyAllowed`
+// says no) and 1 to 8 play its places while it is open. Edit shows every emote: a tap puts one on the wheel in its first empty place or takes it off,
+// and a ninth is refused with WHEEL_FULL; in Edit a tap on a place takes its emote off.
+//
+// The list is Nanoterra's (each id names one of EMOTES: its name and picture come from the kit), the game's own ({ id, label, icon }), or both. The
+// wheel only calls `onPlay(id)`: the game plays it (Nanoterra's on the kit's character: createEmotes(...).play, from "@nano133/nanoterra/emotes/player").
+import { h } from "../../admin/panel/dom.js";
+import { icon } from "../../admin/panel/icons.js";
+import { EMOTE_ICONS_URL } from "../icons.js";
+import { EMOTES, emoteOf, isEmote } from "../list.js";
+import { readEmoteOptions } from "../options.js";
+import { WHEEL_FULL, WHEEL_SLOTS, createWheel } from "../wheel.js";
+/** How far a finger moves on the key before it is a slide, not a tap (CSS pixels). */
+export const SLIDE_PX = 14;
+const NOTHING = { open() { }, close() { }, isOpen: false, slots: [], destroy() { } };
+/** Each place's direction from the middle: slot 1 at the top, then clockwise. */
+const AT = Array.from({ length: WHEEL_SLOTS }, (_, i) => {
+    const a = ((-90 + i * (360 / WHEEL_SLOTS)) * Math.PI) / 180;
+    return { x: Math.cos(a), y: Math.sin(a) };
+});
+const DIGITS = Object.fromEntries(Array.from({ length: WHEEL_SLOTS }, (_, i) => [
+    [`Digit${i + 1}`, i],
+    [`Numpad${i + 1}`, i],
+]).flat());
+/** A key that a field, or a page's own editable text, is holding. */
+const inField = (t) => {
+    const el = t;
+    return !!el && (["INPUT", "SELECT", "TEXTAREA"].includes(el.tagName) || el.isContentEditable === true);
+};
+/** The place under a point of the screen, by its angle from the wheel's middle, outside the middle disc; null in the middle or with no wheel. */
+export function placeAt(rect, x, y) {
+    if (!rect || !rect.width)
+        return null;
+    const dx = x - (rect.left + rect.width / 2);
+    const dy = y - (rect.top + rect.height / 2);
+    if (Math.hypot(dx, dy) < rect.width * 0.2)
+        return null;
+    const turn = (Math.atan2(dy, dx) * 180) / Math.PI + 90;
+    return ((Math.round(turn / (360 / WHEEL_SLOTS)) % WHEEL_SLOTS) + WHEEL_SLOTS) % WHEEL_SLOTS;
+}
+let mounts = 0;
+export function mountEmotes(root, options) {
+    const nanoOn = options.nanoterraEmotes !== "off";
+    const list = [];
+    for (const e of options.emotes ?? EMOTES.map((x) => x.id)) {
+        if (typeof e === "string") {
+            if (nanoOn && isEmote(e))
+                list.push({ id: e, label: emoteOf(e).label, sheet: EMOTES.findIndex((x) => x.id === e), icon: null });
+        }
+        else if (e && typeof e.id === "string" && typeof e.label === "string")
+            list.push({ id: e.id, label: e.label, sheet: -1, icon: typeof e.icon === "string" ? e.icon : null });
+    }
+    // Each id once: the first wins.
+    const items = list.filter((x, i) => list.findIndex((y) => y.id === x.id) === i);
+    if (!items.length)
+        return NOTHING;
+    const byId = new Map(items.map((x) => [x.id, x]));
+    const n = ++mounts;
+    const sheet = options.icons ?? EMOTE_ICONS_URL;
+    const wheel = createWheel({ game: options.game, ids: items.map((x) => x.id), defaults: options.defaults, storage: options.storage });
+    const keys = options.keys !== false;
+    let isOpen = false;
+    let edit = false;
+    let full = false;
+    let hover = null;
+    let mouse = null;
+    let destroyed = false;
+    const cleanup = [];
+    /** An emote's picture: its cell of the strip, or the game's own picture; nothing when it has none. */
+    const picture = (id, cls) => {
+        const it = byId.get(id);
+        if (!it)
+            return null;
+        if (it.sheet >= 0) {
+            const count = EMOTES.length;
+            const el = h("span", { class: cls, "aria-hidden": "true" });
+            el.style.backgroundImage = `url("${sheet}")`;
+            el.style.backgroundSize = `${count * 100}% 100%`;
+            el.style.backgroundPosition = `${(it.sheet / (count - 1)) * 100}% 0`;
+            return el;
+        }
+        if (!it.icon)
+            return null;
+        const el = h("span", { class: `${cls} is-own`, "aria-hidden": "true" });
+        el.style.backgroundImage = `url("${it.icon.replace(/["\\\n\r]/g, "")}")`;
+        return el;
+    };
+    const labelOf = (id) => byId.get(id)?.label ?? id;
+    const key = h("button", { class: "n133e-key", type: "button", "aria-expanded": "false", "aria-haspopup": "dialog", "aria-controls": `n133e-wheel-${n}` }, icon("smile", 20), h("span", {}, "Emotes"));
+    const hubName = h("span", { class: "n133e-hub-name", "aria-live": "polite" });
+    const editKey = h("button", { class: "n133e-edit", type: "button", "aria-pressed": "false" }, "Edit");
+    const slotKeys = AT.map((p, i) => {
+        const b = h("button", { class: "n133e-slot", type: "button", "data-slot": i });
+        b.style.setProperty("--x", String(p.x));
+        b.style.setProperty("--y", String(p.y));
+        b.addEventListener("pointerenter", () => {
+            mouse = i;
+            drawLit();
+        });
+        b.addEventListener("pointerleave", () => {
+            if (mouse === i)
+                mouse = null;
+            drawLit();
+        });
+        b.addEventListener("click", () => pick(i));
+        return b;
+    });
+    const ring = h("div", { class: "n133e-wheel", id: `n133e-wheel-${n}`, role: "dialog", "aria-label": "Emotes" }, h("div", { class: "n133e-ring", "aria-hidden": "true" }), ...slotKeys, h("div", { class: "n133e-hub" }, hubName, editKey));
+    const fullLine = h("p", { class: "n133e-list-line", "aria-live": "polite" });
+    const grid = h("div", { class: "n133e-grid" });
+    const editList = h("div", { class: "n133e-list", role: "group", "aria-label": "All emotes" }, fullLine, grid);
+    const layer = h("div", { class: "n133e-layer", "data-open": "false" }, ring, editList);
+    layer.hidden = true;
+    const wrap = h("div", { class: "n133-emotes" }, key, layer);
+    root.append(wrap);
+    // The theme: the game's word, or the page's (data-n133-theme, which the admin panel sets too), or the device's setting.
+    let media = null;
+    try {
+        media = typeof globalThis.matchMedia === "function" ? globalThis.matchMedia("(prefers-color-scheme: dark)") : null;
+    }
+    catch {
+        media = null;
+    }
+    const drawTheme = () => {
+        const want = options.theme ?? "device";
+        const page = globalThis.document?.documentElement?.getAttribute("data-n133-theme");
+        const dark = want === "device" ? (page === "dark" || page === "light" ? page === "dark" : media?.matches === true) : want === "dark";
+        wrap.setAttribute("data-theme", dark ? "dark" : "light");
+    };
+    drawTheme();
+    media?.addEventListener?.("change", drawTheme);
+    cleanup.push(() => media?.removeEventListener?.("change", drawTheme));
+    // The options: `emotes.show` off hides the key; `keys.emotes` is the key that opens the wheel (B unless the player changed it).
+    let openCode = "KeyB";
+    const drawShow = () => {
+        const o = readEmoteOptions(options.options);
+        key.hidden = !o.show;
+        openCode = o.key;
+        if (keys)
+            key.setAttribute("aria-keyshortcuts", openCode.replace(/^(Key|Digit)/, ""));
+    };
+    drawShow();
+    const unOptions = options.options?.subscribe?.((k) => {
+        if (k === "emotes.show" || k === "keys.emotes")
+            drawShow();
+    });
+    if (unOptions)
+        cleanup.push(unOptions);
+    function drawLit() {
+        const lit = hover ?? mouse;
+        const slots = wheel.slots;
+        slotKeys.forEach((b, i) => b.classList.toggle("is-lit", lit === i && slots[i] !== null));
+        const id = lit !== null ? slots[lit] : null;
+        hubName.textContent = id ? labelOf(id) : edit ? "Your wheel" : "Emotes";
+    }
+    function drawSlots() {
+        const slots = wheel.slots;
+        slotKeys.forEach((b, i) => {
+            const id = slots[i];
+            b.classList.toggle("is-empty", !id);
+            b.setAttribute("aria-label", id ? (edit ? `Take ${labelOf(id)} off the wheel` : labelOf(id)) : edit ? "Empty place" : "Empty place: edit the wheel");
+            if (id && !edit && keys)
+                b.setAttribute("aria-keyshortcuts", String(i + 1));
+            else
+                b.removeAttribute("aria-keyshortcuts");
+            b.replaceChildren(...(id
+                ? [picture(id, "n133e-pic") ?? "", h("span", { class: "n133e-name" }, labelOf(id)), !edit && keys ? h("span", { class: "n133e-num", "aria-hidden": "true" }, String(i + 1)) : "", edit ? h("span", { class: "n133e-off", "aria-hidden": "true" }, "×") : ""]
+                : [h("span", { class: "n133e-plus", "aria-hidden": "true" }, "+")]));
+        });
+        layer.classList.toggle("is-edit", edit);
+        editKey.textContent = edit ? "Done" : "Edit";
+        editKey.setAttribute("aria-pressed", String(edit));
+        editList.hidden = !edit;
+        fullLine.textContent = full ? WHEEL_FULL : `Tap to put on the wheel or take off. Up to ${WHEEL_SLOTS}.`;
+        fullLine.classList.toggle("is-full", full);
+        if (edit) {
+            grid.replaceChildren(...items.map((it) => {
+                const at = slots.indexOf(it.id);
+                return h("button", { class: `n133e-tile${at >= 0 ? " is-on" : ""}`, type: "button", "aria-pressed": String(at >= 0), "data-emote": it.id, onclick: () => tap(it.id) }, picture(it.id, "n133e-tile-pic") ?? h("span", { class: "n133e-tile-pic is-blank", "aria-hidden": "true" }), h("span", { class: "n133e-tile-name" }, it.label), at >= 0 ? h("span", { class: "n133e-badge", "aria-label": `place ${at + 1}` }, String(at + 1)) : null);
+            }));
+        }
+        drawLit();
+    }
+    const unWheel = wheel.subscribe(drawSlots);
+    cleanup.push(unWheel);
+    function tap(id) {
+        full = wheel.toggle(id) === "full";
+        drawSlots();
+        // The tile that was pressed keeps the focus after the grid is drawn again.
+        for (const el of Array.from(grid.children))
+            if (el.dataset.emote === id)
+                el.focus();
+    }
+    function play(id) {
+        close(false);
+        options.onPlay(id);
+    }
+    function pick(i) {
+        const id = wheel.slots[i];
+        if (edit) {
+            if (id)
+                wheel.clear(i);
+            full = false;
+            drawSlots();
+            return;
+        }
+        if (!id) {
+            edit = true;
+            drawSlots();
+            return;
+        }
+        play(id);
+    }
+    function open(focusFirst = false) {
+        if (destroyed || isOpen)
+            return;
+        isOpen = true;
+        edit = false;
+        full = false;
+        hover = null;
+        mouse = null;
+        drawTheme();
+        drawSlots();
+        layer.hidden = false;
+        layer.dataset.open = "true";
+        key.setAttribute("aria-expanded", "true");
+        options.onOpen?.();
+        if (focusFirst)
+            slotKeys[Math.max(0, wheel.slots.findIndex((x) => x !== null))].focus();
+    }
+    function close(focusKey) {
+        if (destroyed || !isOpen)
+            return;
+        isOpen = false;
+        hover = null;
+        press = null;
+        layer.hidden = true;
+        layer.dataset.open = "false";
+        key.setAttribute("aria-expanded", "false");
+        if (focusKey && !key.hidden)
+            key.focus();
+    }
+    editKey.addEventListener("click", () => {
+        edit = !edit;
+        full = false;
+        drawSlots();
+    });
+    // A press on the dim page beside the wheel closes it.
+    layer.addEventListener("pointerdown", (e) => {
+        if (e.target === layer)
+            close(false);
+    });
+    // The key: a press opens the wheel at once; a slide from it onto a place and a let-go plays that place.
+    let press = null;
+    key.addEventListener("pointerdown", (e) => {
+        if (e.button !== 0 || isOpen)
+            return;
+        open();
+        press = { id: e.pointerId, x: e.clientX, y: e.clientY, slid: false };
+        try {
+            key.setPointerCapture(e.pointerId);
+        }
+        catch {
+            // A pointer that is already gone: the wheel stays open for a tap.
+        }
+    });
+    key.addEventListener("pointermove", (e) => {
+        const p = press;
+        if (!p || p.id !== e.pointerId)
+            return;
+        if (!p.slid && Math.hypot(e.clientX - p.x, e.clientY - p.y) > SLIDE_PX)
+            p.slid = true;
+        if (p.slid) {
+            hover = placeAt(ring.getBoundingClientRect(), e.clientX, e.clientY);
+            drawLit();
+        }
+    });
+    key.addEventListener("pointerup", (e) => {
+        const p = press;
+        press = null;
+        if (!p || !p.slid || p.id !== e.pointerId)
+            return;
+        const i = placeAt(ring.getBoundingClientRect(), e.clientX, e.clientY);
+        const id = i === null ? null : wheel.slots[i];
+        if (id)
+            play(id);
+        else {
+            hover = null;
+            drawLit();
+        }
+    });
+    key.addEventListener("pointercancel", () => {
+        press = null;
+        hover = null;
+        drawLit();
+    });
+    // Enter or Space is a click with no pointer: it opens and closes the wheel. A pointer's click is already handled.
+    key.addEventListener("click", (e) => {
+        if (e.detail !== 0)
+            return;
+        if (isOpen)
+            close(true);
+        else
+            open(true);
+    });
+    const onKey = (e) => {
+        if (destroyed)
+            return;
+        if (e.key === "Escape" && isOpen) {
+            e.preventDefault();
+            close(true);
+            return;
+        }
+        if (!keys || e.repeat || e.ctrlKey || e.metaKey || e.altKey || inField(e.target))
+            return;
+        if (e.code === openCode) {
+            if (options.keyAllowed && !options.keyAllowed(e))
+                return;
+            e.preventDefault();
+            if (isOpen)
+                close(true);
+            else
+                open(true);
+            return;
+        }
+        const i = DIGITS[e.code];
+        if (i === undefined || !isOpen || edit)
+            return;
+        const id = wheel.slots[i];
+        if (!id)
+            return;
+        e.preventDefault();
+        play(id);
+    };
+    document.addEventListener("keydown", onKey);
+    cleanup.push(() => document.removeEventListener("keydown", onKey));
+    return {
+        open: () => open(false),
+        close: () => close(false),
+        get isOpen() {
+            return isOpen;
+        },
+        get slots() {
+            return wheel.slots;
+        },
+        destroy() {
+            if (destroyed)
+                return;
+            destroyed = true;
+            for (const f of cleanup)
+                f();
+            wrap.remove();
+        },
+    };
+}

package/dist/emotes/player.d.ts

@@ -0,0 +1,37 @@
+import type { Character } from "../character/create.js";
+import { type EmoteEvent, type EmoteStop } from "./events.js";
+import { type EmoteOptionsStore } from "./options.js";
+export { emoteClip, emotesLoaded, loadEmotes, FADE_END, FADE_IN, FADE_STOP } from "./clip.js";
+export type EmotesOptions = {
+    /** The player played an emote (and again every 10 s while a loop plays): send `emoteMessage(e)` to the other players. */
+    onEmote?: (e: EmoteEvent) => void;
+    /** The player's clip ended: its end, a move, the water or `stop`. Nothing to send for a move (the others see it); see the README for `stop`. */
+    onStop?: (e: EmoteStop) => void;
+};
+export type LocalEmotes = {
+    /** Plays a Nanoterra emote on the player's character (the wheel's onPlay). False, and nothing happens, for an id that is not one. */
+    play(id: string): boolean;
+    /** Stops the player's clip, with its fade. A game with water calls it when the character goes in. */
+    stop(): void;
+    /** The clip on show, or null (the Wave is not a clip: it is never here). */
+    readonly playing: string | null;
+    /** Stops listening (`onEmote`, `onStop`). The character keeps playing what it plays. */
+    destroy(): void;
+};
+/** The local player's emotes on their character, with the events a multiplayer game sends on. */
+export declare function createEmotes(character: Character, options?: EmotesOptions): LocalEmotes;
+/** Another player's emote: its id, and when it came (performance.now(); left out: now). */
+export type RemotePlay = {
+    id: unknown;
+    at?: number;
+};
+/**
+ * Plays another player's emote on their character (from the game's network). An id that is not a Nanoterra emote is ignored (false). The same play
+ * given again (the same `at`) is ignored, so a game may pass the last one every frame; a loop that is on show goes on through a repeat. With an
+ * options store whose `emotes.others` is off, nothing plays.
+ */
+export declare function playRemote(character: Character, play: RemotePlay, opts?: {
+    options?: EmoteOptionsStore | null;
+}): boolean;
+/** Stops a character's clip with its fade (a remote player's, when the game hears a stop, or any character that goes into water). */
+export declare function stopEmote(character: Character): void;

package/dist/emotes/player.js

@@ -0,0 +1,101 @@
+// "@nano133/nanoterra/emotes/player": Nanoterra's emotes on the kit's character (createCharacter of "@nano133/nanoterra/character"). Three.js, as the
+// character is. A clip plays as a layer over the character's pose (../character/layer.ts), so the game calls nothing new each frame: its usual
+// `character.update(dt, motion)` plays the emote too, after the walk and before the tail, the wings and the long hair.
+//
+//   const emotes = createEmotes(hero, { onEmote: (e) => send(emoteMessage(e)) }); // the local player
+//   emotes.play("dance");                                                          // from the wheel's onPlay
+//   playRemote(other, { id: msg.emote });                                          // another player's emote, from your network
+//
+// The Wave is the character's own `wave()`; the ten others are clips, which load on the first emote (`loadEmotes`, one chunk of their own).
+import { setPoseLayer } from "../character/layer.js";
+import { newRun, startClip, stepClip, stopClip } from "./clip.js";
+import { LOOP_AGAIN_MS } from "./events.js";
+import { emoteOf, isEmote } from "./list.js";
+import { readEmoteOptions } from "./options.js";
+export { emoteClip, emotesLoaded, loadEmotes, FADE_END, FADE_IN, FADE_STOP } from "./clip.js";
+/** How fast a character must go before a full clip stops (m/s, the pose's eased speed): the island's. */
+const MOVING = 0.4;
+const states = new WeakMap();
+const now = () => (typeof performance !== "undefined" ? performance.now() : Date.now());
+/** The character's state, and its layer, made on its first emote. */
+function stateOf(character) {
+    let st = states.get(character);
+    if (st)
+        return st;
+    const s = { run: newRun(), seen: Number.NaN, sent: 0, local: null };
+    setPoseLayer(character, (bones, f) => {
+        const was = s.run.id;
+        stepClip(s.run, bones, { dt: f.dt, moving: f.speed > MOVING, air: f.airborne, swim: false, calm: f.reducedMotion });
+        if (!s.local)
+            return;
+        if (was && !s.run.id && s.run.ended)
+            s.local.onStop?.({ id: was, at: now(), why: s.run.ended });
+        else if (s.run.id && emoteOf(s.run.id)?.loop && s.run.stopAge < 0 && s.run.age - s.sent >= LOOP_AGAIN_MS / 1000) {
+            // A loop is sent again while it plays, so a player who comes later sees it.
+            s.sent = s.run.age;
+            s.local.onEmote?.({ id: s.run.id, loop: true, at: now(), again: true });
+        }
+    });
+    states.set(character, s);
+    st = s;
+    return st;
+}
+/** Plays a Nanoterra emote on a character: the Wave is its own `wave()`, the others start a clip. False for an id that is not one. */
+function start(character, id, age = 0) {
+    if (!isEmote(id))
+        return false;
+    if (id === "wave") {
+        character.wave();
+        return true;
+    }
+    const st = stateOf(character);
+    startClip(st.run, id, age);
+    return true;
+}
+/** The local player's emotes on their character, with the events a multiplayer game sends on. */
+export function createEmotes(character, options = {}) {
+    const st = stateOf(character);
+    st.local = options;
+    return {
+        play(id) {
+            if (!start(character, id))
+                return false;
+            st.sent = 0;
+            options.onEmote?.({ id, loop: emoteOf(id)?.loop === true, at: now(), again: false });
+            return true;
+        },
+        stop() {
+            stopClip(st.run);
+        },
+        get playing() {
+            return st.run.id;
+        },
+        destroy() {
+            if (st.local === options)
+                st.local = null;
+        },
+    };
+}
+/**
+ * Plays another player's emote on their character (from the game's network). An id that is not a Nanoterra emote is ignored (false). The same play
+ * given again (the same `at`) is ignored, so a game may pass the last one every frame; a loop that is on show goes on through a repeat. With an
+ * options store whose `emotes.others` is off, nothing plays.
+ */
+export function playRemote(character, play, opts = {}) {
+    if (!play || typeof play !== "object" || !isEmote(play.id))
+        return false;
+    if (!readEmoteOptions(opts.options).others)
+        return false;
+    const at = typeof play.at === "number" && Number.isFinite(play.at) ? play.at : now();
+    const st = stateOf(character);
+    if (st.seen === at)
+        return false;
+    st.seen = at;
+    return start(character, play.id, (now() - at) / 1000);
+}
+/** Stops a character's clip with its fade (a remote player's, when the game hears a stop, or any character that goes into water). */
+export function stopEmote(character) {
+    const st = states.get(character);
+    if (st)
+        stopClip(st.run);
+}

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

@@ -12,15 +12,15 @@ export type FriendsMountOptions = {
     /**
      * The player chose to join a friend. "nanoterra": `target` is the friend's https address (the kit has asked the player already) and there is no
      * `friend` (the window sends no name); with no `onJoin` the page goes there. "own": `target` is the `where` of the friend's invite, for the game to
-     * move the player, and `friend` names them (with no `onJoin`, there is no Join key).
+     * move the player, and `friend` names them (with no `onJoin`, there is no Join key and no Invite key: an invite would lead nowhere).
      */
     onJoin?: (target: string, friend?: {
         name: string;
     }) => void;
     /** The `fetch` to use (default: the page's). */
     fetch?: typeof fetch;
-    /** Asks the player a yes or no question (default: `window.confirm`). */
-    confirm?: (question: string) => boolean;
+    /** 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 MountedFriends = {
     /** Sets where the player is (friends see it). Null: no place. */