@realnation/builder-shared-sdk 1.0.5 → 1.1.1

package/dist/runtime/facade.js

@@ -0,0 +1,427 @@
+import { decodeSilhouette, parseBinaryFrame, binaryCorrelationId } from './decode.js';
+export class RuntimeCommandError extends Error {
+    code;
+    constructor(err) {
+        super(err.message ?? err.code);
+        this.name = 'RuntimeCommandError';
+        this.code = err.code;
+    }
+}
+/** Per-command timeout. Snapshot is slow enough that the default would trip. */
+const TIMEOUTS = {
+    'camera.snapshot': 15000,
+};
+const DEFAULT_TIMEOUT_MS = 5000;
+/** Emitter with unsubscribe. One handler set per channel. */
+class Channel {
+    handlers = new Set();
+    add(fn) {
+        this.handlers.add(fn);
+        return () => {
+            this.handlers.delete(fn);
+        };
+    }
+    emit(v) {
+        for (const fn of this.handlers)
+            fn(v);
+    }
+    get size() {
+        return this.handlers.size;
+    }
+}
+export class RuntimeFacade {
+    transport;
+    pending = new Map();
+    /** Ids whose JSON response said binary:true, in arrival order. */
+    binaryQueue = [];
+    requestSeq = 0;
+    disposers = [];
+    bodyCh = new Channel();
+    gestureCh = new Channel();
+    handGestureCh = new Channel();
+    handGestureDiagnosticCh = new Channel();
+    gestureByName = new Map();
+    pointerCh = new Channel();
+    silhouetteCh = new Channel();
+    playerSilhouetteCh = new Channel();
+    playerSilhouetteLostCh = new Channel();
+    motionCh = new Channel();
+    deviceErrCh = new Channel();
+    deviceConnCh = new Channel();
+    playerLostCh = new Channel();
+    capChangeCh = new Channel();
+    stateCh = new Channel();
+    /** Last `device:connected.config` seen. Read-through only — see effectiveConfig. */
+    lastConfig = {};
+    lastPlayerSilhouette = null;
+    trackedPlayers = new Set();
+    setTimer;
+    clearTimer;
+    constructor(transport, timers) {
+        this.transport = transport;
+        this.setTimer = timers?.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
+        this.clearTimer = timers?.clearTimer ?? ((h) => clearTimeout(h));
+        this.disposers.push(transport.onMessage((m) => this.dispatch(m)));
+        this.disposers.push(transport.onBinary((b) => this.dispatchBinary(b)));
+        this.disposers.push(transport.onStateChange((s) => this.stateCh.emit(s)));
+    }
+    /* --- inbound ----------------------------------------------------------- */
+    dispatch(msg) {
+        switch (msg.type) {
+            case 'body:update': {
+                const body = msg;
+                this.trackedPlayers.add(body.player);
+                this.bodyCh.emit(body);
+                break;
+            }
+            case 'gesture:update': {
+                const g = msg;
+                this.gestureCh.emit(g);
+                this.gestureByName.get(g.gesture)?.emit(g);
+                break;
+            }
+            case 'hand-gesture:update':
+                this.handGestureCh.emit(msg);
+                break;
+            case 'hand-gesture:diagnostic':
+                this.handGestureDiagnosticCh.emit(msg);
+                break;
+            case 'pointer:update':
+                this.pointerCh.emit(msg);
+                break;
+            case 'depth:silhouette':
+                this.silhouetteCh.emit(decodeSilhouette(msg));
+                break;
+            case 'depth:player-silhouette': {
+                const raw = msg;
+                const frame = decodeSilhouette(raw);
+                frame.player = raw.player;
+                this.lastPlayerSilhouette = frame;
+                this.playerSilhouetteCh.emit(frame);
+                break;
+            }
+            case 'player-silhouette:lost': {
+                const raw = msg;
+                this.lastPlayerSilhouette = null;
+                this.playerSilhouetteLostCh.emit({ reason: raw.reason, ts: raw.ts });
+                break;
+            }
+            case 'motion:update':
+                this.motionCh.emit(msg);
+                break;
+            case 'device:connected': {
+                const dc = msg;
+                if (dc.config)
+                    this.lastConfig = dc.config;
+                this.deviceConnCh.emit(dc);
+                break;
+            }
+            case 'device:error': {
+                const de = msg;
+                this.deviceErrCh.emit(de);
+                break;
+            }
+            case 'player:lost':
+                this.trackedPlayers.clear();
+                this.playerLostCh.emit();
+                break;
+            case 'capability:changed':
+                this.capChangeCh.emit(msg);
+                break;
+            case 'response':
+                this.settle(msg);
+                break;
+            default:
+                break; // unknown types are ignored, never fatal
+        }
+    }
+    settle(res) {
+        const entry = this.pending.get(res.id);
+        if (!entry)
+            return; // late response after timeout; nothing to settle
+        if (!res.ok) {
+            this.clearTimer(entry.timer);
+            this.pending.delete(res.id);
+            entry.reject(new RuntimeCommandError(res.error ?? { code: 'INTERNAL' }));
+            return;
+        }
+        if (res.binary) {
+            // Hold the promise open: the payload arrives in the next binary frame.
+            entry.awaitingBinary = { result: res.result ?? {} };
+            this.binaryQueue.push(res.id);
+            return;
+        }
+        this.clearTimer(entry.timer);
+        this.pending.delete(res.id);
+        entry.resolve(res.result ?? {});
+    }
+    dispatchBinary(buf) {
+        const id = this.binaryQueue.shift();
+        if (id === undefined)
+            return; // unsolicited frame
+        const entry = this.pending.get(id);
+        if (!entry?.awaitingBinary)
+            return;
+        let frame;
+        try {
+            frame = parseBinaryFrame(buf);
+        }
+        catch (err) {
+            this.clearTimer(entry.timer);
+            this.pending.delete(id);
+            entry.reject(err);
+            return;
+        }
+        // The header carries the id precisely so a reordered frame is detected
+        // rather than silently handed to the wrong caller.
+        if (frame.id !== binaryCorrelationId(id)) {
+            this.clearTimer(entry.timer);
+            this.pending.delete(id);
+            entry.reject(new Error(`binary frame id mismatch for request ${id}`));
+            return;
+        }
+        const declared = entry.awaitingBinary.result.bytes;
+        if (typeof declared === 'number' && declared !== frame.payload.byteLength) {
+            this.clearTimer(entry.timer);
+            this.pending.delete(id);
+            entry.reject(new Error(`binary payload length ${frame.payload.byteLength} != declared ${declared}`));
+            return;
+        }
+        this.clearTimer(entry.timer);
+        this.pending.delete(id);
+        entry.resolve({ ...entry.awaitingBinary.result, payload: frame.payload });
+    }
+    /* --- commands ---------------------------------------------------------- */
+    /**
+     * A true `#private` method, not a TypeScript `private` one.
+     *
+     * TS `private` is erased at compile time: the method still sits on the
+     * prototype and `runtime['request']('camera.snapshot')` works at runtime. That
+     * is exactly the escape hatch P3-4 exists to close, and once someone reaches
+     * for it, `setInterval(() => request('body'), 33)` follows. `#` is enforced by
+     * the language, so the only way to issue a command is a named method below.
+     */
+    #request(name, args = {}) {
+        const id = `r-${++this.requestSeq}-${Math.random().toString(36).slice(2, 8)}`;
+        const timeoutMs = TIMEOUTS[name] ?? DEFAULT_TIMEOUT_MS;
+        return new Promise((resolve, reject) => {
+            const timer = this.setTimer(() => {
+                this.pending.delete(id);
+                const qi = this.binaryQueue.indexOf(id);
+                if (qi >= 0)
+                    this.binaryQueue.splice(qi, 1);
+                reject(new RuntimeCommandError({ code: 'TIMEOUT', message: `${name} timed out after ${timeoutMs}ms` }));
+            }, timeoutMs);
+            this.pending.set(id, { resolve, reject, timer });
+            this.transport.send({ type: 'request', id, name, args });
+        });
+    }
+    camera = {
+        snapshot: () => this.#request('camera.snapshot').then((r) => r),
+        getConfig: () => this.#request('camera.config').then((r) => r),
+        start: () => this.#request('camera.start').then(() => undefined),
+        stop: () => this.#request('camera.stop').then(() => undefined),
+        stream: () => this.openStream(),
+        stopStream: () => this.closeStream(),
+    };
+    device = {
+        list: () => this.#request('device.list').then((r) => (r.devices ?? r)),
+        onError: (fn) => this.deviceErrCh.add(fn),
+        onConnected: (fn) => this.deviceConnCh.add(fn),
+        onPlayerLost: (fn) => this.playerLostCh.add(fn),
+    };
+    status() {
+        return this.#request('runtime.status').then((r) => r);
+    }
+    /**
+     * Live retuning. Applied by the runtime — the SDK never recomputes Pointer
+     * locally, or the browser and runtime would disagree about where the hand is.
+     */
+    reconfigure(config) {
+        this.transport.send({ type: 'reconfigure', config });
+    }
+    /** Values the runtime reported as actually in effect, for HUDs. Read-only. */
+    get effectiveConfig() {
+        return this.lastConfig;
+    }
+    /* --- subscriptions ----------------------------------------------------- */
+    body = {
+        onUpdate: (fn) => this.bodyCh.add(fn),
+    };
+    gesture = {
+        onUpdate: (fn) => this.gestureCh.add(fn),
+        on: (name, fn) => {
+            let ch = this.gestureByName.get(name);
+            if (!ch) {
+                ch = new Channel();
+                this.gestureByName.set(name, ch);
+            }
+            return ch.add(fn);
+        },
+    };
+    /** Fine-grained fingers/hand-shape events from the optional Hand5 pipeline. */
+    handGesture = {
+        onUpdate: (fn) => this.handGestureCh.add(fn),
+        onDiagnostic: (fn) => this.handGestureDiagnosticCh.add(fn),
+    };
+    pointer = {
+        onUpdate: (fn) => this.pointerCh.add(fn),
+    };
+    silhouette = {
+        onUpdate: (fn) => this.silhouetteCh.add(fn),
+    };
+    playerSilhouette = {
+        onUpdate: (fn) => this.playerSilhouetteCh.add(fn),
+        onLost: (fn) => this.playerSilhouetteLostCh.add(fn),
+        current: () => this.lastPlayerSilhouette,
+    };
+    motion = {
+        onUpdate: (fn) => this.motionCh.add(fn),
+    };
+    onCapabilityChanged(fn) {
+        return this.capChangeCh.add(fn);
+    }
+    onStateChange(fn) {
+        return this.stateCh.add(fn);
+    }
+    /* --- video ------------------------------------------------------------- */
+    pc = null;
+    /**
+     * Establishes the WebRTC stream. The whole signalling exchange is hidden;
+     * callers get a MediaStream.
+     */
+    async openStream() {
+        const RTC = globalThis.RTCPeerConnection;
+        if (!RTC)
+            throw new Error('WebRTC is not available in this environment');
+        this.closeStream(); // one receiver per Runtime session
+        const pc = new RTC({ iceServers: [] }); // local-only: no STUN needed
+        this.pc = pc;
+        pc.addTransceiver('video', { direction: 'recvonly' });
+        const stream = new MediaStream();
+        let remoteDescriptionApplied = false;
+        const pendingRemoteIce = [];
+        const addRemoteIce = async (candidate) => {
+            if (!candidate)
+                return;
+            await pc.addIceCandidate({ candidate, sdpMid: '0' });
+        };
+        // camera:ice is intentionally an event rather than a response: host ICE
+        // gathering can happen while camera.offer is still awaiting its answer.
+        const offRemoteIce = this.transport.onMessage((raw) => {
+            const msg = raw;
+            if (msg.type !== 'camera:ice' || typeof msg.candidate !== 'string' || !msg.candidate)
+                return;
+            if (!remoteDescriptionApplied)
+                pendingRemoteIce.push(msg.candidate);
+            else
+                void addRemoteIce(msg.candidate).catch(() => { });
+        });
+        const track = new Promise((resolve) => {
+            pc.ontrack = (ev) => {
+                stream.addTrack(ev.track);
+                resolve(stream);
+            };
+        });
+        pc.onicecandidate = (ev) => {
+            if (ev.candidate) {
+                void this.#request('camera.ice', { candidate: ev.candidate.candidate }).catch(() => {
+                    /* trickle ICE is best-effort; the offer/answer already carries host candidates */
+                });
+            }
+            else {
+                void this.#request('camera.ice', { done: true }).catch(() => { });
+            }
+        };
+        try {
+            const offer = await pc.createOffer();
+            await pc.setLocalDescription(offer);
+            const res = await this.#request('camera.offer', {
+                sdp: offer.sdp, type: offer.type, stream: 'color', transport: 'webrtc-h264',
+            });
+            if (typeof res.sdp !== 'string' || !res.sdp)
+                throw new Error('camera.offer returned no SDP answer');
+            await pc.setRemoteDescription({ type: 'answer', sdp: res.sdp });
+            remoteDescriptionApplied = true;
+            while (pendingRemoteIce.length)
+                await addRemoteIce(pendingRemoteIce.shift());
+            return await track;
+        }
+        catch (error) {
+            if (this.pc === pc)
+                this.closeStream();
+            throw error;
+        }
+        finally {
+            // The connection-level dispatcher remains installed; this one exists
+            // only to bridge this particular PeerConnection's ICE lifecycle.
+            offRemoteIce();
+        }
+    }
+    closeStream() {
+        this.pc?.close();
+        this.pc = null;
+    }
+    /**
+     * Delays skeleton delivery to match the video's playback clock.
+     *
+     * Skeletons arrive one to two frames ahead of the picture, so drawing an
+     * overlay straight from body.onUpdate puts the lines in front of the player.
+     */
+    alignToVideo(video, offsetMs = 0) {
+        const queue = [];
+        const MAX = 120; // ~4s at 30fps; enough for any plausible offset
+        let baseTs = null;
+        let baseTime = null;
+        let offset = offsetMs;
+        const off = this.bodyCh.add((b) => {
+            if (baseTs === null) {
+                baseTs = b.ts;
+                baseTime = video.currentTime;
+            }
+            queue.push(b);
+            if (queue.length > MAX)
+                queue.shift();
+        });
+        return {
+            current() {
+                if (queue.length === 0 || baseTs === null || baseTime === null)
+                    return null;
+                // Map playback position back onto the skeleton clock.
+                const wanted = baseTs + (video.currentTime - baseTime) * 1000 - offset;
+                let best = queue[0];
+                let bestDist = Math.abs(best.ts - wanted);
+                for (let i = 1; i < queue.length; i++) {
+                    const d = Math.abs(queue[i].ts - wanted);
+                    if (d <= bestDist) {
+                        best = queue[i];
+                        bestDist = d;
+                    }
+                }
+                return best;
+            },
+            setOffset(ms) {
+                offset = ms;
+            },
+            get offsetMs() {
+                return offset;
+            },
+            dispose() {
+                off();
+                queue.length = 0;
+            },
+        };
+    }
+    /* --- lifecycle --------------------------------------------------------- */
+    dispose() {
+        for (const d of this.disposers)
+            d();
+        this.disposers = [];
+        for (const [, entry] of this.pending) {
+            this.clearTimer(entry.timer);
+            entry.reject(new Error('runtime disposed'));
+        }
+        this.pending.clear();
+        this.closeStream();
+    }
+}

package/dist/runtime/index.d.ts

@@ -0,0 +1,42 @@
+import type { ConnectionOptions, ConnectionState, Transport } from './connection.js';
+import type { ConnectStatus } from './capability.js';
+import { RuntimeFacade } from './facade.js';
+import type { HelloMessage } from './protocol.js';
+export interface CreateRuntimeOptions extends Omit<ConnectionOptions, 'require'> {
+    /** 'live' talks to the runtime over WebSocket; 'mock' synthesises the same envelope. */
+    source?: 'live' | 'mock';
+    require?: HelloMessage['require'];
+    /** Frame rate for the mock source. Ignored when live. */
+    mockFps?: number;
+}
+export declare class Runtime extends RuntimeFacade {
+    /** Named for the handshake result, not the runtime.status command above it. */
+    private lastConnectStatus;
+    constructor(transport: Transport, timers?: ConnectionOptions);
+    /**
+     * Opens the connection and returns the runtime's verdict.
+     *
+     * Waits for exactly one message type. The protocol guarantees hello is always
+     * answered with ready — success or not — so there is no race between "wait for
+     * ready" and "wait for an error message".
+     */
+    connect(): Promise<ConnectStatus>;
+    /** The last handshake result. Null before connect() resolves. */
+    get connectStatus(): ConnectStatus | null;
+    get state(): ConnectionState;
+    close(): void;
+}
+export declare function createRuntime(options?: CreateRuntimeOptions): Runtime;
+export { WsConnection, defaultUrl } from './connection.js';
+export { MockTransport } from './mock.js';
+export { RuntimeFacade } from './facade.js';
+export { toConnectStatus, explainMiss, describeGate } from './capability.js';
+export type { ConnectStatus } from './capability.js';
+export { decodeSilhouette, parseBinaryFrame, fnv1a64, binaryCorrelationId, QSBN_HEADER_BYTES } from './decode.js';
+export type { SilhouetteFrame, BinaryFrame } from './decode.js';
+export { RuntimeCommandError } from './facade.js';
+export type { Unsubscribe, GestureName, MotionUpdate, SnapshotResult, DeviceInfo, RuntimeStatus, CameraConfig, CapabilityChange, VideoAligner, PlayerSilhouetteFrame, PlayerSilhouetteLost, } from './facade.js';
+export type { ConnectionState, ConnectionOptions, Transport } from './connection.js';
+export type { BodyUpdate, Capability, CapabilityMiss, CalibBox, DepthSilhouette, DeviceConnected, DeviceError, GestureUpdate, HandGestureUpdate, HandGestureDiagnostic, HelloMessage, Joint, PointerUpdate, PlayerSilhouette, PlayerSilhouetteLost as PlayerSilhouetteLostEvent, ReadyMessage, RequestError, RequestName, RuntimeConfig, RuntimeNamespace, ServerMessage, Timestamp, } from './protocol.js';
+export { SCHEMA_HASH, RUNTIME_URL, GRID_W, GRID_H } from './protocol.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/runtime/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/runtime/index.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAErF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD,MAAM,WAAW,oBAAqB,SAAQ,IAAI,CAAC,iBAAiB,EAAE,SAAS,CAAC;IAC9E,wFAAwF;IACxF,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,OAAO,CAAC,EAAE,YAAY,CAAC,SAAS,CAAC,CAAC;IAClC,yDAAyD;IACzD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,qBAAa,OAAQ,SAAQ,aAAa;IACxC,+EAA+E;IAC/E,OAAO,CAAC,iBAAiB,CAA8B;gBAE3C,SAAS,EAAE,SAAS,EAAE,MAAM,CAAC,EAAE,iBAAiB;IAO5D;;;;;;OAMG;IACG,OAAO,IAAI,OAAO,CAAC,aAAa,CAAC;IAMvC,iEAAiE;IACjE,IAAI,aAAa,IAAI,aAAa,GAAG,IAAI,CAExC;IAED,IAAI,KAAK,IAAI,eAAe,CAE3B;IAED,KAAK,IAAI,IAAI;CAId;AAED,wBAAgB,aAAa,CAAC,OAAO,GAAE,oBAAyB,GAAG,OAAO,CAazE;AAMD,OAAO,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC7E,YAAY,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AACrD,OAAO,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAClH,YAAY,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAChE,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,YAAY,EACV,WAAW,EACX,WAAW,EACX,YAAY,EACZ,cAAc,EACd,UAAU,EACV,aAAa,EACb,YAAY,EACZ,gBAAgB,EAChB,YAAY,EACZ,qBAAqB,EACrB,oBAAoB,GACrB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,eAAe,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AACrF,YAAY,EACV,UAAU,EACV,UAAU,EACV,cAAc,EACd,QAAQ,EACR,eAAe,EACf,eAAe,EACf,WAAW,EACX,aAAa,EACb,iBAAiB,EACjB,qBAAqB,EACrB,YAAY,EACZ,KAAK,EACL,aAAa,EACb,gBAAgB,EAChB,oBAAoB,IAAI,yBAAyB,EACjD,YAAY,EACZ,YAAY,EACZ,WAAW,EACX,aAAa,EACb,gBAAgB,EAChB,aAAa,EACb,SAAS,GACV,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC"}

package/dist/runtime/index.js

@@ -0,0 +1,70 @@
+/**
+ * QikSense Runtime SDK — the single entry point for web experiences.
+ *
+ * Games write `runtime.body.onUpdate(...)`, never `socket.onmessage`. Protocol,
+ * reconnect, heartbeat and capability negotiation all live below this line.
+ *
+ * Framework-free by construction. The Vue adapter is a separate subpath
+ * (`@realnation/builder-shared-sdk/runtime/vue`) so Canvas/WebGL experiences,
+ * tooling and non-Vue hosts never pull in a reactivity system they do not want.
+ */
+import { WsConnection } from './connection.js';
+import { toConnectStatus } from './capability.js';
+import { RuntimeFacade } from './facade.js';
+import { MockTransport } from './mock.js';
+export class Runtime extends RuntimeFacade {
+    /** Named for the handshake result, not the runtime.status command above it. */
+    lastConnectStatus = null;
+    constructor(transport, timers) {
+        super(transport, {
+            setTimer: timers?.setTimer,
+            clearTimer: timers?.clearTimer,
+        });
+    }
+    /**
+     * Opens the connection and returns the runtime's verdict.
+     *
+     * Waits for exactly one message type. The protocol guarantees hello is always
+     * answered with ready — success or not — so there is no race between "wait for
+     * ready" and "wait for an error message".
+     */
+    async connect() {
+        const ready = await this.transport.connect();
+        this.lastConnectStatus = toConnectStatus(ready);
+        return this.lastConnectStatus;
+    }
+    /** The last handshake result. Null before connect() resolves. */
+    get connectStatus() {
+        return this.lastConnectStatus;
+    }
+    get state() {
+        return this.transport.state;
+    }
+    close() {
+        this.dispose();
+        this.transport.close();
+    }
+}
+export function createRuntime(options = {}) {
+    const transport = options.source === 'mock'
+        ? new MockTransport({
+            require: options.require,
+            fps: options.mockFps,
+            setTimer: options.setTimer,
+            clearTimer: options.clearTimer,
+            now: options.now,
+        })
+        : new WsConnection(options);
+    return new Runtime(transport, options);
+}
+/* --- public surface -------------------------------------------------------
+ * Named exports only. `export *` would collide with the package root's generic
+ * names (Capability, Pointer) the moment anyone imports both.
+ */
+export { WsConnection, defaultUrl } from './connection.js';
+export { MockTransport } from './mock.js';
+export { RuntimeFacade } from './facade.js';
+export { toConnectStatus, explainMiss, describeGate } from './capability.js';
+export { decodeSilhouette, parseBinaryFrame, fnv1a64, binaryCorrelationId, QSBN_HEADER_BYTES } from './decode.js';
+export { RuntimeCommandError } from './facade.js';
+export { SCHEMA_HASH, RUNTIME_URL, GRID_W, GRID_H } from './protocol.js';

package/dist/runtime/mock.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Synthetic source. Same envelope as real hardware, no device required.
+ *
+ * Principle: the mock may be stricter than the real runtime, never looser.
+ * A permissive mock lets code pass here and fail on hardware — the most
+ * expensive failure mode there is, because it defers the bug to the one
+ * environment where a camera is plugged in.
+ *
+ * Concretely that means: it answers pong but never sends ping (heartbeat
+ * direction matches), and it emits ready.requested and device:connected.config
+ * even though nothing here reads them.
+ */
+import type { ConnectionState, Transport } from './connection.js';
+import type { Capability, ClientMessage, HelloMessage, ReadyMessage, ServerMessage } from './protocol.js';
+export interface MockOptions {
+    require?: HelloMessage['require'];
+    fps?: number;
+    /** Capabilities the fake runtime claims. Defaults to whatever was requested. */
+    provides?: Capability['name'][];
+    setTimer?: (fn: () => void, ms: number) => unknown;
+    clearTimer?: (h: unknown) => void;
+    now?: () => number;
+    /** Drives frames manually instead of on a timer. For deterministic tests. */
+    manual?: boolean;
+}
+export declare class MockTransport implements Transport {
+    private messageHandlers;
+    private binaryHandlers;
+    private stateHandlers;
+    private timerHandle;
+    private _state;
+    private frame;
+    private readonly opts;
+    /** Set once ping has been observed, so tests can assert direction. */
+    pingsReceived: number;
+    constructor(options?: MockOptions);
+    get state(): ConnectionState;
+    private setState;
+    connect(): Promise<ReadyMessage>;
+    private schedule;
+    /** Emits one frame's worth of events. Public so `manual: true` tests can step. */
+    tick(): void;
+    private makeBody;
+    private makePointer;
+    private makeSilhouette;
+    private makePlayerSilhouette;
+    send(msg: ClientMessage): void;
+    private answer;
+    /**
+     * Public so tests and demos can inject an exact frame. Real sessions never
+     * call it — the mock drives itself from tick().
+     */
+    emit(msg: ServerMessage): void;
+    onMessage(fn: (m: ServerMessage) => void): () => void;
+    onBinary(fn: (d: ArrayBuffer) => void): () => void;
+    onStateChange(fn: (s: ConnectionState) => void): () => void;
+    close(): void;
+}
+//# sourceMappingURL=mock.d.ts.map

package/dist/runtime/mock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock.d.ts","sourceRoot":"","sources":["../../src/runtime/mock.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAElE,OAAO,KAAK,EAEV,UAAU,EACV,aAAa,EAIb,YAAY,EAIZ,YAAY,EAGZ,aAAa,EACd,MAAM,eAAe,CAAC;AAEvB,MAAM,WAAW,WAAW;IAC1B,OAAO,CAAC,EAAE,YAAY,CAAC,SAAS,CAAC,CAAC;IAClC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,gFAAgF;IAChF,QAAQ,CAAC,EAAE,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;IAChC,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC;IACnD,UAAU,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;IAClC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,6EAA6E;IAC7E,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAQD,qBAAa,aAAc,YAAW,SAAS;IAC7C,OAAO,CAAC,eAAe,CAAyC;IAChE,OAAO,CAAC,cAAc,CAAuC;IAC7D,OAAO,CAAC,aAAa,CAA2C;IAChE,OAAO,CAAC,WAAW,CAAiB;IACpC,OAAO,CAAC,MAAM,CAA2B;IACzC,OAAO,CAAC,KAAK,CAAK;IAClB,OAAO,CAAC,QAAQ,CAAC,IAAI,CACuB;IAC5C,sEAAsE;IACtE,aAAa,SAAK;gBAEN,OAAO,GAAE,WAAgB;IAYrC,IAAI,KAAK,IAAI,eAAe,CAE3B;IAED,OAAO,CAAC,QAAQ;IAMhB,OAAO,IAAI,OAAO,CAAC,YAAY,CAAC;IA4ChC,OAAO,CAAC,QAAQ;IAShB,kFAAkF;IAClF,IAAI,IAAI,IAAI;IAmCZ,OAAO,CAAC,QAAQ;IAgBhB,OAAO,CAAC,WAAW;IAcnB,OAAO,CAAC,cAAc;IA2BtB,OAAO,CAAC,oBAAoB;IAQ5B,IAAI,CAAC,GAAG,EAAE,aAAa,GAAG,IAAI;IAsB9B,OAAO,CAAC,MAAM;IA4Bd;;;OAGG;IACH,IAAI,CAAC,GAAG,EAAE,aAAa,GAAG,IAAI;IAI9B,SAAS,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,aAAa,KAAK,IAAI,GAAG,MAAM,IAAI;IAKrD,QAAQ,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,WAAW,KAAK,IAAI,GAAG,MAAM,IAAI;IAKlD,aAAa,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,eAAe,KAAK,IAAI,GAAG,MAAM,IAAI;IAK3D,KAAK,IAAI,IAAI;CAOd"}