@crowdedkingdoms/crowdyjs 8.3.0 → 8.4.0

package/dist/stores/model.js

@@ -0,0 +1,163 @@
+/**
+ * ContainerMirror — the client half of the platform's **notify-to-pull**
+ * pattern for game-model state: keep typed snapshots of the containers you
+ * care about, re-pull them on demand or whenever a bound channel pings
+ * ("state changed"), and render straight from the cache.
+ *
+ * Model changes are pull-based on this platform (there is no model
+ * subscription); functions declare channel/spatial notifications and clients
+ * re-read. The Game Kit's match layer pings a per-match channel — bind the
+ * mirror to that channel and every watched container refreshes itself.
+ */
+/**
+ * The SDK-managed **model mirror**: typed, cached snapshots of watched
+ * game-model containers with coalesced refresh and channel-ping binding.
+ * Reads are synchronous ({@link get}); {@link onChange} fires only when a
+ * refresh actually changed the visible state.
+ */
+export class ContainerMirror {
+    constructor(ctx, config = {}) {
+        this.ctx = ctx;
+        this.watches = new Map();
+        this.listeners = new Set();
+        this.boundChannels = new Set();
+        this.refreshing = false;
+        this.refreshQueued = false;
+        this.now = config.now ?? Date.now;
+        // One listener serves every bound channel: a ping means "model state
+        // changed somewhere relevant" → coalesced refresh of all watches.
+        ctx.onDispose(ctx.on('channelMessage', (notification) => {
+            if (!this.boundChannels.has(String(notification.channelId)))
+                return;
+            void this.refreshAll();
+        }));
+    }
+    /**
+     * Watch a container: fetches the initial snapshot and keeps it refreshable.
+     * `parse` maps the visible properties object to your type (defaults to the
+     * raw object).
+     */
+    async watch(containerId, parse) {
+        const entry = {
+            parse: parse ?? ((props) => props),
+            snapshot: null,
+            lastSerialized: null,
+        };
+        this.watches.set(containerId, entry);
+        await this.refresh(containerId);
+        return entry.snapshot;
+    }
+    /** Stop watching a container (its snapshot is dropped). */
+    unwatch(containerId) {
+        this.watches.delete(containerId);
+    }
+    /** The current snapshot of a watched container (undefined before watch resolves). */
+    get(containerId) {
+        return (this.watches.get(containerId)?.snapshot ?? undefined);
+    }
+    /** Every watched snapshot. */
+    list() {
+        const out = [];
+        for (const entry of this.watches.values()) {
+            if (entry.snapshot)
+                out.push(entry.snapshot);
+        }
+        return out;
+    }
+    /**
+     * Subscribe to snapshot changes — every watched container, or one
+     * `containerId`. Fires only when a refresh changed the visible state.
+     * @returns off.
+     */
+    onChange(handler, containerId) {
+        const entry = { containerId, handler };
+        this.listeners.add(entry);
+        return () => this.listeners.delete(entry);
+    }
+    /**
+     * Bind a channel: any message on it triggers a coalesced {@link refreshAll}
+     * — pair with model functions that declare channel notifications (e.g. the
+     * Game Kit's `match_changed` pings).
+     */
+    bindToChannel(channelId) {
+        this.boundChannels.add(String(channelId));
+        return () => this.boundChannels.delete(String(channelId));
+    }
+    /** Re-pull one watched container now. */
+    async refresh(containerId) {
+        const entry = this.watches.get(containerId);
+        if (!entry)
+            return;
+        const state = await this.ctx.client.gameModel.containerState({
+            appId: this.ctx.appId,
+            containerId,
+        });
+        let properties;
+        try {
+            properties = JSON.parse(state.propertiesJson);
+        }
+        catch {
+            properties = {};
+        }
+        const serialized = `${state.displayName}|${state.propertiesJson}`;
+        const changed = serialized !== entry.lastSerialized;
+        entry.lastSerialized = serialized;
+        if (!entry.snapshot) {
+            entry.snapshot = {
+                containerId,
+                typeName: state.typeName,
+                displayName: state.displayName,
+                ownerUserId: state.ownerUserId != null ? String(state.ownerUserId) : null,
+                value: entry.parse(properties),
+                revision: 1,
+                refreshedAt: this.now(),
+            };
+        }
+        else {
+            entry.snapshot.refreshedAt = this.now();
+            if (changed) {
+                entry.snapshot.typeName = state.typeName;
+                entry.snapshot.displayName = state.displayName;
+                entry.snapshot.ownerUserId =
+                    state.ownerUserId != null ? String(state.ownerUserId) : null;
+                entry.snapshot.value = entry.parse(properties);
+                entry.snapshot.revision += 1;
+            }
+        }
+        if (changed) {
+            for (const listener of [...this.listeners]) {
+                if (listener.containerId === undefined ||
+                    listener.containerId === containerId) {
+                    listener.handler(entry.snapshot);
+                }
+            }
+        }
+    }
+    /**
+     * Re-pull every watched container. Concurrent calls coalesce: a refresh
+     * requested while one is running queues exactly one follow-up pass (pings
+     * can burst; state converges without stampeding the API).
+     */
+    async refreshAll() {
+        if (this.refreshing) {
+            this.refreshQueued = true;
+            return;
+        }
+        this.refreshing = true;
+        try {
+            do {
+                this.refreshQueued = false;
+                await Promise.all([...this.watches.keys()].map((id) => this.refresh(id).catch(() => {
+                    // A failed pull keeps the previous snapshot; the next ping retries.
+                })));
+            } while (this.refreshQueued);
+        }
+        finally {
+            this.refreshing = false;
+        }
+    }
+}
+/** Attach a {@link ContainerMirror}. Prefer the `model` config key. */
+export function attachContainerMirror(ctx, config = {}) {
+    return new ContainerMirror(ctx, config);
+}

package/dist/stores/session.d.ts

@@ -0,0 +1,119 @@
+/**
+ * The World Session — the wiring hub of the World Stores layer.
+ *
+ * `createWorldSession(client, appId, config)` opens at most ONE
+ * `udpNotifications` subscription and fans every notification out to the
+ * stores you configured (decode once, route everywhere), replacing the
+ * hand-written "NetworkManager singleton" pattern every game rebuilds.
+ * Stores are opt-in twice over: only configured stores are constructed
+ * (runtime), and only imported store modules end up in your bundle
+ * (compile time — the layer lives behind the `@crowdedkingdoms/crowdyjs/stores`
+ * subpath and the core client never imports it).
+ *
+ * Render-loop contract: stores never touch `requestAnimationFrame`. Writes
+ * happen in WebSocket message handlers (not throttled in hidden tabs) and
+ * reads are synchronous snapshots, so a paused render loop simply catches up
+ * on resume. Timer-driven behaviors run on the session {@link Ticker} — pass
+ * `workerTicker()` to keep them at full rate in backgrounded tabs.
+ */
+import type { AvatarsAPI } from '../domains/avatars.js';
+import type { ChunksAPI } from '../domains/chunks.js';
+import type { GameModelAPI } from '../domains/gameModel.js';
+import type { HostAPI } from '../domains/host.js';
+import type { StateAPI } from '../domains/state.js';
+import type { UdpAPI } from '../domains/udp.js';
+import type { UdpNotificationHandlers } from '../realtime.js';
+import { type Ticker } from './ticker.js';
+/**
+ * The sub-clients the stores compose — structurally satisfied by a
+ * `CrowdyClient`, so `createWorldSession(client, appId, ...)` just works;
+ * tests pass stubs.
+ */
+export interface WorldStoresClient {
+    udp: UdpAPI;
+    chunks: ChunksAPI;
+    state: StateAPI;
+    avatars: AvatarsAPI;
+    host: HostAPI;
+    gameModel: GameModelAPI;
+}
+/** The kinds of outbound sends the session can attribute errors to. */
+export type SentPacketKind = 'actorUpdate' | 'voxelUpdate' | 'text' | 'clientEvent' | 'audio' | 'singleActorMessage' | 'channelMessage';
+/** A record of one outbound send, kept so errors can be attributed. */
+export interface SentPacketRecord {
+    kind: SentPacketKind;
+    sequenceNumber: number;
+    sentAt: number;
+    /** The sending actor uuid, when the send had one. */
+    uuid?: string;
+    /** Optional app-relevant detail (voxel coords, channel id, …). */
+    detail?: Record<string, unknown>;
+}
+/** A listener registration on the session's notification bus. */
+export type BusKey = keyof UdpNotificationHandlers;
+/**
+ * The internal context handed to each store: the shared notification bus
+ * (lazy single subscription), the shared ticker, send tracking, and the
+ * domains. Exposed for custom store implementations; regular apps never
+ * touch it.
+ */
+export interface WorldSessionContext {
+    readonly appId: string;
+    readonly client: WorldStoresClient;
+    readonly ticker: Ticker;
+    /**
+     * Listen for one notification kind. The first listener opens the shared
+     * `udpNotifications` subscription; disposing the session closes it.
+     * @returns An off function for this listener.
+     */
+    on<K extends BusKey>(key: K, listener: NonNullable<UdpNotificationHandlers[K]>): () => void;
+    /**
+     * Record an outbound send so a later `GenericErrorResponse` with the same
+     * `sequenceNumber` can be attributed (consumed by the error store; a no-op
+     * until one registers).
+     */
+    trackSend(record: SentPacketRecord): void;
+    /** Replace the send-tracking sink (registered by the error store). */
+    setSendTracker(sink: (record: SentPacketRecord) => void): void;
+    /** Register cleanup to run on session dispose. */
+    onDispose(cleanup: () => void): void;
+}
+/**
+ * The session core: one lazy subscription, a per-kind listener registry, a
+ * shared ticker, send tracking, and dispose. Store modules build on this via
+ * their `attach*` factories; `createWorldSession` composes them.
+ */
+export declare class WorldSessionCore implements WorldSessionContext {
+    readonly appId: string;
+    readonly client: WorldStoresClient;
+    readonly ticker: Ticker;
+    private readonly listeners;
+    private readonly cleanups;
+    private unsubscribe;
+    private sendTracker;
+    private readonly ownsTicker;
+    private disposed;
+    constructor(client: WorldStoresClient, appId: string, ticker?: Ticker);
+    on<K extends BusKey>(key: K, listener: NonNullable<UdpNotificationHandlers[K]>): () => void;
+    trackSend(record: SentPacketRecord): void;
+    setSendTracker(sink: (record: SentPacketRecord) => void): void;
+    onDispose(cleanup: () => void): void;
+    /** Close the subscription, cancel timers, and run store cleanups. */
+    dispose(): void;
+    /** Open the single shared subscription on first listener. */
+    private ensureSubscribed;
+}
+/**
+ * Base configuration every session accepts; store-specific keys are added by
+ * the store modules (see `createWorldSession` in `stores/index.ts`).
+ */
+export interface WorldSessionBaseConfig {
+    /**
+     * Scheduler for timer-driven store behaviors (send loop, reaping,
+     * write-back, heartbeats). Defaults to `intervalTicker()`; pass
+     * `workerTicker()` to keep full rate in backgrounded browser tabs. A
+     * caller-supplied ticker is NOT disposed with the session.
+     */
+    ticker?: Ticker;
+}
+//# sourceMappingURL=session.d.ts.map

package/dist/stores/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/stores/session.ts"],"names":[],"mappings":"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"}

package/dist/stores/session.js

@@ -0,0 +1,116 @@
+/**
+ * The World Session — the wiring hub of the World Stores layer.
+ *
+ * `createWorldSession(client, appId, config)` opens at most ONE
+ * `udpNotifications` subscription and fans every notification out to the
+ * stores you configured (decode once, route everywhere), replacing the
+ * hand-written "NetworkManager singleton" pattern every game rebuilds.
+ * Stores are opt-in twice over: only configured stores are constructed
+ * (runtime), and only imported store modules end up in your bundle
+ * (compile time — the layer lives behind the `@crowdedkingdoms/crowdyjs/stores`
+ * subpath and the core client never imports it).
+ *
+ * Render-loop contract: stores never touch `requestAnimationFrame`. Writes
+ * happen in WebSocket message handlers (not throttled in hidden tabs) and
+ * reads are synchronous snapshots, so a paused render loop simply catches up
+ * on resume. Timer-driven behaviors run on the session {@link Ticker} — pass
+ * `workerTicker()` to keep them at full rate in backgrounded tabs.
+ */
+import { intervalTicker } from './ticker.js';
+/** All handler keys the fan-out dispatches (mirrors {@link UdpNotificationHandlers}). */
+const BUS_KEYS = [
+    'actorUpdate',
+    'actorUpdateResponse',
+    'voxelUpdate',
+    'voxelUpdateResponse',
+    'audio',
+    'text',
+    'clientEvent',
+    'serverEvent',
+    'singleActorMessage',
+    'channelMessage',
+    'genericError',
+    'connectionEvent',
+    'any',
+    'error',
+];
+/**
+ * The session core: one lazy subscription, a per-kind listener registry, a
+ * shared ticker, send tracking, and dispose. Store modules build on this via
+ * their `attach*` factories; `createWorldSession` composes them.
+ */
+export class WorldSessionCore {
+    constructor(client, appId, ticker) {
+        this.listeners = new Map();
+        this.cleanups = [];
+        this.unsubscribe = null;
+        this.sendTracker = null;
+        this.disposed = false;
+        this.client = client;
+        this.appId = appId;
+        this.ownsTicker = ticker === undefined;
+        this.ticker = ticker ?? intervalTicker();
+    }
+    on(key, listener) {
+        let set = this.listeners.get(key);
+        if (!set) {
+            set = new Set();
+            this.listeners.set(key, set);
+        }
+        set.add(listener);
+        this.ensureSubscribed();
+        return () => {
+            set.delete(listener);
+        };
+    }
+    trackSend(record) {
+        this.sendTracker?.(record);
+    }
+    setSendTracker(sink) {
+        this.sendTracker = sink;
+    }
+    onDispose(cleanup) {
+        this.cleanups.push(cleanup);
+    }
+    /** Close the subscription, cancel timers, and run store cleanups. */
+    dispose() {
+        if (this.disposed)
+            return;
+        this.disposed = true;
+        for (const cleanup of this.cleanups.splice(0)) {
+            try {
+                cleanup();
+            }
+            catch {
+                // Cleanup must never mask other cleanups.
+            }
+        }
+        this.unsubscribe?.();
+        this.unsubscribe = null;
+        this.listeners.clear();
+        if (this.ownsTicker)
+            this.ticker.dispose();
+    }
+    /** Open the single shared subscription on first listener. */
+    ensureSubscribed() {
+        if (this.unsubscribe || this.disposed)
+            return;
+        const handlers = {};
+        for (const key of BUS_KEYS) {
+            handlers[key] = (notification) => {
+                const set = this.listeners.get(key);
+                if (!set)
+                    return;
+                for (const listener of [...set]) {
+                    try {
+                        listener(notification);
+                    }
+                    catch {
+                        // One listener's throw must not starve the others.
+                    }
+                }
+            };
+        }
+        this.unsubscribe = this.client.udp.subscribe(handlers, this.appId);
+    }
+}

package/dist/stores/ticker.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The scheduler behind every timer-driven store behavior (the actor send
+ * loop, stale reaping, chunk write-back throttling, the host heartbeat).
+ *
+ * Why an abstraction: browsers throttle main-thread timers in hidden tabs
+ * (≥1 s immediately, down to ~1/minute under intensive throttling), which
+ * would silently drop a backgrounded player's presence rate. Timers inside a
+ * **dedicated Web Worker are exempt**, so games that need full-rate sends
+ * while backgrounded pass {@link workerTicker} to `createWorldSession`;
+ * everything else defaults to {@link intervalTicker}. Tests drive stores
+ * deterministically with {@link manualTicker}.
+ *
+ * (WebSocket message delivery is NOT throttled in hidden tabs, so inbound
+ * store updates flow regardless of the ticker choice.)
+ */
+/** A cancellable repeating-callback scheduler. */
+export interface Ticker {
+    /**
+     * Invoke `callback` every `intervalMs` until cancelled.
+     * @returns A cancel function for this schedule.
+     */
+    every(intervalMs: number, callback: () => void): () => void;
+    /** Cancel every schedule and release resources (e.g. terminate the worker). */
+    dispose(): void;
+}
+/** Plain `setInterval` ticker — the default. Subject to background-tab throttling. */
+export declare function intervalTicker(): Ticker;
+/**
+ * A ticker whose intervals run inside an inline dedicated Web Worker —
+ * exempt from background-tab timer throttling, so a hidden tab keeps
+ * sending presence at full rate. Falls back to {@link intervalTicker} in
+ * runtimes without `Worker`/`Blob` support (Node, SSR).
+ */
+export declare function workerTicker(): Ticker;
+/** A {@link manualTicker}: time only moves when the test calls `advance`. */
+export interface ManualTicker extends Ticker {
+    /** Advance virtual time, firing due callbacks (repeatedly, in due order). */
+    advance(ms: number): void;
+    /** The current virtual time in ms. */
+    readonly now: number;
+}
+/** Deterministic ticker for tests — no real timers. */
+export declare function manualTicker(): ManualTicker;
+//# sourceMappingURL=ticker.d.ts.map

package/dist/stores/ticker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ticker.d.ts","sourceRoot":"","sources":["../../src/stores/ticker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,kDAAkD;AAClD,MAAM,WAAW,MAAM;IACrB;;;OAGG;IACH,KAAK,CAAC,UAAU,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;IAC5D,+EAA+E;IAC/E,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,sFAAsF;AACtF,wBAAgB,cAAc,IAAI,MAAM,CAgBvC;AAeD;;;;;GAKG;AACH,wBAAgB,YAAY,IAAI,MAAM,CA6CrC;AAED,6EAA6E;AAC7E,MAAM,WAAW,YAAa,SAAQ,MAAM;IAC1C,6EAA6E;IAC7E,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,sCAAsC;IACtC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,uDAAuD;AACvD,wBAAgB,YAAY,IAAI,YAAY,CAuC3C"}

package/dist/stores/ticker.js

@@ -0,0 +1,127 @@
+/**
+ * The scheduler behind every timer-driven store behavior (the actor send
+ * loop, stale reaping, chunk write-back throttling, the host heartbeat).
+ *
+ * Why an abstraction: browsers throttle main-thread timers in hidden tabs
+ * (≥1 s immediately, down to ~1/minute under intensive throttling), which
+ * would silently drop a backgrounded player's presence rate. Timers inside a
+ * **dedicated Web Worker are exempt**, so games that need full-rate sends
+ * while backgrounded pass {@link workerTicker} to `createWorldSession`;
+ * everything else defaults to {@link intervalTicker}. Tests drive stores
+ * deterministically with {@link manualTicker}.
+ *
+ * (WebSocket message delivery is NOT throttled in hidden tabs, so inbound
+ * store updates flow regardless of the ticker choice.)
+ */
+/** Plain `setInterval` ticker — the default. Subject to background-tab throttling. */
+export function intervalTicker() {
+    const handles = new Set();
+    return {
+        every(intervalMs, callback) {
+            const handle = setInterval(callback, intervalMs);
+            handles.add(handle);
+            return () => {
+                clearInterval(handle);
+                handles.delete(handle);
+            };
+        },
+        dispose() {
+            for (const handle of handles)
+                clearInterval(handle);
+            handles.clear();
+        },
+    };
+}
+const WORKER_SOURCE = `
+const timers = new Map();
+self.onmessage = (event) => {
+  const { id, intervalMs, cancel } = event.data;
+  if (cancel) {
+    const handle = timers.get(id);
+    if (handle !== undefined) { clearInterval(handle); timers.delete(id); }
+    return;
+  }
+  timers.set(id, setInterval(() => self.postMessage({ id }), intervalMs));
+};
+`;
+/**
+ * A ticker whose intervals run inside an inline dedicated Web Worker —
+ * exempt from background-tab timer throttling, so a hidden tab keeps
+ * sending presence at full rate. Falls back to {@link intervalTicker} in
+ * runtimes without `Worker`/`Blob` support (Node, SSR).
+ */
+export function workerTicker() {
+    const g = globalThis;
+    if (!g.Worker || !g.Blob || !g.URL?.createObjectURL) {
+        return intervalTicker();
+    }
+    const url = g.URL.createObjectURL(new g.Blob([WORKER_SOURCE], { type: 'application/javascript' }));
+    let worker;
+    try {
+        worker = new g.Worker(url);
+    }
+    catch {
+        g.URL.revokeObjectURL(url);
+        return intervalTicker();
+    }
+    const callbacks = new Map();
+    let nextId = 1;
+    worker.onmessage = (event) => {
+        callbacks.get(event.data.id)?.();
+    };
+    return {
+        every(intervalMs, callback) {
+            if (!worker)
+                return () => { };
+            const id = nextId++;
+            callbacks.set(id, callback);
+            worker.postMessage({ id, intervalMs });
+            return () => {
+                callbacks.delete(id);
+                worker?.postMessage({ id, cancel: true });
+            };
+        },
+        dispose() {
+            callbacks.clear();
+            worker?.terminate();
+            worker = null;
+            g.URL?.revokeObjectURL(url);
+        },
+    };
+}
+/** Deterministic ticker for tests — no real timers. */
+export function manualTicker() {
+    const tasks = new Set();
+    let now = 0;
+    return {
+        get now() {
+            return now;
+        },
+        every(intervalMs, callback) {
+            const task = { intervalMs, callback, nextAt: now + intervalMs };
+            tasks.add(task);
+            return () => tasks.delete(task);
+        },
+        advance(ms) {
+            const end = now + ms;
+            // Fire tasks in due order until none are due before `end`.
+            for (;;) {
+                let next = null;
+                for (const task of tasks) {
+                    if (task.nextAt <= end && (next === null || task.nextAt < next.nextAt)) {
+                        next = task;
+                    }
+                }
+                if (!next)
+                    break;
+                now = next.nextAt;
+                next.nextAt += next.intervalMs;
+                next.callback();
+            }
+            now = end;
+        },
+        dispose() {
+            tasks.clear();
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crowdedkingdoms/crowdyjs",
-  "version": "8.3.0",
+  "version": "8.4.0",
   "description": "Client SDK for Crowded Kingdoms GraphQL API with UDP proxy support",
   "type": "module",
   "main": "dist/index.js",
@@ -13,8 +13,13 @@
     "./generated": {
       "import": "./dist/generated/graphql.js",
       "types": "./dist/generated/graphql.d.ts"
+    },
+    "./stores": {
+      "import": "./dist/stores/index.js",
+      "types": "./dist/stores/index.d.ts"
     }
   },
+  "sideEffects": false,
   "files": [
     "dist",
     "README.md",