@realnation/builder-shared-sdk 1.0.5 → 1.1.0

package/README.md

@@ -242,6 +242,12 @@ const result = await uploadOssFile({
 console.log(result.url);
 ```
 
+
+## 测试
+```bash
+npm run test
+```
+
 ## 🔧 构建
 
 ```bash

package/dist/events.d.ts

@@ -1,4 +1,4 @@
-import type { SdkEventName, EventPayload } from './types';
+import type { SdkEventName, EventPayload } from './types.js';
 type Listener<TPayload extends EventPayload> = (payload: TPayload) => void;
 export declare class SdkEventBus {
     private listeners;

package/dist/events.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE1D,KAAK,QAAQ,CAAC,QAAQ,SAAS,YAAY,IAAI,CAAC,OAAO,EAAE,QAAQ,KAAK,IAAI,CAAC;AAI3E,qBAAa,WAAW;IACtB,OAAO,CAAC,SAAS,CAAwD;IAEzE,IAAI,CAAC,QAAQ,SAAS,YAAY,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ,GAAG,IAAI;IAMhF,EAAE,CAAC,QAAQ,SAAS,YAAY,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ,CAAC,QAAQ,CAAC,GAAG,MAAM,IAAI;IAO9F,GAAG,CAAC,QAAQ,SAAS,YAAY,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ,CAAC,QAAQ,CAAC,GAAG,IAAI;IASzF,KAAK,IAAI,IAAI;CAGd;AAED,wBAAgB,iBAAiB,IAAI,WAAW,CAE/C;AAED,wBAAgB,iBAAiB,IAAI,WAAW,CAU/C"}
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../src/events.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE7D,KAAK,QAAQ,CAAC,QAAQ,SAAS,YAAY,IAAI,CAAC,OAAO,EAAE,QAAQ,KAAK,IAAI,CAAC;AAI3E,qBAAa,WAAW;IACtB,OAAO,CAAC,SAAS,CAAwD;IAEzE,IAAI,CAAC,QAAQ,SAAS,YAAY,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ,GAAG,IAAI;IAMhF,EAAE,CAAC,QAAQ,SAAS,YAAY,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ,CAAC,QAAQ,CAAC,GAAG,MAAM,IAAI;IAO9F,GAAG,CAAC,QAAQ,SAAS,YAAY,EAAE,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,QAAQ,CAAC,QAAQ,CAAC,GAAG,IAAI;IASzF,KAAK,IAAI,IAAI;CAGd;AAED,wBAAgB,iBAAiB,IAAI,WAAW,CAE/C;AAED,wBAAgB,iBAAiB,IAAI,WAAW,CAU/C"}

package/dist/events.js

@@ -1,8 +1,6 @@
 const GLOBAL_KEY = '__BUILDER_SDK_EVENT_BUS__';
 export class SdkEventBus {
-    constructor() {
-        this.listeners = new Map();
-    }
+    listeners = new Map();
     emit(name, payload) {
         const handlers = this.listeners.get(name);
         if (!handlers)

package/dist/http.d.ts

@@ -1,5 +1,5 @@
 import { type AxiosInstance } from 'axios';
-import type { RequestContext } from './types';
+import type { RequestContext } from './types.js';
 export interface HttpClientOptions extends RequestContext {
 }
 type TokenResolver = () => string | null;

package/dist/http.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAAA,OAAc,EAAE,KAAK,aAAa,EAA6D,MAAM,OAAO,CAAC;AAC7G,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C,MAAM,WAAW,iBAAkB,SAAQ,cAAc;CAAG;AAE5D,KAAK,aAAa,GAAG,MAAM,MAAM,GAAG,IAAI,CAAC;AAazC,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAEvD;AAED,wBAAgB,YAAY,IAAI,MAAM,GAAG,IAAI,CAE5C;AAED,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI,GAAG,IAAI,CAErE;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,aAAa,CAS1E;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,iBAAiB,GAAG,aAAa,CAG7E;AAED,wBAAgB,aAAa,IAAI,aAAa,CAK7C;AAED,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,aAAa,EAAE,aAAa,CAAC,EAAE,aAAa,GAAG,IAAI,CAS7F"}
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAAA,OAAc,EAAE,KAAK,aAAa,EAA6D,MAAM,OAAO,CAAC;AAC7G,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,MAAM,WAAW,iBAAkB,SAAQ,cAAc;CAAG;AAE5D,KAAK,aAAa,GAAG,MAAM,MAAM,GAAG,IAAI,CAAC;AAazC,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAEvD;AAED,wBAAgB,YAAY,IAAI,MAAM,GAAG,IAAI,CAE5C;AAED,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI,GAAG,IAAI,CAErE;AAED,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,aAAa,CAS1E;AAED,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,iBAAiB,GAAG,aAAa,CAG7E;AAED,wBAAgB,aAAa,IAAI,aAAa,CAK7C;AAED,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,aAAa,EAAE,aAAa,CAAC,EAAE,aAAa,GAAG,IAAI,CAS7F"}

package/dist/index.d.ts

@@ -1,6 +1,6 @@
-export * from './types';
-export * from './http';
-export * from './events';
-export * from './flow';
-export * from './oss';
+export * from './types.js';
+export * from './http.js';
+export * from './events.js';
+export * from './flow.js';
+export * from './oss.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,QAAQ,CAAC;AACvB,cAAc,UAAU,CAAC;AACzB,cAAc,QAAQ,CAAC;AACvB,cAAc,OAAO,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,WAAW,CAAC;AAC1B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,UAAU,CAAC"}

package/dist/index.js

@@ -1,5 +1,5 @@
-export * from './types';
-export * from './http';
-export * from './events';
-export * from './flow';
-export * from './oss';
+export * from './types.js';
+export * from './http.js';
+export * from './events.js';
+export * from './flow.js';
+export * from './oss.js';

package/dist/oss.js

@@ -1,5 +1,5 @@
 import OSS from 'ali-oss';
-import { getHttpClient } from './http';
+import { getHttpClient } from './http.js';
 const DEFAULT_PART_SIZE = 1024 * 1024;
 const DEFAULT_CACHE_SKEW_MS = 60 * 1000;
 const credentialCache = new Map();

package/dist/runtime/capability.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Capability gating.
+ *
+ * The SDK deliberately does no matching of its own. The verdict is computed by
+ * the runtime, which is the only side that can see whether a device is actually
+ * plugged in; a second implementation here would drift from it and could never
+ * produce a reason like NO_DEVICE anyway. This file only reshapes `ready` into
+ * something a gate screen can render.
+ */
+import type { Capability, CapabilityMiss, ReadyMessage } from './protocol.js';
+export interface ConnectStatus {
+    /** Taken straight from ready.ok — not recomputed. */
+    ok: boolean;
+    capabilities: Capability[];
+    /** Non-empty means ok === false. */
+    missing: CapabilityMiss[];
+    /** Optional capabilities that were not provided. Does not affect ok. */
+    unsatisfied: CapabilityMiss[];
+    /** Verbatim echo of what we asked for. For troubleshooting. */
+    requested: unknown;
+    runtimeVersion: string;
+    clientId: string;
+    plugins: string[];
+}
+export declare function toConnectStatus(ready: ReadyMessage): ConnectStatus;
+/**
+ * Operator-facing text for a miss.
+ *
+ * Centralised here so every experience shows the same wording. The six reasons
+ * exist because each needs a different action on site — collapsing them into
+ * "device unavailable" would leave an operator with nothing to do.
+ */
+export declare function explainMiss(miss: CapabilityMiss): string;
+/** A ready-to-render gate summary. */
+export declare function describeGate(status: ConnectStatus): {
+    ok: boolean;
+    title: string;
+    items: Array<{
+        name: string;
+        reason: string;
+        text: string;
+        blocking: boolean;
+    }>;
+};
+//# sourceMappingURL=capability.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../../src/runtime/capability.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAE9E,MAAM,WAAW,aAAa;IAC5B,qDAAqD;IACrD,EAAE,EAAE,OAAO,CAAC;IACZ,YAAY,EAAE,UAAU,EAAE,CAAC;IAC3B,oCAAoC;IACpC,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,wEAAwE;IACxE,WAAW,EAAE,cAAc,EAAE,CAAC;IAC9B,+DAA+D;IAC/D,SAAS,EAAE,OAAO,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,YAAY,GAAG,aAAa,CAWlE;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,CAiBxD;AAED,sCAAsC;AACtC,wBAAgB,YAAY,CAAC,MAAM,EAAE,aAAa,GAAG;IACnD,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CACjF,CAoBA"}

package/dist/runtime/capability.js

@@ -0,0 +1,59 @@
+export function toConnectStatus(ready) {
+    return {
+        ok: ready.ok,
+        capabilities: ready.capabilities ?? [],
+        missing: ready.missing ?? [],
+        unsatisfied: ready.unsatisfied ?? [],
+        requested: ready.requested,
+        runtimeVersion: ready.runtimeVersion,
+        clientId: ready.clientId,
+        plugins: ready.plugins ?? [],
+    };
+}
+/**
+ * Operator-facing text for a miss.
+ *
+ * Centralised here so every experience shows the same wording. The six reasons
+ * exist because each needs a different action on site — collapsing them into
+ * "device unavailable" would leave an operator with nothing to do.
+ */
+export function explainMiss(miss) {
+    switch (miss.reason) {
+        case 'NO_PLUGIN':
+            return `没有插件提供「${miss.name}」能力，请检查 Runtime 的插件目录`;
+        case 'NO_DEVICE':
+            return `「${miss.name}」所需的设备未连接，请检查 USB 连接与供电`;
+        case 'PARAMS':
+            return `设备支持「${miss.name}」，但不满足玩法要求的参数`;
+        case 'VERSION':
+            return `「${miss.name}」的版本与玩法要求不匹配，请升级 Runtime 或插件`;
+        case 'CAPABILITY_CONFLICT':
+            return `「${miss.name}」与已启用的其它能力冲突，无法同时使用`;
+        case 'START_FAILED':
+            return `「${miss.name}」的设备启动失败，可能被其它程序占用`;
+        default:
+            return `「${miss.name}」不可用`;
+    }
+}
+/** A ready-to-render gate summary. */
+export function describeGate(status) {
+    const items = [
+        ...status.missing.map((m) => ({
+            name: m.name,
+            reason: m.reason,
+            text: explainMiss(m),
+            blocking: true,
+        })),
+        ...status.unsatisfied.map((m) => ({
+            name: m.name,
+            reason: m.reason,
+            text: explainMiss(m),
+            blocking: false,
+        })),
+    ];
+    return {
+        ok: status.ok,
+        title: status.ok ? '设备就绪' : '设备未就绪，无法开始',
+        items,
+    };
+}

package/dist/runtime/connection.d.ts

@@ -0,0 +1,92 @@
+/**
+ * WebSocket transport: handshake, heartbeat, reconnect.
+ *
+ * Everything above this file deals in decoded messages and never sees a socket.
+ * That boundary is what makes `source: 'mock'` a drop-in replacement — the mock
+ * implements this same interface, so nothing downstream can tell the difference.
+ */
+import type { ClientMessage, HelloMessage, ReadyMessage, ServerMessage } from './protocol.js';
+/** Anything that can carry protocol messages: a real socket, or the mock. */
+export interface Transport {
+    connect(): Promise<ReadyMessage>;
+    send(msg: ClientMessage): void;
+    /** Registers the sink for every server message. Returns an unsubscribe fn. */
+    onMessage(fn: (msg: ServerMessage) => void): () => void;
+    /** Binary frames (QSBN). Separate from onMessage because they are not JSON. */
+    onBinary(fn: (data: ArrayBuffer) => void): () => void;
+    onStateChange(fn: (state: ConnectionState) => void): () => void;
+    close(): void;
+    readonly state: ConnectionState;
+}
+export type ConnectionState = 'idle' | 'connecting' | 'ready' | 'reconnecting' | 'closed';
+export interface ConnectionOptions {
+    url?: string;
+    client?: string;
+    sessionId?: string;
+    require?: HelloMessage['require'];
+    /** Heartbeat period. The client pings; the runtime only ever answers. */
+    heartbeatMs?: number;
+    /** Reconnect backoff. Capped so a long outage still retries about twice a minute. */
+    backoffStartMs?: number;
+    backoffMaxMs?: number;
+    /** How long to wait for `ready` before treating the attempt as failed. */
+    handshakeTimeoutMs?: number;
+    /** Injection seam for tests; defaults to globalThis.WebSocket. */
+    socketFactory?: (url: string) => WebSocketLike;
+    now?: () => number;
+    setTimer?: (fn: () => void, ms: number) => unknown;
+    clearTimer?: (handle: unknown) => void;
+}
+/** The subset of WebSocket this file uses. Keeps tests free of a DOM shim. */
+export interface WebSocketLike {
+    send(data: string): void;
+    close(): void;
+    binaryType?: string;
+    onopen: ((ev?: unknown) => void) | null;
+    onclose: ((ev?: unknown) => void) | null;
+    onerror: ((ev?: unknown) => void) | null;
+    onmessage: ((ev: {
+        data: unknown;
+    }) => void) | null;
+}
+/**
+ * Resolves the endpoint. An https page cannot open a ws:// socket — the browser
+ * blocks it as mixed content — so the scheme follows the page rather than being
+ * hardcoded, and the failure never reaches a user as "connection refused".
+ */
+export declare function defaultUrl(): string;
+export declare class WsConnection implements Transport {
+    private readonly opts;
+    private socket;
+    private messageHandlers;
+    private binaryHandlers;
+    private stateHandlers;
+    private heartbeatHandle;
+    private reconnectHandle;
+    private handshakeHandle;
+    private backoffMs;
+    private closedByUser;
+    private _state;
+    /** Resolves the *first* connect() only. Reconnects are silent to the caller. */
+    private pendingHandshake;
+    constructor(options?: ConnectionOptions);
+    get state(): ConnectionState;
+    connect(): Promise<ReadyMessage>;
+    private setState;
+    private open;
+    private receive;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private clearHandshakeTimer;
+    private failHandshake;
+    private dropSocket;
+    private scheduleReconnect;
+    /** Current backoff delay, exposed for tests and debug HUDs. */
+    get nextBackoffMs(): number;
+    send(msg: ClientMessage): void;
+    onMessage(fn: (m: ServerMessage) => void): () => void;
+    onBinary(fn: (d: ArrayBuffer) => void): () => void;
+    onStateChange(fn: (s: ConnectionState) => void): () => void;
+    close(): void;
+}
+//# sourceMappingURL=connection.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../src/runtime/connection.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAG9F,6EAA6E;AAC7E,MAAM,WAAW,SAAS;IACxB,OAAO,IAAI,OAAO,CAAC,YAAY,CAAC,CAAC;IACjC,IAAI,CAAC,GAAG,EAAE,aAAa,GAAG,IAAI,CAAC;IAC/B,8EAA8E;IAC9E,SAAS,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,aAAa,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IACxD,+EAA+E;IAC/E,QAAQ,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IACtD,aAAa,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,eAAe,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IAChE,KAAK,IAAI,IAAI,CAAC;IACd,QAAQ,CAAC,KAAK,EAAE,eAAe,CAAC;CACjC;AAED,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,YAAY,GAAG,OAAO,GAAG,cAAc,GAAG,QAAQ,CAAC;AAE1F,MAAM,WAAW,iBAAiB;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,YAAY,CAAC,SAAS,CAAC,CAAC;IAClC,yEAAyE;IACzE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,qFAAqF;IACrF,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,0EAA0E;IAC1E,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,kEAAkE;IAClE,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,aAAa,CAAC;IAC/C,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,IAAI,EAAE,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC;IACnD,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;CACxC;AAED,8EAA8E;AAC9E,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,KAAK,IAAI,IAAI,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IACxC,OAAO,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IACzC,OAAO,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;IACzC,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC;CACrD;AASD;;;;GAIG;AACH,wBAAgB,UAAU,IAAI,MAAM,CAInC;AAED,qBAAa,YAAa,YAAW,SAAS;IAC5C,OAAO,CAAC,QAAQ,CAAC,IAAI,CACgD;IACrE,OAAO,CAAC,MAAM,CAA8B;IAC5C,OAAO,CAAC,eAAe,CAAyC;IAChE,OAAO,CAAC,cAAc,CAAuC;IAC7D,OAAO,CAAC,aAAa,CAA2C;IAChE,OAAO,CAAC,eAAe,CAAiB;IACxC,OAAO,CAAC,eAAe,CAAiB;IACxC,OAAO,CAAC,eAAe,CAAiB;IACxC,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,MAAM,CAA2B;IACzC,gFAAgF;IAChF,OAAO,CAAC,gBAAgB,CAGR;gBAEJ,OAAO,GAAE,iBAAsB;IAkB3C,IAAI,KAAK,IAAI,eAAe,CAE3B;IAED,OAAO,IAAI,OAAO,CAAC,YAAY,CAAC;IAQhC,OAAO,CAAC,QAAQ;IAMhB,OAAO,CAAC,IAAI;IAoDZ,OAAO,CAAC,OAAO;IA2Bf,OAAO,CAAC,cAAc;IAWtB,OAAO,CAAC,aAAa;IAOrB,OAAO,CAAC,mBAAmB;IAO3B,OAAO,CAAC,aAAa;IAMrB,OAAO,CAAC,UAAU;IAalB,OAAO,CAAC,iBAAiB;IAezB,+DAA+D;IAC/D,IAAI,aAAa,IAAI,MAAM,CAE1B;IAED,IAAI,CAAC,GAAG,EAAE,aAAa,GAAG,IAAI;IAS9B,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;CAYd"}

package/dist/runtime/connection.js

@@ -0,0 +1,247 @@
+import { RUNTIME_URL } from './protocol.js';
+const DEFAULTS = {
+    heartbeatMs: 5000,
+    backoffStartMs: 500,
+    backoffMaxMs: 30000,
+    handshakeTimeoutMs: 8000,
+};
+/**
+ * Resolves the endpoint. An https page cannot open a ws:// socket — the browser
+ * blocks it as mixed content — so the scheme follows the page rather than being
+ * hardcoded, and the failure never reaches a user as "connection refused".
+ */
+export function defaultUrl() {
+    const loc = globalThis.location;
+    if (loc?.protocol === 'https:')
+        return RUNTIME_URL.replace(/^ws:/, 'wss:');
+    return RUNTIME_URL;
+}
+export class WsConnection {
+    opts;
+    socket = null;
+    messageHandlers = new Set();
+    binaryHandlers = new Set();
+    stateHandlers = new Set();
+    heartbeatHandle = null;
+    reconnectHandle = null;
+    handshakeHandle = null;
+    backoffMs;
+    closedByUser = false;
+    _state = 'idle';
+    /** Resolves the *first* connect() only. Reconnects are silent to the caller. */
+    pendingHandshake = null;
+    constructor(options = {}) {
+        this.opts = {
+            url: options.url ?? defaultUrl(),
+            client: options.client ?? 'qiksense-web',
+            heartbeatMs: options.heartbeatMs ?? DEFAULTS.heartbeatMs,
+            backoffStartMs: options.backoffStartMs ?? DEFAULTS.backoffStartMs,
+            backoffMaxMs: options.backoffMaxMs ?? DEFAULTS.backoffMaxMs,
+            handshakeTimeoutMs: options.handshakeTimeoutMs ?? DEFAULTS.handshakeTimeoutMs,
+            now: options.now ?? (() => Date.now()),
+            setTimer: options.setTimer ?? ((fn, ms) => setTimeout(fn, ms)),
+            clearTimer: options.clearTimer ?? ((h) => clearTimeout(h)),
+            require: options.require,
+            sessionId: options.sessionId,
+            socketFactory: options.socketFactory,
+        };
+        this.backoffMs = this.opts.backoffStartMs;
+    }
+    get state() {
+        return this._state;
+    }
+    connect() {
+        this.closedByUser = false;
+        return new Promise((resolve, reject) => {
+            this.pendingHandshake = { resolve, reject };
+            this.open();
+        });
+    }
+    setState(next) {
+        if (this._state === next)
+            return;
+        this._state = next;
+        for (const fn of this.stateHandlers)
+            fn(next);
+    }
+    open() {
+        this.setState(this._state === 'idle' ? 'connecting' : this._state);
+        const make = this.opts.socketFactory ??
+            ((url) => new globalThis.WebSocket(url));
+        let sock;
+        try {
+            sock = make(this.opts.url);
+        }
+        catch (err) {
+            this.scheduleReconnect();
+            return;
+        }
+        this.socket = sock;
+        if ('binaryType' in sock)
+            sock.binaryType = 'arraybuffer';
+        sock.onopen = () => {
+            const hello = {
+                type: 'hello',
+                client: this.opts.client,
+                protocolVersion: 1,
+            };
+            if (this.opts.sessionId)
+                hello.sessionId = this.opts.sessionId;
+            if (this.opts.require)
+                hello.require = this.opts.require;
+            sock.send(JSON.stringify(hello));
+            // A socket that opens but never answers `ready` is the nastiest case: it
+            // looks alive, so without this the caller waits forever on connect().
+            this.handshakeHandle = this.opts.setTimer(() => {
+                this.failHandshake(new Error('runtime did not answer hello within timeout'));
+                this.dropSocket();
+                this.scheduleReconnect();
+            }, this.opts.handshakeTimeoutMs);
+        };
+        sock.onmessage = (ev) => this.receive(ev.data);
+        sock.onerror = () => {
+            /* onclose always follows; reconnect is handled there so it runs once. */
+        };
+        sock.onclose = () => {
+            this.stopHeartbeat();
+            this.clearHandshakeTimer();
+            if (this.closedByUser) {
+                this.setState('closed');
+                return;
+            }
+            this.scheduleReconnect();
+        };
+    }
+    receive(data) {
+        if (typeof data !== 'string') {
+            const buf = toArrayBuffer(data);
+            if (buf)
+                for (const fn of this.binaryHandlers)
+                    fn(buf);
+            return;
+        }
+        let msg;
+        try {
+            msg = JSON.parse(data);
+        }
+        catch {
+            return; // A malformed frame must not kill the connection.
+        }
+        if (msg.type === 'ready') {
+            this.clearHandshakeTimer();
+            this.backoffMs = this.opts.backoffStartMs; // a real handshake resets backoff
+            this.setState('ready');
+            this.startHeartbeat();
+            const pending = this.pendingHandshake;
+            this.pendingHandshake = null;
+            pending?.resolve(msg);
+        }
+        for (const fn of this.messageHandlers)
+            fn(msg);
+    }
+    startHeartbeat() {
+        this.stopHeartbeat();
+        const tick = () => {
+            // Client-initiated only. The runtime never sends ping; a client waiting
+            // for one would eventually decide a healthy link was dead.
+            this.send({ type: 'ping', ts: this.opts.now() });
+            this.heartbeatHandle = this.opts.setTimer(tick, this.opts.heartbeatMs);
+        };
+        this.heartbeatHandle = this.opts.setTimer(tick, this.opts.heartbeatMs);
+    }
+    stopHeartbeat() {
+        if (this.heartbeatHandle !== null) {
+            this.opts.clearTimer(this.heartbeatHandle);
+            this.heartbeatHandle = null;
+        }
+    }
+    clearHandshakeTimer() {
+        if (this.handshakeHandle !== null) {
+            this.opts.clearTimer(this.handshakeHandle);
+            this.handshakeHandle = null;
+        }
+    }
+    failHandshake(err) {
+        const pending = this.pendingHandshake;
+        this.pendingHandshake = null;
+        pending?.reject(err);
+    }
+    dropSocket() {
+        const sock = this.socket;
+        this.socket = null;
+        if (!sock)
+            return;
+        sock.onopen = sock.onclose = sock.onerror = null;
+        sock.onmessage = null;
+        try {
+            sock.close();
+        }
+        catch {
+            /* already gone */
+        }
+    }
+    scheduleReconnect() {
+        if (this.closedByUser)
+            return;
+        if (this.reconnectHandle !== null)
+            return; // one timer at a time
+        this.setState('reconnecting');
+        const delay = this.backoffMs;
+        // Grow before the attempt so the *next* failure waits longer even if this
+        // attempt dies before onclose fires.
+        this.backoffMs = Math.min(this.backoffMs * 2, this.opts.backoffMaxMs);
+        this.reconnectHandle = this.opts.setTimer(() => {
+            this.reconnectHandle = null;
+            if (this.closedByUser)
+                return;
+            this.open();
+        }, delay);
+    }
+    /** Current backoff delay, exposed for tests and debug HUDs. */
+    get nextBackoffMs() {
+        return this.backoffMs;
+    }
+    send(msg) {
+        if (!this.socket)
+            return; // dropped while offline; reconnect replays nothing
+        try {
+            this.socket.send(JSON.stringify(msg));
+        }
+        catch {
+            /* socket died mid-send; onclose drives the reconnect */
+        }
+    }
+    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() {
+        this.closedByUser = true;
+        this.stopHeartbeat();
+        this.clearHandshakeTimer();
+        if (this.reconnectHandle !== null) {
+            this.opts.clearTimer(this.reconnectHandle);
+            this.reconnectHandle = null;
+        }
+        this.failHandshake(new Error('connection closed before handshake completed'));
+        this.dropSocket();
+        this.setState('closed');
+    }
+}
+function toArrayBuffer(data) {
+    if (data instanceof ArrayBuffer)
+        return data;
+    if (ArrayBuffer.isView(data)) {
+        const view = data;
+        return view.buffer.slice(view.byteOffset, view.byteOffset + view.byteLength);
+    }
+    return null;
+}

package/dist/runtime/decode.d.ts

@@ -0,0 +1,40 @@
+import type { DepthSilhouette } from './protocol.js';
+/** Decoded occupancy grid: one byte per cell, 0 or 1, row-major. */
+export interface SilhouetteFrame {
+    w: number;
+    h: number;
+    cells: Uint8Array;
+    coverage: number;
+    nearest?: number;
+    farthest?: number;
+    ts: number;
+    /** Occupancy at a cell. Out-of-range reads as empty rather than throwing. */
+    at(cx: number, cy: number): boolean;
+    /** Hit test in normalised 0..1 game space. */
+    hit(x: number, y: number): boolean;
+}
+/**
+ * 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 declare function decodeSilhouette(msg: DepthSilhouette): SilhouetteFrame;
+export declare const QSBN_HEADER_BYTES = 16;
+export interface BinaryFrame {
+    version: number;
+    /** Correlation id: the request id, or its FNV-1a hash when over 8 bytes. */
+    id: bigint;
+    payload: ArrayBuffer;
+}
+/**
+ * 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 declare function fnv1a64(s: string): bigint;
+/** The id as it appears in a QSBN header: raw big-endian bytes, or the hash. */
+export declare function binaryCorrelationId(id: string): bigint;
+export declare function parseBinaryFrame(buf: ArrayBuffer): BinaryFrame;
+//# sourceMappingURL=decode.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"decode.d.ts","sourceRoot":"","sources":["../../src/runtime/decode.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD,oEAAoE;AACpE,MAAM,WAAW,eAAe;IAC9B,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,UAAU,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,EAAE,EAAE,MAAM,CAAC;IACX,6EAA6E;IAC7E,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IACpC,8CAA8C;IAC9C,GAAG,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACpC;AAeD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,eAAe,GAAG,eAAe,CAkCtE;AAUD,eAAO,MAAM,iBAAiB,KAAK,CAAC;AAGpC,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,WAAW,CAAC;CACtB;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CASzC;AAED,gFAAgF;AAChF,wBAAgB,mBAAmB,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAKtD;AAED,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,WAAW,GAAG,WAAW,CAc9D"}