@my-swu/simulator-client 0.1.0

package/dist/internal/socket-frame.js

@@ -0,0 +1,47 @@
+import { messageEventDataString } from './websocket-event.js';
+/**
+ * Parses one browser-style message event into a typed, validated socket frame.
+ *
+ * Shared by every socket in the SDK so all of them answer a malformed known
+ * frame the same way, whatever their protocol root. The validator decides
+ * whether anything is actually checked: with the pass-through the frame is
+ * trusted exactly as sent, which is the SDK's default.
+ *
+ * A JSON syntax error and a schema violation both surface as an `error`
+ * result rather than a throw, because the only caller is a socket `message`
+ * listener — throwing there escapes into the transport, not into the consumer.
+ *
+ * @param event Raw socket message event.
+ * @param validator Boundary validator; the pass-through trusts the frame.
+ * @param schemaName Generated schema name this socket's frames must match.
+ */
+export function decodeSocketFrame(event, validator, schemaName) {
+    const raw = messageEventDataString(event);
+    if (raw == null) {
+        return { type: 'ignored' };
+    }
+    try {
+        const payload = JSON.parse(raw);
+        // A `type` this build does not know is a newer server variant, not a
+        // contract violation: drop it so the wire can grow message types. A known
+        // type with a malformed payload still fails validation below.
+        //
+        // Without a schema map there is no set of known types to test against, so
+        // the check is absent rather than negative: the frame is decoded and the
+        // caller's dispatch `switch` — which has no case for it — ignores it.
+        if (validator.hasUnknownDiscriminant?.(schemaName, payload) === true) {
+            return { type: 'ignored' };
+        }
+        return {
+            message: validator.parse(schemaName, payload),
+            type: 'message',
+        };
+    }
+    catch (cause) {
+        const message = cause instanceof Error ? cause.message : `invalid ${schemaName}`;
+        return {
+            error: { code: 'sdk_invalid_server_message', message },
+            type: 'error',
+        };
+    }
+}

package/dist/internal/transport.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Fetch implementation accepted by the SDK.
+ *
+ * Browser runtimes and Node 18+ usually provide this globally. Pass a custom
+ * value when your runtime needs a fetch adapter, proxy wrapper, or test double.
+ *
+ * @example
+ * ```ts
+ * import type { FetchLike } from '@my-swu/simulator-client'
+ *
+ * const tracedFetch: FetchLike = (input, init) => {
+ *   console.log('SDK request', input)
+ *   return fetch(input, init)
+ * }
+ *
+ * console.log(typeof tracedFetch)
+ * ```
+ *
+ * @see https://simulator-sdk.my-swu.com/guide/runtime-adapters
+ */
+export type FetchLike = typeof fetch;
+/**
+ * Minimal WebSocket shape required by the SDK.
+ *
+ * This intentionally matches the browser event-listener style used by
+ * `WebSocket` and common Node adapters.
+ *
+ * @see https://simulator-sdk.my-swu.com/guide/runtime-adapters
+ */
+export interface EngineWebSocket {
+    /**
+     * Registers one DOM-style event listener.
+     */
+    addEventListener(type: 'open' | 'message' | 'error' | 'close', listener: (event: unknown) => void): void;
+    /**
+     * Unregisters one DOM-style event listener.
+     */
+    removeEventListener(type: 'open' | 'message' | 'error' | 'close', listener: (event: unknown) => void): void;
+    /**
+     * Sends one text frame.
+     */
+    send(data: string): void;
+    /**
+     * Closes the socket.
+     */
+    close(code?: number, reason?: string): void;
+}
+/**
+ * Factory used to create WebSocket clients.
+ *
+ * Use this in runtimes without a global browser-style `WebSocket`.
+ *
+ * The optional `protocols` argument carries the WebSocket subprotocol list used
+ * to authenticate the connection (the auth token is sent off-URL via
+ * `Sec-WebSocket-Protocol`; see the connection docs). A custom factory MUST
+ * forward `protocols` to its underlying socket, otherwise authentication will
+ * fail once tokens are no longer placed in the URL.
+ *
+ * @example
+ * ```ts
+ * import WebSocket from 'ws'
+ * import type { WebSocketFactory } from '@my-swu/simulator-client'
+ *
+ * const nodeWebSocketFactory: WebSocketFactory = (url, protocols) => new WebSocket(url, protocols)
+ * console.log(typeof nodeWebSocketFactory)
+ * ```
+ *
+ * @see https://simulator-sdk.my-swu.com/guide/runtime-adapters
+ */
+export type WebSocketFactory = (url: string, protocols?: string | string[]) => EngineWebSocket;
+/**
+ * Returns the ambient fetch implementation.
+ */
+export declare function getDefaultFetch(): FetchLike;
+/**
+ * Returns the ambient browser-style WebSocket factory.
+ */
+export declare function getDefaultWebSocketFactory(): WebSocketFactory;

package/dist/internal/transport.js

@@ -0,0 +1,18 @@
+/**
+ * Returns the ambient fetch implementation.
+ */
+export function getDefaultFetch() {
+    if (typeof globalThis.fetch !== 'function') {
+        throw new Error('global fetch is not available; pass options.fetch');
+    }
+    return globalThis.fetch.bind(globalThis);
+}
+/**
+ * Returns the ambient browser-style WebSocket factory.
+ */
+export function getDefaultWebSocketFactory() {
+    if (typeof globalThis.WebSocket !== 'function') {
+        throw new Error('global WebSocket is not available; pass options.webSocketFactory');
+    }
+    return (url, protocols) => new globalThis.WebSocket(url, protocols);
+}

package/dist/internal/websocket-event.d.ts

@@ -0,0 +1,15 @@
+import type { WebSocketCloseInfo } from './errors.js';
+/**
+ * Returns text data from one browser-style WebSocket message event.
+ *
+ * The SDK's transport boundary accepts `unknown` events so browser sockets,
+ * Node adapters, and local-worker sockets all share one safe extraction path.
+ */
+export declare function messageEventDataString(event: unknown): string | undefined;
+/**
+ * Returns close facts from one browser-style WebSocket close event.
+ *
+ * Browsers expose `{ code, reason }` on `CloseEvent`; Node adapters and test
+ * doubles may pass anything, so both fields are validated defensively.
+ */
+export declare function websocketCloseInfo(event: unknown): WebSocketCloseInfo;

package/dist/internal/websocket-event.js

@@ -0,0 +1,31 @@
+/**
+ * Returns text data from one browser-style WebSocket message event.
+ *
+ * The SDK's transport boundary accepts `unknown` events so browser sockets,
+ * Node adapters, and local-worker sockets all share one safe extraction path.
+ */
+export function messageEventDataString(event) {
+    if (typeof event === 'object' && event != null && 'data' in event) {
+        const data = event.data;
+        if (typeof data === 'string') {
+            return data;
+        }
+    }
+    return undefined;
+}
+/**
+ * Returns close facts from one browser-style WebSocket close event.
+ *
+ * Browsers expose `{ code, reason }` on `CloseEvent`; Node adapters and test
+ * doubles may pass anything, so both fields are validated defensively.
+ */
+export function websocketCloseInfo(event) {
+    if (typeof event === 'object' && event != null) {
+        const { code, reason } = event;
+        return {
+            closeCode: typeof code === 'number' ? code : undefined,
+            reason: typeof reason === 'string' ? reason : undefined,
+        };
+    }
+    return {};
+}

package/dist/local/assets.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Engine asset store: downloads the browser-engine runtime assets (wasm
+ * binary, wasm-bindgen glue, and gzip card blobs) from a simulator-served base URL into a dedicated
+ * Cache API bucket, versioned by the server manifest's content hash.
+ *
+ * Deliberately dependency-free so app boot code can import it without
+ * dragging in the transport/worker modules: keep this module's import list
+ * empty (types only).
+ */
+/** Shape of `GET {baseUrl}/manifest.json` served by the simulator backend. */
+export interface EngineAssetManifest {
+    version: string;
+    files: {
+        wasm: {
+            path: string;
+            size: number;
+        };
+        glue: {
+            path: string;
+            size: number;
+        };
+        catalog: {
+            path: string;
+            size: number;
+        };
+    };
+}
+/** Locally persisted marker describing the last successful prefetch. */
+export interface EngineAssetMeta {
+    version: string;
+    cachedAt: string;
+    totalBytes: number;
+}
+/** Decompressed byte payloads the engine worker init frame needs. */
+export interface EngineAssetBytes {
+    wasmBytes: ArrayBuffer;
+    /** wasm-bindgen ES module source matching `wasmBytes`. */
+    glueSource: string;
+    catalogBytes: ArrayBuffer;
+}
+export interface EngineAssetStoreOptions {
+    /** Base URL of the asset routes (e.g. `https://sim.example/assets/engine`). */
+    baseUrl: string;
+    /** Cache bucket prefix; the bucket is `${prefix}:v${version}`. */
+    cachePrefix?: string;
+    /** localStorage key for the prefetch marker. */
+    metaKey?: string;
+}
+/** Byte-level download progress across all assets of one `prepare()` run. */
+export interface EngineAssetProgress {
+    /** Bytes accounted for so far (cache hits count immediately). */
+    loadedBytes: number;
+    /** Expected total from the manifest's file sizes. */
+    totalBytes: number;
+}
+export interface EngineAssetPrepareOptions {
+    /** Streams download progress (called per network chunk + per cache hit). */
+    onProgress?: ((progress: EngineAssetProgress) => void) | undefined;
+}
+export interface EngineAssetPrepareResult {
+    meta: EngineAssetMeta;
+    /** Whether any bytes were actually fetched (false = pure cache hit). */
+    downloaded: boolean;
+}
+export interface EngineAssetStore {
+    /**
+     * Fetches the live server manifest (requires network). Lets callers
+     * compare the served version against `meta()` to detect updates.
+     */
+    manifest: () => Promise<EngineAssetManifest>;
+    /**
+     * Syncs the cache to the server manifest. Only bumps `cachedAt` when bytes
+     * were actually downloaded, so "last updated" stays truthful across
+     * cache-hit boots. Requires network for the manifest read.
+     */
+    prepare: (options?: EngineAssetPrepareOptions) => Promise<EngineAssetPrepareResult>;
+    /** Whether every asset of the last-prepared version is cached. */
+    ready: () => Promise<boolean>;
+    /** The last prefetch marker, or `null` when never prepared. */
+    meta: () => EngineAssetMeta | null;
+    /** Total cached bytes (0 when nothing is cached). */
+    cacheSize: () => Promise<number>;
+    /** Deletes every bucket under the prefix and the meta marker. */
+    wipe: () => Promise<void>;
+    /** Reads (and decompresses) the cached assets for the worker init frame. */
+    loadBytes: () => Promise<EngineAssetBytes>;
+}
+/**
+ * Creates the store. Browser-only: requires the Cache API and localStorage.
+ */
+export declare function createEngineAssetStore(options: EngineAssetStoreOptions): EngineAssetStore;
+/**
+ * Decompresses a gzip payload (`.gz` assets are stored pre-compressed and
+ * served raw). Skips when a proxy already inflated the bytes.
+ */
+export declare function decompressGzip(bytes: ArrayBuffer): Promise<ArrayBuffer>;

package/dist/local/assets.js

@@ -0,0 +1,235 @@
+/**
+ * Engine asset store: downloads the browser-engine runtime assets (wasm
+ * binary, wasm-bindgen glue, and gzip card blobs) from a simulator-served base URL into a dedicated
+ * Cache API bucket, versioned by the server manifest's content hash.
+ *
+ * Deliberately dependency-free so app boot code can import it without
+ * dragging in the transport/worker modules: keep this module's import list
+ * empty (types only).
+ */
+/** Fixed route paths under the base URL — the server contract. */
+const ASSET_PATHS = {
+    wasm: 'wasm',
+    glue: 'glue',
+    catalog: 'catalog',
+};
+const ASSET_KEYS = ['wasm', 'glue', 'catalog'];
+/**
+ * Creates the store. Browser-only: requires the Cache API and localStorage.
+ */
+export function createEngineAssetStore(options) {
+    const cachePrefix = options.cachePrefix ?? 'swu-sim:engine';
+    const metaKey = options.metaKey ?? 'swu:simOffline:engineMeta';
+    // Cache keys MUST be absolute: `Request.url` is always absolute, so a
+    // relative base (dev-server route) would make the stale-key prune below
+    // mismatch — and delete — every entry it just stored.
+    const trimmedBase = options.baseUrl.replace(/\/$/, '');
+    const baseUrl = typeof location !== 'undefined'
+        ? new URL(trimmedBase, location.href).toString()
+        : trimmedBase;
+    const bucketName = (version) => `${cachePrefix}:v${version}`;
+    /** Stable cache key per asset — versioning lives in the bucket name. */
+    const assetKeyUrl = (path) => `${baseUrl}/${path}`;
+    function readMeta() {
+        try {
+            const raw = localStorage.getItem(metaKey);
+            if (!raw) {
+                return null;
+            }
+            const parsed = JSON.parse(raw);
+            if (typeof parsed.version !== 'string' || typeof parsed.cachedAt !== 'string') {
+                return null;
+            }
+            return {
+                version: parsed.version,
+                cachedAt: parsed.cachedAt,
+                totalBytes: typeof parsed.totalBytes === 'number' ? parsed.totalBytes : 0,
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    async function fetchManifest() {
+        const response = await fetch(`${baseUrl}/manifest.json`, { cache: 'no-cache' });
+        if (!response.ok) {
+            throw new Error(`failed to fetch engine asset manifest: ${response.status}`);
+        }
+        const manifest = await response.json();
+        if (typeof manifest.version !== 'string' || !manifest.files) {
+            throw new Error('invalid engine asset manifest');
+        }
+        return manifest;
+    }
+    async function dropOtherBuckets(keep) {
+        const names = await caches.keys();
+        await Promise.all(names
+            .filter(name => name.startsWith(`${cachePrefix}:`) && name !== keep)
+            .map(name => caches.delete(name)));
+    }
+    async function prepare(prepareOptions) {
+        const manifest = await fetchManifest();
+        const bucket = bucketName(manifest.version);
+        await dropOtherBuckets(bucket);
+        const cache = await caches.open(bucket);
+        // Progress denominator comes from the manifest so the bar is meaningful
+        // from the first chunk of the first file.
+        const expectedTotal = ASSET_KEYS.reduce((sum, key) => sum + (manifest.files[key]?.size ?? 0), 0);
+        let loadedBytes = 0;
+        const report = () => prepareOptions?.onProgress?.({ loadedBytes, totalBytes: expectedTotal });
+        report();
+        let downloaded = false;
+        let totalBytes = 0;
+        const wantedKeys = new Set();
+        for (const key of ASSET_KEYS) {
+            const keyUrl = assetKeyUrl(ASSET_PATHS[key]);
+            wantedKeys.add(keyUrl);
+            const hit = await cache.match(keyUrl);
+            if (hit) {
+                const size = (await hit.blob()).size;
+                totalBytes += size;
+                loadedBytes += size;
+                report();
+                continue;
+            }
+            // `?v=` busts intermediary HTTP caches; the bucket key stays stable.
+            const response = await fetch(`${keyUrl}?v=${encodeURIComponent(manifest.version)}`);
+            if (!response.ok) {
+                throw new Error(`failed to fetch engine asset ${ASSET_PATHS[key]}: ${response.status}`);
+            }
+            const bytes = await readWithProgress(response, (chunkBytes) => {
+                loadedBytes += chunkBytes;
+                report();
+            });
+            totalBytes += bytes.byteLength;
+            // `.buffer` is exact-size (allocated by readWithProgress) — the cast
+            // only bridges the TS 5.7 generic-Uint8Array vs DOM BodyInit gap.
+            await cache.put(keyUrl, new Response(bytes.buffer, {
+                headers: {
+                    'content-type': response.headers.get('content-type') ?? 'application/octet-stream',
+                },
+            }));
+            downloaded = true;
+        }
+        // Prune keys a base-URL change or manifest rename left behind.
+        for (const request of await cache.keys()) {
+            if (!wantedKeys.has(request.url)) {
+                await cache.delete(request);
+            }
+        }
+        const previous = readMeta();
+        const meta = {
+            version: manifest.version,
+            cachedAt: downloaded || previous?.version !== manifest.version
+                ? new Date().toISOString()
+                : previous.cachedAt,
+            totalBytes,
+        };
+        localStorage.setItem(metaKey, JSON.stringify(meta));
+        return { meta, downloaded };
+    }
+    async function openCurrentCache() {
+        const meta = readMeta();
+        if (!meta) {
+            return null;
+        }
+        return { cache: await caches.open(bucketName(meta.version)), meta };
+    }
+    async function ready() {
+        const current = await openCurrentCache();
+        if (!current) {
+            return false;
+        }
+        for (const key of ASSET_KEYS) {
+            if (!(await current.cache.match(assetKeyUrl(ASSET_PATHS[key])))) {
+                return false;
+            }
+        }
+        return true;
+    }
+    async function cacheSize() {
+        const current = await openCurrentCache();
+        if (!current) {
+            return 0;
+        }
+        let total = 0;
+        for (const request of await current.cache.keys()) {
+            const hit = await current.cache.match(request);
+            if (hit) {
+                total += (await hit.blob()).size;
+            }
+        }
+        return total;
+    }
+    async function wipe() {
+        const names = await caches.keys();
+        await Promise.all(names
+            .filter(name => name.startsWith(`${cachePrefix}:`))
+            .map(name => caches.delete(name)));
+        localStorage.removeItem(metaKey);
+    }
+    async function loadBytes() {
+        const current = await openCurrentCache();
+        if (!current) {
+            throw new Error('engine assets have not been prepared');
+        }
+        const read = async (path) => {
+            const hit = await current.cache.match(assetKeyUrl(path));
+            if (!hit) {
+                throw new Error(`engine asset ${path} missing from cache`);
+            }
+            return await hit.arrayBuffer();
+        };
+        const [wasmBytes, glueSource, catalogBytes] = await Promise.all([
+            read(ASSET_PATHS.wasm),
+            read(ASSET_PATHS.glue).then(bytes => new TextDecoder().decode(bytes)),
+            read(ASSET_PATHS.catalog).then(decompressGzip),
+        ]);
+        return { wasmBytes, glueSource, catalogBytes };
+    }
+    return { manifest: fetchManifest, prepare, ready, meta: readMeta, cacheSize, wipe, loadBytes };
+}
+/**
+ * Reads a response body to completion, reporting each chunk's byte count.
+ * Falls back to one `arrayBuffer()` read when the body is not streamable.
+ */
+async function readWithProgress(response, onChunk) {
+    const reader = response.body?.getReader();
+    if (!reader) {
+        const buffer = new Uint8Array(await response.arrayBuffer());
+        onChunk(buffer.byteLength);
+        return buffer;
+    }
+    const chunks = [];
+    let length = 0;
+    while (true) {
+        const { done, value } = await reader.read();
+        if (done) {
+            break;
+        }
+        chunks.push(value);
+        length += value.byteLength;
+        onChunk(value.byteLength);
+    }
+    const merged = new Uint8Array(length);
+    let offset = 0;
+    for (const chunk of chunks) {
+        merged.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    return merged;
+}
+/**
+ * Decompresses a gzip payload (`.gz` assets are stored pre-compressed and
+ * served raw). Skips when a proxy already inflated the bytes.
+ */
+export async function decompressGzip(bytes) {
+    const view = new Uint8Array(bytes);
+    // gzip magic bytes; anything else is already-decompressed JSON.
+    if (view[0] !== 0x1F || view[1] !== 0x8B) {
+        return bytes;
+    }
+    const stream = new DecompressionStream('gzip');
+    const decompressed = new Response(new Response(bytes).body.pipeThrough(stream));
+    return await decompressed.arrayBuffer();
+}

package/dist/local/client.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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.
+ */
+import type { FetchLike, WebSocketFactory } from '../internal/transport.js';
+import type { WorkerLike } from './protocol.js';
+export interface WorkerTransport {
+    fetch: FetchLike;
+    webSocketFactory: WebSocketFactory;
+    /** Installs the engine assets; resolves with the engine version. */
+    init: (wasmBytes: ArrayBuffer, glueSource: string, catalogBytes: ArrayBuffer) => Promise<string>;
+    /** Replaces dynamic app catalog metadata for future local validation. */
+    applyCatalogSync: (catalogSyncJson: string) => Promise<void>;
+    /** Saves the active match's local record. */
+    saveRecord: () => Promise<{
+        matchId: string;
+        seatToken: string;
+        bytes: ArrayBuffer;
+    }>;
+    /** Restores a match from record bytes; resolves with its access info. */
+    restoreRecord: (bytes: ArrayBuffer) => Promise<{
+        matchId: string;
+        seatToken: string;
+    }>;
+    dispose: () => void;
+}
+/**
+ * Creates the transport over a running engine worker (or a test double).
+ */
+export declare function createWorkerTransport(port: WorkerLike): WorkerTransport;