@my-swu/simulator-client 0.1.0

package/dist/local/client.js

@@ -0,0 +1,211 @@
+/**
+ * Main-thread half of the local transport: a `FetchLike` + `WebSocketFactory`
+ * pair backed by the engine worker. Injecting these into
+ * `createSimulatorClient` lights up the entire existing SDK (resources,
+ * `MatchSession`, reconnect) against the in-browser engine with zero changes.
+ */
+/**
+ * Creates the transport over a running engine worker (or a test double).
+ */
+export function createWorkerTransport(port) {
+    let nextId = 1;
+    let nextChannelId = 1;
+    const pending = new Map();
+    const sockets = new Map();
+    const rejectAll = (message) => {
+        for (const entry of pending.values()) {
+            entry.reject(new Error(message));
+        }
+        pending.clear();
+    };
+    /** Fails every established socket so the UI transitions instead of freezing. */
+    const failAllSockets = (message) => {
+        for (const socket of [...sockets.values()]) {
+            socket.handle({ kind: 'wsFailed', channelId: 0, message });
+        }
+        sockets.clear();
+    };
+    const onError = (event) => {
+        const message = `engine worker failed: ${event?.message ?? 'unknown error'}`;
+        rejectAll(message);
+        failAllSockets(message);
+    };
+    const onMessage = (event) => {
+        const response = event.data;
+        // A negative id is the worker's global failure signal (module or wasm
+        // init failed before any request could be served).
+        if (response.kind === 'error' && response.id < 0) {
+            rejectAll(response.message);
+            failAllSockets(response.message);
+            return;
+        }
+        switch (response.kind) {
+            case 'ok': {
+                const entry = pending.get(response.id);
+                if (entry?.kind === 'plain') {
+                    pending.delete(response.id);
+                    entry.resolve({ status: response.status, body: response.body });
+                }
+                break;
+            }
+            case 'error': {
+                const entry = pending.get(response.id);
+                if (entry) {
+                    pending.delete(response.id);
+                    entry.reject(new Error(response.message));
+                }
+                break;
+            }
+            case 'saved': {
+                const entry = pending.get(response.id);
+                if (entry?.kind === 'saved') {
+                    pending.delete(response.id);
+                    entry.resolve({
+                        matchId: response.matchId,
+                        seatToken: response.seatToken,
+                        bytes: response.bytes,
+                    });
+                }
+                break;
+            }
+            case 'wsOpened':
+            case 'wsMessage':
+            case 'wsClosed':
+            case 'wsFailed': {
+                sockets.get(response.channelId)?.handle(response);
+                break;
+            }
+        }
+    };
+    port.addEventListener('message', onMessage);
+    port.addEventListener('error', onError);
+    const post = (request, transfer) => {
+        port.postMessage(request, transfer);
+    };
+    const call = (request, transfer) => new Promise((resolve, reject) => {
+        pending.set(request.id, { resolve, reject, kind: 'plain' });
+        post(request, transfer);
+    });
+    const fetchLike = async (input, init) => {
+        const url = typeof input === 'string' ? input : input instanceof URL ? input.toString() : input.url;
+        const parsed = new URL(url);
+        const method = init?.method ?? 'GET';
+        const body = typeof init?.body === 'string' ? init.body : undefined;
+        const result = await call({
+            kind: 'http',
+            id: nextId++,
+            method,
+            path: `${parsed.pathname}${parsed.search}`,
+            body,
+        });
+        return new Response(result.body, {
+            status: result.status ?? 200,
+            headers: { 'content-type': 'application/json' },
+        });
+    };
+    const webSocketFactory = (url, protocols) => {
+        const channelId = nextChannelId++;
+        const socket = new LocalWebSocket(channelId, () => sockets.delete(channelId), post);
+        sockets.set(channelId, socket);
+        post({
+            kind: 'wsOpen',
+            channelId,
+            url,
+            protocols: protocols == null ? [] : Array.isArray(protocols) ? protocols : [protocols],
+        });
+        return socket;
+    };
+    return {
+        fetch: fetchLike,
+        webSocketFactory,
+        init: async (wasmBytes, glueSource, catalogBytes) => {
+            const result = await call({ kind: 'init', id: nextId++, wasmBytes, glueSource, catalogBytes }, [wasmBytes, catalogBytes]);
+            return result.body ?? '';
+        },
+        applyCatalogSync: async (catalogSyncJson) => {
+            await call({ kind: 'syncCatalog', id: nextId++, catalogSyncJson });
+        },
+        saveRecord: () => new Promise((resolve, reject) => {
+            const id = nextId++;
+            pending.set(id, { resolve, reject, kind: 'saved' });
+            post({ kind: 'saveRecord', id });
+        }),
+        restoreRecord: async (bytes) => {
+            const result = await call({ kind: 'restoreRecord', id: nextId++, bytes }, [bytes]);
+            if (!result.body) {
+                throw new Error('restoreRecord returned no access info');
+            }
+            return JSON.parse(result.body);
+        },
+        dispose: () => {
+            port.removeEventListener('message', onMessage);
+            port.removeEventListener('error', onError);
+            rejectAll('local transport disposed');
+            for (const [channelId, socket] of [...sockets.entries()]) {
+                // Tell the worker so its scheduler stops ticking the AI.
+                post({ kind: 'wsClose', channelId });
+                socket.handle({ kind: 'wsClosed', channelId, code: 1001, reason: 'transport disposed' });
+            }
+            sockets.clear();
+        },
+    };
+}
+/** DOM-style `EngineWebSocket` over one worker channel. */
+class LocalWebSocket {
+    #channelId;
+    #detach;
+    #post;
+    #listeners = new Map();
+    constructor(channelId, detach, post) {
+        this.#channelId = channelId;
+        this.#detach = detach;
+        this.#post = post;
+    }
+    addEventListener(type, listener) {
+        let set = this.#listeners.get(type);
+        if (!set) {
+            set = new Set();
+            this.#listeners.set(type, set);
+        }
+        set.add(listener);
+    }
+    removeEventListener(type, listener) {
+        this.#listeners.get(type)?.delete(listener);
+    }
+    send(data) {
+        this.#post({ kind: 'wsSend', channelId: this.#channelId, data });
+    }
+    close(code, reason) {
+        this.#post({ kind: 'wsClose', channelId: this.#channelId });
+        // Real WebSockets fire `close` asynchronously; matching that keeps
+        // still-attached listeners from re-entering inside the caller's stack.
+        queueMicrotask(() => {
+            this.handle({ kind: 'wsClosed', channelId: this.#channelId, code, reason });
+        });
+    }
+    /** Dispatches one worker frame as a DOM-style event. */
+    handle(response) {
+        switch (response.kind) {
+            case 'wsOpened':
+                this.#emit('open', {});
+                break;
+            case 'wsMessage':
+                this.#emit('message', { data: response.data });
+                break;
+            case 'wsFailed':
+                this.#emit('error', { message: response.message });
+                this.#emit('close', { code: 1006, reason: response.message });
+                this.#detach();
+                break;
+            case 'wsClosed':
+                this.#emit('close', { code: response.code ?? 1000, reason: response.reason ?? '' });
+                this.#detach();
+                break;
+        }
+    }
+    #emit(type, event) {
+        for (const listener of this.#listeners.get(type) ?? []) {
+            listener(event);
+        }
+    }
+}

package/dist/local/engine.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Typed contract over the `swu-wasm` module, so the in-worker server
+ * ({@link createLocalEngineServer}) is testable with a scripted fake engine
+ * and never imports wasm glue directly.
+ */
+/** One ordered outbound wire batch produced by the Rust host. */
+export interface LocalWireBatch {
+    /** Milliseconds to wait before sending this batch's messages. */
+    delayBeforeMs: number;
+    /** `ServerMessage` values, pre-serialized member by member on send. */
+    messages: unknown[];
+}
+/** Result of one AI tick. */
+export interface LocalAiTick {
+    batches: LocalWireBatch[];
+    moreWork: boolean;
+}
+/** One live offline match inside the engine. */
+export interface LocalEngineMatch {
+    matchId: string;
+    seatToken: string;
+    /** `ServerMessage[]` handshake for a fresh connection. */
+    connect: () => unknown[];
+    /** Applies one `ClientMessage` JSON string; returns ordered batches. */
+    handleMessage: (seatToken: string, messageJson: string, nowMs: number) => LocalWireBatch[];
+    aiHasWork: () => boolean;
+    tickAi: (nowMs: number) => LocalAiTick;
+    /** Server-compatible `MatchSavePayload` JSON. */
+    save: () => string;
+    /** Full local record bytes (undo + feed) for reload persistence. */
+    toRecordBytes: () => Uint8Array;
+    /** Viewer-projected `GameState` JSON. */
+    snapshot: () => string;
+}
+/** One offline limited lobby inside the engine. */
+export interface LocalEngineLobby {
+    lobbyId: string;
+    /** Throws when the token is not the host's player token. */
+    authorize: (playerToken: string) => void;
+    /** All lobby mutators return `LobbyAccessResponse` JSON. */
+    addAiPlayer: (difficulty: string) => string;
+    setHostReady: (ready: boolean) => string;
+    start: (nowMs: number) => string;
+    /** `LimitedEventResponse` JSON (advances AI picks first). */
+    eventSnapshot: (seatToken: string | null, nowMs: number) => string;
+    eventApplyCommand: (seatToken: string, commandJson: string, nowMs: number) => string;
+    submitLimitedDeck: (requestJson: string) => string;
+    prepareLimitedAiDecks: () => string;
+    /** `CreateMatchRequest` JSON for the pod's two-player match. */
+    limitedMatchRequest: () => string;
+    storeStartedMatch: (accessJson: string) => string;
+    accessJson: () => string;
+}
+/** The engine capabilities the local server needs. */
+export interface LocalSimulatorEngine {
+    /** Installs the card catalog. Must be called before anything else. */
+    install: (catalogBytes: Uint8Array) => void;
+    /** Replaces dynamic app catalog metadata for future local validation. */
+    applyCatalogSync: (catalogSyncJson: string) => void;
+    /** Creates a match from `CreateMatchRequest` JSON; returns access JSON. */
+    createMatch: (requestJson: string, nowMs: number) => {
+        match: LocalEngineMatch;
+        accessJson: string;
+    };
+    /** Restores a match from local record bytes. */
+    restoreRecord: (bytes: Uint8Array) => LocalEngineMatch;
+    /** `CardsResponse` JSON for the requested card ids. */
+    cardsGet: (ids: number[]) => string;
+    /** `LimitedEventPreflightResponse` JSON without retaining state. */
+    preflightLimitedEvent: (requestJson: string) => string;
+    /** Creates an offline limited lobby from `CreateLobbyRequest` JSON. */
+    createLobby: (requestJson: string) => {
+        lobby: LocalEngineLobby;
+        accessJson: string;
+    };
+    /** Difficulty ids the offline UI may offer. */
+    offlineDifficulties: () => string[];
+    engineVersion: () => string;
+}

package/dist/local/engine.js

@@ -0,0 +1,6 @@
+/**
+ * Typed contract over the `swu-wasm` module, so the in-worker server
+ * ({@link createLocalEngineServer}) is testable with a scripted fake engine
+ * and never imports wasm glue directly.
+ */
+export {};

package/dist/local/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Offline (in-browser) engine transport for the simulator SDK.
+ *
+ * `createWorkerTransport` runs on the main thread and produces the
+ * `fetch`/`webSocketFactory` pair to inject into `createSimulatorClient`;
+ * `createLocalEngineServer` runs inside the engine worker (see `worker.ts`).
+ */
+export type { LocalAiTick, LocalEngineLobby, LocalEngineMatch, LocalSimulatorEngine, LocalWireBatch } from './engine.js';
+export type { LocalEngineRequest, LocalEngineResponse, WorkerLike } from './protocol.js';
+export { createWorkerTransport } from './client.js';
+export type { WorkerTransport } from './client.js';
+export { createLocalEngineServer } from './server/index.js';
+export type { LocalEngineWorkerBootOptions } from './worker-boot.js';
+export { bootLocalEngineWorker } from './worker-boot.js';
+export type { SwuWasmModule } from './wasm-engine.js';
+export { createWasmEngine } from './wasm-engine.js';
+export type { OfflineEngineHost, OfflineEngineHostOptions, OfflineEngineWorker } from './offline-engine.js';
+export { createOfflineEngineHost } from './offline-engine.js';
+export * from './assets.js';
+export * from './routing.js';

package/dist/local/index.js

@@ -0,0 +1,17 @@
+/**
+ * Offline (in-browser) engine transport for the simulator SDK.
+ *
+ * `createWorkerTransport` runs on the main thread and produces the
+ * `fetch`/`webSocketFactory` pair to inject into `createSimulatorClient`;
+ * `createLocalEngineServer` runs inside the engine worker (see `worker.ts`).
+ */
+export { createWorkerTransport } from './client.js';
+export { createLocalEngineServer } from './server/index.js';
+export { bootLocalEngineWorker } from './worker-boot.js';
+export { createWasmEngine } from './wasm-engine.js';
+export { createOfflineEngineHost } from './offline-engine.js';
+// Assets + routing also have their own light subpath exports
+// (`./local/assets`, `./local/routing`) for boot-time imports that must not
+// pull this barrel's transport/server modules.
+export * from './assets.js';
+export * from './routing.js';

package/dist/local/offline-engine.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Offline engine host: owns the engine worker lifecycle (spawn, init with
+ * cached assets, save/restore, teardown) behind one object so consumers only
+ * wire UI state. The app-side composable is a thin reactive wrapper.
+ */
+import type { WorkerTransport } from './client.js';
+import type { EngineAssetBytes } from './assets.js';
+import type { WorkerLike } from './protocol.js';
+/** A spawned engine worker (the DOM `Worker`, or a test double). */
+export interface OfflineEngineWorker extends WorkerLike {
+    terminate?: () => void;
+}
+export interface OfflineEngineHostOptions {
+    /** Spawns the engine worker (the caller owns the module URL). */
+    createWorker: () => OfflineEngineWorker;
+    /** Reads the cached engine assets for the init frame. */
+    loadAssets: () => Promise<EngineAssetBytes>;
+    /** Reads current or cached app-owned catalog metadata for the worker. */
+    loadCatalogSync: () => Promise<string>;
+    /** Observes running-state flips (drive routing flags / UI refs). */
+    onRunningChange?: ((running: boolean) => void) | undefined;
+}
+export interface OfflineEngineHost {
+    /** The transport bound to the running worker (boots it on demand). */
+    ensureTransport: () => Promise<WorkerTransport>;
+    /** Whether the worker is up and the engine installed. */
+    isRunning: () => boolean;
+    /** Saves the active local match's record bytes (`null` when not running). */
+    saveActiveRecord: () => Promise<{
+        matchId: string;
+        seatToken: string;
+        bytes: ArrayBuffer;
+    } | null>;
+    /** Restores a match from record bytes before reconnecting to it. */
+    restoreRecord: (bytes: ArrayBuffer) => Promise<{
+        matchId: string;
+        seatToken: string;
+    }>;
+    /** Terminates the worker and drops all live matches. */
+    shutdown: () => void;
+}
+/**
+ * Creates the host. One instance per app; each `shutdown` + `ensureTransport`
+ * cycle spawns a fresh worker.
+ */
+export declare function createOfflineEngineHost(options: OfflineEngineHostOptions): OfflineEngineHost;

package/dist/local/offline-engine.js

@@ -0,0 +1,74 @@
+/**
+ * Offline engine host: owns the engine worker lifecycle (spawn, init with
+ * cached assets, save/restore, teardown) behind one object so consumers only
+ * wire UI state. The app-side composable is a thin reactive wrapper.
+ */
+import { createWorkerTransport } from './client.js';
+/**
+ * Creates the host. One instance per app; each `shutdown` + `ensureTransport`
+ * cycle spawns a fresh worker.
+ */
+export function createOfflineEngineHost(options) {
+    let worker = null;
+    let transport = null;
+    let running = false;
+    let initPromise = null;
+    const setRunning = (next) => {
+        if (running !== next) {
+            running = next;
+            options.onRunningChange?.(next);
+        }
+    };
+    /** Applies latest app-owned metadata without changing any running local match. */
+    async function syncCatalog(activeTransport) {
+        await activeTransport.applyCatalogSync(await options.loadCatalogSync());
+    }
+    function shutdown() {
+        transport?.dispose();
+        worker?.terminate?.();
+        transport = null;
+        worker = null;
+        setRunning(false);
+    }
+    async function ensureTransport() {
+        if (transport && running) {
+            await syncCatalog(transport);
+            return transport;
+        }
+        if (initPromise) {
+            return await initPromise;
+        }
+        initPromise = (async () => {
+            const assets = await options.loadAssets();
+            worker = options.createWorker();
+            transport = createWorkerTransport(worker);
+            await transport.init(assets.wasmBytes, assets.glueSource, assets.catalogBytes);
+            await syncCatalog(transport);
+            setRunning(true);
+            return transport;
+        })()
+            .catch((error) => {
+            shutdown();
+            throw error;
+        })
+            .finally(() => {
+            initPromise = null;
+        });
+        return await initPromise;
+    }
+    return {
+        ensureTransport,
+        isRunning: () => running,
+        saveActiveRecord: async () => {
+            if (!transport || !running) {
+                return null;
+            }
+            return await transport.saveRecord();
+        },
+        restoreRecord: async (bytes) => {
+            const activeTransport = await ensureTransport();
+            return await activeTransport.restoreRecord(bytes);
+        },
+        shutdown,
+    };
+}

package/dist/local/protocol.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Structured-clone-safe RPC frames between the main-thread local transport
+ * ({@link createWorkerTransport}) and the engine worker
+ * ({@link createLocalEngineServer}).
+ *
+ * The transport impersonates the Crucible server at the HTTP-route and
+ * WebSocket-envelope level, so payloads are always JSON strings of the same
+ * generated protocol types the network path uses.
+ */
+/** Main-thread → worker request frames. */
+export type LocalEngineRequest = {
+    kind: 'init';
+    id: number;
+    /** Raw bytes of `swu_wasm_bg.wasm` (compiled in the worker). */
+    wasmBytes: ArrayBuffer;
+    /** wasm-bindgen ES module source served with the matching wasm binary. */
+    glueSource: string;
+    /** Decompressed bytes of `card_catalog.v1.json`. */
+    catalogBytes: ArrayBuffer;
+} | {
+    kind: 'http';
+    id: number;
+    method: string;
+    /** Path + query, e.g. `/api/matches` or `/api/cards?ids=1,2`. */
+    path: string;
+    /** JSON request body, when the method carries one. */
+    body?: string | undefined;
+} | {
+    /** Replaces app-owned dynamic catalog metadata after static catalog installs. */
+    kind: 'syncCatalog';
+    id: number;
+    catalogSyncJson: string;
+} | {
+    kind: 'wsOpen';
+    channelId: number;
+    /** Socket URL as built by the SDK (`…/ws/{matchId}`). */
+    url: string;
+    /** Subprotocol list carrying the auth token off-URL. */
+    protocols: string[];
+} | {
+    kind: 'wsSend';
+    channelId: number;
+    data: string;
+} | {
+    kind: 'wsClose';
+    channelId: number;
+} | {
+    /** Serializes the active match's full local record for persistence. */
+    kind: 'saveRecord';
+    id: number;
+} | {
+    /** Restores a match from record bytes before any socket attaches. */
+    kind: 'restoreRecord';
+    id: number;
+    bytes: ArrayBuffer;
+};
+/** Worker → main-thread response/event frames. */
+export type LocalEngineResponse = {
+    kind: 'ok';
+    id: number;
+    status?: number | undefined;
+    body?: string | undefined;
+} | {
+    kind: 'error';
+    id: number;
+    message: string;
+} | {
+    kind: 'saved';
+    id: number;
+    matchId: string;
+    seatToken: string;
+    bytes: ArrayBuffer;
+} | {
+    kind: 'wsOpened';
+    channelId: number;
+} | {
+    kind: 'wsMessage';
+    channelId: number;
+    data: string;
+} | {
+    kind: 'wsClosed';
+    channelId: number;
+    code?: number | undefined;
+    reason?: string | undefined;
+} | {
+    kind: 'wsFailed';
+    channelId: number;
+    message: string;
+};
+/** Minimal message-port shape shared by `Worker` and test doubles. */
+export interface WorkerLike {
+    postMessage: (message: unknown, transfer?: Transferable[]) => void;
+    addEventListener: (type: 'message' | 'error', listener: (event: any) => void) => void;
+    removeEventListener: (type: 'message' | 'error', listener: (event: any) => void) => void;
+}

package/dist/local/protocol.js

@@ -0,0 +1,10 @@
+/**
+ * Structured-clone-safe RPC frames between the main-thread local transport
+ * ({@link createWorkerTransport}) and the engine worker
+ * ({@link createLocalEngineServer}).
+ *
+ * The transport impersonates the Crucible server at the HTTP-route and
+ * WebSocket-envelope level, so payloads are always JSON strings of the same
+ * generated protocol types the network path uses.
+ */
+export {};

package/dist/local/routing.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Routing transport: network by default, the in-browser engine for offline
+ * matches. Injectable into `createSimulatorClient` as its `fetch` +
+ * `webSocketFactory`.
+ *
+ * Routing rules, in order:
+ * 1. `/api/availability` is ALWAYS network — it describes the real backend.
+ * 2. Requests inside a `runWithLocalScope` callback go local (how offline
+ *    match/lobby creation is opted in).
+ * 3. Requests whose path references a registered local id go local — covers
+ *    every post-create call including reconnect after a page reload.
+ * 4. `/api/cards*` goes local while the engine is running (offline metadata).
+ * 5. Everything else is network.
+ *
+ * This module must stay light: it lazily receives the heavy transport via
+ * `loadLocalTransport`, so the online path never loads the engine chunk.
+ */
+import type { EngineWebSocket, FetchLike, WebSocketFactory } from '../internal/transport.js';
+/** The engine-backed transport pair, loaded lazily on first local request. */
+export interface LocalTransportPair {
+    fetch: FetchLike;
+    webSocketFactory: WebSocketFactory;
+}
+export interface RoutingTransportOptions {
+    /** Lazily resolves the local transport (the only edge into the engine chunk). */
+    loadLocalTransport: () => Promise<LocalTransportPair>;
+    /** Network fetch (defaults to the global). */
+    networkFetch?: FetchLike | undefined;
+    /** Network socket factory (defaults to `new WebSocket`). */
+    createNetworkSocket?: ((url: string, protocols?: string | string[]) => EngineWebSocket) | undefined;
+}
+export interface RoutingTransport {
+    fetch: FetchLike;
+    webSocketFactory: WebSocketFactory;
+    /** Runs `operation` with local-engine routing for creation requests. */
+    runWithLocalScope: <T>(operation: () => Promise<T>) => Promise<T>;
+    /** Whether creation scope is active (exposed for tests). */
+    isLocalScopeActive: () => boolean;
+    /** Marks one id (match/lobby/limited event) as locally hosted. */
+    registerLocalId: (id: string) => void;
+    /** Whether this id belongs to the in-browser engine. */
+    isLocalId: (id: string | undefined | null) => boolean;
+    /** Engine liveness flag, mirrored for synchronous routing decisions. */
+    setEngineRunning: (running: boolean) => void;
+    isEngineRunning: () => boolean;
+    /** Test-only: clears ids, scope, and the running flag. */
+    reset: () => void;
+}
+/**
+ * Creates one routing transport (one per app/client).
+ */
+export declare function createRoutingTransport(options: RoutingTransportOptions): RoutingTransport;