@uptimizr/sdk-core 0.1.0

package/dist/offloadProtocol.d.ts

@@ -0,0 +1,40 @@
+import type { CollectRequest } from "@uptimizr/schema";
+/**
+ * Wire protocol for the opt-in offload worker (ADR 0031).
+ *
+ * These are **type-only** definitions shared by the main-thread processor
+ * ([`processor.ts`](./processor.ts)) and the worker entry
+ * ([`offloadWorker.ts`](./offloadWorker.ts)). Keeping the protocol in its own
+ * module (with no runtime exports) means the worker bundle pulls in none of the
+ * processor's runtime code — it stays tiny.
+ *
+ * The only thing that crosses the boundary is the plain-data `CollectRequest`
+ * DTO: by the time a batch reaches the worker it is an array of Zod-shaped plain
+ * objects with no engine/DOM handles, so it travels by structured clone (or, for
+ * buffer-backed fields, by transfer).
+ */
+/** Sets the collector URL the worker dispatches to. Sent once at construction. */
+export interface WorkerInitMessage {
+    type: "init";
+    /** Fully-resolved collect endpoint (e.g. `https://host/api/v1/collect`). */
+    url: string;
+}
+/** A batch to serialize and dispatch off the main thread. */
+export interface WorkerBatchMessage {
+    type: "batch";
+    /** Correlates the result back to the awaiting `process()` call. */
+    id: number;
+    /** The plain-data batch to serialize and send. */
+    batch: CollectRequest;
+}
+/** Messages the main thread sends to the worker. */
+export type WorkerInbound = WorkerInitMessage | WorkerBatchMessage;
+/** The delivery result for one batch, reported back to the main thread. */
+export interface WorkerResultMessage {
+    type: "result";
+    id: number;
+    ok: boolean;
+}
+/** Messages the worker sends back to the main thread. */
+export type WorkerOutbound = WorkerResultMessage;
+//# sourceMappingURL=offloadProtocol.d.ts.map

package/dist/offloadProtocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"offloadProtocol.d.ts","sourceRoot":"","sources":["../src/offloadProtocol.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD;;;;;;;;;;;;;GAaG;AAEH,kFAAkF;AAClF,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,4EAA4E;IAC5E,GAAG,EAAE,MAAM,CAAC;CACb;AAED,6DAA6D;AAC7D,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,OAAO,CAAC;IACd,mEAAmE;IACnE,EAAE,EAAE,MAAM,CAAC;IACX,kDAAkD;IAClD,KAAK,EAAE,cAAc,CAAC;CACvB;AAED,oDAAoD;AACpD,MAAM,MAAM,aAAa,GAAG,iBAAiB,GAAG,kBAAkB,CAAC;AAEnE,2EAA2E;AAC3E,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,QAAQ,CAAC;IACf,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,OAAO,CAAC;CACb;AAED,yDAAyD;AACzD,MAAM,MAAM,cAAc,GAAG,mBAAmB,CAAC"}

package/dist/offloadProtocol.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=offloadProtocol.js.map

package/dist/offloadProtocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"offloadProtocol.js","sourceRoot":"","sources":["../src/offloadProtocol.ts"],"names":[],"mappings":""}

package/dist/offloadWorker.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=offloadWorker.d.ts.map

package/dist/offloadWorker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"offloadWorker.d.ts","sourceRoot":"","sources":["../src/offloadWorker.ts"],"names":[],"mappings":""}

package/dist/offloadWorker.js

@@ -0,0 +1,41 @@
+// The build uses the DOM lib (not WebWorker), so narrow `self` structurally.
+const scope = self;
+/** Resolved collector URL, set by the `init` message before any batch arrives. */
+let collectUrl = "";
+scope.addEventListener("message", (event) => {
+    const message = event.data;
+    if (!message) {
+        return;
+    }
+    if (message.type === "init") {
+        collectUrl = message.url;
+        return;
+    }
+    if (message.type === "batch") {
+        void dispatch(message.id, message.batch);
+    }
+});
+/** Serialize and POST one batch, then report the outcome back to the page. */
+async function dispatch(id, batch) {
+    let ok = false;
+    try {
+        if (collectUrl) {
+            const body = JSON.stringify(batch);
+            const res = await scope.fetch(collectUrl, {
+                method: "POST",
+                headers: { "content-type": "application/json" },
+                body,
+                // `keepalive` has a ~64 KB browser cap; only request it under the limit.
+                keepalive: body.length < 64_000,
+            });
+            ok = res.ok;
+        }
+    }
+    catch {
+        ok = false;
+    }
+    const result = { type: "result", id, ok };
+    scope.postMessage(result);
+}
+export {};
+//# sourceMappingURL=offloadWorker.js.map

package/dist/offloadWorker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"offloadWorker.js","sourceRoot":"","sources":["../src/offloadWorker.ts"],"names":[],"mappings":"AAuBA,6EAA6E;AAC7E,MAAM,KAAK,GAAG,IAA8B,CAAC;AAE7C,kFAAkF;AAClF,IAAI,UAAU,GAAG,EAAE,CAAC;AAEpB,KAAK,CAAC,gBAAgB,CAAC,SAAS,EAAE,CAAC,KAAK,EAAE,EAAE;IAC1C,MAAM,OAAO,GAAG,KAAK,CAAC,IAAiC,CAAC;IACxD,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO;IACT,CAAC;IACD,IAAI,OAAO,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;QAC5B,UAAU,GAAG,OAAO,CAAC,GAAG,CAAC;QACzB,OAAO;IACT,CAAC;IACD,IAAI,OAAO,CAAC,IAAI,KAAK,OAAO,EAAE,CAAC;QAC7B,KAAK,QAAQ,CAAC,OAAO,CAAC,EAAE,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IAC3C,CAAC;AACH,CAAC,CAAC,CAAC;AAEH,8EAA8E;AAC9E,KAAK,UAAU,QAAQ,CAAC,EAAU,EAAE,KAAc;IAChD,IAAI,EAAE,GAAG,KAAK,CAAC;IACf,IAAI,CAAC;QACH,IAAI,UAAU,EAAE,CAAC;YACf,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;YACnC,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,KAAK,CAAC,UAAU,EAAE;gBACxC,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE;gBAC/C,IAAI;gBACJ,yEAAyE;gBACzE,SAAS,EAAE,IAAI,CAAC,MAAM,GAAG,MAAM;aAChC,CAAC,CAAC;YACH,EAAE,GAAG,GAAG,CAAC,EAAE,CAAC;QACd,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,EAAE,GAAG,KAAK,CAAC;IACb,CAAC;IACD,MAAM,MAAM,GAAwB,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC;IAC/D,KAAK,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;AAC5B,CAAC"}

package/dist/processor.d.ts

@@ -0,0 +1,102 @@
+import type { CollectRequest } from "@uptimizr/schema";
+import type { Transport } from "./types.js";
+/**
+ * A **Processor** owns the offload-eligible *processing* phase of the SDK
+ * (ADR 0031): turning a drained batch into a delivered one — serialization plus
+ * network dispatch. It sits between the client's flush loop and the wire.
+ *
+ * The boundary that makes this work is the plain-data {@link CollectRequest}
+ * DTO. By the time a batch reaches a processor it is already an array of
+ * Zod-shaped plain objects with no engine or DOM handles, so it can either be
+ * serialized in place (main-thread processor) or shipped to a worker
+ * (worker processor) without touching the live 3D scene.
+ *
+ * Two implementations exist:
+ * - {@link createMainProcessor} — the default; runs everything on the main
+ *   thread via the configured {@link Transport}. Behaviour is unchanged from
+ *   before this seam existed, byte-for-byte.
+ * - {@link createWorkerProcessor} — opt-in; moves steady-state serialization +
+ *   dispatch to a Web Worker, keeping the terminal unload flush on the main
+ *   thread.
+ */
+export interface Processor {
+    /**
+     * Serialize and deliver a steady-state batch. Resolves `true` on success;
+     * `false` re-queues the batch for the next attempt.
+     */
+    process(batch: CollectRequest): Promise<boolean>;
+    /**
+     * Deliver the **final** batch on page unload. This MUST run on the main/page
+     * thread: `navigator.sendBeacon` is only reliable from the page context during
+     * `visibilitychange: hidden` / `pagehide` (ADR 0031 §5, ADR 0006), and a
+     * worker may be torn down with the page before an async post completes.
+     */
+    processUnload(batch: CollectRequest): Promise<boolean>;
+    /** Release resources (e.g. terminate the worker). Idempotent. */
+    dispose(): void;
+}
+/**
+ * The default processor: serialize + dispatch on the main thread via the given
+ * transport. This is the no-op-fallback baseline — identical to the behaviour
+ * before the seam was introduced. Both the steady-state and unload paths use the
+ * same transport (the beacon transport already prefers `sendBeacon`).
+ */
+export declare function createMainProcessor(transport: Transport): Processor;
+/**
+ * Minimal structural type for a dedicated worker — the subset of the DOM
+ * `Worker` interface the processor uses. A real `Worker` satisfies it; tests
+ * inject a lightweight stub so the protocol can be exercised without a runtime
+ * worker (jsdom/Node have no usable `Worker`).
+ */
+export interface WorkerLike {
+    postMessage(message: unknown, transfer?: Transferable[]): void;
+    addEventListener(type: "message", listener: (event: {
+        data: unknown;
+    }) => void): void;
+    addEventListener(type: "error", listener: (event: unknown) => void): void;
+    terminate?(): void;
+}
+/** Constructs the offload worker. Injectable so bundlers/tests can override it. */
+export type WorkerFactory = () => WorkerLike;
+export interface WorkerProcessorOptions {
+    /** Collector base URL (the same value as the client `endpoint`). */
+    endpoint: string;
+    /**
+     * Transport used for the **unload** flush, which stays on the main thread
+     * (ADR 0031 §5). Normally the client's default beacon transport.
+     */
+    unloadTransport: Transport;
+    /**
+     * How to construct the worker. Defaults to a module worker bundled with the
+     * SDK via the `new Worker(new URL("./offloadWorker.js", import.meta.url))`
+     * pattern recognized by Vite/webpack5/Rollup/esbuild.
+     */
+    workerFactory?: WorkerFactory;
+}
+/**
+ * Collect the transferable buffers carried by a batch so they move to the worker
+ * **zero-copy** instead of being structured-cloned (ADR 0031 §6, #98).
+ *
+ * Today's events are plain JSON objects, so this returns an empty list — the
+ * mechanism is in place for the buffer-backed continuous-channel DTOs that the
+ * connector-side offload follow-up will introduce. The scan is shallow (one pass
+ * over each event's own values) to keep the per-flush cost negligible, and it
+ * de-duplicates so a buffer shared across fields is only transferred once
+ * (a duplicate in the transfer list would throw).
+ *
+ * Caveat: transferring a buffer **neuters** it on the main thread. Continuous
+ * channels that opt in must own a fresh buffer per batch.
+ */
+export declare function collectTransferables(batch: CollectRequest): Transferable[];
+/**
+ * Create a worker-backed processor that runs steady-state serialization +
+ * dispatch off the main thread (ADR 0031). Returns `null` when a worker cannot
+ * be constructed (no `Worker` global, the bundler did not emit the asset, a
+ * restrictive CSP, SSR, or tests) so the caller can fall back to the
+ * main-thread processor — worker mode is never required for correctness.
+ *
+ * The unload flush deliberately does **not** use the worker; it goes through
+ * {@link WorkerProcessorOptions.unloadTransport} on the main thread.
+ */
+export declare function createWorkerProcessor(options: WorkerProcessorOptions): Processor | null;
+//# sourceMappingURL=processor.d.ts.map

package/dist/processor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"processor.d.ts","sourceRoot":"","sources":["../src/processor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAG5C;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,WAAW,SAAS;IACxB;;;OAGG;IACH,OAAO,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACjD;;;;;OAKG;IACH,aAAa,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACvD,iEAAiE;IACjE,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,SAAS,GAAG,SAAS,CAQnE;AAED;;;;;GAKG;AACH,MAAM,WAAW,UAAU;IACzB,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,QAAQ,CAAC,EAAE,YAAY,EAAE,GAAG,IAAI,CAAC;IAC/D,gBAAgB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,KAAK,IAAI,GAAG,IAAI,CAAC;IACtF,gBAAgB,CAAC,IAAI,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI,CAAC;IAC1E,SAAS,CAAC,IAAI,IAAI,CAAC;CACpB;AAED,mFAAmF;AACnF,MAAM,MAAM,aAAa,GAAG,MAAM,UAAU,CAAC;AAE7C,MAAM,WAAW,sBAAsB;IACrC,oEAAoE;IACpE,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,eAAe,EAAE,SAAS,CAAC;IAC3B;;;;OAIG;IACH,aAAa,CAAC,EAAE,aAAa,CAAC;CAC/B;AASD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,cAAc,GAAG,YAAY,EAAE,CAkB1E;AAWD;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,sBAAsB,GAAG,SAAS,GAAG,IAAI,CA8EvF"}

package/dist/processor.js

@@ -0,0 +1,145 @@
+/**
+ * The default processor: serialize + dispatch on the main thread via the given
+ * transport. This is the no-op-fallback baseline — identical to the behaviour
+ * before the seam was introduced. Both the steady-state and unload paths use the
+ * same transport (the beacon transport already prefers `sendBeacon`).
+ */
+export function createMainProcessor(transport) {
+    return {
+        process: (batch) => transport.send(batch),
+        processUnload: (batch) => transport.send(batch),
+        dispose: () => {
+            /* nothing to release */
+        },
+    };
+}
+const COLLECT_PATH = "/api/v1/collect";
+/** Build the collector POST URL the worker dispatches to. */
+function collectUrl(endpoint) {
+    return endpoint.replace(/\/$/, "") + COLLECT_PATH;
+}
+/**
+ * Collect the transferable buffers carried by a batch so they move to the worker
+ * **zero-copy** instead of being structured-cloned (ADR 0031 §6, #98).
+ *
+ * Today's events are plain JSON objects, so this returns an empty list — the
+ * mechanism is in place for the buffer-backed continuous-channel DTOs that the
+ * connector-side offload follow-up will introduce. The scan is shallow (one pass
+ * over each event's own values) to keep the per-flush cost negligible, and it
+ * de-duplicates so a buffer shared across fields is only transferred once
+ * (a duplicate in the transfer list would throw).
+ *
+ * Caveat: transferring a buffer **neuters** it on the main thread. Continuous
+ * channels that opt in must own a fresh buffer per batch.
+ */
+export function collectTransferables(batch) {
+    const seen = new Set();
+    const out = [];
+    for (const event of batch.events) {
+        for (const value of Object.values(event)) {
+            let buffer;
+            if (value instanceof ArrayBuffer) {
+                buffer = value;
+            }
+            else if (ArrayBuffer.isView(value)) {
+                buffer = value.buffer;
+            }
+            if (buffer && !seen.has(buffer)) {
+                seen.add(buffer);
+                out.push(buffer);
+            }
+        }
+    }
+    return out;
+}
+/** Default factory: a module worker shipped alongside the SDK in `dist/`. */
+function defaultWorkerFactory() {
+    // `new URL(..., import.meta.url)` + `new Worker` is the pattern bundlers
+    // recognize to emit and resolve a library-owned worker asset.
+    return new Worker(new URL("./offloadWorker.js", import.meta.url), {
+        type: "module",
+    });
+}
+/**
+ * Create a worker-backed processor that runs steady-state serialization +
+ * dispatch off the main thread (ADR 0031). Returns `null` when a worker cannot
+ * be constructed (no `Worker` global, the bundler did not emit the asset, a
+ * restrictive CSP, SSR, or tests) so the caller can fall back to the
+ * main-thread processor — worker mode is never required for correctness.
+ *
+ * The unload flush deliberately does **not** use the worker; it goes through
+ * {@link WorkerProcessorOptions.unloadTransport} on the main thread.
+ */
+export function createWorkerProcessor(options) {
+    const factory = options.workerFactory ?? defaultWorkerFactory;
+    let worker;
+    try {
+        worker = factory();
+    }
+    catch {
+        return null;
+    }
+    let nextId = 1;
+    let disposed = false;
+    const pending = new Map();
+    const settleAll = (ok) => {
+        for (const resolve of pending.values()) {
+            resolve(ok);
+        }
+        pending.clear();
+    };
+    worker.addEventListener("message", (event) => {
+        const data = event.data;
+        if (!data || data.type !== "result") {
+            return;
+        }
+        const resolve = pending.get(data.id);
+        if (resolve) {
+            pending.delete(data.id);
+            resolve(data.ok);
+        }
+    });
+    // If the worker errors, fail every in-flight send so the batches re-queue and
+    // are retried on the main thread — no events are lost.
+    worker.addEventListener("error", () => {
+        settleAll(false);
+    });
+    try {
+        worker.postMessage({
+            type: "init",
+            url: collectUrl(options.endpoint),
+        });
+    }
+    catch {
+        worker.terminate?.();
+        return null;
+    }
+    return {
+        process(batch) {
+            if (disposed) {
+                return Promise.resolve(false);
+            }
+            const id = nextId++;
+            return new Promise((resolve) => {
+                pending.set(id, resolve);
+                try {
+                    worker.postMessage({ type: "batch", id, batch }, collectTransferables(batch));
+                }
+                catch {
+                    pending.delete(id);
+                    resolve(false);
+                }
+            });
+        },
+        processUnload: (batch) => options.unloadTransport.send(batch),
+        dispose: () => {
+            if (disposed) {
+                return;
+            }
+            disposed = true;
+            settleAll(false);
+            worker.terminate?.();
+        },
+    };
+}
+//# sourceMappingURL=processor.js.map

package/dist/processor.js.map

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

package/dist/queue.d.ts

@@ -0,0 +1,22 @@
+import type { AnyEvent } from "@uptimizr/schema";
+/**
+ * A bounded in-memory FIFO queue for pending events.
+ *
+ * When the queue exceeds `maxSize` (e.g. the device is offline and flushes keep
+ * failing), the oldest events are dropped to cap memory use. This is a deliberate
+ * trade-off: recent events are more valuable than unbounded retention.
+ */
+export declare class EventQueue {
+    private readonly maxSize;
+    private items;
+    constructor(maxSize: number);
+    /** Number of queued events. */
+    get size(): number;
+    /** Append an event, dropping the oldest if the cap is exceeded. */
+    enqueue(event: AnyEvent): void;
+    /** Remove and return all queued events. */
+    drain(): AnyEvent[];
+    /** Put events back at the front (e.g. after a failed flush). */
+    prepend(events: AnyEvent[]): void;
+}
+//# sourceMappingURL=queue.d.ts.map

package/dist/queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.d.ts","sourceRoot":"","sources":["../src/queue.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAEjD;;;;;;GAMG;AACH,qBAAa,UAAU;IAGT,OAAO,CAAC,QAAQ,CAAC,OAAO;IAFpC,OAAO,CAAC,KAAK,CAAkB;gBAEF,OAAO,EAAE,MAAM;IAE5C,+BAA+B;IAC/B,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED,mEAAmE;IACnE,OAAO,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI;IAO9B,2CAA2C;IAC3C,KAAK,IAAI,QAAQ,EAAE;IAMnB,gEAAgE;IAChE,OAAO,CAAC,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI;CAMlC"}

package/dist/queue.js

@@ -0,0 +1,39 @@
+/**
+ * A bounded in-memory FIFO queue for pending events.
+ *
+ * When the queue exceeds `maxSize` (e.g. the device is offline and flushes keep
+ * failing), the oldest events are dropped to cap memory use. This is a deliberate
+ * trade-off: recent events are more valuable than unbounded retention.
+ */
+export class EventQueue {
+    maxSize;
+    items = [];
+    constructor(maxSize) {
+        this.maxSize = maxSize;
+    }
+    /** Number of queued events. */
+    get size() {
+        return this.items.length;
+    }
+    /** Append an event, dropping the oldest if the cap is exceeded. */
+    enqueue(event) {
+        this.items.push(event);
+        if (this.items.length > this.maxSize) {
+            this.items.splice(0, this.items.length - this.maxSize);
+        }
+    }
+    /** Remove and return all queued events. */
+    drain() {
+        const drained = this.items;
+        this.items = [];
+        return drained;
+    }
+    /** Put events back at the front (e.g. after a failed flush). */
+    prepend(events) {
+        this.items = [...events, ...this.items];
+        if (this.items.length > this.maxSize) {
+            this.items.splice(0, this.items.length - this.maxSize);
+        }
+    }
+}
+//# sourceMappingURL=queue.js.map

package/dist/queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"queue.js","sourceRoot":"","sources":["../src/queue.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,OAAO,UAAU;IAGQ;IAFrB,KAAK,GAAe,EAAE,CAAC;IAE/B,YAA6B,OAAe;QAAf,YAAO,GAAP,OAAO,CAAQ;IAAG,CAAC;IAEhD,+BAA+B;IAC/B,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC;IAC3B,CAAC;IAED,mEAAmE;IACnE,OAAO,CAAC,KAAe;QACrB,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACvB,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;YACrC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC;QACzD,CAAC;IACH,CAAC;IAED,2CAA2C;IAC3C,KAAK;QACH,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC;QAC3B,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;QAChB,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,gEAAgE;IAChE,OAAO,CAAC,MAAkB;QACxB,IAAI,CAAC,KAAK,GAAG,CAAC,GAAG,MAAM,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;QACxC,IAAI,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC;YACrC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,CAAC;QACzD,CAAC;IACH,CAAC;CACF"}

package/dist/sampling.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Capture-fidelity sampling profile (ADR 0012).
+ *
+ * Fidelity is an explicit, per-channel, developer-owned contract with
+ * conservative defaults and no hard cap. The dial governs **continuous** channels
+ * only — camera/head pose, pointer move, and (ADR 0011) controller/hand poses.
+ * **Discrete** semantic events (`pointer_click`, `pointer_down`/`pointer_up`,
+ * `mesh_interaction`, `scene_change`, `session_start`/`session_end`, `custom`)
+ * are always captured at 100% and MUST NOT be rate-limited.
+ *
+ * The profile is a static literal at init today; it is shaped so the same object
+ * can later be fetched from the collector per project (remote config) without a
+ * redesign.
+ */
+/**
+ * A per-channel sample rate:
+ * - a positive number — target rate in **Hz** (samples/second),
+ * - `0` — channel off (do not sample),
+ * - `"frame"` — emit every render tick (the 100% / per-frame case).
+ */
+export type SampleRate = number | "frame";
+/**
+ * Per-channel and per-source sampling rates. Omitted channels fall back to the
+ * connector's conservative defaults (≈1 Hz camera, ≈4 Hz pointer, ≈0.5 Hz perf).
+ */
+export interface SamplingProfile {
+    /** Camera/head pose channel. */
+    camera?: SampleRate;
+    /** Pointer-move channel. */
+    pointerMove?: SampleRate;
+    /** Performance (FPS) channel. */
+    perf?: SampleRate;
+    /**
+     * Per-source overrides keyed by input-source id (ADR 0011), e.g.
+     * `{ leftController: 30, rightHand: 30, gaze: 0 }`. Forward-looking: connectors
+     * apply these to the continuous pose stream of each source they capture.
+     */
+    perSource?: Record<string, SampleRate>;
+    /**
+     * Scene-actor (`node_transform`) capture rates, keyed by the developer-declared
+     * actor id (ADR 0027 Tier 1). **Default OFF** — only ids listed here are
+     * sampled, and each MUST also be declared in the connector's `actors` map; an
+     * unknown id is a no-op with a dev-mode warning. There is no "track all nodes"
+     * switch (cost + privacy). Example: `{ "npc-guard": 10, elevator: "frame" }`.
+     *
+     * A value may also be a {@link NodeSamplingConfig} to opt the actor's **subtree**
+     * into capture (ADR 0033) — e.g. a whole glTF whose internal parts move
+     * independently. The descendant transforms are emitted as `node_transform`
+     * samples carrying a `childPath` (engine node path relative to the actor); the
+     * walk is anchored, bounded (`maxDepth`/`maxNodes`), and still opt-in.
+     */
+    nodes?: Record<string, SampleRate | NodeSamplingConfig>;
+    /**
+     * Skeleton-bone (`node_transform` with `boneId`) capture, keyed by the
+     * developer-declared actor id (ADR 0027 **Tier 2** — opt-in, higher cost and
+     * privacy). The actor MUST also be declared in `actors` and resolve to a
+     * skinned node with a skeleton. Each entry allowlists the bones to capture
+     * (`include`) and an optional rate (`hz`); bone transforms are skeleton-local.
+     * A humanoid rig is ~50–65 bones, so there is **no whole-skeleton default** —
+     * `include: "*"` is a permitted but explicitly expensive opt-in.
+     * Example: `{ "npc-guard": { include: ["mixamorig:RightHand"], hz: 30 } }`.
+     */
+    bones?: Record<string, BoneSamplingConfig>;
+}
+/**
+ * Tier-2 bone-capture configuration for one declared actor (ADR 0027 §5). The
+ * `include` allowlist is required — either an explicit list of bone names or the
+ * explicit `"*"` wildcard for the full rig (documented as expensive). `hz`
+ * follows the same {@link SampleRate} vocabulary as every other channel and
+ * defaults to the connector's node default when omitted.
+ */
+export interface BoneSamplingConfig {
+    /** Bone names to capture, or `"*"` for the whole rig (explicit, expensive). */
+    include: string[] | "*";
+    /** Capture rate for this actor's bones (Hz / `"frame"` / `0`-off). */
+    hz?: SampleRate;
+}
+/**
+ * Tier-1 **subtree** capture configuration for one declared actor (ADR 0033).
+ * Lets a single declared actor stand in for a moving hierarchy (e.g. a glTF whose
+ * internal parts animate) without naming every descendant. Each captured
+ * descendant is emitted as a `node_transform` carrying a `childPath` (the engine
+ * node path relative to the actor). The walk is anchored to the actor, visits
+ * transform nodes only (bones go through {@link BoneSamplingConfig}; cameras are
+ * refused), and is **bounded** so a deep/wide hierarchy cannot blow up the wire.
+ */
+export interface NodeSamplingConfig {
+    /** Capture rate for the actor and its captured descendants. */
+    hz?: SampleRate;
+    /**
+     * Descendant node names to also capture, or `"*"` for every descendant under
+     * the caps below. Omitted ⇒ root-only (identical to a bare {@link SampleRate}).
+     */
+    include?: string[] | "*";
+    /** Max depth below the actor to descend (root is depth 0). Default 8. */
+    maxDepth?: number;
+    /** Max number of descendants to capture after deterministic BFS truncation. Default 64. */
+    maxNodes?: number;
+    /** Descendant node names to skip (and prune their subtree). */
+    exclude?: string[];
+}
+/** A channel's resolved cadence: off, every render frame, or a fixed interval. */
+export type ResolvedCadence = {
+    readonly mode: "off";
+} | {
+    readonly mode: "frame";
+} | {
+    readonly mode: "interval";
+    readonly ms: number;
+};
+/**
+ * Resolve a {@link SampleRate} (or `undefined`) into a concrete cadence.
+ *
+ * - `undefined` ⇒ the connector default (`defaultMs`), preserving the legacy
+ *   `sampleCameraMs`/`samplePerfMs`/`pointerMoveThrottleMs` knobs.
+ * - `"frame"` ⇒ every render tick.
+ * - `0` (or any non-positive number) ⇒ off.
+ * - `N` Hz ⇒ an interval of `1000 / N` ms.
+ *
+ * There is no enforced upper bound in the OSS SDK (ADR 0012 §3); a caller may opt
+ * into `"frame"` on every channel.
+ */
+export declare function resolveCadence(rate: SampleRate | undefined, defaultMs: number): ResolvedCadence;
+//# sourceMappingURL=sampling.d.ts.map

package/dist/sampling.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sampling.d.ts","sourceRoot":"","sources":["../src/sampling.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,OAAO,CAAC;AAE1C;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,gCAAgC;IAChC,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB,4BAA4B;IAC5B,WAAW,CAAC,EAAE,UAAU,CAAC;IACzB,iCAAiC;IACjC,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACvC;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,GAAG,kBAAkB,CAAC,CAAC;IACxD;;;;;;;;;OASG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,kBAAkB,CAAC,CAAC;CAC5C;AAED;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,+EAA+E;IAC/E,OAAO,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC;IACxB,sEAAsE;IACtE,EAAE,CAAC,EAAE,UAAU,CAAC;CACjB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,kBAAkB;IACjC,+DAA+D;IAC/D,EAAE,CAAC,EAAE,UAAU,CAAC;IAChB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC;IACzB,yEAAyE;IACzE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,2FAA2F;IAC3F,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+DAA+D;IAC/D,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,kFAAkF;AAClF,MAAM,MAAM,eAAe,GACvB;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAA;CAAE,GACxB;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAC1B;IAAE,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvD;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,UAAU,GAAG,SAAS,EAAE,SAAS,EAAE,MAAM,GAAG,eAAe,CAK/F"}

package/dist/sampling.js

@@ -0,0 +1,36 @@
+/**
+ * Capture-fidelity sampling profile (ADR 0012).
+ *
+ * Fidelity is an explicit, per-channel, developer-owned contract with
+ * conservative defaults and no hard cap. The dial governs **continuous** channels
+ * only — camera/head pose, pointer move, and (ADR 0011) controller/hand poses.
+ * **Discrete** semantic events (`pointer_click`, `pointer_down`/`pointer_up`,
+ * `mesh_interaction`, `scene_change`, `session_start`/`session_end`, `custom`)
+ * are always captured at 100% and MUST NOT be rate-limited.
+ *
+ * The profile is a static literal at init today; it is shaped so the same object
+ * can later be fetched from the collector per project (remote config) without a
+ * redesign.
+ */
+/**
+ * Resolve a {@link SampleRate} (or `undefined`) into a concrete cadence.
+ *
+ * - `undefined` ⇒ the connector default (`defaultMs`), preserving the legacy
+ *   `sampleCameraMs`/`samplePerfMs`/`pointerMoveThrottleMs` knobs.
+ * - `"frame"` ⇒ every render tick.
+ * - `0` (or any non-positive number) ⇒ off.
+ * - `N` Hz ⇒ an interval of `1000 / N` ms.
+ *
+ * There is no enforced upper bound in the OSS SDK (ADR 0012 §3); a caller may opt
+ * into `"frame"` on every channel.
+ */
+export function resolveCadence(rate, defaultMs) {
+    if (rate === undefined)
+        return { mode: "interval", ms: defaultMs };
+    if (rate === "frame")
+        return { mode: "frame" };
+    if (rate <= 0)
+        return { mode: "off" };
+    return { mode: "interval", ms: 1000 / rate };
+}
+//# sourceMappingURL=sampling.js.map

package/dist/sampling.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sampling.js","sourceRoot":"","sources":["../src/sampling.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAmGH;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,cAAc,CAAC,IAA4B,EAAE,SAAiB;IAC5E,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,EAAE,EAAE,SAAS,EAAE,CAAC;IACnE,IAAI,IAAI,KAAK,OAAO;QAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;IAC/C,IAAI,IAAI,IAAI,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;IACtC,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,EAAE,EAAE,IAAI,GAAG,IAAI,EAAE,CAAC;AAC/C,CAAC"}

package/dist/transport.d.ts

@@ -0,0 +1,10 @@
+import type { Transport } from "./types.js";
+/**
+ * Default browser transport.
+ *
+ * Prefers `navigator.sendBeacon` so in-flight batches survive page unload, and
+ * falls back to `fetch` with `keepalive` (and finally a plain `fetch`) in
+ * environments where beacon is unavailable (including Node for tests).
+ */
+export declare function createBeaconTransport(endpoint: string): Transport;
+//# sourceMappingURL=transport.d.ts.map

package/dist/transport.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.d.ts","sourceRoot":"","sources":["../src/transport.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,CA+BjE"}