@my-swu/simulator-client 0.1.0

package/dist/local/routing.js

@@ -0,0 +1,193 @@
+/**
+ * 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.
+ */
+/**
+ * Creates one routing transport (one per app/client).
+ */
+export function createRoutingTransport(options) {
+    const localIds = new Set();
+    let engineRunning = false;
+    let localScopeDepth = 0;
+    const networkFetch = options.networkFetch
+        ?? ((input, init) => fetch(input, init));
+    const createNetworkSocket = options.createNetworkSocket
+        ?? ((url, protocols) => new WebSocket(url, protocols));
+    function shouldRouteHttpToLocal(path) {
+        if (path.startsWith('/api/availability')) {
+            return false;
+        }
+        if (localScopeDepth > 0
+            && (path === '/api/matches'
+                || path === '/api/lobbies'
+                || path === '/api/limited-events/preflight'
+                || path.startsWith('/api/cards'))) {
+            return true;
+        }
+        if (!engineRunning) {
+            return false;
+        }
+        if (path.startsWith('/api/cards')) {
+            return true;
+        }
+        const resourceId = path.match(/^\/api\/(?:matches|lobbies|limited-events)\/([^/?]+)/)?.[1];
+        return Boolean(resourceId && localIds.has(decodeURIComponent(resourceId)));
+    }
+    function shouldRouteSocketToLocal(url) {
+        if (!engineRunning) {
+            return false;
+        }
+        const matchId = new URL(url).pathname.split('/').filter(Boolean).pop();
+        return Boolean(matchId && localIds.has(decodeURIComponent(matchId)));
+    }
+    const routingFetch = async (input, init) => {
+        const url = typeof input === 'string'
+            ? input
+            : input instanceof URL ? input.toString() : input.url;
+        const pathname = new URL(url, 'http://placeholder.local').pathname;
+        if (!shouldRouteHttpToLocal(pathname)) {
+            return await networkFetch(input, init);
+        }
+        const local = await options.loadLocalTransport();
+        const response = await local.fetch(url, init);
+        if ((init?.method ?? 'GET') === 'POST' && response.ok) {
+            // Register every id the local engine mints so follow-up requests
+            // (snapshots, sockets, reconnect) route local without a scope flag:
+            // matches, lobbies, and the limited event + match a lobby starts.
+            const payload = await response.clone().json().catch(() => null);
+            for (const id of [
+                payload?.matchId,
+                payload?.lobbyId,
+                payload?.private?.startedAccess?.access?.eventId,
+                payload?.private?.startedAccess?.access?.matchId,
+            ]) {
+                if (id) {
+                    localIds.add(id);
+                }
+            }
+        }
+        return response;
+    };
+    const webSocketFactory = (url, protocols) => {
+        if (!shouldRouteSocketToLocal(url)) {
+            return createNetworkSocket(url, protocols);
+        }
+        return createDeferredSocket(async () => {
+            const local = await options.loadLocalTransport();
+            return local.webSocketFactory(url, protocols);
+        });
+    };
+    return {
+        fetch: routingFetch,
+        webSocketFactory,
+        runWithLocalScope: async (operation) => {
+            localScopeDepth += 1;
+            try {
+                return await operation();
+            }
+            finally {
+                localScopeDepth -= 1;
+            }
+        },
+        isLocalScopeActive: () => localScopeDepth > 0,
+        registerLocalId: id => void localIds.add(id),
+        isLocalId: id => id != null && localIds.has(id),
+        setEngineRunning: (running) => {
+            engineRunning = running;
+        },
+        isEngineRunning: () => engineRunning,
+        reset: () => {
+            localIds.clear();
+            engineRunning = false;
+            localScopeDepth = 0;
+        },
+    };
+}
+/**
+ * Buffers listener registrations/sends until the inner socket resolves. The
+ * SDK expects a socket object synchronously; the local transport may still be
+ * lazy-loading. A failed load surfaces as `error` + `close 1006` so the
+ * connection layer transitions instead of hanging.
+ */
+function createDeferredSocket(resolve) {
+    let inner = null;
+    const listeners = [];
+    const queued = [];
+    let closed = false;
+    const emit = (type, event) => {
+        for (const [listenerType, listener] of [...listeners]) {
+            if (listenerType === type) {
+                listener(event);
+            }
+        }
+    };
+    void resolve()
+        .then((socket) => {
+        if (closed) {
+            socket.close();
+            return;
+        }
+        inner = socket;
+        for (const [type, listener] of listeners) {
+            socket.addEventListener(type, listener);
+        }
+        for (const data of queued) {
+            socket.send(data);
+        }
+        queued.length = 0;
+    })
+        .catch((error) => {
+        if (closed) {
+            return;
+        }
+        closed = true;
+        emit('error', { message: String(error) });
+        emit('close', { code: 1006, reason: String(error) });
+    });
+    return {
+        addEventListener: (type, listener) => {
+            if (inner) {
+                inner.addEventListener(type, listener);
+            }
+            else {
+                listeners.push([type, listener]);
+            }
+        },
+        removeEventListener: (type, listener) => {
+            if (inner) {
+                inner.removeEventListener(type, listener);
+            }
+            else {
+                const index = listeners.findIndex(([t, l]) => t === type && l === listener);
+                if (index >= 0) {
+                    listeners.splice(index, 1);
+                }
+            }
+        },
+        send: (data) => {
+            if (inner) {
+                inner.send(data);
+            }
+            else {
+                queued.push(data);
+            }
+        },
+        close: (code, reason) => {
+            closed = true;
+            inner?.close(code, reason);
+        },
+    };
+}

package/dist/local/server/ai-scheduler.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Single-lane scheduler for one local match: delivers wire batches in order
+ * (honoring `delayBeforeMs` pacing barriers with real timers), applies human
+ * messages between AI decisions, and keeps ticking the engine while an AI
+ * seat has work. Everything runs on the worker's event loop — the blocking
+ * MCTS search inside `tickAi` never overlaps a queued human message because
+ * the queue is drained one operation at a time.
+ */
+import type { LocalEngineMatch, LocalWireBatch } from '../engine.js';
+export interface AiSchedulerOptions {
+    match: LocalEngineMatch;
+    /** Sends one batch's messages to the connected client. */
+    deliver: (batch: LocalWireBatch) => void;
+    /**
+     * Called when an engine call throws (wasm panic, corrupt message). The
+     * scheduler stops itself first; the socket layer should fail the channel so
+     * the client sees `error` + `close` instead of a silently frozen match.
+     */
+    failed: (error: unknown) => void;
+}
+export interface AiScheduler {
+    /** Queues one human operation; its batches are delivered in order. */
+    enqueueHuman: (operation: () => LocalWireBatch[]) => void;
+    /** Starts (or continues) AI ticking if the engine reports work. */
+    pump: () => void;
+    stop: () => void;
+}
+/**
+ * Creates the scheduler for one match socket.
+ */
+export declare function createAiScheduler(options: AiSchedulerOptions): AiScheduler;

package/dist/local/server/ai-scheduler.js

@@ -0,0 +1,93 @@
+/**
+ * Single-lane scheduler for one local match: delivers wire batches in order
+ * (honoring `delayBeforeMs` pacing barriers with real timers), applies human
+ * messages between AI decisions, and keeps ticking the engine while an AI
+ * seat has work. Everything runs on the worker's event loop — the blocking
+ * MCTS search inside `tickAi` never overlaps a queued human message because
+ * the queue is drained one operation at a time.
+ */
+/**
+ * Creates the scheduler for one match socket.
+ */
+export function createAiScheduler(options) {
+    const { match, deliver, failed } = options;
+    const queue = [];
+    let draining = false;
+    let stopped = false;
+    let aiScheduled = false;
+    const sleep = (ms) => new Promise(resolve => setTimeout(resolve, ms));
+    async function drain() {
+        if (draining || stopped) {
+            return;
+        }
+        draining = true;
+        try {
+            while (queue.length > 0 && !stopped) {
+                const operation = queue.shift();
+                let batches;
+                try {
+                    batches = operation.run();
+                }
+                catch (error) {
+                    // An engine throw would otherwise escape this async loop as an
+                    // unhandled rejection with the match frozen and no client signal.
+                    stopped = true;
+                    queue.length = 0;
+                    failed(error);
+                    return;
+                }
+                for (const batch of batches) {
+                    if (stopped) {
+                        return;
+                    }
+                    if (batch.delayBeforeMs > 0) {
+                        await sleep(batch.delayBeforeMs);
+                    }
+                    deliver(batch);
+                }
+                if (operation.thenPump) {
+                    scheduleAiTick();
+                }
+            }
+        }
+        finally {
+            draining = false;
+        }
+        if (queue.length > 0) {
+            void drain();
+        }
+    }
+    function scheduleAiTick() {
+        if (stopped || aiScheduled || !match.aiHasWork()) {
+            return;
+        }
+        aiScheduled = true;
+        // Yield to the worker event loop first so freshly posted human messages
+        // (undo, pause) can slot in before the next blocking search.
+        setTimeout(() => {
+            aiScheduled = false;
+            if (stopped || !match.aiHasWork()) {
+                return;
+            }
+            queue.push({
+                run: () => {
+                    const tick = match.tickAi(Date.now());
+                    return tick.batches;
+                },
+                thenPump: true,
+            });
+            void drain();
+        }, 0);
+    }
+    return {
+        enqueueHuman: (operation) => {
+            queue.push({ run: operation, thenPump: true });
+            void drain();
+        },
+        pump: () => scheduleAiTick(),
+        stop: () => {
+            stopped = true;
+            queue.length = 0;
+        },
+    };
+}

package/dist/local/server/http-router.d.ts

@@ -0,0 +1,35 @@
+/**
+ * HTTP-route emulation for the offline engine. Implements exactly the routes
+ * the app's offline flows call; everything else returns a 501-style
+ * `ApiErrorResponse` so unexpected traffic fails loudly instead of silently.
+ */
+import type { LocalEngineLobby, LocalEngineMatch, LocalSimulatorEngine, LocalWireBatch } from '../engine.js';
+/** Result of one routed request. */
+export interface RoutedResponse {
+    status: number;
+    body: string;
+}
+/** Open-socket handle for one match (broadcast + AI re-pump from HTTP routes). */
+export interface LocalMatchChannel {
+    /** Enqueues pre-computed batches behind any in-flight paced delivery. */
+    deliver: (batches: LocalWireBatch[]) => void;
+}
+/** Mutable match/lobby registry shared with the socket layer. */
+export interface LocalMatchRegistry {
+    matches: Map<string, LocalEngineMatch>;
+    lobbies: Map<string, LocalEngineLobby>;
+    /** Limited event id → owning lobby id (for /api/limited-events routing). */
+    eventLobbies: Map<string, string>;
+    /** Match id → its open socket, while one is connected. */
+    matchChannels: Map<string, LocalMatchChannel>;
+}
+/**
+ * Maps an engine throw (invalid request payload, wasm-side rejection) to the
+ * same 4xx `ApiErrorResponse` shape the online server produces, so app error
+ * handling sees an `EngineHttpError` with a code instead of a rejected fetch.
+ */
+export declare function engineFailureResponse(error: unknown): RoutedResponse;
+/**
+ * Routes one HTTP request against the engine.
+ */
+export declare function routeHttpRequest(engine: LocalSimulatorEngine, registry: LocalMatchRegistry, method: string, path: string, body: string | undefined, nowMs: number): RoutedResponse;

package/dist/local/server/http-router.js

@@ -0,0 +1,185 @@
+/**
+ * HTTP-route emulation for the offline engine. Implements exactly the routes
+ * the app's offline flows call; everything else returns a 501-style
+ * `ApiErrorResponse` so unexpected traffic fails loudly instead of silently.
+ */
+function jsonError(status, code, message) {
+    return {
+        status,
+        body: JSON.stringify({ error: { code, message } }),
+    };
+}
+/**
+ * Maps an engine throw (invalid request payload, wasm-side rejection) to the
+ * same 4xx `ApiErrorResponse` shape the online server produces, so app error
+ * handling sees an `EngineHttpError` with a code instead of a rejected fetch.
+ */
+export function engineFailureResponse(error) {
+    return jsonError(400, 'localEngineError', String(error));
+}
+/** Drops every hosted match except `kept` — offline flows host one live match. */
+function retainOnlyMatch(registry, kept) {
+    for (const [id] of registry.matches) {
+        if (id !== kept.matchId) {
+            registry.matches.delete(id);
+        }
+    }
+}
+/**
+ * Routes one HTTP request against the engine.
+ */
+export function routeHttpRequest(engine, registry, method, path, body, nowMs) {
+    const url = new URL(path, 'http://local.engine');
+    const segments = url.pathname.split('/').filter(Boolean);
+    // GET /api/availability is deliberately NOT served here: availability
+    // always describes the real Crucible backend.
+    if (segments[0] !== 'api') {
+        return jsonError(404, 'notFound', `unknown path ${url.pathname}`);
+    }
+    if (segments[1] === 'cards' && segments.length === 2 && method === 'GET') {
+        const ids = (url.searchParams.get('ids') ?? '')
+            .split(',')
+            .map(value => Number.parseInt(value, 10))
+            .filter(value => Number.isFinite(value));
+        return { status: 200, body: engine.cardsGet(ids) };
+    }
+    if (segments[1] === 'lobbies') {
+        return routeLobbyRequest(engine, registry, segments, method, body, nowMs);
+    }
+    if (segments[1] === 'limited-events') {
+        if (segments[2] === 'preflight' && segments.length === 3 && method === 'POST') {
+            if (body == null) {
+                return jsonError(400, 'invalidRequest', 'missing preflight request body');
+            }
+            return { status: 200, body: engine.preflightLimitedEvent(body) };
+        }
+        const eventId = segments[2] ? decodeURIComponent(segments[2]) : undefined;
+        const lobby = eventId ? registry.lobbies.get(registry.eventLobbies.get(eventId) ?? '') : undefined;
+        if (!lobby) {
+            return jsonError(404, 'eventNotFound', 'limited event not found');
+        }
+        if (segments.length === 3 && method === 'GET') {
+            const seatToken = url.searchParams.get('seatToken');
+            return { status: 200, body: lobby.eventSnapshot(seatToken, nowMs) };
+        }
+        if (segments[3] === 'commands' && method === 'POST') {
+            if (body == null) {
+                return jsonError(400, 'invalidRequest', 'missing command body');
+            }
+            const request = JSON.parse(body);
+            return {
+                status: 200,
+                body: lobby.eventApplyCommand(request.seatToken, JSON.stringify(request.command), nowMs),
+            };
+        }
+        return jsonError(501, 'notImplemented', `offline engine does not serve ${method} ${url.pathname}`);
+    }
+    if (segments[1] === 'matches') {
+        if (segments.length === 2 && method === 'POST') {
+            if (body == null) {
+                return jsonError(400, 'invalidRequest', 'missing create request body');
+            }
+            const { match, accessJson } = engine.createMatch(body, nowMs);
+            registry.matches.set(match.matchId, match);
+            retainOnlyMatch(registry, match);
+            return { status: 200, body: accessJson };
+        }
+        const matchId = segments[2] ? decodeURIComponent(segments[2]) : undefined;
+        const match = matchId ? registry.matches.get(matchId) : undefined;
+        if (!match) {
+            return jsonError(404, 'matchNotFound', 'match not found');
+        }
+        if (segments.length === 3 && method === 'GET') {
+            return { status: 200, body: JSON.stringify({ snapshot: JSON.parse(match.snapshot()) }) };
+        }
+        if (segments[3] === 'ai' && segments[4] === 'pause' && method === 'POST') {
+            if (body == null) {
+                return jsonError(400, 'invalidRequest', 'missing pause request body');
+            }
+            const request = JSON.parse(body);
+            const batches = match.handleMessage(request.seatToken, JSON.stringify({ type: 'setAiPaused', payload: { paused: request.paused } }), nowMs);
+            // The HTTP reply is the refreshed AI status; the full batch set is
+            // broadcast to the open socket (which also re-pumps the AI — critical
+            // after `paused: false`, or the AI would stall until the next message).
+            registry.matchChannels.get(match.matchId)?.deliver(batches);
+            const status = batches
+                .flatMap(batch => batch.messages)
+                .find((message) => message?.type === 'aiStatus');
+            if (!status) {
+                return jsonError(409, 'invalidRequest', 'AI pause rejected');
+            }
+            return { status: 200, body: JSON.stringify(status.payload) };
+        }
+        if (segments[3] === 'save' && method === 'POST') {
+            return { status: 200, body: match.save() };
+        }
+        return jsonError(501, 'notImplemented', `offline engine does not serve ${method} ${url.pathname}`);
+    }
+    return jsonError(501, 'notImplemented', `offline engine does not serve ${method} ${url.pathname}`);
+}
+/**
+ * Routes the hidden limited-lobby bootstrap the offline vs-AI pods drive.
+ */
+function routeLobbyRequest(engine, registry, segments, method, body, nowMs) {
+    if (segments.length === 2 && method === 'POST') {
+        if (body == null) {
+            return jsonError(400, 'invalidRequest', 'missing lobby request body');
+        }
+        const { lobby, accessJson } = engine.createLobby(body);
+        registry.lobbies.set(lobby.lobbyId, lobby);
+        return { status: 200, body: accessJson };
+    }
+    const lobbyId = segments[2] ? decodeURIComponent(segments[2]) : undefined;
+    const lobby = lobbyId ? registry.lobbies.get(lobbyId) : undefined;
+    if (!lobby) {
+        return jsonError(404, 'lobbyNotFound', 'lobby not found');
+    }
+    const action = segments.slice(3).join('/');
+    const request = body == null ? {} : JSON.parse(body);
+    try {
+        lobby.authorize(String(request.playerToken ?? ''));
+    }
+    catch {
+        return jsonError(403, 'invalidToken', 'invalid lobby player token');
+    }
+    switch (`${method} ${action}`) {
+        case 'POST players/ai': {
+            return { status: 200, body: lobby.addAiPlayer(String(request.difficulty ?? 'medium')) };
+        }
+        case 'POST players/me': {
+            const ready = typeof request.ready === 'boolean' ? request.ready : true;
+            return { status: 200, body: lobby.setHostReady(ready) };
+        }
+        case 'POST start': {
+            const accessJson = lobby.start(nowMs);
+            const access = JSON.parse(accessJson);
+            const eventId = access.private?.startedAccess?.access?.eventId;
+            if (eventId && lobby.lobbyId) {
+                registry.eventLobbies.set(eventId, lobby.lobbyId);
+            }
+            return { status: 200, body: accessJson };
+        }
+        case 'POST limited-deck': {
+            return { status: 200, body: lobby.submitLimitedDeck(body ?? '{}') };
+        }
+        case 'POST prepare-limited-ai-decks': {
+            return { status: 200, body: lobby.prepareLimitedAiDecks() };
+        }
+        case 'POST start-limited-match': {
+            const { match, accessJson } = engine.createMatch(lobby.limitedMatchRequest(), nowMs);
+            registry.matches.set(match.matchId, match);
+            retainOnlyMatch(registry, match);
+            return { status: 200, body: lobby.storeStartedMatch(accessJson) };
+        }
+        case 'POST sync': {
+            return { status: 200, body: lobby.accessJson() };
+        }
+        case 'POST leave': {
+            const response = lobby.accessJson();
+            registry.lobbies.delete(lobbyId);
+            return { status: 200, body: response };
+        }
+        default:
+            return jsonError(501, 'notImplemented', `offline engine does not serve ${method} /api/lobbies/.../${action}`);
+    }
+}

package/dist/local/server/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * In-worker server: binds the RPC protocol to the engine (HTTP router, virtual
+ * sockets, record persistence). The worker entry wires this to the real wasm
+ * engine; tests drive it with a scripted fake over an in-process port.
+ */
+import type { LocalSimulatorEngine } from '../engine.js';
+import type { WorkerLike } from '../protocol.js';
+export interface LocalEngineServerOptions {
+    engine: LocalSimulatorEngine;
+    /** The worker-global port (`self`) or an in-process test double. */
+    port: WorkerLike;
+}
+/**
+ * Attaches the local engine server to a message port. Returns a disposer.
+ */
+export declare function createLocalEngineServer(options: LocalEngineServerOptions): () => void;