@realnation/builder-shared-sdk 1.0.4 → 1.1.0

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,58 @@
+/**
+ * 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;
+    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,EAGb,YAAY,EAGZ,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;IAsBZ,OAAO,CAAC,QAAQ;IAgBhB,OAAO,CAAC,WAAW;IAcnB,OAAO,CAAC,cAAc;IA2BtB,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"}

package/dist/runtime/mock.js

@@ -0,0 +1,276 @@
+import { GRID_H, GRID_W } from './protocol.js';
+const JOINT_NAMES = [
+    'head', 'neck', 'leftShoulder', 'rightShoulder', 'leftElbow', 'rightElbow',
+    'leftHand', 'rightHand', 'leftHip', 'rightHip', 'leftKnee', 'rightKnee',
+    'leftFoot', 'rightFoot',
+];
+export class MockTransport {
+    messageHandlers = new Set();
+    binaryHandlers = new Set();
+    stateHandlers = new Set();
+    timerHandle = null;
+    _state = 'idle';
+    frame = 0;
+    opts;
+    /** Set once ping has been observed, so tests can assert direction. */
+    pingsReceived = 0;
+    constructor(options = {}) {
+        this.opts = {
+            fps: options.fps ?? 30,
+            setTimer: options.setTimer ?? ((fn, ms) => setTimeout(fn, ms)),
+            clearTimer: options.clearTimer ?? ((h) => clearTimeout(h)),
+            now: options.now ?? (() => Date.now()),
+            manual: options.manual ?? false,
+            require: options.require,
+            provides: options.provides,
+        };
+    }
+    get state() {
+        return this._state;
+    }
+    setState(s) {
+        if (this._state === s)
+            return;
+        this._state = s;
+        for (const fn of this.stateHandlers)
+            fn(s);
+    }
+    connect() {
+        const requested = this.opts.require?.capabilities ?? [];
+        const provided = this.opts.provides
+            ? this.opts.provides.map((name) => ({ name, version: 1 }))
+            : requested.map((c) => ({ name: c.name, version: c.version ?? 1, params: c.params }));
+        const providedNames = new Set(provided.map((c) => c.name));
+        const missing = requested
+            .filter((c) => !c.optional && !providedNames.has(c.name))
+            .map((c) => ({ name: c.name, reason: 'NO_PLUGIN' }));
+        const unsatisfied = requested
+            .filter((c) => c.optional && !providedNames.has(c.name))
+            .map((c) => ({ name: c.name, reason: 'NO_PLUGIN' }));
+        const ready = {
+            type: 'ready',
+            ok: missing.length === 0,
+            runtimeVersion: '0.0.0-mock',
+            protocolVersion: 1,
+            clientId: 'mock-client',
+            capabilities: provided,
+            missing,
+            unsatisfied,
+            plugins: ['mock'],
+            // Echoed even though nothing here reads it: a mock that drops the
+            // troubleshooting fields would hide bugs in code that relies on them.
+            requested: this.opts.require ?? {},
+        };
+        this.setState('ready');
+        this.emit(ready);
+        this.emit({
+            type: 'device:connected',
+            device: 'mock',
+            id: 'mock-0',
+            config: {
+                runtime: { preset: 'standard', minDistanceM: 0.2, maxDistanceM: 3.0, gain: 1.0 },
+            },
+        });
+        if (!this.opts.manual)
+            this.schedule();
+        return Promise.resolve(ready);
+    }
+    schedule() {
+        const period = Math.round(1000 / this.opts.fps);
+        const tick = () => {
+            this.tick();
+            this.timerHandle = this.opts.setTimer(tick, period);
+        };
+        this.timerHandle = this.opts.setTimer(tick, period);
+    }
+    /** Emits one frame's worth of events. Public so `manual: true` tests can step. */
+    tick() {
+        const t = this.frame / this.opts.fps;
+        const ts = this.opts.now();
+        this.frame++;
+        this.emit(this.makeBody(t, ts));
+        this.emit(this.makePointer(t, ts));
+        // A gesture every two seconds, alternating, so handlers get exercised.
+        if (this.frame % (this.opts.fps * 2) === 0) {
+            const gestures = ['raise_left', 'raise_right', 'jump', 'wave'];
+            this.emit({
+                type: 'gesture:update',
+                player: 0,
+                gesture: gestures[(this.frame / (this.opts.fps * 2)) % gestures.length | 0],
+                ts,
+            });
+        }
+        if (this.frame % 3 === 0)
+            this.emit(this.makeSilhouette(t, ts));
+    }
+    makeBody(t, ts) {
+        const sway = Math.sin(t * 0.7) * 0.08;
+        const skeleton = {};
+        for (const name of JOINT_NAMES) {
+            skeleton[name] = jointFor(name, t, sway);
+        }
+        return {
+            type: 'body:update',
+            player: 0,
+            center: { x: 0.5 + sway, y: 0.5 },
+            depth: 2.0 + Math.sin(t * 0.3) * 0.2,
+            ts,
+            skeleton,
+        };
+    }
+    makePointer(t, ts) {
+        const x = 0.5 + Math.sin(t * 1.1) * 0.35;
+        const y = 0.5 + Math.cos(t * 0.9) * 0.3;
+        return {
+            type: 'pointer:update',
+            id: 0,
+            x: clamp01(x),
+            y: clamp01(y),
+            down: Math.sin(t * 1.1) > 0.8,
+            raw: { x: x * 1.4 - 0.2, y: y * 1.4 - 0.2 },
+            ts,
+        };
+    }
+    makeSilhouette(t, ts) {
+        const bytes = new Uint8Array(Math.ceil((GRID_W * GRID_H) / 8));
+        const cx = GRID_W * (0.5 + Math.sin(t * 0.7) * 0.15);
+        let set = 0;
+        for (let y = 0; y < GRID_H; y++) {
+            // A rough torso-and-head column.
+            const halfWidth = y < GRID_H * 0.2 ? GRID_W * 0.05 : GRID_W * 0.11;
+            for (let x = 0; x < GRID_W; x++) {
+                if (y > GRID_H * 0.1 && Math.abs(x - cx) < halfWidth) {
+                    const i = y * GRID_W + x;
+                    bytes[i >> 3] |= 0x80 >> (i & 7); // MSB is leftmost, as the runtime packs
+                    set++;
+                }
+            }
+        }
+        return {
+            type: 'depth:silhouette',
+            w: GRID_W,
+            h: GRID_H,
+            mask: bytesToBase64(bytes),
+            coverage: set / (GRID_W * GRID_H),
+            nearest: 1.8,
+            farthest: 2.4,
+            ts,
+        };
+    }
+    send(msg) {
+        if (msg.type === 'ping') {
+            this.pingsReceived++;
+            this.emit({ type: 'pong', ts: msg.ts });
+            return;
+        }
+        if (msg.type === 'request') {
+            this.answer(msg.id, msg.name);
+            return;
+        }
+        if (msg.type === 'reconfigure') {
+            // Same guarantee as the real runtime: retuning does not interrupt the
+            // stream, and the effective values come back on device:connected.
+            this.emit({
+                type: 'device:connected',
+                device: 'mock',
+                id: 'mock-0',
+                config: msg.config,
+            });
+        }
+    }
+    answer(id, name) {
+        const reply = (ok, body) => this.emit({ type: 'response', id, ok, ...body });
+        switch (name) {
+            case 'device.list':
+                reply(true, { result: { devices: [{ id: 'mock-0', plugin: 'mock', status: 'running' }] } });
+                break;
+            case 'runtime.status':
+                reply(true, { result: { version: '0.0.0-mock', uptimeMs: this.frame * 33, clients: 1 } });
+                break;
+            case 'camera.config':
+                reply(true, { result: { width: 1280, height: 720, fps: 30 } });
+                break;
+            case 'camera.start':
+            case 'camera.stop':
+                reply(true, { result: { ok: true } });
+                break;
+            case 'camera.snapshot':
+                reply(true, { result: { mime: 'image/png', data: TINY_PNG_BASE64 } });
+                break;
+            default:
+                // Mirrors the real runtime: nothing claimed the name.
+                reply(false, { error: { code: 'UNSUPPORTED', message: `mock does not implement ${name}` } });
+                break;
+        }
+    }
+    /**
+     * Public so tests and demos can inject an exact frame. Real sessions never
+     * call it — the mock drives itself from tick().
+     */
+    emit(msg) {
+        for (const fn of this.messageHandlers)
+            fn(msg);
+    }
+    onMessage(fn) {
+        this.messageHandlers.add(fn);
+        return () => this.messageHandlers.delete(fn);
+    }
+    onBinary(fn) {
+        this.binaryHandlers.add(fn);
+        return () => this.binaryHandlers.delete(fn);
+    }
+    onStateChange(fn) {
+        this.stateHandlers.add(fn);
+        return () => this.stateHandlers.delete(fn);
+    }
+    close() {
+        if (this.timerHandle !== null) {
+            this.opts.clearTimer(this.timerHandle);
+            this.timerHandle = null;
+        }
+        this.setState('closed');
+    }
+}
+function jointFor(name, t, sway) {
+    const wave = Math.sin(t * 1.6);
+    const table = {
+        head: [0.5, 0.14],
+        neck: [0.5, 0.22],
+        leftShoulder: [0.42, 0.26],
+        rightShoulder: [0.58, 0.26],
+        leftElbow: [0.37, 0.38],
+        rightElbow: [0.63, 0.38],
+        leftHand: [0.33 - wave * 0.12, 0.5 - wave * 0.22],
+        rightHand: [0.67 + wave * 0.12, 0.5 + wave * 0.18],
+        leftHip: [0.45, 0.56],
+        rightHip: [0.55, 0.56],
+        leftKnee: [0.45, 0.74],
+        rightKnee: [0.55, 0.74],
+        leftFoot: [0.45, 0.92],
+        rightFoot: [0.55, 0.92],
+    };
+    const [x, y] = table[name] ?? [0.5, 0.5];
+    return {
+        x: clamp01(x + sway),
+        y: clamp01(y),
+        z: 2.0,
+        c: 0.9,
+        valid: true, // derived from confidence in the real path, never hardcoded there
+    };
+}
+function clamp01(v) {
+    return v < 0 ? 0 : v > 1 ? 1 : v;
+}
+function bytesToBase64(bytes) {
+    const g = globalThis;
+    if (g.Buffer)
+        return g.Buffer.from(bytes).toString('base64');
+    let bin = '';
+    for (let i = 0; i < bytes.length; i++)
+        bin += String.fromCharCode(bytes[i]);
+    if (typeof g.btoa === 'function')
+        return g.btoa(bin);
+    throw new Error('no base64 encoder available');
+}
+/** 1x1 transparent PNG. Enough for snapshot plumbing to be exercised. */
+const TINY_PNG_BASE64 = 'iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==';

package/dist/runtime/protocol.d.ts

@@ -0,0 +1,231 @@
+/**
+ * QikSense Runtime protocol types.
+ *
+ * @generated from protocol/*.schema.json — DO NOT EDIT BY HAND.
+ * schema-hash: 608c0091
+ *
+ * Regenerate with:  node protocol/generate.mjs
+ *
+ * When copying this file into qik-sense-shared-sdk, keep schema-hash intact:
+ * a test there asserts it matches, which is the only automatic signal that the
+ * copy has fallen behind the schemas.
+ */
+/** Hash of the schema inputs this file was generated from. */
+export declare const SCHEMA_HASH = "608c0091";
+/** Default local endpoint. https pages must use wss to avoid mixed-content blocking. */
+export declare const RUNTIME_URL = "ws://127.0.0.1:17872";
+/** Silhouette grid geometry. Must match qs_silhouette_v1 in qs_data_abi.h. */
+export declare const GRID_W = 64;
+export declare const GRID_H = 48;
+/**
+ * Closed set of built-in commands (design/02 §6.2). Closed rather than free-form so the SDK can expose one semantic method per command; a client cannot invent a name the runtime has no handler for.
+ */
+export type RequestName = "device.list" | "runtime.status" | "camera.config" | "camera.start" | "camera.stop" | "camera.snapshot" | "camera.offer" | "camera.ice";
+/**
+ * Why a command failed. UNSUPPORTED means no handler claimed the name — the runtime tried its built-ins and every loaded plugin.
+ */
+export interface RequestError {
+    code: "UNSUPPORTED" | "NO_DEVICE" | "TIMEOUT" | "BAD_ARGS" | "INTERNAL";
+    message?: string;
+}
+/**
+ * Web → Runtime. `id` is client-generated and echoed back verbatim; the runtime never interprets it.
+ */
+export interface RequestMessage {
+    type: "request";
+    id: string;
+    name: RequestName;
+    args?: Record<string, unknown>;
+}
+/**
+ * Runtime → Web, paired by `id`. Same shape as ready: one message type, `ok` carries the verdict, so clients never branch on which message arrived.
+ */
+export interface ResponseMessage {
+    type: "response";
+    id: string;
+    ok: boolean;
+    /** When true a WS binary frame follows immediately, carrying the 16-byte QSBN header (design/02 §9). Whether a command sets this is fixed per name — never per call — so the client can decide how to read before it asks. */
+    binary?: boolean;
+    result?: Record<string, unknown>;
+    error?: RequestError;
+}
+/**
+ * Live retuning. Fields that do not affect stream parameters (calibration, thresholds, filtering) must take effect without interrupting the stream — that is the precondition for keeping Pointer in the runtime.
+ */
+export interface ReconfigureMessage {
+    type: "reconfigure";
+    config: RuntimeConfig;
+}
+/**
+ * Two namespaces with different owners (design/04 §2.2). `runtime` is consumed by the native runtime; `web` is for the browser side and the runtime does not read it.
+ */
+export interface RuntimeConfig {
+    runtime?: RuntimeNamespace;
+    /** Opaque to the runtime. Present so one config object can travel intact through the runtime to the client. */
+    web?: Record<string, unknown>;
+}
+/**
+ * Consumed by the native runtime only.
+ */
+export interface RuntimeNamespace {
+    preset?: "close" | "standard" | "far";
+    minDistanceM?: number;
+    maxDistanceM?: number;
+    calibBox?: CalibBox;
+    gain?: number;
+    smoothing?: "none" | "ema" | "oneEuro";
+    lockPolicy?: "nearest" | "largest" | "first";
+}
+/**
+ * Physical region mapped onto the 0..1 game plane. Owned by the runtime namespace because the runtime is what computes Pointer.
+ */
+export interface CalibBox {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/**
+ * Left/right are labelled from the subject's point of view; the runtime never mirrors. Screen mirroring belongs to the web layer, and doing it on both sides flips twice.
+ */
+export interface Joint {
+    /** normalized 0..1, unmirrored */
+    x: number;
+    /** normalized 0..1 */
+    y: number;
+    /** metres from camera */
+    z: number;
+    /** model confidence 0..1 */
+    c: number;
+    /** derived from confidence; never hardcoded true */
+    valid: boolean;
+}
+export interface BodyUpdate {
+    type: "body:update";
+    player: number;
+    center?: {
+        x?: number;
+        y?: number;
+    };
+    /** body centre distance, metres */
+    depth?: number;
+    ts: Timestamp;
+    skeleton: Record<string, Joint>;
+}
+export interface GestureUpdate {
+    type: "gesture:update";
+    player: number;
+    gesture: "raise_left" | "raise_right" | "jump" | "squat" | "wave" | "swipe" | "push";
+    ts: Timestamp;
+}
+/**
+ * x/y are already calibrated into 0..1 game space. `raw` is the uncalibrated position and exists only for the tuning HUD — reading it from gameplay bypasses calibration and is wrong at any non-default standing position.
+ */
+export interface PointerUpdate {
+    type: "pointer:update";
+    id: number;
+    x: number;
+    y: number;
+    down: boolean;
+    raw?: {
+        x?: number;
+        y?: number;
+    };
+    ts: Timestamp;
+}
+/**
+ * Occupancy grid, independent of any body tracker — it comes straight off the depth frame, which makes it the safest path for first light on new hardware.
+ */
+export interface DepthSilhouette {
+    type: "depth:silhouette";
+    w: number;
+    h: number;
+    /** base64 of w*h/8 bytes, row-major, MSB is the leftmost pixel. This layout is what the browser hit test decodes; changing it requires changing both sides. */
+    mask: string;
+    /** fraction of set cells; 0 = nobody in frame */
+    coverage?: number;
+    nearest?: number;
+    farthest?: number;
+    ts: Timestamp;
+}
+export interface DeviceConnected {
+    type: "device:connected";
+    device: string;
+    id?: string;
+    /** The values actually in effect after presets are expanded, so thresholds can be checked in devtools without a rebuild. */
+    config?: Record<string, unknown>;
+}
+export interface DeviceError {
+    type: "device:error";
+    device?: string;
+    /** NO_TRACKER must be reported explicitly: silently producing no skeleton is indistinguishable from nobody standing in front of the camera. */
+    code: "NO_DEVICE" | "NO_TRACKER" | "START_FAILED" | "CAPABILITY_CONFLICT";
+    message?: string;
+}
+/**
+ * Client-initiated only. The runtime answers pong and never sends ping; a client waiting for a server ping would decide the link is dead.
+ */
+export interface Ping {
+    type: "ping";
+    ts?: number;
+}
+export interface Pong {
+    type: "pong";
+    ts?: number;
+}
+/**
+ * Monotonic milliseconds, same clock and unit from plugin to browser. Not Unix epoch — it is only ever used for intervals, and wall clock gets stepped by NTP.
+ */
+export type Timestamp = number;
+/**
+ * A named capability with a version and capability-specific params. Params matter: an experience needing leftHand cannot tell from the name alone whether a body-tracking plugin supplies it.
+ */
+export interface Capability {
+    name: "body-tracking" | "hand-tracking" | "face-tracking" | "pointer" | "gesture" | "imu" | "depth" | "depth-silhouette" | "camera-stream";
+    version?: number;
+    params?: Record<string, unknown>;
+    /** When absent this capability does not block startup; it is reported in ready.unsatisfied instead. */
+    optional?: boolean;
+}
+/**
+ * Why a requested capability could not be provided. Six distinct reasons because they need six different responses in the field; a single 'device not connected' cannot be acted on.
+ */
+export interface CapabilityMiss {
+    name: string;
+    reason: "NO_PLUGIN" | "NO_DEVICE" | "PARAMS" | "VERSION" | "CAPABILITY_CONFLICT" | "START_FAILED";
+    detail?: Record<string, unknown>;
+}
+export interface HelloMessage {
+    type: "hello";
+    client: string;
+    sessionId?: string;
+    protocolVersion?: number;
+    /** Clients declare capabilities, never plugin names — that is what keeps Builder and Runner independent of any vendor. */
+    require?: {
+        capabilities?: Capability[];
+        config?: Record<string, unknown>;
+    };
+}
+export interface ReadyMessage {
+    type: "ready";
+    /** True when `missing` is empty. Unsatisfied optional capabilities do not affect it. */
+    ok: boolean;
+    runtimeVersion: string;
+    protocolVersion?: number;
+    clientId: string;
+    capabilities?: Capability[];
+    missing?: CapabilityMiss[];
+    unsatisfied?: CapabilityMiss[];
+    plugins?: string[];
+    /** Verbatim echo of hello.require. Answers the most common field question — 'my device config had no effect' — by showing whether it arrived at all. */
+    requested?: Record<string, unknown>;
+}
+/** Anything the runtime sends. The trailing member keeps forward-compatibility:
+ *  an older client must ignore unknown types rather than fail. */
+export type ServerMessage = ReadyMessage | BodyUpdate | GestureUpdate | PointerUpdate | DepthSilhouette | DeviceConnected | DeviceError | Pong | ResponseMessage | {
+    type: string;
+    [k: string]: unknown;
+};
+/** Anything a client sends. */
+export type ClientMessage = HelloMessage | Ping | RequestMessage | ReconfigureMessage;
+//# sourceMappingURL=protocol.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../src/runtime/protocol.ts"],"names":[],"mappings":"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"}

package/dist/runtime/protocol.js

@@ -0,0 +1,19 @@
+/**
+ * QikSense Runtime protocol types.
+ *
+ * @generated from protocol/*.schema.json — DO NOT EDIT BY HAND.
+ * schema-hash: 608c0091
+ *
+ * Regenerate with:  node protocol/generate.mjs
+ *
+ * When copying this file into qik-sense-shared-sdk, keep schema-hash intact:
+ * a test there asserts it matches, which is the only automatic signal that the
+ * copy has fallen behind the schemas.
+ */
+/** Hash of the schema inputs this file was generated from. */
+export const SCHEMA_HASH = '608c0091';
+/** Default local endpoint. https pages must use wss to avoid mixed-content blocking. */
+export const RUNTIME_URL = 'ws://127.0.0.1:17872';
+/** Silhouette grid geometry. Must match qs_silhouette_v1 in qs_data_abi.h. */
+export const GRID_W = 64;
+export const GRID_H = 48;