@realnation/builder-shared-sdk 1.0.5 → 1.1.0

package/dist/runtime/decode.js

@@ -0,0 +1,106 @@
+/**
+ * Pure decoding helpers. No state, no I/O — all directly unit-testable.
+ */
+import { GRID_H, GRID_W } from './protocol.js';
+function base64ToBytes(b64) {
+    // atob in browsers, Buffer under node/vitest.
+    const g = globalThis;
+    if (typeof g.atob === 'function') {
+        const bin = g.atob(b64);
+        const out = new Uint8Array(bin.length);
+        for (let i = 0; i < bin.length; i++)
+            out[i] = bin.charCodeAt(i);
+        return out;
+    }
+    if (g.Buffer)
+        return new Uint8Array(g.Buffer.from(b64, 'base64'));
+    throw new Error('no base64 decoder available');
+}
+/**
+ * Unpacks the 1-bit mask.
+ *
+ * MSB is the leftmost pixel of each byte — the same order the runtime packs
+ * (qs_silhouette_v1). Getting this backwards mirrors every row, which looks
+ * plausible on a symmetric scene and is why the bit order is asserted in tests.
+ */
+export function decodeSilhouette(msg) {
+    const w = msg.w || GRID_W;
+    const h = msg.h || GRID_H;
+    const bytes = base64ToBytes(msg.mask);
+    const cells = new Uint8Array(w * h);
+    const expected = Math.ceil((w * h) / 8);
+    if (bytes.length < expected) {
+        throw new Error(`silhouette mask truncated: got ${bytes.length} bytes, need ${expected}`);
+    }
+    for (let i = 0; i < w * h; i++) {
+        const byte = bytes[i >> 3];
+        const bit = 7 - (i & 7);
+        cells[i] = (byte >> bit) & 1;
+    }
+    const frame = {
+        w,
+        h,
+        cells,
+        coverage: msg.coverage ?? countSet(cells) / (w * h),
+        nearest: msg.nearest,
+        farthest: msg.farthest,
+        ts: msg.ts,
+        at(cx, cy) {
+            if (cx < 0 || cy < 0 || cx >= w || cy >= h)
+                return false;
+            return cells[cy * w + cx] === 1;
+        },
+        hit(x, y) {
+            return frame.at(Math.floor(x * w), Math.floor(y * h));
+        },
+    };
+    return frame;
+}
+function countSet(cells) {
+    let n = 0;
+    for (let i = 0; i < cells.length; i++)
+        n += cells[i];
+    return n;
+}
+/* --- QSBN binary frame header (design/02 §9) ------------------------------ */
+export const QSBN_HEADER_BYTES = 16;
+const QSBN_MAGIC = 0x5153424e; // "QSBN"
+/**
+ * FNV-1a over the id string. Ids longer than 8 bytes are hashed by both sides
+ * with this same function, so the header stays fixed-width without giving up
+ * the ability to detect a mispaired frame.
+ */
+export function fnv1a64(s) {
+    let hash = 0xcbf29ce484222325n;
+    const prime = 0x100000001b3n;
+    const mask = 0xffffffffffffffffn;
+    for (let i = 0; i < s.length; i++) {
+        hash = (hash ^ BigInt(s.charCodeAt(i) & 0xff)) & mask;
+        hash = (hash * prime) & mask;
+    }
+    return hash;
+}
+/** The id as it appears in a QSBN header: raw big-endian bytes, or the hash. */
+export function binaryCorrelationId(id) {
+    if (id.length > 8)
+        return fnv1a64(id);
+    let v = 0n;
+    for (let i = 0; i < id.length; i++)
+        v = (v << 8n) | BigInt(id.charCodeAt(i) & 0xff);
+    return v;
+}
+export function parseBinaryFrame(buf) {
+    if (buf.byteLength < QSBN_HEADER_BYTES) {
+        throw new Error(`binary frame shorter than header: ${buf.byteLength} bytes`);
+    }
+    const view = new DataView(buf);
+    const magic = view.getUint32(0, false);
+    if (magic !== QSBN_MAGIC) {
+        throw new Error('binary frame missing QSBN magic');
+    }
+    return {
+        version: view.getUint16(4, false),
+        id: view.getBigUint64(8, false),
+        payload: buf.slice(QSBN_HEADER_BYTES),
+    };
+}

package/dist/runtime/facade.d.ts

@@ -0,0 +1,165 @@
+/**
+ * The public surface: subscriptions, semantic commands, video.
+ *
+ * Two things are deliberately absent and must stay absent:
+ *   - `publish` — a client publishing would break the runtime's control boundary.
+ *   - a raw `request(name)` — that leaks an internal concept back out and
+ *     re-enables the polling antipattern the command table exists to prevent.
+ * Adding a command means adding a named method here, not opening an escape hatch.
+ */
+import type { Transport, ConnectionState } from './connection.js';
+import type { SilhouetteFrame } from './decode.js';
+import type { BodyUpdate, DeviceConnected, DeviceError, GestureUpdate, PointerUpdate, RequestError, RuntimeConfig } from './protocol.js';
+export type Unsubscribe = () => void;
+export type GestureName = GestureUpdate['gesture'];
+/** Motion (IMU). Carried as a generic event until the schema grows a definition. */
+export interface MotionUpdate {
+    type: 'motion:update';
+    euler?: {
+        yaw: number;
+        pitch: number;
+        roll: number;
+    };
+    quat?: {
+        w: number;
+        x: number;
+        y: number;
+        z: number;
+    };
+    accel?: {
+        x: number;
+        y: number;
+        z: number;
+    };
+    battery?: {
+        voltage?: number;
+        percent?: number;
+    };
+    ts: number;
+}
+export declare class RuntimeCommandError extends Error {
+    readonly code: RequestError['code'];
+    constructor(err: RequestError);
+}
+export interface SnapshotResult {
+    mime: string;
+    data: string;
+}
+export interface DeviceInfo {
+    id: string;
+    plugin: string;
+    status: string;
+}
+export interface RuntimeStatus {
+    version: string;
+    uptimeMs: number;
+    clients: number;
+}
+export interface CameraConfig {
+    width: number;
+    height: number;
+    fps: number;
+}
+export interface CapabilityChange {
+    capabilities: unknown[];
+    lost: unknown[];
+}
+/** Aligns skeleton data to the video's playback clock (design/03 §4.5). */
+export interface VideoAligner {
+    current(): BodyUpdate | null;
+    setOffset(ms: number): void;
+    readonly offsetMs: number;
+    dispose(): void;
+}
+interface VideoElementLike {
+    currentTime: number;
+}
+export declare class RuntimeFacade {
+    #private;
+    protected readonly transport: Transport;
+    private pending;
+    /** Ids whose JSON response said binary:true, in arrival order. */
+    private binaryQueue;
+    private requestSeq;
+    private disposers;
+    private readonly bodyCh;
+    private readonly gestureCh;
+    private readonly gestureByName;
+    private readonly pointerCh;
+    private readonly silhouetteCh;
+    private readonly motionCh;
+    private readonly deviceErrCh;
+    private readonly deviceConnCh;
+    private readonly playerLostCh;
+    private readonly capChangeCh;
+    private readonly stateCh;
+    /** Last `device:connected.config` seen. Read-through only — see effectiveConfig. */
+    private lastConfig;
+    private trackedPlayers;
+    private readonly setTimer;
+    private readonly clearTimer;
+    constructor(transport: Transport, timers?: {
+        setTimer?: (fn: () => void, ms: number) => unknown;
+        clearTimer?: (h: unknown) => void;
+    });
+    private dispatch;
+    private settle;
+    private dispatchBinary;
+    readonly camera: {
+        snapshot: () => Promise<SnapshotResult>;
+        getConfig: () => Promise<CameraConfig>;
+        start: () => Promise<void>;
+        stop: () => Promise<void>;
+        stream: () => Promise<MediaStream>;
+        stopStream: () => void;
+    };
+    readonly device: {
+        list: () => Promise<DeviceInfo[]>;
+        onError: (fn: (e: DeviceError) => void) => Unsubscribe;
+        onConnected: (fn: (e: DeviceConnected) => void) => Unsubscribe;
+        onPlayerLost: (fn: () => void) => Unsubscribe;
+    };
+    status(): Promise<RuntimeStatus>;
+    /**
+     * 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: RuntimeConfig): void;
+    /** Values the runtime reported as actually in effect, for HUDs. Read-only. */
+    get effectiveConfig(): Record<string, unknown>;
+    readonly body: {
+        onUpdate: (fn: (b: BodyUpdate) => void) => Unsubscribe;
+    };
+    readonly gesture: {
+        onUpdate: (fn: (g: GestureUpdate) => void) => Unsubscribe;
+        on: (name: GestureName, fn: (g: GestureUpdate) => void) => Unsubscribe;
+    };
+    readonly pointer: {
+        onUpdate: (fn: (p: PointerUpdate) => void) => Unsubscribe;
+    };
+    readonly silhouette: {
+        onUpdate: (fn: (f: SilhouetteFrame) => void) => Unsubscribe;
+    };
+    readonly motion: {
+        onUpdate: (fn: (m: MotionUpdate) => void) => Unsubscribe;
+    };
+    onCapabilityChanged(fn: (c: CapabilityChange) => void): Unsubscribe;
+    onStateChange(fn: (s: ConnectionState) => void): Unsubscribe;
+    private pc;
+    /**
+     * Establishes the WebRTC stream. The whole signalling exchange is hidden;
+     * callers get a MediaStream.
+     */
+    private openStream;
+    private closeStream;
+    /**
+     * 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: VideoElementLike, offsetMs?: number): VideoAligner;
+    dispose(): void;
+}
+export {};
+//# sourceMappingURL=facade.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"facade.d.ts","sourceRoot":"","sources":["../../src/runtime/facade.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AAElE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACnD,OAAO,KAAK,EACV,UAAU,EACV,eAAe,EACf,WAAW,EACX,aAAa,EACb,aAAa,EAEb,YAAY,EAEZ,aAAa,EAEd,MAAM,eAAe,CAAC;AAEvB,MAAM,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC;AAErC,MAAM,MAAM,WAAW,GAAG,aAAa,CAAC,SAAS,CAAC,CAAC;AAEnD,oFAAoF;AACpF,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,eAAe,CAAC;IACtB,KAAK,CAAC,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IACrD,IAAI,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACtD,KAAK,CAAC,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,OAAO,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACjD,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC,MAAM,CAAC,CAAC;gBACxB,GAAG,EAAE,YAAY;CAK9B;AAyBD,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,gBAAgB;IAC/B,YAAY,EAAE,OAAO,EAAE,CAAC;IACxB,IAAI,EAAE,OAAO,EAAE,CAAC;CACjB;AAED,2EAA2E;AAC3E,MAAM,WAAW,YAAY;IAC3B,OAAO,IAAI,UAAU,GAAG,IAAI,CAAC;IAC7B,SAAS,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,UAAU,gBAAgB;IACxB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,qBAAa,aAAa;;IACxB,SAAS,CAAC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IACxC,OAAO,CAAC,OAAO,CASX;IACJ,kEAAkE;IAClE,OAAO,CAAC,WAAW,CAAgB;IACnC,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,SAAS,CAAqB;IAEtC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA6B;IACpD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgC;IAC1D,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAkD;IAChF,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAgC;IAC1D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAkC;IAC/D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA+B;IACxD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA8B;IAC1D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAkC;IAC/D,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAuB;IACpD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAmC;IAC/D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkC;IAE1D,oFAAoF;IACpF,OAAO,CAAC,UAAU,CAA+B;IACjD,OAAO,CAAC,cAAc,CAAqB;IAC3C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA0C;IACnE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAuB;gBAGhD,SAAS,EAAE,SAAS,EACpB,MAAM,CAAC,EAAE;QACP,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC;QACnD,UAAU,CAAC,EAAE,CAAC,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;KACnC;IAaH,OAAO,CAAC,QAAQ;IAiDhB,OAAO,CAAC,MAAM;IAuBd,OAAO,CAAC,cAAc;IAqEtB,QAAQ,CAAC,MAAM;wBACC,OAAO,CAAC,cAAc,CAAC;yBAEtB,OAAO,CAAC,YAAY,CAAC;qBAEzB,OAAO,CAAC,IAAI,CAAC;oBACd,OAAO,CAAC,IAAI,CAAC;sBACX,OAAO,CAAC,WAAW,CAAC;0BAChB,IAAI;MACpB;IAEF,QAAQ,CAAC,MAAM;oBACH,OAAO,CAAC,UAAU,EAAE,CAAC;sBAEjB,CAAC,CAAC,EAAE,WAAW,KAAK,IAAI,KAAG,WAAW;0BAClC,CAAC,CAAC,EAAE,eAAe,KAAK,IAAI,KAAG,WAAW;2BACzC,MAAM,IAAI,KAAG,WAAW;MAC3C;IAEF,MAAM,IAAI,OAAO,CAAC,aAAa,CAAC;IAIhC;;;OAGG;IACH,WAAW,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI;IAIxC,8EAA8E;IAC9E,IAAI,eAAe,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAE7C;IAID,QAAQ,CAAC,IAAI;uBACI,CAAC,CAAC,EAAE,UAAU,KAAK,IAAI,KAAG,WAAW;MACpD;IAEF,QAAQ,CAAC,OAAO;uBACC,CAAC,CAAC,EAAE,aAAa,KAAK,IAAI,KAAG,WAAW;mBAC5C,WAAW,MAAM,CAAC,CAAC,EAAE,aAAa,KAAK,IAAI,KAAG,WAAW;MAQpE;IAEF,QAAQ,CAAC,OAAO;uBACC,CAAC,CAAC,EAAE,aAAa,KAAK,IAAI,KAAG,WAAW;MACvD;IAEF,QAAQ,CAAC,UAAU;uBACF,CAAC,CAAC,EAAE,eAAe,KAAK,IAAI,KAAG,WAAW;MACzD;IAEF,QAAQ,CAAC,MAAM;uBACE,CAAC,CAAC,EAAE,YAAY,KAAK,IAAI,KAAG,WAAW;MACtD;IAEF,mBAAmB,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,gBAAgB,KAAK,IAAI,GAAG,WAAW;IAInE,aAAa,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,eAAe,KAAK,IAAI,GAAG,WAAW;IAM5D,OAAO,CAAC,EAAE,CAAkC;IAE5C;;;OAGG;YACW,UAAU;IAmCxB,OAAO,CAAC,WAAW;IAKnB;;;;;OAKG;IACH,YAAY,CAAC,KAAK,EAAE,gBAAgB,EAAE,QAAQ,SAAI,GAAG,YAAY;IA+CjE,OAAO,IAAI,IAAI;CAUhB"}

package/dist/runtime/facade.js

@@ -0,0 +1,354 @@
+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();
+    gestureByName = new Map();
+    pointerCh = new Channel();
+    silhouetteCh = 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 = {};
+    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 'pointer:update':
+                this.pointerCh.emit(msg);
+                break;
+            case 'depth:silhouette':
+                this.silhouetteCh.emit(decodeSilhouette(msg));
+                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);
+        },
+    };
+    pointer = {
+        onUpdate: (fn) => this.pointerCh.add(fn),
+    };
+    silhouette = {
+        onUpdate: (fn) => this.silhouetteCh.add(fn),
+    };
+    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');
+        const pc = new RTC({ iceServers: [] }); // local-only: no STUN needed
+        this.pc = pc;
+        pc.addTransceiver('video', { direction: 'recvonly' });
+        const stream = new MediaStream();
+        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.toJSON() }).catch(() => {
+                    /* trickle ICE is best-effort; the offer/answer already carries host candidates */
+                });
+            }
+        };
+        const offer = await pc.createOffer();
+        await pc.setLocalDescription(offer);
+        const res = await this.#request('camera.offer', { sdp: offer.sdp, type: offer.type });
+        await pc.setRemoteDescription({
+            type: 'answer',
+            sdp: res.sdp,
+        });
+        return track;
+    }
+    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, } from './facade.js';
+export type { ConnectionState, ConnectionOptions, Transport } from './connection.js';
+export type { BodyUpdate, Capability, CapabilityMiss, CalibBox, DepthSilhouette, DeviceConnected, DeviceError, GestureUpdate, HelloMessage, Joint, PointerUpdate, 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,GACb,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,YAAY,EACZ,KAAK,EACL,aAAa,EACb,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"}