@mentra/miniapp 3.2.1-beta.319 → 3.2.1-beta.355

package/dist/react/stream-preview/controlChannel.d.ts

@@ -0,0 +1,75 @@
+/**
+ * The reserved `_preview` UI channel, as seen from the page.
+ *
+ * The Mentra App answers this channel itself; it never reaches the miniapp's background. Requests
+ * ride `mentra.request`, and host events arrive on `mentra.on("_preview")`. Every control request
+ * carries the page identity (`docGen`, `token`, `mountEpoch`) so the host can drop operations
+ * from a document or a component that has since been replaced.
+ */
+/** `injectFault` is honoured only in debug builds or with the host's hidden developer setting. */
+export type PreviewCommand = "handshake" | "configure" | "start" | "stop" | "rendererError" | "injectFault";
+export interface PreviewControlRequest {
+    cmd: PreviewCommand;
+    /** 0 until the first handshake has told the page which document it is. */
+    docGen: number;
+    token?: string;
+    mountEpoch: number;
+    /** `configure` only: rendered box in device pixels, after rotation. */
+    boxWidth?: number;
+    boxHeight?: number;
+    /** `rendererError` only. */
+    message?: string;
+    /** `injectFault` only: `ack_delay`, `ack_drop`, `transport_close`, `pack_throw`, `sink_throw`, `clear`. */
+    kind?: string;
+    ms?: number;
+}
+export interface PreviewDocumentConfig {
+    t: "config";
+    protocolVersion: number;
+    transport: "webmessage" | "websocket";
+    url?: string;
+    portName?: string;
+    token: string;
+    docGen: number;
+}
+/** `stale`: the host minted a newer document while this handshake was in flight. */
+export type PreviewHandshakeResult = PreviewDocumentConfig | {
+    t: "waiting_for_lease";
+    docGen: number;
+} | {
+    t?: undefined;
+    stale: true;
+};
+/** Reply to configure/start/stop. `stale` means the host dropped it; that is not an error. */
+export interface PreviewControlReply {
+    applied?: boolean;
+    stale?: boolean;
+}
+export type PreviewHostEvent = PreviewDocumentConfig | ({
+    t: "status";
+} & Record<string, unknown>) | {
+    t: "lease_available";
+} | {
+    t: "lease_ended";
+    reason: string;
+} | {
+    t: "error";
+    code: string;
+    docGen?: number;
+} | {
+    t: "paused_background";
+} | {
+    t: "resumed";
+};
+/** A `_preview` request the host refused. `code` is a preview error code. */
+export declare class PreviewControlError extends Error {
+    readonly code: string;
+    constructor(code: string, message?: string);
+}
+export interface PreviewControlChannel {
+    request(request: PreviewControlRequest): Promise<unknown>;
+    onEvent(cb: (event: PreviewHostEvent) => void): () => void;
+}
+/** The channel over the injected `window.mentra` bridge. Null outside a Mentra App WebView. */
+export declare function createMentraControlChannel(): PreviewControlChannel | null;
+//# sourceMappingURL=controlChannel.d.ts.map

package/dist/react/stream-preview/controlChannel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"controlChannel.d.ts","sourceRoot":"","sources":["../../../src/react/stream-preview/controlChannel.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,kGAAkG;AAClG,MAAM,MAAM,cAAc,GAAG,WAAW,GAAG,WAAW,GAAG,OAAO,GAAG,MAAM,GAAG,eAAe,GAAG,aAAa,CAAA;AAE3G,MAAM,WAAW,qBAAqB;IACpC,GAAG,EAAE,cAAc,CAAA;IACnB,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,MAAM,CAAA;IAClB,uEAAuE;IACvE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,4BAA4B;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,2GAA2G;IAC3G,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,EAAE,CAAC,EAAE,MAAM,CAAA;CACZ;AAED,MAAM,WAAW,qBAAqB;IACpC,CAAC,EAAE,QAAQ,CAAA;IACX,eAAe,EAAE,MAAM,CAAA;IACvB,SAAS,EAAE,YAAY,GAAG,WAAW,CAAA;IACrC,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;CACf;AAED,oFAAoF;AACpF,MAAM,MAAM,sBAAsB,GAC9B,qBAAqB,GACrB;IAAC,CAAC,EAAE,mBAAmB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAC,GACxC;IAAC,CAAC,CAAC,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,IAAI,CAAA;CAAC,CAAA;AAEhC,8FAA8F;AAC9F,MAAM,WAAW,mBAAmB;IAClC,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AAED,MAAM,MAAM,gBAAgB,GACxB,qBAAqB,GACrB,CAAC;IAAC,CAAC,EAAE,QAAQ,CAAA;CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GACzC;IAAC,CAAC,EAAE,iBAAiB,CAAA;CAAC,GACtB;IAAC,CAAC,EAAE,aAAa,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAC,GAClC;IAAC,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAC,GAC3C;IAAC,CAAC,EAAE,mBAAmB,CAAA;CAAC,GACxB;IAAC,CAAC,EAAE,SAAS,CAAA;CAAC,CAAA;AAElB,6EAA6E;AAC7E,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;gBAET,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM;CAK3C;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IACzD,OAAO,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,gBAAgB,KAAK,IAAI,GAAG,MAAM,IAAI,CAAA;CAC3D;AAgBD,+FAA+F;AAC/F,wBAAgB,0BAA0B,IAAI,qBAAqB,GAAG,IAAI,CA0BzE"}

package/dist/react/stream-preview/controlChannel.js

@@ -0,0 +1,55 @@
+/**
+ * The reserved `_preview` UI channel, as seen from the page.
+ *
+ * The Mentra App answers this channel itself; it never reaches the miniapp's background. Requests
+ * ride `mentra.request`, and host events arrive on `mentra.on("_preview")`. Every control request
+ * carries the page identity (`docGen`, `token`, `mountEpoch`) so the host can drop operations
+ * from a document or a component that has since been replaced.
+ */
+import { PREVIEW_UI_CHANNEL } from "../../protocol";
+/** A `_preview` request the host refused. `code` is a preview error code. */
+export class PreviewControlError extends Error {
+    constructor(code, message) {
+        super(message ?? code);
+        this.name = "PreviewControlError";
+        this.code = code;
+    }
+}
+/** Host replies are local and fast; this only bounds a host that never answers. */
+const REQUEST_TIMEOUT_MS = 10000;
+function mentraGlobal() {
+    const candidate = globalThis.mentra;
+    if (!candidate || typeof candidate.request !== "function" || typeof candidate.on !== "function")
+        return null;
+    return candidate;
+}
+/** The channel over the injected `window.mentra` bridge. Null outside a Mentra App WebView. */
+export function createMentraControlChannel() {
+    const mentra = mentraGlobal();
+    if (!mentra)
+        return null;
+    return {
+        async request(request) {
+            try {
+                return await mentra.request(PREVIEW_UI_CHANNEL, request, { timeout: REQUEST_TIMEOUT_MS });
+            }
+            catch (error) {
+                const value = (error ?? {});
+                const code = typeof value.code === "string"
+                    ? value.code
+                    : value.name === "MentraRpcTimeoutError"
+                        ? "transport_failed"
+                        : "unsupported";
+                throw new PreviewControlError(code, typeof value.message === "string" ? value.message : undefined);
+            }
+        },
+        onEvent(cb) {
+            return mentra.on(PREVIEW_UI_CHANNEL, (payload) => {
+                if (payload && typeof payload === "object" && typeof payload.t === "string") {
+                    cb(payload);
+                }
+            });
+        },
+    };
+}
+//# sourceMappingURL=controlChannel.js.map

package/dist/react/stream-preview/controlChannel.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"controlChannel.js","sourceRoot":"","sources":["../../../src/react/stream-preview/controlChannel.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAC,kBAAkB,EAAC,MAAM,gBAAgB,CAAA;AAoDjD,6EAA6E;AAC7E,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IAG5C,YAAY,IAAY,EAAE,OAAgB;QACxC,KAAK,CAAC,OAAO,IAAI,IAAI,CAAC,CAAA;QACtB,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAA;QACjC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAA;IAClB,CAAC;CACF;AAYD,mFAAmF;AACnF,MAAM,kBAAkB,GAAG,KAAM,CAAA;AAEjC,SAAS,YAAY;IACnB,MAAM,SAAS,GAAI,UAAwD,CAAC,MAAM,CAAA;IAClF,IAAI,CAAC,SAAS,IAAI,OAAO,SAAS,CAAC,OAAO,KAAK,UAAU,IAAI,OAAO,SAAS,CAAC,EAAE,KAAK,UAAU;QAAE,OAAO,IAAI,CAAA;IAC5G,OAAO,SAAuB,CAAA;AAChC,CAAC;AAED,+FAA+F;AAC/F,MAAM,UAAU,0BAA0B;IACxC,MAAM,MAAM,GAAG,YAAY,EAAE,CAAA;IAC7B,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAA;IACxB,OAAO;QACL,KAAK,CAAC,OAAO,CAAC,OAAO;YACnB,IAAI,CAAC;gBACH,OAAO,MAAM,MAAM,CAAC,OAAO,CAAC,kBAAkB,EAAE,OAAO,EAAE,EAAC,OAAO,EAAE,kBAAkB,EAAC,CAAC,CAAA;YACzF,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,MAAM,KAAK,GAAG,CAAC,KAAK,IAAI,EAAE,CAAwD,CAAA;gBAClF,MAAM,IAAI,GACR,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ;oBAC5B,CAAC,CAAC,KAAK,CAAC,IAAI;oBACZ,CAAC,CAAC,KAAK,CAAC,IAAI,KAAK,uBAAuB;wBACtC,CAAC,CAAC,kBAAkB;wBACpB,CAAC,CAAC,aAAa,CAAA;gBACrB,MAAM,IAAI,mBAAmB,CAAC,IAAI,EAAE,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC,CAAA;YACpG,CAAC;QACH,CAAC;QACD,OAAO,CAAC,EAAE;YACR,OAAO,MAAM,CAAC,EAAE,CAAC,kBAAkB,EAAE,CAAC,OAAO,EAAE,EAAE;gBAC/C,IAAI,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ,IAAI,OAAQ,OAAyB,CAAC,CAAC,KAAK,QAAQ,EAAE,CAAC;oBAC/F,EAAE,CAAC,OAA2B,CAAC,CAAA;gBACjC,CAAC;YACH,CAAC,CAAC,CAAA;QACJ,CAAC;KACF,CAAA;AACH,CAAC"}

package/dist/react/stream-preview/creditLoop.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Consumer side of the one-frame credit scheme.
+ *
+ * The native sender holds exactly one frame in flight and will not send the next until this side
+ * acknowledges the last, so there is no queue anywhere and a slow consumer shows up as a lower
+ * frame rate rather than as growing latency. This module is the half that makes that true: parse,
+ * draw, ack — and never hold a reference to a frame after its ack.
+ *
+ * Durations here would be `performance.now()` and describe JavaScript only; the header's
+ * `timestampNs` / `sentAtNs` are a native monotonic clock with a different epoch. End-to-end
+ * latency is measured natively (it sees both the send and the ack on one clock).
+ */
+import { type ParsedFrame, type PreviewParseErrorReason } from "./protocol";
+export interface CreditLoopFrameSummary {
+    gen: number;
+    seq: number;
+    width: number;
+    height: number;
+    pixelFormat: string;
+    rotationQuarters: number;
+}
+export interface CreditLoopStats {
+    framesReceived: number;
+    drawsSubmitted: number;
+    acksSent: number;
+    parseErrors: number;
+    parseErrorsByReason: Partial<Record<PreviewParseErrorReason, number>>;
+    /**
+     * Frames that arrived while another was still being processed. Native guarantees one at a time,
+     * so any value above zero means the credit scheme is broken.
+     */
+    overlapped: number;
+    /** Frames the sender skipped, counted from gaps in the header sequence. */
+    sequenceGaps: number;
+    skippedBySender: number;
+    lastError: string | null;
+    lastFrame: CreditLoopFrameSummary | null;
+}
+export interface CreditLoopOptions {
+    sendAck: (gen: number, seq: number) => void;
+    /**
+     * Submit the frame. Returns the submit duration in ms, or null when there is no renderer (the
+     * component is unmounted or its GL context is lost). The frame is acked either way.
+     */
+    draw?: (frame: ParsedFrame) => number | null;
+    /** Called once per rejected frame, before anything else happens to it. */
+    onParseError?: (reason: PreviewParseErrorReason, detail?: string) => void;
+}
+export declare class CreditLoop {
+    private readonly options;
+    private readonly errorsByReason;
+    private idleWaiters;
+    private inFlightCount;
+    private framesReceived;
+    private drawsSubmitted;
+    private acksSent;
+    private parseErrors;
+    private overlapped;
+    private sequenceGaps;
+    private skippedBySender;
+    private lastSeq;
+    private lastGen;
+    private lastError;
+    private lastFrame;
+    private draw;
+    constructor(options: CreditLoopOptions);
+    /** Swap the renderer without touching the credit state. Null means frames are acked undrawn. */
+    setDraw(draw: CreditLoopOptions["draw"] | null): void;
+    /** Frames currently being processed. The credit scheme means this is 0 or 1. */
+    get inFlight(): number;
+    /** Entry point for the transport. Deliberately not awaited: the transport must not block. */
+    handleBinary(buffer: ArrayBuffer): void;
+    /** Resolves once nothing is being processed. */
+    idle(): Promise<void>;
+    recordError(reason: string): void;
+    snapshot(): CreditLoopStats;
+    reset(): void;
+    private process;
+    private trackSequence;
+}
+//# sourceMappingURL=creditLoop.d.ts.map

package/dist/react/stream-preview/creditLoop.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"creditLoop.d.ts","sourceRoot":"","sources":["../../../src/react/stream-preview/creditLoop.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAoB,KAAK,WAAW,EAAE,KAAK,uBAAuB,EAAC,MAAM,YAAY,CAAA;AAE5F,MAAM,WAAW,sBAAsB;IACrC,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,WAAW,EAAE,MAAM,CAAA;IACnB,gBAAgB,EAAE,MAAM,CAAA;CACzB;AAED,MAAM,WAAW,eAAe;IAC9B,cAAc,EAAE,MAAM,CAAA;IACtB,cAAc,EAAE,MAAM,CAAA;IACtB,QAAQ,EAAE,MAAM,CAAA;IAChB,WAAW,EAAE,MAAM,CAAA;IACnB,mBAAmB,EAAE,OAAO,CAAC,MAAM,CAAC,uBAAuB,EAAE,MAAM,CAAC,CAAC,CAAA;IACrE;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAA;IAClB,2EAA2E;IAC3E,YAAY,EAAE,MAAM,CAAA;IACpB,eAAe,EAAE,MAAM,CAAA;IACvB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAA;IACxB,SAAS,EAAE,sBAAsB,GAAG,IAAI,CAAA;CACzC;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,IAAI,CAAA;IAC3C;;;OAGG;IACH,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,MAAM,GAAG,IAAI,CAAA;IAC5C,0EAA0E;IAC1E,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,uBAAuB,EAAE,MAAM,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;CAC1E;AAED,qBAAa,UAAU;IAiBT,OAAO,CAAC,QAAQ,CAAC,OAAO;IAhBpC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA6C;IAC5E,OAAO,CAAC,WAAW,CAAwB;IAC3C,OAAO,CAAC,aAAa,CAAI;IACzB,OAAO,CAAC,cAAc,CAAI;IAC1B,OAAO,CAAC,cAAc,CAAI;IAC1B,OAAO,CAAC,QAAQ,CAAI;IACpB,OAAO,CAAC,WAAW,CAAI;IACvB,OAAO,CAAC,UAAU,CAAI;IACtB,OAAO,CAAC,YAAY,CAAI;IACxB,OAAO,CAAC,eAAe,CAAI;IAC3B,OAAO,CAAC,OAAO,CAAsB;IACrC,OAAO,CAAC,OAAO,CAAsB;IACrC,OAAO,CAAC,SAAS,CAAsB;IACvC,OAAO,CAAC,SAAS,CAAsC;IACvD,OAAO,CAAC,IAAI,CAA2B;gBAEV,OAAO,EAAE,iBAAiB;IAIvD,gGAAgG;IAChG,OAAO,CAAC,IAAI,EAAE,iBAAiB,CAAC,MAAM,CAAC,GAAG,IAAI,GAAG,IAAI;IAIrD,gFAAgF;IAChF,IAAI,QAAQ,IAAI,MAAM,CAErB;IAED,6FAA6F;IAC7F,YAAY,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI;IAavC,gDAAgD;IAChD,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAKrB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAIjC,QAAQ,IAAI,eAAe;IAiB3B,KAAK,IAAI,IAAI;YAeC,OAAO;IAiCrB,OAAO,CAAC,aAAa;CAetB"}

package/dist/react/stream-preview/creditLoop.js

@@ -0,0 +1,146 @@
+/**
+ * Consumer side of the one-frame credit scheme.
+ *
+ * The native sender holds exactly one frame in flight and will not send the next until this side
+ * acknowledges the last, so there is no queue anywhere and a slow consumer shows up as a lower
+ * frame rate rather than as growing latency. This module is the half that makes that true: parse,
+ * draw, ack — and never hold a reference to a frame after its ack.
+ *
+ * Durations here would be `performance.now()` and describe JavaScript only; the header's
+ * `timestampNs` / `sentAtNs` are a native monotonic clock with a different epoch. End-to-end
+ * latency is measured natively (it sees both the send and the ack on one clock).
+ */
+import { parsePreviewFrame } from "./protocol";
+export class CreditLoop {
+    constructor(options) {
+        this.options = options;
+        this.errorsByReason = new Map();
+        this.idleWaiters = [];
+        this.inFlightCount = 0;
+        this.framesReceived = 0;
+        this.drawsSubmitted = 0;
+        this.acksSent = 0;
+        this.parseErrors = 0;
+        this.overlapped = 0;
+        this.sequenceGaps = 0;
+        this.skippedBySender = 0;
+        this.lastSeq = null;
+        this.lastGen = null;
+        this.lastError = null;
+        this.lastFrame = null;
+        this.draw = options.draw;
+    }
+    /** Swap the renderer without touching the credit state. Null means frames are acked undrawn. */
+    setDraw(draw) {
+        this.draw = draw ?? undefined;
+    }
+    /** Frames currently being processed. The credit scheme means this is 0 or 1. */
+    get inFlight() {
+        return this.inFlightCount;
+    }
+    /** Entry point for the transport. Deliberately not awaited: the transport must not block. */
+    handleBinary(buffer) {
+        if (this.inFlightCount > 0)
+            this.overlapped += 1;
+        this.inFlightCount += 1;
+        void this.process(buffer).finally(() => {
+            this.inFlightCount -= 1;
+            if (this.inFlightCount === 0) {
+                const waiters = this.idleWaiters;
+                this.idleWaiters = [];
+                for (const resolve of waiters)
+                    resolve();
+            }
+        });
+    }
+    /** Resolves once nothing is being processed. */
+    idle() {
+        if (this.inFlightCount === 0)
+            return Promise.resolve();
+        return new Promise((resolve) => this.idleWaiters.push(resolve));
+    }
+    recordError(reason) {
+        this.lastError = reason;
+    }
+    snapshot() {
+        const parseErrorsByReason = {};
+        for (const [reason, count] of this.errorsByReason)
+            parseErrorsByReason[reason] = count;
+        return {
+            framesReceived: this.framesReceived,
+            drawsSubmitted: this.drawsSubmitted,
+            acksSent: this.acksSent,
+            parseErrors: this.parseErrors,
+            parseErrorsByReason,
+            overlapped: this.overlapped,
+            sequenceGaps: this.sequenceGaps,
+            skippedBySender: this.skippedBySender,
+            lastError: this.lastError,
+            lastFrame: this.lastFrame,
+        };
+    }
+    reset() {
+        this.framesReceived = 0;
+        this.drawsSubmitted = 0;
+        this.acksSent = 0;
+        this.parseErrors = 0;
+        this.overlapped = 0;
+        this.sequenceGaps = 0;
+        this.skippedBySender = 0;
+        this.lastSeq = null;
+        this.lastGen = null;
+        this.lastError = null;
+        this.lastFrame = null;
+        this.errorsByReason.clear();
+    }
+    async process(buffer) {
+        this.framesReceived += 1;
+        const parsed = parsePreviewFrame(buffer);
+        if (!parsed.ok) {
+            // No ack: a frame this side could not read is not a frame it consumed, and acking it would
+            // hide the fault behind a healthy-looking rate.
+            this.parseErrors += 1;
+            this.errorsByReason.set(parsed.reason, (this.errorsByReason.get(parsed.reason) ?? 0) + 1);
+            this.lastError = parsed.detail ? `${parsed.reason} (${parsed.detail})` : parsed.reason;
+            this.options.onParseError?.(parsed.reason, parsed.detail);
+            return;
+        }
+        this.trackSequence(parsed);
+        this.lastFrame = {
+            gen: parsed.sessionGen,
+            seq: parsed.frameSeq,
+            width: parsed.width,
+            height: parsed.height,
+            pixelFormat: parsed.pixelFormat,
+            rotationQuarters: parsed.rotationQuarters,
+        };
+        if (this.draw) {
+            const submitMs = this.draw(parsed);
+            if (submitMs === null)
+                this.lastError = "draw_failed";
+            else
+                this.drawsSubmitted += 1;
+        }
+        // Ack last, after the draw has been submitted, so the credit the sender gets back means "this
+        // side is done with that frame" rather than "this side received some bytes". A dead canvas
+        // still acks: withholding credit would stall the sender on top of it.
+        this.options.sendAck(parsed.sessionGen, parsed.frameSeq);
+        this.acksSent += 1;
+    }
+    trackSequence(parsed) {
+        if (this.lastGen !== parsed.sessionGen) {
+            this.lastGen = parsed.sessionGen;
+            this.lastSeq = parsed.frameSeq;
+            return;
+        }
+        if (this.lastSeq !== null) {
+            const delta = parsed.frameSeq - this.lastSeq;
+            if (delta > 1) {
+                this.sequenceGaps += 1;
+                this.skippedBySender += delta - 1;
+            }
+        }
+        this.lastSeq = parsed.frameSeq;
+    }
+}
+//# sourceMappingURL=creditLoop.js.map

package/dist/react/stream-preview/creditLoop.js.map

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

package/dist/react/stream-preview/protocol.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Wire format for raw decoded-frame preview (`MFPV`): a 64-byte little-endian header followed by
+ * a tightly packed 8-bit YUV payload.
+ *
+ * Nothing in this module may copy the payload. `parsePreviewFrame` returns `Uint8Array` views onto
+ * the caller's ArrayBuffer and the renderer uploads those views straight to WebGL; a `.slice()`
+ * anywhere in this path turns a zero-copy preview into a per-frame memcpy.
+ *
+ * Bad input is expected — a truncated or stale frame is a measurement, not an exception — so the
+ * parser returns a discriminated union and never throws.
+ *
+ *   offset  size  field
+ *        0     4  magic "MFPV"
+ *        4     2  version u16
+ *        6     2  headerLen u16
+ *        8     4  payloadLen u32
+ *       12     4  sessionGen u32
+ *       16     4  frameSeq u32
+ *       20     2  width u16
+ *       22     2  height u16
+ *       24     1  pixelFormat u8 (1 = I420, 2 = NV12)
+ *       25     1  rotation u8 (quarter turns clockwise)
+ *       26     1  colorMatrix u8 (0 unknown, 1 BT.601, 2 BT.709)
+ *       27     1  colorRange u8 (0 unknown, 1 limited, 2 full)
+ *       28     2  flags u16 (bit 0: the sender fell back on default colour metadata)
+ *       30     2  reserved u16
+ *       32     8  timestampNs i64 (native monotonic decode time, 0 when unknown)
+ *       40     8  sentAtNs i64 (native monotonic at the send call)
+ *       48    16  reserved
+ */
+/** Fixed header size. A sender that disagrees is rejected rather than guessed at. */
+export declare const PREVIEW_FRAME_HEADER_BYTES = 64;
+export declare const PREVIEW_FRAME_VERSION = 1;
+/** ASCII "MFPV". */
+export declare const PREVIEW_FRAME_MAGIC: readonly [77, 70, 80, 86];
+/** Neither the glasses nor a phone camera reaches this; anything above it is a corrupt header. */
+export declare const PREVIEW_FRAME_MAX_DIMENSION = 4096;
+export declare const PIXEL_FORMAT_I420 = 1;
+export declare const PIXEL_FORMAT_NV12 = 2;
+export type PreviewPixelFormat = "i420" | "nv12";
+export type PreviewColorMatrix = "bt601" | "bt709";
+export type PreviewColorRange = "limited" | "full";
+/**
+ * One code per rejected frame, because "the frame was bad" is not a finding. A run that drops
+ * frames on `truncated-payload` and one that drops them on `payload-size-mismatch` point at
+ * different halves of the native sender.
+ */
+export type PreviewParseErrorReason = "short-buffer" | "bad-magic" | "unsupported-version" | "bad-header-length" | "bad-dimensions" | "unknown-pixel-format" | "payload-size-mismatch" | "truncated-payload";
+export declare const PREVIEW_PARSE_ERROR_REASONS: readonly PreviewParseErrorReason[];
+interface ParsedFrameBase {
+    ok: true;
+    sessionGen: number;
+    frameSeq: number;
+    width: number;
+    height: number;
+    /** Quarter turns clockwise, normalized to 0..3. */
+    rotationQuarters: number;
+    colorMatrix: PreviewColorMatrix;
+    colorRange: PreviewColorRange;
+    /** The header said "unknown" and BT.601 was assumed. */
+    colorMatrixAssumed: boolean;
+    /** The header said "unknown" and limited range was assumed. */
+    colorRangeAssumed: boolean;
+    /** Header flag bit 0: the native sender itself had to fall back on default colour metadata. */
+    senderColorFallback: boolean;
+    /**
+     * Native monotonic clock, nanoseconds. Never subtract a `performance.now()` value from these:
+     * the two clocks share no epoch. Only native-to-native differences mean anything.
+     */
+    timestampNs: bigint;
+    sentAtNs: bigint;
+    yStride: number;
+    chromaWidth: number;
+    chromaHeight: number;
+    chromaStride: number;
+    payloadLen: number;
+}
+export interface ParsedI420Frame extends ParsedFrameBase {
+    pixelFormat: "i420";
+    y: Uint8Array;
+    u: Uint8Array;
+    v: Uint8Array;
+}
+export interface ParsedNv12Frame extends ParsedFrameBase {
+    pixelFormat: "nv12";
+    y: Uint8Array;
+    /** Interleaved U,V pairs: `chromaStride` is 2 × `chromaWidth` bytes. */
+    uv: Uint8Array;
+}
+export type ParsedFrame = ParsedI420Frame | ParsedNv12Frame;
+export interface PreviewParseError {
+    ok: false;
+    reason: PreviewParseErrorReason;
+    /** Numbers the reason alone does not carry, for the log line. */
+    detail?: string;
+}
+export type PreviewParseResult = ParsedFrame | PreviewParseError;
+/** Chroma plane dimensions for 4:2:0, which both supported formats are. */
+export declare function chromaDimensions(width: number, height: number): {
+    width: number;
+    height: number;
+};
+/** Bytes a tightly packed I420 or NV12 frame occupies. Both layouts are the same size. */
+export declare function packedPayloadBytes(width: number, height: number): number;
+/**
+ * Validate a frame and expose its planes.
+ *
+ * The plane fields are views onto `buffer`, so they stay valid only as long as the caller holds
+ * that buffer and nothing else writes into it.
+ */
+export declare function parsePreviewFrame(buffer: ArrayBuffer): PreviewParseResult;
+export {};
+//# sourceMappingURL=protocol.d.ts.map

package/dist/react/stream-preview/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../../src/react/stream-preview/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,qFAAqF;AACrF,eAAO,MAAM,0BAA0B,KAAK,CAAA;AAC5C,eAAO,MAAM,qBAAqB,IAAI,CAAA;AACtC,oBAAoB;AACpB,eAAO,MAAM,mBAAmB,2BAAoC,CAAA;AACpE,kGAAkG;AAClG,eAAO,MAAM,2BAA2B,OAAO,CAAA;AAE/C,eAAO,MAAM,iBAAiB,IAAI,CAAA;AAClC,eAAO,MAAM,iBAAiB,IAAI,CAAA;AAElC,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,MAAM,CAAA;AAChD,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,OAAO,CAAA;AAClD,MAAM,MAAM,iBAAiB,GAAG,SAAS,GAAG,MAAM,CAAA;AAElD;;;;GAIG;AACH,MAAM,MAAM,uBAAuB,GAC/B,cAAc,GACd,WAAW,GACX,qBAAqB,GACrB,mBAAmB,GACnB,gBAAgB,GAChB,sBAAsB,GACtB,uBAAuB,GACvB,mBAAmB,CAAA;AAEvB,eAAO,MAAM,2BAA2B,EAAE,SAAS,uBAAuB,EASzE,CAAA;AAED,UAAU,eAAe;IACvB,EAAE,EAAE,IAAI,CAAA;IACR,UAAU,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,MAAM,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,mDAAmD;IACnD,gBAAgB,EAAE,MAAM,CAAA;IACxB,WAAW,EAAE,kBAAkB,CAAA;IAC/B,UAAU,EAAE,iBAAiB,CAAA;IAC7B,wDAAwD;IACxD,kBAAkB,EAAE,OAAO,CAAA;IAC3B,+DAA+D;IAC/D,iBAAiB,EAAE,OAAO,CAAA;IAC1B,+FAA+F;IAC/F,mBAAmB,EAAE,OAAO,CAAA;IAC5B;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAA;IACnB,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,MAAM,CAAA;IACnB,YAAY,EAAE,MAAM,CAAA;IACpB,YAAY,EAAE,MAAM,CAAA;IACpB,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,eAAgB,SAAQ,eAAe;IACtD,WAAW,EAAE,MAAM,CAAA;IACnB,CAAC,EAAE,UAAU,CAAA;IACb,CAAC,EAAE,UAAU,CAAA;IACb,CAAC,EAAE,UAAU,CAAA;CACd;AAED,MAAM,WAAW,eAAgB,SAAQ,eAAe;IACtD,WAAW,EAAE,MAAM,CAAA;IACnB,CAAC,EAAE,UAAU,CAAA;IACb,wEAAwE;IACxE,EAAE,EAAE,UAAU,CAAA;CACf;AAED,MAAM,MAAM,WAAW,GAAG,eAAe,GAAG,eAAe,CAAA;AAE3D,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,KAAK,CAAA;IACT,MAAM,EAAE,uBAAuB,CAAA;IAC/B,iEAAiE;IACjE,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,MAAM,kBAAkB,GAAG,WAAW,GAAG,iBAAiB,CAAA;AAEhE,2EAA2E;AAC3E,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAC,CAE/F;AAED,0FAA0F;AAC1F,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAGxE;AAMD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,WAAW,GAAG,kBAAkB,CA+EzE"}

package/dist/react/stream-preview/protocol.js

@@ -0,0 +1,148 @@
+/**
+ * Wire format for raw decoded-frame preview (`MFPV`): a 64-byte little-endian header followed by
+ * a tightly packed 8-bit YUV payload.
+ *
+ * Nothing in this module may copy the payload. `parsePreviewFrame` returns `Uint8Array` views onto
+ * the caller's ArrayBuffer and the renderer uploads those views straight to WebGL; a `.slice()`
+ * anywhere in this path turns a zero-copy preview into a per-frame memcpy.
+ *
+ * Bad input is expected — a truncated or stale frame is a measurement, not an exception — so the
+ * parser returns a discriminated union and never throws.
+ *
+ *   offset  size  field
+ *        0     4  magic "MFPV"
+ *        4     2  version u16
+ *        6     2  headerLen u16
+ *        8     4  payloadLen u32
+ *       12     4  sessionGen u32
+ *       16     4  frameSeq u32
+ *       20     2  width u16
+ *       22     2  height u16
+ *       24     1  pixelFormat u8 (1 = I420, 2 = NV12)
+ *       25     1  rotation u8 (quarter turns clockwise)
+ *       26     1  colorMatrix u8 (0 unknown, 1 BT.601, 2 BT.709)
+ *       27     1  colorRange u8 (0 unknown, 1 limited, 2 full)
+ *       28     2  flags u16 (bit 0: the sender fell back on default colour metadata)
+ *       30     2  reserved u16
+ *       32     8  timestampNs i64 (native monotonic decode time, 0 when unknown)
+ *       40     8  sentAtNs i64 (native monotonic at the send call)
+ *       48    16  reserved
+ */
+/** Fixed header size. A sender that disagrees is rejected rather than guessed at. */
+export const PREVIEW_FRAME_HEADER_BYTES = 64;
+export const PREVIEW_FRAME_VERSION = 1;
+/** ASCII "MFPV". */
+export const PREVIEW_FRAME_MAGIC = [0x4d, 0x46, 0x50, 0x56];
+/** Neither the glasses nor a phone camera reaches this; anything above it is a corrupt header. */
+export const PREVIEW_FRAME_MAX_DIMENSION = 4096;
+export const PIXEL_FORMAT_I420 = 1;
+export const PIXEL_FORMAT_NV12 = 2;
+export const PREVIEW_PARSE_ERROR_REASONS = [
+    "short-buffer",
+    "bad-magic",
+    "unsupported-version",
+    "bad-header-length",
+    "bad-dimensions",
+    "unknown-pixel-format",
+    "payload-size-mismatch",
+    "truncated-payload",
+];
+/** Chroma plane dimensions for 4:2:0, which both supported formats are. */
+export function chromaDimensions(width, height) {
+    return { width: Math.ceil(width / 2), height: Math.ceil(height / 2) };
+}
+/** Bytes a tightly packed I420 or NV12 frame occupies. Both layouts are the same size. */
+export function packedPayloadBytes(width, height) {
+    const chroma = chromaDimensions(width, height);
+    return width * height + 2 * chroma.width * chroma.height;
+}
+function fail(reason, detail) {
+    return detail === undefined ? { ok: false, reason } : { ok: false, reason, detail };
+}
+/**
+ * Validate a frame and expose its planes.
+ *
+ * The plane fields are views onto `buffer`, so they stay valid only as long as the caller holds
+ * that buffer and nothing else writes into it.
+ */
+export function parsePreviewFrame(buffer) {
+    if (buffer.byteLength < PREVIEW_FRAME_HEADER_BYTES) {
+        return fail("short-buffer", `${buffer.byteLength} bytes`);
+    }
+    const header = new DataView(buffer, 0, PREVIEW_FRAME_HEADER_BYTES);
+    const magic = new Uint8Array(buffer, 0, PREVIEW_FRAME_MAGIC.length);
+    if (PREVIEW_FRAME_MAGIC.some((byte, index) => magic[index] !== byte)) {
+        return fail("bad-magic", Array.from(magic, (byte) => byte.toString(16).padStart(2, "0")).join(" "));
+    }
+    const version = header.getUint16(4, true);
+    if (version !== PREVIEW_FRAME_VERSION)
+        return fail("unsupported-version", `v${version}`);
+    const headerLen = header.getUint16(6, true);
+    if (headerLen !== PREVIEW_FRAME_HEADER_BYTES)
+        return fail("bad-header-length", `${headerLen} bytes`);
+    const payloadLen = header.getUint32(8, true);
+    const sessionGen = header.getUint32(12, true);
+    const frameSeq = header.getUint32(16, true);
+    const width = header.getUint16(20, true);
+    const height = header.getUint16(22, true);
+    if (width === 0 || height === 0 || width > PREVIEW_FRAME_MAX_DIMENSION || height > PREVIEW_FRAME_MAX_DIMENSION) {
+        return fail("bad-dimensions", `${width}x${height}`);
+    }
+    const formatCode = header.getUint8(24);
+    if (formatCode !== PIXEL_FORMAT_I420 && formatCode !== PIXEL_FORMAT_NV12) {
+        return fail("unknown-pixel-format", `code ${formatCode}`);
+    }
+    const expectedPayload = packedPayloadBytes(width, height);
+    if (payloadLen !== expectedPayload) {
+        return fail("payload-size-mismatch", `${payloadLen} bytes, expected ${expectedPayload}`);
+    }
+    if (buffer.byteLength < headerLen + payloadLen) {
+        return fail("truncated-payload", `${buffer.byteLength - headerLen} of ${payloadLen} bytes`);
+    }
+    const matrixCode = header.getUint8(26);
+    const rangeCode = header.getUint8(27);
+    const flags = header.getUint16(28, true);
+    const chroma = chromaDimensions(width, height);
+    const luma = width * height;
+    const base = {
+        ok: true,
+        sessionGen,
+        frameSeq,
+        width,
+        height,
+        rotationQuarters: header.getUint8(25) % 4,
+        // Unknown metadata is not a rejection: BT.601 limited is what an untagged 8-bit camera frame
+        // almost always is. The assumption is surfaced so a wrong-looking picture can be traced to it
+        // instead of to the shader.
+        colorMatrix: matrixCode === 2 ? "bt709" : "bt601",
+        colorRange: rangeCode === 2 ? "full" : "limited",
+        colorMatrixAssumed: matrixCode !== 1 && matrixCode !== 2,
+        colorRangeAssumed: rangeCode !== 1 && rangeCode !== 2,
+        senderColorFallback: (flags & 0x0001) !== 0,
+        timestampNs: header.getBigInt64(32, true),
+        sentAtNs: header.getBigInt64(40, true),
+        yStride: width,
+        chromaWidth: chroma.width,
+        chromaHeight: chroma.height,
+        chromaStride: formatCode === PIXEL_FORMAT_NV12 ? chroma.width * 2 : chroma.width,
+        payloadLen,
+    };
+    // Subviews, never copies.
+    if (formatCode === PIXEL_FORMAT_NV12) {
+        return {
+            ...base,
+            pixelFormat: "nv12",
+            y: new Uint8Array(buffer, headerLen, luma),
+            uv: new Uint8Array(buffer, headerLen + luma, 2 * chroma.width * chroma.height),
+        };
+    }
+    const chromaPlane = chroma.width * chroma.height;
+    return {
+        ...base,
+        pixelFormat: "i420",
+        y: new Uint8Array(buffer, headerLen, luma),
+        u: new Uint8Array(buffer, headerLen + luma, chromaPlane),
+        v: new Uint8Array(buffer, headerLen + luma + chromaPlane, chromaPlane),
+    };
+}
+//# sourceMappingURL=protocol.js.map

package/dist/react/stream-preview/protocol.js.map

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