@realnation/builder-shared-sdk 1.0.5 → 1.1.1

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,192 @@
+/**
+ * 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, HandGestureUpdate, HandGestureDiagnostic, PointerUpdate, PlayerSilhouetteLost as PlayerSilhouetteLostEvent, 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[];
+}
+/** A selected foreground player, not generic depth occupancy. */
+export interface PlayerSilhouetteFrame extends SilhouetteFrame {
+    player: {
+        id: number;
+        distance: number;
+        confidence: number;
+    };
+}
+export interface PlayerSilhouetteLost {
+    reason: PlayerSilhouetteLostEvent['reason'];
+    ts: number;
+}
+/** 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 handGestureCh;
+    private readonly handGestureDiagnosticCh;
+    private readonly gestureByName;
+    private readonly pointerCh;
+    private readonly silhouetteCh;
+    private readonly playerSilhouetteCh;
+    private readonly playerSilhouetteLostCh;
+    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 lastPlayerSilhouette;
+    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;
+    };
+    /** Fine-grained fingers/hand-shape events from the optional Hand5 pipeline. */
+    readonly handGesture: {
+        onUpdate: (fn: (g: HandGestureUpdate) => void) => Unsubscribe;
+        onDiagnostic: (fn: (d: HandGestureDiagnostic) => void) => Unsubscribe;
+    };
+    readonly pointer: {
+        onUpdate: (fn: (p: PointerUpdate) => void) => Unsubscribe;
+    };
+    readonly silhouette: {
+        onUpdate: (fn: (f: SilhouetteFrame) => void) => Unsubscribe;
+    };
+    readonly playerSilhouette: {
+        onUpdate: (fn: (f: PlayerSilhouetteFrame) => void) => Unsubscribe;
+        onLost: (fn: (lost: PlayerSilhouetteLost) => void) => Unsubscribe;
+        current: () => PlayerSilhouetteFrame | null;
+    };
+    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,iBAAiB,EACjB,qBAAqB,EACrB,aAAa,EAEb,oBAAoB,IAAI,yBAAyB,EAEjD,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,iEAAiE;AACjE,MAAM,WAAW,qBAAsB,SAAQ,eAAe;IAC5D,MAAM,EAAE;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;CAC9D;AAED,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,yBAAyB,CAAC,QAAQ,CAAC,CAAC;IAC5C,EAAE,EAAE,MAAM,CAAC;CACZ;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,CAAoC;IAClE,OAAO,CAAC,QAAQ,CAAC,uBAAuB,CAAwC;IAChF,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,kBAAkB,CAAwC;IAC3E,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAuC;IAC9E,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,oBAAoB,CAAsC;IAClE,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;IAqEhB,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,+EAA+E;IAC/E,QAAQ,CAAC,WAAW;uBACH,CAAC,CAAC,EAAE,iBAAiB,KAAK,IAAI,KAAG,WAAW;2BACxC,CAAC,CAAC,EAAE,qBAAqB,KAAK,IAAI,KAAG,WAAW;MACnE;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,gBAAgB;uBACR,CAAC,CAAC,EAAE,qBAAqB,KAAK,IAAI,KAAG,WAAW;qBAClD,CAAC,IAAI,EAAE,oBAAoB,KAAK,IAAI,KAAG,WAAW;uBAClD,qBAAqB,GAAG,IAAI;MACzC;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;IA8DxB,OAAO,CAAC,WAAW;IAKnB;;;;;OAKG;IACH,YAAY,CAAC,KAAK,EAAE,gBAAgB,EAAE,QAAQ,SAAI,GAAG,YAAY;IA+CjE,OAAO,IAAI,IAAI;CAUhB"}