@nano133/nanoterra 0.5.0 → 0.6.0

package/dist/friends/panel/mount.js

@@ -0,0 +1,321 @@
+// The Friends key and panel of a game: `mountFriends(element, options)`. Plain DOM, no framework, no Three.js. The mode is the admin's friends
+// setting (GET {admin}/game gives it as `friends`; a game with no admin passes its own word):
+//
+//   "nanoterra"  the key opens the nano133 window (./window.ts, contract v1). The window is made at once and kept while the panel is closed: it holds
+//                the player's live connection, which tells their friends "Playing <game>" and keeps the badge true. Closed, it is hidden (not shown,
+//                off the screen, out of the tab order), never removed or `display: none`. `destroy()` removes it. The badge shows the requests
+//                (the thing to do) when there are any, else the friends online, in another colour.
+//   "own"        the key opens the game's own list, from the handler of "@nano133/nanoterra/friends" at `base`: the view every 20 s while open (every
+//                60 s while closed, for the badge), a pulse every 45 s with this tab's lease, and a "leave" pulse when the page goes away.
+//   "off"        nothing is drawn.
+//
+// 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 { 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 };
+const NOTHING = { setWhere() { }, open() { }, close() { }, destroy() { } };
+let mounts = 0;
+export function mountFriends(root, options) {
+    if (options.mode !== "nanoterra" && options.mode !== "own")
+        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;
+    const cleanup = [];
+    const badge = h("span", { class: "n133f-badge", "aria-hidden": "true" });
+    badge.hidden = true;
+    const keyWords = h("span", { class: "n133f-key-word" }, "Friends");
+    const key = h("button", { class: "n133f-key", type: "button", "aria-expanded": "false", "aria-controls": `n133f-panel-${n}` }, icon("players", 20), keyWords, badge);
+    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 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. */
+    const setBadge = ({ requests, online }) => {
+        const shown = requests > 0 ? requests : online;
+        badge.hidden = shown <= 0;
+        badge.classList.toggle("is-online", requests <= 0 && online > 0);
+        badge.textContent = shown > 9 ? "9+" : String(shown);
+        const parts = [requests > 0 ? `${requests} ${requests === 1 ? "request" : "requests"}` : "", online > 0 ? `${online} online` : ""].filter(Boolean);
+        key.setAttribute("aria-label", parts.length ? `Friends, ${parts.join(", ")}` : "Friends");
+    };
+    let onOpen = () => { };
+    let onClose = () => { };
+    const open = () => {
+        if (destroyed || isOpen)
+            return;
+        isOpen = true;
+        panel.dataset.open = "true";
+        key.setAttribute("aria-expanded", "true");
+        onOpen();
+        closeKey.focus();
+    };
+    const close = () => {
+        if (destroyed || !isOpen)
+            return;
+        isOpen = false;
+        panel.dataset.open = "false";
+        key.setAttribute("aria-expanded", "false");
+        onClose();
+        key.focus();
+    };
+    key.addEventListener("click", () => (isOpen ? close() : open()));
+    closeKey.addEventListener("click", close);
+    const onKey = (e) => {
+        if (e.key === "Escape" && isOpen)
+            close();
+    };
+    document.addEventListener("keydown", onKey);
+    cleanup.push(() => document.removeEventListener("keydown", onKey));
+    let setWhereHere = (_w) => { };
+    if (options.mode === "nanoterra") {
+        // The window, made at once (no lazy loading) and kept while the panel is closed.
+        const frame = h("iframe", {
+            class: "n133f-window",
+            src: windowUrl(origin, options.game),
+            title: "Friends",
+            referrerpolicy: "origin",
+            allow: "storage-access",
+            sandbox: "allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox allow-storage-access-by-user-activation",
+        });
+        body.append(frame);
+        const hideFrame = (hidden) => {
+            if (hidden) {
+                frame.setAttribute("aria-hidden", "true");
+                frame.tabIndex = -1;
+            }
+            else {
+                frame.removeAttribute("aria-hidden");
+                frame.removeAttribute("tabindex");
+            }
+        };
+        hideFrame(true);
+        let ready = false;
+        const send = (msg) => {
+            if (ready)
+                frame.contentWindow?.postMessage(msg, origin);
+        };
+        onOpen = () => {
+            hideFrame(false);
+            send(toWindow({ type: "open" }));
+        };
+        onClose = () => {
+            hideFrame(true);
+            send(toWindow({ type: "closed" }));
+        };
+        setWhereHere = (w) => send(toWindow({ type: "where", where: w }));
+        const onMessage = (e) => {
+            // Only the window itself, from nano133's origin.
+            if (e.origin !== origin || e.source !== frame.contentWindow)
+                return;
+            const m = readWindowMessage(e.data);
+            if (!m)
+                return;
+            if (m.type === "ready") {
+                // Right after ready: where the player is, then whether the panel is open.
+                ready = true;
+                send(toWindow({ type: "where", where }));
+                send(toWindow({ type: isOpen ? "open" : "closed" }));
+            }
+            else if (m.type === "size") {
+                // The height its content needs, at most the panel's own room.
+                const room = body.clientHeight;
+                frame.style.height = `${room > 0 ? Math.min(m.height, room) : m.height}px`;
+            }
+            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);
+            }
+            // "signin": the window needs a tap (Storage Access) inside itself. The panel stays as it is; the kit does nothing else.
+        };
+        window.addEventListener("message", onMessage);
+        cleanup.push(() => window.removeEventListener("message", onMessage));
+    }
+    else {
+        const own = ownList(body, options, () => where, setBadge, ask);
+        onOpen = own.opened;
+        onClose = own.closed;
+        setWhereHere = own.moved;
+        cleanup.push(own.stop);
+    }
+    return {
+        setWhere(w) {
+            where = whereText(w);
+            setWhereHere(where);
+        },
+        open,
+        close,
+        destroy() {
+            if (destroyed)
+                return;
+            destroyed = true;
+            for (const f of cleanup)
+                f();
+            wrap.remove();
+        },
+    };
+}
+/** The game's own list in `body`. */
+function ownList(body, options, whereNow, setBadge, ask) {
+    const api = createApi(options.base ?? "/friends", options.fetch);
+    const lease = Array.from(globalThis.crypto.getRandomValues(new Uint8Array(16)), (b) => b.toString(16).padStart(2, "0")).join("");
+    const status = h("p", { class: "n133f-status", role: "status", "aria-live": "polite" });
+    const nameInput = h("input", { class: "n133f-input", type: "text", name: "friend", maxlength: 64, autocomplete: "off", placeholder: "A player's name", "aria-label": "A player's name" });
+    const addKey = h("button", { class: "n133f-btn n133f-primary", type: "submit" }, "Add");
+    const form = h("form", { class: "n133f-add" }, nameInput, addKey);
+    const list = h("div", { class: "n133f-list" });
+    const show = h("input", { type: "checkbox", class: "n133f-check" });
+    const showRow = h("label", { class: "n133f-show" }, show, h("span", {}, "Show friends when I am online"));
+    body.append(form, status, list, showRow);
+    let view = null;
+    let isOpen = false;
+    let stopped = false;
+    let timer = null;
+    const fail = (e) => {
+        status.textContent = e instanceof ApiError ? e.message : "The game's server did not answer. Try again.";
+    };
+    const draw = () => {
+        if (!view)
+            return;
+        show.checked = view.showOnline;
+        const requests = view.people.filter((p) => p.state === "incoming" || (p.state === "friend" && p.invite)).length;
+        setBadge({ requests, online: view.people.filter((p) => p.state === "friend" && p.online).length });
+        const groups = [
+            ["Requests", view.people.filter((p) => p.state === "incoming")],
+            ["Friends", view.people.filter((p) => p.state === "friend")],
+            ["Sent", view.people.filter((p) => p.state === "outgoing")],
+            ["Blocked", view.people.filter((p) => p.state === "blocked")],
+        ];
+        const parts = [];
+        for (const [label, rows] of groups) {
+            if (!rows.length)
+                continue;
+            parts.push(h("h3", { class: "n133f-group" }, `${label} (${rows.length})`), h("ul", { class: "n133f-rows" }, ...rows.map(rowEl)));
+        }
+        if (!parts.length)
+            parts.push(h("p", { class: "n133f-empty" }, "No friends yet. Add a player by their name."));
+        list.replaceChildren(...parts);
+    };
+    const act = async (body, done) => {
+        try {
+            view = await api.post("", body);
+            status.textContent = done ?? "";
+            draw();
+        }
+        catch (e) {
+            fail(e);
+        }
+    };
+    const btn = (words, onclick, kind = "") => h("button", { class: `n133f-btn ${kind}`.trim(), type: "button", onclick }, words);
+    function rowEl(p) {
+        const keys = [];
+        if (p.state === "incoming")
+            keys.push(btn("Accept", () => void act({ op: "accept", edge: p.edge }, `${p.name} is your friend now.`), "n133f-primary"), btn("Decline", () => void act({ op: "decline", edge: p.edge })));
+        if (p.state === "friend") {
+            if (p.invite && options.onJoin)
+                keys.push(btn("Join", () => options.onJoin(p.invite.where, { name: p.name }), "n133f-primary"));
+            const here = whereNow();
+            if (here)
+                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"));
+        }
+        if (p.state === "outgoing")
+            keys.push(btn("Cancel", () => void act({ op: "decline", edge: p.edge })));
+        if (p.state === "blocked")
+            keys.push(btn("Unblock", () => void act({ op: "unblock", edge: p.edge })));
+        const line = p.state === "friend" ? (p.online ? p.where ?? "Online" : "Offline") : p.state === "incoming" ? "Wants to be friends" : p.state === "outgoing" ? "Asked" : "Blocked";
+        const invite = p.state === "friend" && p.invite ? h("p", { class: "n133f-invite" }, `Invites you: ${p.invite.where}`) : null;
+        return h("li", { class: `n133f-row n133f-${p.state}${p.online ? " is-online" : ""}` }, h("span", { class: "n133f-dot", "aria-hidden": "true" }), h("div", { class: "n133f-who" }, h("strong", {}, p.name), h("span", { class: "n133f-line" }, p.online ? `Online · ${line}` : line), invite), h("div", { class: "n133f-keys" }, ...keys));
+    }
+    const read = async () => {
+        try {
+            view = await api.get("");
+            draw();
+        }
+        catch (e) {
+            if (isOpen)
+                fail(e);
+        }
+    };
+    const pulse = async (place) => {
+        try {
+            await api.post("", { op: "pulse", where: place, lease });
+        }
+        catch {
+            // A missed pulse only makes the player look offline for a while.
+        }
+    };
+    /** The next read of the view. One timer at a time: a new one replaces the old. */
+    const loop = () => {
+        if (timer)
+            clearTimeout(timer);
+        if (stopped)
+            return;
+        timer = setTimeout(() => {
+            void read().finally(loop);
+        }, isOpen ? FRIENDS_TIMING.viewOpenMs : FRIENDS_TIMING.viewClosedMs);
+    };
+    const beat = setInterval(() => {
+        const here = whereNow();
+        if (here)
+            void pulse(here);
+    }, FRIENDS_TIMING.pulseMs);
+    const leave = () => {
+        // The page goes away: this tab's place is cleared (an old tab cannot clear a newer one: the lease).
+        void (options.fetch ?? fetch)(options.base ?? "/friends", { method: "POST", credentials: "same-origin", keepalive: true, headers: { "Content-Type": "application/json" }, body: JSON.stringify({ op: "pulse", where: null, lease }) }).catch(() => undefined);
+    };
+    window.addEventListener("pagehide", leave);
+    form.addEventListener("submit", (e) => {
+        e.preventDefault();
+        const name = nameInput.value.trim();
+        if (!name)
+            return;
+        void act({ op: "request", name }, `Asked ${name}.`).then(() => {
+            if (!status.textContent?.startsWith("Asked"))
+                return;
+            nameInput.value = "";
+        });
+    });
+    show.addEventListener("change", () => void act({ op: "visibility", showOnline: show.checked }));
+    void read();
+    if (whereNow())
+        void pulse(whereNow());
+    loop();
+    return {
+        opened() {
+            isOpen = true;
+            status.textContent = "";
+            void read();
+            loop();
+        },
+        closed() {
+            isOpen = false;
+        },
+        moved(place) {
+            void pulse(place);
+            draw();
+        },
+        stop() {
+            stopped = true;
+            if (timer)
+                clearTimeout(timer);
+            clearInterval(beat);
+            window.removeEventListener("pagehide", leave);
+            leave();
+        },
+    };
+}

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

@@ -0,0 +1,52 @@
+/** The `source` of every message, both ways. A message with another `source` is not for this contract. */
+export declare const WINDOW_SOURCE = "nanoterra-friends";
+/** The version of the messages. A message with another `v` is ignored. */
+export declare const WINDOW_V = 1;
+type Head = {
+    source: "nanoterra-friends";
+    v: 1;
+};
+/** Messages from the game's page to the window (sent with the window's origin as the target). */
+export type ToWindow = Head & ({
+    type: "open";
+} | {
+    type: "closed";
+} | {
+    type: "where";
+    where: string | null;
+});
+/** Messages from the window that the kit acts on. Anything else is ignored. */
+export type FromWindow = Head & ({
+    type: "ready";
+} | {
+    type: "size";
+    height: number;
+} | {
+    type: "badge";
+    online: number;
+    requests: number;
+} | {
+    type: "join";
+    url: string;
+} | {
+    type: "signin";
+});
+/** The window's address for a game. */
+export declare function windowUrl(origin: string, game: string): string;
+/** A message to the window. */
+export declare function toWindow(m: {
+    type: "open";
+} | {
+    type: "closed";
+} | {
+    type: "where";
+    where: string | null;
+}): ToWindow;
+/**
+ * The game's `where` as the kit sends it: plain text, control characters removed, trimmed, at most 64 characters (the site does the same again and
+ * shows it as text only). Null when nothing is left.
+ */
+export declare function whereText(where: unknown): string | null;
+/** A message from the window, checked: its source, its version, its type and each field. Null for anything else (a bad field too). */
+export declare function readWindowMessage(data: unknown): FromWindow | null;
+export {};

package/dist/friends/panel/window.js

@@ -0,0 +1,72 @@
+// The nano133 friends window: the contract between the kit and nano133's page /embed/friends (contract v1, accepted by the site on 2026-10-30).
+// The window holds the player's Nanoterra friends and their live connection; the game gets none of them. It says only its height, two counts for
+// the badge, that it needs a tap (Storage Access), and a friend's https address to join (the kit asks the player first). No message carries an
+// address, a pass or a player id.
+/** The `source` of every message, both ways. A message with another `source` is not for this contract. */
+export const WINDOW_SOURCE = "nanoterra-friends";
+/** The version of the messages. A message with another `v` is ignored. */
+export const WINDOW_V = 1;
+/** The window's address for a game. */
+export function windowUrl(origin, game) {
+    return `${origin}/embed/friends?game=${encodeURIComponent(game)}&v=${WINDOW_V}`;
+}
+/** A message to the window. */
+export function toWindow(m) {
+    return { source: WINDOW_SOURCE, v: WINDOW_V, ...m };
+}
+/**
+ * The game's `where` as the kit sends it: plain text, control characters removed, trimmed, at most 64 characters (the site does the same again and
+ * shows it as text only). Null when nothing is left.
+ */
+export function whereText(where) {
+    if (typeof where !== "string")
+        return null;
+    // eslint-disable-next-line no-control-regex
+    const plain = where.replace(/[\u0000-\u001f\u007f-\u009f\u2028\u2029]/g, "").trim();
+    const cut = Array.from(plain).slice(0, 64).join("").trim();
+    return cut || null;
+}
+const count = (v) => (typeof v === "number" && Number.isFinite(v) && v >= 0 ? Math.min(99, Math.floor(v)) : null);
+/** A message from the window, checked: its source, its version, its type and each field. Null for anything else (a bad field too). */
+export function readWindowMessage(data) {
+    if (!data || typeof data !== "object" || Array.isArray(data))
+        return null;
+    const m = data;
+    if (m.source !== WINDOW_SOURCE || m.v !== WINDOW_V || typeof m.type !== "string")
+        return null;
+    const head = { source: WINDOW_SOURCE, v: WINDOW_V };
+    switch (m.type) {
+        case "ready":
+        case "signin":
+            return { ...head, type: m.type };
+        case "size": {
+            if (typeof m.height !== "number" || !Number.isFinite(m.height) || m.height < 0)
+                return null;
+            return { ...head, type: "size", height: Math.min(10_000, Math.ceil(m.height)) };
+        }
+        case "badge": {
+            const online = count(m.online);
+            const requests = count(m.requests);
+            if (online === null || requests === null)
+                return null;
+            return { ...head, type: "badge", online, requests };
+        }
+        case "join": {
+            if (typeof m.url !== "string" || m.url.length > 2048)
+                return null;
+            let url;
+            try {
+                url = new URL(m.url);
+            }
+            catch {
+                return null;
+            }
+            // https only: an island friend's room on nano133, or a friend's game at its listed address. No name or password in it.
+            if (url.protocol !== "https:" || url.username || url.password)
+                return null;
+            return { ...head, type: "join", url: url.href };
+        }
+        default:
+            return null;
+    }
+}

package/dist/friends/rules.d.ts

@@ -0,0 +1,92 @@
+import { type FriendRow, type FriendState } from "./types.js";
+/** An edge as an adapter keeps it. `a` and `b` are the two players' ids, `a < b`. `rev` grows with each write (an adapter may use it to refuse a write on a row that changed). */
+export type EdgeRec = {
+    edge: string;
+    a: string;
+    b: string;
+    from: string;
+    state: "pending" | "friend" | "blocked";
+    blockedBy: string[];
+    at: number;
+    invite: {
+        from: string;
+        where: string;
+        at: number;
+    } | null;
+    rev: number;
+};
+/** What an adapter does after a rule: write this edge (new or changed), delete it, or nothing. */
+export type Plan = {
+    put: EdgeRec;
+} | {
+    drop: EdgeRec;
+} | {
+    none: true;
+};
+/** A presence row: where a player is, which tab said so, and when. */
+export type PresenceRec = {
+    player: string;
+    where: string;
+    lease: string;
+    at: number;
+};
+/** The two ids of a pair in the order an adapter keeps them. */
+export declare const pairOf: (x: string, y: string) => [string, string];
+export declare const otherOf: (rec: EdgeRec, me: string) => string;
+export declare const hasPlayer: (rec: EdgeRec, me: string) => boolean;
+/** A request that nobody answered in time is gone; anything else is live. */
+export declare const liveEdge: (rec: EdgeRec, now: number) => boolean;
+/** A new opaque edge id: random, never made from a player id. */
+export declare function newEdgeId(): string;
+/** An edge id as the browser may send one: letters, digits, "-" and "_", 8 to 64. Anything else is refused before a store is asked. */
+export declare const EDGE_PATTERN: RegExp;
+/** A tab's lease, as for an edge. */
+export declare const LEASE_PATTERN: RegExp;
+/**
+ * The game's `where` text as a store keeps it: control characters removed, spaces at the ends trimmed, cut to FRIEND_WHERE_MAX characters
+ * (whole characters, not halves of one). Null when nothing is left, or when it is not text.
+ */
+export declare function cleanWhere(where: unknown): string | null;
+/** The state of an edge for one of its players, or null when they must not see it (a block by the other, an old request). */
+export declare function stateFor(rec: EdgeRec, me: string, now: number): FriendState | null;
+/**
+ * A request from `me` to `other`. `rec` is the pair's edge (or null); `counts` are the live edges of each, which the adapter reads only when a new
+ * edge would be made (it passes a function).
+ */
+export declare function planRequest(me: string, other: string, rec: EdgeRec | null, now: number, counts: () => Promise<{
+    mine: number;
+    theirs: number;
+}>): Promise<Plan>;
+export declare function planAccept(me: string, rec: EdgeRec | null, now: number): Plan;
+/** Declines a request to `me`, or takes back a request of `me`'s. */
+export declare function planDecline(me: string, rec: EdgeRec | null, now: number): Plan;
+/** Ends a friendship (or a request, either way). A block is ended by unblock, not by remove. */
+export declare function planRemove(me: string, rec: EdgeRec | null, now: number): Plan;
+export declare function planBlock(me: string, rec: EdgeRec | null, now: number): Plan;
+/** Takes `me`'s block away. With no block left the pair has no edge (they are not friends again: either may ask). */
+export declare function planUnblock(me: string, rec: EdgeRec | null, now: number): Plan;
+export declare function planInvite(me: string, rec: EdgeRec | null, where: unknown, now: number): Plan;
+/** The lease and the place of a pulse, checked. `where` null means the tab is leaving (it clears the row only when the lease is the same). */
+export declare function checkPulse(where: unknown, lease: unknown): {
+    where: string | null;
+    lease: string;
+};
+/** What a pulse does to the presence row `was`: the new row, a deletion, or nothing (an old tab that leaves after a newer one came). */
+export declare function planPulse(player: string, where: string | null, lease: string, was: PresenceRec | null, now: number): {
+    put: PresenceRec;
+} | {
+    drop: true;
+} | {
+    none: true;
+};
+/** A presence row that still counts. */
+export declare const presenceLive: (p: PresenceRec | null | undefined, now: number) => p is PresenceRec;
+/**
+ * The browser's view of `me`'s edges. `presence` and `showOnline` are of the OTHER players (only friends' are read). `names` comes from the game's
+ * directory; a player it does not know reads "A player". No player id goes into a row.
+ */
+export declare function buildRows(me: string, recs: EdgeRec[], now: number, names: Map<string, string>, presence: Map<string, PresenceRec>, showOnline: Map<string, boolean>): FriendRow[];
+/** The other players whose names a view needs: every edge `me` can see. */
+export declare function shownOthers(me: string, recs: EdgeRec[], now: number): string[];
+/** The friends of `me` (their presence is read for the view). */
+export declare function friendsOf(me: string, recs: EdgeRec[], now: number): string[];