@net-mesh/browser 0.37.0

package/dist/world/regions.js

@@ -0,0 +1,314 @@
+/**
+ * Large worlds: regions, their directory, and a player's merged view
+ * (browser plan §9 items 1–2).
+ *
+ * The map is cut into square regions of `size` units; region `r:<rx>:<rz>`
+ * covers `rx*size <= x < (rx+1)*size`, the same for z. Each region is its
+ * own store, hosted by whichever node announces it:
+ *
+ * ```ts
+ * // A region host (usually a dedicated Node host):
+ * hostStore({ definition: world, store: 'r:4:7', transport, … });
+ * announceRegions(node, 'my-world', ['r:4:7', 'r:4:8']);
+ *
+ * // A player:
+ * const view = joinWorld({ node, world: 'my-world', definition: world, collection: 'ships',
+ *                          position: { x, z }, size: 256, key: 'player', maxEventBytes: 8104 });
+ * bindEntities({ store: view, select: entities => entities, … });
+ * view.setPosition(x, z);                  // as the player moves
+ * await view.act('fire', { … });           // to the region the player is in
+ * ```
+ *
+ * **The directory is discovery, not a root of trust.** Any node can
+ * announce any tag. {@link regionDirectory} therefore takes `trustedHosts`,
+ * the node ids that may host this world's regions. Without that list, a
+ * region two nodes claim is `ambiguous` and is NOT joined, rather than
+ * joining whichever answered first. A handoff link that authenticates by this
+ * directory (`handoffLink({ peerOf: directory.peerOf })`) needs the list:
+ * otherwise a node that announces a region could also send offers as it.
+ */
+import { peerHexOf } from '../store/host.js';
+import { joinStore } from '../store/join.js';
+/** Region `r:<rx>:<rz>` for a position, with regions `size` units square. */
+export function regionOf(x, z, size) {
+    if (!(size > 0))
+        throw new RangeError('region size must be positive');
+    return `r:${Math.floor(x / size)}:${Math.floor(z / size)}`;
+}
+/** The regions within `radius` regions of a position (a square, `(2r+1)²`). */
+export function regionsAround(x, z, options) {
+    const radius = Math.max(0, Math.floor(options.radius ?? 1));
+    const cx = Math.floor(x / options.size);
+    const cz = Math.floor(z / options.size);
+    const out = [];
+    for (let dx = -radius; dx <= radius; dx += 1) {
+        for (let dz = -radius; dz <= radius; dz += 1)
+            out.push(`r:${cx + dx}:${cz + dz}`);
+    }
+    return out;
+}
+/** The directory tag a region host announces. */
+export function regionTag(world, region) {
+    return `net-world:${world}:region:${region}`;
+}
+/** How often region hosts re-announce: an announcement is a lease. */
+export const REGION_ANNOUNCE_MS = 2_000;
+/**
+ * Announce that this node hosts `regions` of `world`, and keep announcing
+ * (an announcement is a lease). `announce` replaces a node's tags, so pass
+ * any other tags this node carries in `tags`. Returns a stop function.
+ */
+export function announceRegions(node, world, regions, options = {}) {
+    const tags = [...(options.tags ?? []), ...regions.map(region => regionTag(world, region))];
+    let stopped = false;
+    const once = () => {
+        if (!stopped)
+            void node.announce(tags).catch(() => undefined);
+    };
+    once();
+    const timer = setInterval(once, options.everyMs ?? REGION_ANNOUNCE_MS);
+    timer.unref?.();
+    return () => {
+        stopped = true;
+        clearInterval(timer);
+    };
+}
+/** A region directory over the mesh's signed announcements. */
+export function regionDirectory(options) {
+    const trusted = options.trustedHosts === undefined
+        ? null
+        : new Set(options.trustedHosts.map(id => peerHexOf(id)).filter((id) => id !== null));
+    const cache = new Map();
+    return {
+        async lookup(region) {
+            let found;
+            try {
+                found = await options.node.query(regionTag(options.world, region));
+            }
+            catch {
+                found = [];
+            }
+            const hosts = [
+                ...new Set(found
+                    .map(descriptor => peerHexOf(descriptor.peerIdHex))
+                    .filter((id) => id !== null && (trusted === null || trusted.has(id)))),
+            ].sort();
+            const answer = hosts.length === 0
+                ? { status: 'unhosted' }
+                : hosts.length === 1
+                    ? { status: 'hosted', host: hosts[0] }
+                    : { status: 'ambiguous', hosts };
+            cache.set(region, answer);
+            return answer;
+        },
+        peerOf(region) {
+            const known = cache.get(region);
+            return known?.status === 'hosted' ? known.host : null;
+        },
+    };
+}
+/** Join a world: the player's region and its neighbours, merged into one view. */
+export function joinWorld(options) {
+    const radius = Math.max(0, Math.floor(options.radius ?? 1));
+    const retryMs = options.retryMs ?? 2_000;
+    const directory = options.directory ??
+        regionDirectory({
+            node: options.node,
+            world: options.world,
+            ...(options.trustedHosts === undefined ? {} : { trustedHosts: options.trustedHosts }),
+        });
+    const held = new Map();
+    const listeners = new Set();
+    let position = { x: options.position.x, z: options.position.z };
+    let merged = {};
+    let closed = false;
+    const lingerMs = Math.max(0, options.lingerMs ?? 500);
+    // Where each entity in `merged` came from, and entities lingering after
+    // vanishing from a held region: their last state and when they vanished.
+    let origin = new Map();
+    const lingering = new Map();
+    let lingerTimer = null;
+    const remerge = () => {
+        const next = {};
+        const from = new Map();
+        for (const [region, entry] of held) {
+            if (entry.phase !== 'ready' || entry.replica === null)
+                continue;
+            const doc = entry.replica.getState();
+            const entities = doc[options.collection];
+            if (typeof entities !== 'object' || entities === null)
+                continue;
+            for (const [id, entity] of Object.entries(entities)) {
+                const already = from.get(id);
+                if (already !== undefined) {
+                    // In two regions at once (mid-handoff): keep the copy from the
+                    // region that contains it, when we can tell.
+                    const at = options.positionOf?.(entity) ?? null;
+                    if (at === null || regionOf(at.x, at.z, options.size) !== region)
+                        continue;
+                }
+                Object.defineProperty(next, id, { value: entity, enumerable: true, writable: true, configurable: true });
+                from.set(id, region);
+            }
+        }
+        // Vanished from a region still held: linger. Reappeared anywhere, or its
+        // region released, or its time up: gone from the lingering set.
+        const at = Date.now();
+        for (const [id, region] of origin) {
+            if (from.has(id) || lingering.has(id) || lingerMs === 0)
+                continue;
+            if (held.get(region)?.phase === 'ready') {
+                lingering.set(id, { entity: merged[id], region, since: at });
+            }
+        }
+        let soonest = Infinity;
+        for (const [id, linger] of lingering) {
+            if (from.has(id) || held.get(linger.region)?.phase !== 'ready' || at - linger.since >= lingerMs) {
+                lingering.delete(id);
+                continue;
+            }
+            Object.defineProperty(next, id, { value: linger.entity, enumerable: true, writable: true, configurable: true });
+            soonest = Math.min(soonest, linger.since + lingerMs);
+        }
+        if (lingerTimer !== null)
+            clearTimeout(lingerTimer);
+        lingerTimer = null;
+        if (soonest !== Infinity && !closed) {
+            lingerTimer = setTimeout(remerge, Math.max(0, soonest - at) + 1);
+            lingerTimer.unref?.();
+        }
+        origin = from;
+        const previous = merged;
+        merged = next;
+        for (const listener of [...listeners]) {
+            try {
+                listener(merged, previous);
+            }
+            catch {
+                // One listener's bug is not the view's.
+            }
+        }
+    };
+    const release = (region) => {
+        const entry = held.get(region);
+        if (entry === undefined)
+            return;
+        held.delete(region);
+        entry.stop?.();
+        if (entry.retry !== null)
+            clearTimeout(entry.retry);
+        if (entry.replica !== null)
+            void entry.replica.close().catch(() => undefined);
+        remerge();
+    };
+    const acquire = (region) => {
+        if (held.has(region) || closed)
+            return;
+        const entry = { phase: 'looking', host: null, replica: null, stop: null, retry: null };
+        held.set(region, entry);
+        const later = () => {
+            if (held.get(region) !== entry || closed)
+                return;
+            entry.retry = setTimeout(() => {
+                entry.retry = null;
+                if (held.get(region) !== entry || closed)
+                    return;
+                entry.phase = 'looking';
+                void attempt();
+            }, retryMs);
+            entry.retry.unref?.();
+        };
+        const attempt = async () => {
+            const found = await directory.lookup(region);
+            if (held.get(region) !== entry || closed)
+                return;
+            if (found.status !== 'hosted') {
+                entry.phase = found.status;
+                later();
+                return;
+            }
+            entry.host = found.host;
+            entry.phase = 'joining';
+            const replica = joinStore({
+                definition: options.definition,
+                transport: options.node,
+                host: found.host,
+                store: region,
+                audience: options.audience ?? [],
+                key: options.key,
+                maxEventBytes: options.maxEventBytes,
+            });
+            entry.replica = replica;
+            entry.stop = replica.subscribe(() => {
+                if (held.get(region) === entry && entry.phase === 'ready')
+                    remerge();
+            });
+            try {
+                await replica.ready();
+            }
+            catch {
+                if (held.get(region) !== entry)
+                    return;
+                entry.stop?.();
+                entry.stop = null;
+                entry.replica = null;
+                entry.phase = 'failed';
+                void replica.close().catch(() => undefined);
+                later();
+                return;
+            }
+            if (held.get(region) !== entry || closed) {
+                void replica.close().catch(() => undefined);
+                return;
+            }
+            entry.phase = 'ready';
+            remerge();
+        };
+        void attempt();
+    };
+    const reconcile = () => {
+        const wanted = new Set(regionsAround(position.x, position.z, { size: options.size, radius }));
+        const kept = new Set(regionsAround(position.x, position.z, { size: options.size, radius: radius + 1 }));
+        for (const region of [...held.keys()])
+            if (!kept.has(region))
+                release(region);
+        for (const region of wanted)
+            acquire(region);
+    };
+    reconcile();
+    return {
+        getState: () => merged,
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        setPosition(x, z) {
+            if (closed)
+                return;
+            position = { x, z };
+            reconcile();
+        },
+        currentRegion: () => regionOf(position.x, position.z, options.size),
+        regions: () => [...held].map(([region, entry]) => ({ region, phase: entry.phase, host: entry.host })),
+        act(name, input) {
+            const region = regionOf(position.x, position.z, options.size);
+            const entry = held.get(region);
+            if (entry === undefined || entry.phase !== 'ready' || entry.replica === null) {
+                return Promise.reject(new Error(`region ${region} is not ready (${entry?.phase ?? 'not held'})`));
+            }
+            return entry.replica.act(name, input);
+        },
+        async close() {
+            if (closed)
+                return;
+            closed = true;
+            if (lingerTimer !== null)
+                clearTimeout(lingerTimer);
+            for (const region of [...held.keys()])
+                release(region);
+            listeners.clear();
+        },
+    };
+}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@net-mesh/browser",
+  "version": "0.37.0",
+  "description": "Browser-native Net mesh leaf \u2014 idiomatic TypeScript over the net-mesh-leaf wasm node",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./bundle": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.bundle.js"
+    },
+    "./three": {
+      "types": "./dist/three/index.d.ts",
+      "default": "./dist/three/index.js"
+    },
+    "./local": {
+      "types": "./dist/local.d.ts",
+      "default": "./dist/local.js"
+    },
+    "./netcode": {
+      "types": "./dist/netcode/index.d.ts",
+      "default": "./dist/netcode/index.js"
+    },
+    "./world": {
+      "types": "./dist/world/index.d.ts",
+      "default": "./dist/world/index.js"
+    }
+  },
+  "sideEffects": false,
+  "license": "MIT OR Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ai-2070/net.git"
+  },
+  "keywords": [
+    "net",
+    "mesh",
+    "browser",
+    "webrtc",
+    "datachannel",
+    "wasm",
+    "nrpc",
+    "rust"
+  ],
+  "files": [
+    "dist",
+    "CHANGELOG.md",
+    "LICENSE-APACHE",
+    "LICENSE-MIT"
+  ],
+  "scripts": {
+    "build": "tsc && node scripts/bundle.mjs",
+    "size": "node scripts/size.mjs",
+    "check:package": "node scripts/check-package.mjs",
+    "test": "tsc -p tsconfig.test.json && vitest run",
+    "test:watch": "vitest",
+    "bench:world": "node scripts/bench-world.mjs"
+  },
+  "devDependencies": {
+    "esbuild": "^0.28.0",
+    "typescript": "^6.0.0",
+    "vitest": "^5.0.0"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}