@net-mesh/browser 0.37.0

package/dist/wasm.js

@@ -0,0 +1,98 @@
+/**
+ * The wasm-bindgen boundary, described in TypeScript.
+ *
+ * These are the *only* shapes this package assumes about
+ * `net-mesh-leaf`. They are snake_case because that is what
+ * `wasm-bindgen` emits from Rust method names; every camelCase name a
+ * consumer sees is added by {@link BrowserNode} one layer up. Keeping
+ * the boundary in one file means a change on the Rust side breaks
+ * compilation here, at the seam, instead of somewhere in the middle of
+ * the wrapper.
+ */
+/**
+ * One instantiation per specifier, shared by every `connect()`.
+ *
+ * `wasm-bindgen`'s initialiser instantiates a fresh module every call;
+ * two `connect()`s in one page would otherwise ship two copies of the
+ * leaf into memory.
+ */
+const instantiated = new Map();
+/** Resolve and instantiate the leaf wasm described by `source`. */
+export async function loadLeafWasm(source = {}) {
+    if (source.wasm)
+        return source.wasm;
+    const specifier = source.wasmModule ?? new URL('./net_leaf.js', import.meta.url).href;
+    const key = `${specifier}|${String(source.wasmUrl ?? '')}`;
+    const pending = instantiated.get(key);
+    if (pending)
+        return pending;
+    const loading = importAndInit(specifier, source.wasmUrl);
+    instantiated.set(key, loading);
+    try {
+        return await loading;
+    }
+    catch (error) {
+        // A failed instantiation must not poison every later attempt: a
+        // page may retry with a corrected URL.
+        instantiated.delete(key);
+        throw error;
+    }
+}
+async function importAndInit(specifier, wasmUrl) {
+    // Genuinely runtime-selected, and a static import would be wrong
+    // twice over: the glue is a build artifact of the Rust crate that
+    // does not exist when this package is type-checked or published,
+    // and a page may point at any URL it serves it from.
+    const loaded = await import(/* @vite-ignore */ specifier);
+    const module = asLeafWasmModule(loaded, specifier);
+    if (module.default) {
+        await module.default(wasmUrl === undefined ? undefined : { module_or_path: wasmUrl });
+    }
+    return module;
+}
+function asLeafWasmModule(loaded, specifier) {
+    if (loaded === null || typeof loaded !== 'object' || !('LeafNode' in loaded)) {
+        throw new Error(`${specifier} is not a net-mesh-leaf module: no LeafNode export`);
+    }
+    // `wasm-bindgen` emits `LeafNode` as an ES class, so it is a
+    // *function* and `connect` is a static on it — not a plain object.
+    const leafNode = loaded.LeafNode;
+    if (typeof leafNode !== 'function' || !('connect' in leafNode)) {
+        throw new Error(`${specifier} exports a LeafNode without a static connect()`);
+    }
+    if (typeof leafNode.connect !== 'function') {
+        throw new Error(`${specifier} exports a LeafNode whose connect is not callable`);
+    }
+    // Checked as far as a runtime check can reach: the export exists and
+    // `connect` is callable. Its argument and return types are
+    // `wasm-bindgen`'s contract, not something JS can inspect.
+    return loaded;
+}
+/**
+ * One id argument of {@link LeafWasmNode.signal} as it crosses the
+ * wasm seam: a string passes through VERBATIM, and anything else is
+ * refused by the parsers' own names before it can reach the boundary.
+ *
+ * Refused, never coerced, and either alternative is fatal. A JS
+ * number cannot carry a `u64` id losslessly (`as f64 as u64`
+ * re-spells 511 of every 512 minted dialogs) — and a non-string must
+ * never reach `wasm-bindgen`'s String marshaling at all: it corrupts
+ * there, panicking `assert!(old_size > 0)` inside
+ * `passStringToWasm0`'s `__wbindgen_realloc`, and the call dies
+ * before `parse_peer_id` runs (finding #52's repro, on every peer
+ * spelling alike). The refusal carries the parser's name — "is not a
+ * peer id" / "is not a dialog id", as `name` picks — so a page that
+ * classifies a refusal by its text reads this one as the refusal it
+ * is. Peer before dialog at the call sites, the order
+ * `LeafNode::signal` parses in.
+ */
+export function idArg(value, name) {
+    if (typeof value === 'string')
+        return value;
+    // `String(value)` on a null-prototype object throws, and a refusal
+    // that dies is not a refusal.
+    const shown = typeof value === 'object' && value !== null ? Object.prototype.toString.call(value) : String(value);
+    throw new TypeError(`${shown} is not a ${name} id: a ${name} id crosses this boundary as 16 hex digits as a ` +
+        `STRING — the spelling this boundary hands out; a ${typeof value} is refused rather than ` +
+        `coerced, because a number cannot carry a u64 id`);
+}

package/dist/world/border.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Cross-border actions (browser plan §9 item 4): region A asks region B to
+ * act on an entity B owns — a hit across the border, a door on the other
+ * side — and **B's authority decides**. At-most-once, like handoff:
+ *
+ * - A sends `{ id, name, input }` and repeats it until B answers.
+ * - B runs the action ONCE per id, records the outcome in `acts` in the same
+ *   commit as its effect, makes both durable, and answers. Every repeat of
+ *   that id gets the recorded answer and changes nothing.
+ * - A that hears nothing within `giveUpMs` reports `unresolved`: the action
+ *   may or may not have happened, but it never happened twice. The caller
+ *   decides whether to ask again under a NEW id.
+ *
+ * A's pending actions are not persisted: an action A loses in a crash either
+ * reached B (and happened once) or did not (and did not happen).
+ */
+import type { RegionState } from './handoff.js';
+/** A to B: act on something B owns. */
+export interface ForwardedAction {
+    readonly k: 'act';
+    readonly id: string;
+    /** The asking region. */
+    readonly from: string;
+    readonly name: string;
+    readonly input: unknown;
+}
+/** B to A: the recorded outcome of one action id, the same every time. */
+export type ActionResult = {
+    readonly k: 'result';
+    readonly id: string;
+    readonly from: string;
+    readonly ok: true;
+    readonly output: unknown;
+} | {
+    readonly k: 'result';
+    readonly id: string;
+    readonly from: string;
+    readonly ok: false;
+    readonly reason: string;
+};
+/** An outcome the target recorded for an action id. */
+export interface ActRecord {
+    readonly at: number;
+    readonly ok: boolean;
+    readonly output?: unknown;
+    readonly reason?: string;
+}
+/**
+ * How a region applies one kind of forwarded action: the entities after it
+ * and the answer, or a refusal reason (string). Pure: the driver commits the
+ * returned entities, the record and nothing else.
+ */
+export type BorderAction<E> = (entities: Readonly<Record<string, E>>, input: unknown, from: string) => {
+    readonly entities: Readonly<Record<string, E>>;
+    readonly output: unknown;
+} | string;
+/**
+ * At the target: apply a forwarded action once per id and answer every copy
+ * of it the same way. An unknown action name is refused (and recorded, so
+ * the answer stays the same).
+ */
+export declare function onForwardedAction<E>(state: RegionState<E>, act: ForwardedAction, now: number, actions: Readonly<Record<string, BorderAction<E>>>): {
+    readonly state: RegionState<E>;
+    readonly reply: ActionResult;
+};
+/**
+ * Region A to neighbour B: A's entities near their shared border, read-only
+ * (plan §9 item 5, ghosting). Newer `seq` replaces older; nothing here is
+ * authoritative in B.
+ */
+export interface GhostFrame<E> {
+    readonly k: 'ghost';
+    readonly from: string;
+    readonly seq: number;
+    readonly entities: Readonly<Record<string, E>>;
+}
+/**
+ * Which neighbours of region `r:<rx>:<rz>` (squares of `size`) should see an
+ * entity at (x, z) within `margin` of their edge — up to three (two sides
+ * and the corner between them).
+ */
+export declare function ghostTargets(region: string, x: number, z: number, size: number, margin: number): string[];
+/** Forget action records older than `retentionMs` (which must outlast any source's retries). */
+export declare function pruneActs<E>(state: RegionState<E>, now: number, retentionMs: number): RegionState<E>;

package/dist/world/border.js

@@ -0,0 +1,99 @@
+/**
+ * Cross-border actions (browser plan §9 item 4): region A asks region B to
+ * act on an entity B owns — a hit across the border, a door on the other
+ * side — and **B's authority decides**. At-most-once, like handoff:
+ *
+ * - A sends `{ id, name, input }` and repeats it until B answers.
+ * - B runs the action ONCE per id, records the outcome in `acts` in the same
+ *   commit as its effect, makes both durable, and answers. Every repeat of
+ *   that id gets the recorded answer and changes nothing.
+ * - A that hears nothing within `giveUpMs` reports `unresolved`: the action
+ *   may or may not have happened, but it never happened twice. The caller
+ *   decides whether to ask again under a NEW id.
+ *
+ * A's pending actions are not persisted: an action A loses in a crash either
+ * reached B (and happened once) or did not (and did not happen).
+ */
+const has = (record, key) => Object.prototype.hasOwnProperty.call(record, key);
+function resultOf(region, id, record) {
+    return record.ok
+        ? { k: 'result', id, from: region, ok: true, output: record.output ?? null }
+        : { k: 'result', id, from: region, ok: false, reason: record.reason ?? 'refused' };
+}
+/**
+ * At the target: apply a forwarded action once per id and answer every copy
+ * of it the same way. An unknown action name is refused (and recorded, so
+ * the answer stays the same).
+ */
+export function onForwardedAction(state, act, now, actions) {
+    const acts = state.acts ?? {};
+    if (has(acts, act.id))
+        return { state, reply: resultOf(state.region, act.id, acts[act.id]) };
+    let record;
+    let entities = state.entities;
+    const handler = has(actions, act.name) ? actions[act.name] : undefined;
+    if (handler === undefined) {
+        record = { at: now, ok: false, reason: `no action '${act.name}' here` };
+    }
+    else {
+        let outcome;
+        try {
+            outcome = handler(state.entities, act.input, act.from);
+        }
+        catch (error) {
+            outcome = `action threw: ${String(error)}`;
+        }
+        if (typeof outcome === 'string') {
+            record = { at: now, ok: false, reason: outcome };
+        }
+        else {
+            entities = outcome.entities;
+            record = { at: now, ok: true, output: outcome.output };
+        }
+    }
+    const nextActs = { ...acts };
+    Object.defineProperty(nextActs, act.id, { value: record, enumerable: true, writable: true, configurable: true });
+    return { state: { ...state, entities, acts: nextActs }, reply: resultOf(state.region, act.id, record) };
+}
+/**
+ * Which neighbours of region `r:<rx>:<rz>` (squares of `size`) should see an
+ * entity at (x, z) within `margin` of their edge — up to three (two sides
+ * and the corner between them).
+ */
+export function ghostTargets(region, x, z, size, margin) {
+    const match = /^r:(-?\d+):(-?\d+)$/.exec(region);
+    if (match === null)
+        return [];
+    const rx = Number(match[1]);
+    const rz = Number(match[2]);
+    const near = (low, high, at) => {
+        const out = [0];
+        if (at - low < margin)
+            out.push(-1);
+        if (high - at <= margin)
+            out.push(1);
+        return out;
+    };
+    const out = [];
+    for (const dx of near(rx * size, (rx + 1) * size, x)) {
+        for (const dz of near(rz * size, (rz + 1) * size, z)) {
+            if (dx !== 0 || dz !== 0)
+                out.push(`r:${rx + dx}:${rz + dz}`);
+        }
+    }
+    return out;
+}
+/** Forget action records older than `retentionMs` (which must outlast any source's retries). */
+export function pruneActs(state, now, retentionMs) {
+    const acts = state.acts;
+    if (acts === undefined)
+        return state;
+    let next = null;
+    for (const [id, record] of Object.entries(acts)) {
+        if (now - record.at > retentionMs) {
+            next ??= { ...acts };
+            delete next[id];
+        }
+    }
+    return next === null ? state : { ...state, acts: next };
+}

package/dist/world/handoff.d.ts

@@ -0,0 +1,187 @@
+/**
+ * Entity handoff between region hosts — at-most-once, with a typed failure
+ * (browser plan §9 item 3, decision Q6).
+ *
+ * An entity crossing from region A to region B must never be live in both,
+ * and must never be applied twice. Exactly-once is not attempted; the
+ * failure a crash can cause is an entity that is **nowhere live for a
+ * while**, reported typed, never a duplicate.
+ *
+ * The protocol, over any lossy, duplicating, reordering carrier:
+ *
+ * 1. **A freezes.** The entity leaves A's live entities and waits in A's
+ *    `outgoing` under a fresh handoff id, with its state. A answers inputs for
+ *    it with `in-transit` (see {@link locate}).
+ * 2. **A offers** `{ id, entity, state }` to B, and repeats the offer until it
+ *    hears back. The id is the idempotence key.
+ * 3. **B decides once per id.** On the first offer it either admits the
+ *    entity (it is now live in B) or refuses it, and records the decision in
+ *    `handled`. Every later copy of that offer gets the SAME answer and
+ *    changes nothing.
+ * 4. **A settles.** `accept`: the frozen copy is dropped, and the entity is
+ *    B's. `refuse`: the entity returns to A's live entities. Only an explicit
+ *    refusal can bring it back to A, because silence proves nothing: B may
+ *    have admitted it and the answer been lost.
+ * 5. **No answer.** A keeps it frozen and keeps offering. After `giveUpMs`,
+ *    {@link retryHandoffs} reports it `unresolved` and stops offering. The
+ *    entity stays frozen, still nowhere live twice. Recovery (the destination
+ *    returning, an operator) re-offers with the same id through
+ *    {@link reofferHandoff}, which B answers from its record.
+ *
+ * **Durability is the caller's, and it is the whole correctness argument.**
+ * Every step here is a pure function from one {@link RegionState} to the
+ * next. The host MUST make the returned state durable (e.g.
+ * `persistStore(…).flush()`) BEFORE it sends the messages the step returns. A
+ * crash then either loses the step with its messages, which is the same as a
+ * lost message, or keeps both. B must also remember a decision for longer
+ * than any A keeps offering: `handledRetentionMs` > `giveUpMs`.
+ */
+import type { ActRecord, ActionResult, ForwardedAction, GhostFrame } from './border.js';
+/** A handoff's idempotence key: unique per crossing. */
+export type HandoffId = string;
+/** A to B: take this entity. */
+export interface HandoffOffer<E> {
+    readonly k: 'offer';
+    readonly id: HandoffId;
+    /** The source region. */
+    readonly from: string;
+    readonly entity: string;
+    readonly state: E;
+}
+/** B to A: the decision for one handoff id, the same every time it is asked. */
+export type HandoffReply = {
+    readonly k: 'accept';
+    readonly id: HandoffId;
+    readonly from: string;
+} | {
+    readonly k: 'refuse';
+    readonly id: HandoffId;
+    readonly from: string;
+    readonly reason: string;
+};
+/** A message between region hosts, addressed to region `to`. */
+export type HandoffMessage<E> = {
+    readonly to: string;
+    readonly body: HandoffOffer<E> | HandoffReply | ForwardedAction | ActionResult | GhostFrame<E>;
+};
+/** An entity frozen at the source, on its way out. */
+export interface Outgoing<E> {
+    readonly entity: string;
+    readonly state: E;
+    readonly to: string;
+    /** When the handoff began, ms. */
+    readonly since: number;
+    /** When the offer was last sent, ms. */
+    readonly sentAt: number;
+    /** Stopped offering after `giveUpMs` (typed `unresolved`); still frozen. */
+    readonly unresolved: boolean;
+}
+/** A decision the target recorded for an id. */
+export interface Handled {
+    readonly decision: 'accept' | 'refuse';
+    readonly reason?: string;
+    readonly at: number;
+}
+/**
+ * A region host's handoff-relevant state. Keep it IN the region's persisted
+ * document, and make it durable as one unit with the entities: a frozen
+ * entity must not come back live after a restart, and an admitted one must
+ * not be admitted again.
+ */
+export interface RegionState<E> {
+    readonly region: string;
+    readonly entities: Readonly<Record<string, E>>;
+    readonly outgoing: Readonly<Record<HandoffId, Outgoing<E>>>;
+    readonly handled: Readonly<Record<HandoffId, Handled>>;
+    /** Cross-border actions applied here, by id (`border.ts`). */
+    readonly acts?: Readonly<Record<string, ActRecord>>;
+}
+/** Timing for {@link retryHandoffs} and {@link pruneHandled}. */
+export interface HandoffTiming {
+    /** Re-offer an unanswered handoff this often, ms. Default 250. */
+    readonly retryMs?: number;
+    /** Stop offering after this long and report `unresolved`, ms. Default 60 000. */
+    readonly giveUpMs?: number;
+    /** How long a target remembers a decision, ms. Default 600 000; must exceed `giveUpMs`. */
+    readonly handledRetentionMs?: number;
+}
+/** What one step did, for the host to act on AFTER making the state durable. */
+export interface HandoffStep<E> {
+    readonly state: RegionState<E>;
+    /** Send these, after the state is durable. */
+    readonly send: readonly HandoffMessage<E>[];
+    /** Settled handoffs, for the game (e.g. tell the player where to go). */
+    readonly events: readonly HandoffEvent[];
+}
+/** A handoff outcome at the source, or an admission at the target. */
+export type HandoffEvent = {
+    readonly type: 'moved';
+    readonly id: HandoffId;
+    readonly entity: string;
+    readonly to: string;
+} | {
+    readonly type: 'refused';
+    readonly id: HandoffId;
+    readonly entity: string;
+    readonly to: string;
+    readonly reason: string;
+} | {
+    readonly type: 'unresolved';
+    readonly id: HandoffId;
+    readonly entity: string;
+    readonly to: string;
+} | {
+    readonly type: 'admitted';
+    readonly id: HandoffId;
+    readonly entity: string;
+    readonly from: string;
+};
+/** An empty region. */
+export declare function regionState<E>(region: string, entities?: Readonly<Record<string, E>>): RegionState<E>;
+/**
+ * Step 1–2 at the source: freeze `entity` and offer it to region `to`.
+ * Throws if the entity is not live here (frozen already, or unknown).
+ */
+export declare function beginHandoff<E>(state: RegionState<E>, entity: string, to: string, id: HandoffId, now: number): HandoffStep<E>;
+/**
+ * Step 3 at the target: decide an offer once, and answer every copy of it
+ * the same way. `admit` is asked only the first time; it returns `true` or a
+ * refusal reason. An admitted entity whose id is already live here is
+ * refused (`occupied`), never overwritten.
+ */
+export declare function onHandoffOffer<E>(state: RegionState<E>, offer: HandoffOffer<E>, now: number, admit?: (entity: string, value: E) => true | string): HandoffStep<E>;
+/**
+ * Step 4 at the source: settle on the target's answer. A reply for a handoff
+ * this region is not holding (already settled, or never begun) changes
+ * nothing: replies are duplicated and reordered like everything else.
+ */
+export declare function onHandoffReply<E>(state: RegionState<E>, reply: HandoffReply): HandoffStep<E>;
+/**
+ * Step 2 and 5 at the source, on a timer: re-offer what is unanswered, and
+ * mark what has waited past `giveUpMs` as `unresolved` (reported once, still
+ * frozen, no longer offered).
+ */
+export declare function retryHandoffs<E>(state: RegionState<E>, now: number, options?: HandoffTiming): HandoffStep<E>;
+/**
+ * Recovery: offer an `unresolved` handoff again, under the SAME id (the
+ * destination answers it from its record, so this cannot admit twice), and
+ * restart its give-up clock. Use it when the destination is known to be
+ * back. A no-op for a handoff that is not unresolved.
+ */
+export declare function reofferHandoff<E>(state: RegionState<E>, id: HandoffId, now: number): HandoffStep<E>;
+/** Forget target decisions older than `handledRetentionMs` (which must outlast any source's offers). */
+export declare function pruneHandled<E>(state: RegionState<E>, now: number, options?: HandoffTiming): RegionState<E>;
+/**
+ * Where an entity is, from this region's point of view — what to answer an
+ * input for it: `here` (apply it), `in-transit` (frozen, on its way to
+ * `to`; refuse, never apply), or `unknown`.
+ */
+export declare function locate<E>(state: RegionState<E>, entity: string): {
+    readonly at: 'here';
+} | {
+    readonly at: 'in-transit';
+    readonly to: string;
+    readonly id: HandoffId;
+} | {
+    readonly at: 'unknown';
+};