@smartspectra/node-sdk 3.2.0-rc.6

package/js/renderer/index.js

@@ -0,0 +1,670 @@
+// js/renderer/index.js
+// Copyright (C) 2026 Presage Technologies, Inc.
+//
+// SPDX-License-Identifier: LicenseRef-Proprietary
+//
+// Renderer-side `SmartSpectraSDK` for Electron applications. Reads
+// VideoFrames directly from the MediaStreamTrack via
+// `MediaStreamTrackProcessor`, draws each frame into an OffscreenCanvas to
+// extract RGBA pixels, and ships the buffer (structured-cloned — Electron's
+// MessagePortMain drops ArrayBuffer transfer lists) to the main-process SDK
+// via the preload bridge. SDK callbacks come back over the same bridge and
+// surface as events on this class.
+//
+// Requires Electron 16+ (Chromium 94+) for MediaStreamTrackProcessor.
+
+'use strict';
+
+const SUPPORTED_EVENTS = new Set([
+    'processingStatus',
+    'validationStatus',
+    'metrics',
+    'accumulatedMetrics',
+    'insight',
+    'frameSentThrough',
+    'error',
+    // Fires once the SDK has acquired (or re-acquired, after a Stop) the
+    // default MediaStream. Host apps attach this stream to their preview
+    // <video> element. Not fired when the host supplies its own stream
+    // via useMediaStream() — in that case the host already owns the
+    // reference.
+    'streamAvailable',
+]);
+
+const PIXEL_FORMAT_RGBA = 2;  // mirrors PixelFormat.kRGBA in constants.js
+
+// kStarting and kRunning enum values from constants.js. Mirrored here so
+// the renderer doesn't need to pull in the constants module for these
+// comparisons.
+const PROCESSING_STATUS_STARTING = 2;
+const PROCESSING_STATUS_RUNNING  = 3;
+
+// kProcessingFailed error code from constants.js. Used by the startup
+// watchdog when the graph stays stuck at Starting without producing a
+// single validation packet for STARTUP_WATCHDOG_MS.
+const ERROR_CODE_PROCESSING_FAILED = 8;
+const STARTUP_WATCHDOG_MS = 30_000;
+
+// Default getUserMedia constraints — 1280x720 at 30 fps with the
+// front-facing camera, matching what the signal pipeline is tuned for.
+// `ideal` qualifiers let the browser fall back gracefully when a webcam
+// doesn't natively support these numbers; the signal processing
+// tolerates moderate deviations.
+const DEFAULT_VIDEO_CONSTRAINTS = Object.freeze({
+    width:      { ideal: 1280 },
+    height:     { ideal: 720  },
+    frameRate:  { ideal: 30   },
+    facingMode: 'user',
+});
+
+class SmartSpectraSDK {
+    /**
+     * @param {Object} [options]
+     * @param {string} [options.apiKey]
+     * @param {number[]} [options.requestedMetrics]
+     * @param {boolean} [options.enableAccumulatedOutput=false]
+     * @param {number} [options.sendTimeoutMs=30000] Per-call timeout for
+     *   renderer→main IPC roundtrips (start/stop/reset/requestInsight/configure).
+     *   If the main process crashes or stalls, the pending call rejects with a
+     *   `SMARTSPECTRA_IPC_TIMEOUT` error instead of hanging the UI forever.
+     *   Set to 0 to disable the timeout.
+     */
+    constructor(options = {}) {
+        if (typeof window === 'undefined' || !window.__smartspectraBridge) {
+            throw new Error(
+                '@smartspectra/node-sdk/renderer: window.__smartspectraBridge is unavailable. ' +
+                'Set webPreferences.preload to require.resolve(\'@smartspectra/node-sdk/preload\') ' +
+                'on the BrowserWindow that loads this renderer, and call ' +
+                'bindSmartSpectraIpc(window) from the main process.');
+        }
+        for (const method of ['attach', 'postMessage', 'onMessage', 'close']) {
+            if (typeof window.__smartspectraBridge[method] !== 'function') {
+                throw new Error(
+                    `@smartspectra/node-sdk/renderer: bridge is missing ${method}(). ` +
+                    'The preload script may be out of sync with the renderer module.');
+            }
+        }
+        if (typeof MediaStreamTrackProcessor === 'undefined') {
+            throw new Error(
+                '@smartspectra/node-sdk/renderer: MediaStreamTrackProcessor is unavailable. ' +
+                'Requires Electron 16+ (Chromium 94+).');
+        }
+
+        this._options = {
+            apiKey:                  options.apiKey ?? '',
+            requestedMetrics:        options.requestedMetrics,
+            enableAccumulatedOutput: !!options.enableAccumulatedOutput,
+        };
+
+        this._listeners        = new Map();
+        this._processingStatus = 0;              // kUninitialized
+
+        this._stream           = null;
+        // true when the SDK acquired the stream via getUserMedia and is
+        // therefore responsible for stopping its tracks on stop()/destroy().
+        // false when the host supplied the stream via useMediaStream() —
+        // the host owns the lifecycle in that case.
+        this._streamOwned      = false;
+        this._track            = null;
+        this._processor        = null;
+        this._reader           = null;
+        this._frameLoopActive  = false;
+        this._frameLoopPromise = null;
+        // Monotonic frame-timestamp ratchet. Lives on the instance (not the
+        // frame loop) so it persists across stop()/start() cycles: the main
+        // process reuses one native session whose per-session monotonic guard
+        // is NOT reset by stop/start, so a fresh camera clock starting lower
+        // than the previous session's last timestamp would otherwise trip
+        // kNonMonotonicTimestamp.
+        this._lastFrameTs      = 0n;
+        // Set true once the AE/AWB/focus lock has been attempted post-Running
+        // so we don't try to relock every frame after kRunning.
+        this._cameraLocked     = false;
+        // Startup watchdog: if processingStatus stays at kStarting for
+        // STARTUP_WATCHDOG_MS without a single validationStatus packet,
+        // we synthesize an 'error' event so host apps can show a real
+        // failure instead of an indefinite "Starting…" UI. Cleared when
+        // we first see kRunning, the first validationStatus packet, or
+        // any other status transition out of kStarting.
+        this._startupWatchdog  = null;
+
+        this._bridge        = window.__smartspectraBridge;
+        // Diagnostic logging is opt-in via SMARTSPECTRA_DIAGNOSTICS=1 in the
+        // host process, mirrored onto the bridge by the preload script (this
+        // context can't read process.env). Older preload builds lack the
+        // property — strict-compare so they resolve to "off".
+        this._diagnostics   = this._bridge.diagnostics === true;
+        this._nextReplyId   = 1;
+        this._pendingAcks   = new Map();         // replyId → { resolve, reject }
+        // Per-call IPC ack timeout. A finite, non-negative number overrides the
+        // 30s default; 0 disables the timeout entirely.
+        const sendTimeoutMs = options.sendTimeoutMs;
+        this._sendTimeoutMs = (typeof sendTimeoutMs === 'number'
+            && Number.isFinite(sendTimeoutMs) && sendTimeoutMs >= 0)
+            ? sendTimeoutMs
+            : 30_000;
+
+        this._bridge.onMessage((data) => this._handleBridgeMessage(data));
+        this._bridge.attach();
+
+        // Configure the main-process SDK eagerly so a frame pushed shortly
+        // after `start()` doesn't race against a still-unconstructed
+        // SmartSpectraSDK on the main side.
+        this._bridge.postMessage({ kind: 'configure', options: this._options });
+    }
+
+    /** SDK package version. */
+    static get version() { return require('../../package.json').version; }
+
+    /** Current ProcessingStatus integer value. */
+    get processingStatus() { return this._processingStatus; }
+
+    /**
+     * Override the default camera with a host-supplied `MediaStream` from
+     * `navigator.mediaDevices.getUserMedia`, `desktopCapturer`, a
+     * `<canvas>.captureStream()`, etc. Optional — if not called, `start()`
+     * acquires its own MediaStream with sensible defaults (front camera,
+     * 1280x720 at 30 fps, AE/AWB lock after settle) and emits it via the
+     * `'streamAvailable'` event.
+     *
+     * When the host supplies the stream the host also owns its lifecycle —
+     * the SDK never stops the original tracks, only its own internal clone.
+     */
+    useMediaStream(stream) {
+        if (!(stream instanceof MediaStream)) {
+            throw new TypeError('useMediaStream: argument must be a MediaStream');
+        }
+        this._stream = stream;
+        this._streamOwned = false;
+        return this;
+    }
+
+    /**
+     * Begin processing. If no stream has been attached via useMediaStream(),
+     * the SDK acquires the default front-facing camera and emits it through
+     * `'streamAvailable'` so the host can show a live preview. Resolves once
+     * the main-process SDK has armed the graph and is ready to accept frames.
+     * On failure, rolls back the renderer-side frame pump and (if the SDK
+     * acquired the stream itself) releases the camera so a retry isn't
+     * blocked.
+     */
+    async start() {
+        // Acquire the default camera if the host didn't supply one. The
+        // streamAvailable event is dispatched synchronously after acquire
+        // so the host can attach it to a <video> element before the frame
+        // loop kicks off — that way the preview shows the same warm-up
+        // window the signal processor sees.
+        if (!this._stream) {
+            this._stream = await this._acquireDefaultStream();
+            this._streamOwned = true;
+            this._emit('streamAvailable', this._stream);
+        }
+
+        const tracks = this._stream.getVideoTracks();
+        if (tracks.length === 0) {
+            // If we acquired this stream ourselves, release it before
+            // surfacing the error — otherwise the camera stays open and
+            // the next start() races against a half-built state.
+            if (this._streamOwned) {
+                for (const t of this._stream.getTracks()) {
+                    try { t.stop(); } catch { /* already stopped */ }
+                }
+                this._stream = null;
+                this._streamOwned = false;
+            }
+            throw new Error('start(): MediaStream has no video tracks');
+        }
+
+        // Clone the source track so MediaStreamTrackProcessor doesn't starve
+        // other consumers of the original stream (e.g. a preview <video>
+        // element the host app renders). Both tracks share the underlying
+        // camera source and receive identical frames; each can be consumed
+        // independently. The clone is stopped in _stopFrameLoop().
+        this._track = tracks[0].clone();
+        this._processor = new MediaStreamTrackProcessor({ track: this._track });
+        this._reader = this._processor.readable.getReader();
+        this._cameraLocked = false;
+        // Send `start` before arming the frame loop. The main process calls
+        // startCustom() inside the `start` handler; any frames posted before
+        // that returns would pass the JS guard (_customInputActive=true) but
+        // fail the C guard (custom_input=null), producing a misleading error.
+        // Frames captured while the ack is in flight are buffered by the reader
+        // and drained once the loop starts below.
+
+        try {
+            await this._send({ kind: 'start', frameTransform: 0 });
+        } catch (err) {
+            // _stopFrameLoop is idempotent: cleans up reader/track even if the
+            // loop was never started.
+            await this._stopFrameLoop();
+            this._releaseOwnedStream();
+            throw err;
+        }
+
+        this._frameLoopActive = true;
+        this._frameLoopPromise = this._runFrameLoop();
+    }
+
+    /**
+     * Stop processing. Resolves once the main-process SDK has stopped.
+     * If the SDK acquired the camera itself, the stream is released here
+     * — start() will re-acquire on the next call. Host-supplied streams
+     * are left untouched; the host owns their lifecycle.
+     */
+    async stop() {
+        this._clearStartupWatchdog();
+        await this._stopFrameLoop();
+        await this._send({ kind: 'stop' });
+        this._releaseOwnedStream();
+    }
+
+    /**
+     * Rebuild the graph after a kError state. Releases any SDK-acquired
+     * camera so the next start() re-runs the acquire + settle sequence
+     * from scratch.
+     */
+    async reset() {
+        this._clearStartupWatchdog();
+        await this._stopFrameLoop();
+        await this._send({ kind: 'reset' });
+        this._releaseOwnedStream();
+    }
+
+    /**
+     * Dispatch an on-demand insight prompt. Resolves with the request id
+     * assigned to it; the matching Insight response arrives via the
+     * `'insight'` event with the same id.
+     */
+    async requestInsight(text) {
+        if (typeof text !== 'string') {
+            throw new TypeError('requestInsight: text must be a string');
+        }
+        const ack = await this._send({ kind: 'requestInsight', text });
+        return ack.requestId | 0;
+    }
+
+    /**
+     * Tear down the renderer-side resources and instruct the main process
+     * to destroy its SDK instance. Idempotent.
+     */
+    destroy() {
+        if (this._destroyed) return;
+        this._destroyed = true;
+        this._clearStartupWatchdog();
+        // Reject any in-flight IPC roundtrips so awaiters of start()/stop()/
+        // reset()/requestInsight() don't hang on a session that's gone (the
+        // bridge is closed below and no ack will ever arrive). Typed so
+        // cleanup code can distinguish it from a session-level error or an
+        // IPC timeout; each pending entry's wrapped reject also clears its
+        // own timeout timer. A one-sided bridge disconnect (main-process
+        // death) can't be caught here — the DOM MessagePort has no close
+        // event — but the per-call _send timeout rejects those waiters.
+        const destroyedErr = new Error('SmartSpectraSDK: destroyed before main-process ack');
+        destroyedErr.code = 'SMARTSPECTRA_DESTROYED';
+        this._rejectPendingAcks(destroyedErr);
+        this._frameLoopActive = false;
+        if (this._reader) {
+            try { this._reader.cancel().catch(() => {}); } catch { /* ignore */ }
+            this._reader = null;
+        }
+        this._processor = null;
+        if (this._track) {
+            try { this._track.stop(); } catch { /* already stopped */ }
+            this._track = null;
+        }
+        this._releaseOwnedStream();
+        this._stream = null;
+        try { this._bridge.postMessage({ kind: 'destroy' }); } catch { /* bridge may be dead */ }
+        try { this._bridge.close(); } catch { /* already closed */ }
+    }
+
+    on(event, callback) {
+        if (typeof event !== 'string' || typeof callback !== 'function') {
+            throw new TypeError('on(event: string, callback: Function)');
+        }
+        if (!SUPPORTED_EVENTS.has(event)) {
+            throw new RangeError(`on(): unsupported event ${event}`);
+        }
+        this._listeners.set(event, callback);
+        return this;
+    }
+
+    // ---------- internal --------------------------------------------------
+
+    _armStartupWatchdog() {
+        // Idempotent: if we're already armed (e.g. duplicate kStarting
+        // status events) keep the original timer so the deadline is
+        // measured from the first Starting transition, not the latest.
+        if (this._startupWatchdog) return;
+        this._startupWatchdog = setTimeout(() => {
+            this._startupWatchdog = null;
+            // Defensive: don't fire if we somehow advanced past Starting
+            // in the meantime (status race vs. timer).
+            if (this._processingStatus !== PROCESSING_STATUS_STARTING) return;
+            const message =
+                `Processing stalled at Starting for ${Math.round(STARTUP_WATCHDOG_MS / 1000)} s ` +
+                'without producing a validation packet. Common causes: model ' +
+                'download blocked by network/firewall, server-side service unavailable, ' +
+                'or an SDK-level error that didn\'t propagate through the bridge. ' +
+                'Check the main-process terminal for SDK log lines, then retry or fall ' +
+                'back to the basic metrics bundle (breathing, pulse rate), which has no ' +
+                'additional model-load requirement.';
+            this._emit(
+                'error',
+                ERROR_CODE_PROCESSING_FAILED,
+                message,
+                /*retryable=*/true);
+        }, STARTUP_WATCHDOG_MS);
+    }
+
+    _clearStartupWatchdog() {
+        if (this._startupWatchdog) {
+            clearTimeout(this._startupWatchdog);
+            this._startupWatchdog = null;
+        }
+    }
+
+    async _acquireDefaultStream() {
+        if (!navigator || !navigator.mediaDevices ||
+            typeof navigator.mediaDevices.getUserMedia !== 'function') {
+            throw new Error(
+                '@smartspectra/node-sdk/renderer: navigator.mediaDevices.getUserMedia ' +
+                'is unavailable. Set webPreferences.contextIsolation=true and ensure ' +
+                'the BrowserWindow has been granted camera permission.');
+        }
+        try {
+            return await navigator.mediaDevices.getUserMedia({
+                video: DEFAULT_VIDEO_CONSTRAINTS,
+            });
+        } catch (err) {
+            // Surface the failure with a hint about the likely cause —
+            // macOS / Windows prompt the user the first time, and a denial
+            // surfaces as NotAllowedError. Chrome also raises NotReadable
+            // when another app holds the camera.
+            const detail = err && err.name
+                ? ` (${err.name})`
+                : '';
+            const e = new Error(
+                `Failed to acquire default camera${detail}: ` +
+                `${err && err.message ? err.message : err}. ` +
+                'Either grant camera permission and retry, or call ' +
+                'useMediaStream() with your own MediaStream before start().');
+            e.cause = err;
+            throw e;
+        }
+    }
+
+    _releaseOwnedStream() {
+        if (!this._streamOwned || !this._stream) return;
+        // Stop every track so the OS-level camera indicator turns off and
+        // a subsequent getUserMedia call doesn't race against a held
+        // device handle. Audio tracks are stopped too even though we only
+        // requested video — defensive in case constraints widen later.
+        for (const track of this._stream.getTracks()) {
+            try { track.stop(); } catch { /* already stopped */ }
+        }
+        this._stream = null;
+        this._streamOwned = false;
+        this._cameraLocked = false;
+    }
+
+    _tryLockCameraParameters() {
+        if (this._cameraLocked || !this._stream) return;
+        this._cameraLocked = true;  // gate retries even if applyConstraints fails
+
+        // Lock the ORIGINAL track, not the cloned one we feed into
+        // MediaStreamTrackProcessor. The original is what a host-app
+        // preview <video> renders; the clone shares the same underlying
+        // camera source so the lock applied here propagates.
+        const tracks = this._stream.getVideoTracks();
+        const track = tracks[0];
+        if (!track || typeof track.applyConstraints !== 'function') return;
+
+        // Probe capabilities first so we only request modes the hardware
+        // advertises — many built-in webcams don't expose manual exposure
+        // at all, and unsupported constraints are a hard reject. Each
+        // advanced entry is an OR, so the browser picks the first the
+        // device supports.
+        const caps = (typeof track.getCapabilities === 'function')
+            ? track.getCapabilities() || {}
+            : {};
+        const advanced = [];
+        if (Array.isArray(caps.exposureMode) && caps.exposureMode.includes('manual')) {
+            advanced.push({ exposureMode: 'manual' });
+        }
+        if (Array.isArray(caps.whiteBalanceMode) && caps.whiteBalanceMode.includes('manual')) {
+            advanced.push({ whiteBalanceMode: 'manual' });
+        }
+        if (Array.isArray(caps.focusMode) && caps.focusMode.includes('manual')) {
+            advanced.push({ focusMode: 'manual' });
+        }
+        if (advanced.length === 0) return;
+
+        // Fire-and-forget — applyConstraints returns a Promise that
+        // rejects on unsupported constraints. We swallow the rejection
+        // because the graph tolerates auto-modes; the lock is an
+        // accuracy improvement, not a correctness requirement.
+        track.applyConstraints({ advanced }).catch((err) => {
+            console.warn(
+                '[smartspectra/renderer] camera lock applyConstraints rejected, ' +
+                'continuing in auto-mode:', err && err.message ? err.message : err);
+        });
+    }
+
+    async _stopFrameLoop() {
+        this._frameLoopActive = false;
+        if (this._reader) {
+            try { await this._reader.cancel(); } catch { /* already closed */ }
+            this._reader = null;
+        }
+        this._processor = null;
+        if (this._track) {
+            // Stop the cloned track to release the per-track camera reference.
+            // The original stream's track (which the host app may still be
+            // rendering as a preview) is unaffected.
+            try { this._track.stop(); } catch { /* already stopped */ }
+            this._track = null;
+        }
+        if (this._frameLoopPromise) {
+            try { await this._frameLoopPromise; } catch { /* loop errors are logged in-loop */ }
+            this._frameLoopPromise = null;
+        }
+    }
+
+    async _runFrameLoop() {
+        const canvas = new OffscreenCanvas(1, 1);
+        const ctx = canvas.getContext('2d', { willReadFrequently: true });
+        let frameCount = 0;
+
+        try {
+            while (this._frameLoopActive && !this._destroyed) {
+                let read;
+                try {
+                    read = await this._reader.read();
+                } catch (e) {
+                    console.warn('[smartspectra/renderer] reader.read() threw:', e);
+                    break;
+                }
+                if (read.done) break;
+                const vf = read.value;
+                if (!vf) continue;
+
+                try {
+                    if (this._destroyed) break;
+                    if (canvas.width !== vf.codedWidth || canvas.height !== vf.codedHeight) {
+                        canvas.width = vf.codedWidth;
+                        canvas.height = vf.codedHeight;
+                    }
+                    ctx.drawImage(vf, 0, 0);
+                    const imageData = ctx.getImageData(0, 0, vf.codedWidth, vf.codedHeight);
+
+                    // VideoFrame.timestamp is already in microseconds.
+                    // Ratchet to guarantee strict monotonicity across stream
+                    // pauses, re-attaches, and stop()/start() restarts (see
+                    // _lastFrameTs).
+                    let ts = BigInt(vf.timestamp || 0);
+                    if (ts <= this._lastFrameTs) ts = this._lastFrameTs + 1n;
+                    this._lastFrameTs = ts;
+
+                    const ab = imageData.data.buffer;
+                    this._bridge.postMessage({
+                        kind:        'frame',
+                        buffer:      ab,
+                        width:       vf.codedWidth,
+                        height:      vf.codedHeight,
+                        stride:      vf.codedWidth * 4,
+                        pixelFormat: PIXEL_FORMAT_RGBA,
+                        timestampUs: Number(ts),
+                    });
+                    frameCount++;
+                    if (this._diagnostics) {
+                        if (frameCount === 1) {
+                            console.log(
+                                `[smartspectra/renderer] first frame forwarded ` +
+                                `(${vf.codedWidth}x${vf.codedHeight}, ts=${ts}µs)`);
+                        } else if (frameCount % 60 === 0) {
+                            console.log(`[smartspectra/renderer] forwarded ${frameCount} frames`);
+                        }
+                    }
+                } finally {
+                    vf.close();
+                }
+            }
+        } catch (e) {
+            console.error('[smartspectra/renderer] frame loop failed:', e);
+        } finally {
+            if (this._diagnostics) {
+                console.log(
+                    `[smartspectra/renderer] frame loop exited after ${frameCount} frames`);
+            }
+        }
+    }
+
+    _send(message) {
+        const replyId = this._nextReplyId++;
+        const timeoutMs = this._sendTimeoutMs;
+        return new Promise((resolve, reject) => {
+            const onTimeout = () => {
+                // delete() returns false if the ack already arrived and cleared
+                // the entry — guards against rejecting an already-settled call.
+                if (this._pendingAcks.delete(replyId)) {
+                    const err = new Error(
+                        `smartspectra: main-process ack for kind=${message && message.kind} ` +
+                        `timed out after ${timeoutMs}ms`);
+                    err.code = 'SMARTSPECTRA_IPC_TIMEOUT';
+                    reject(err);
+                }
+            };
+            const timer = timeoutMs > 0 ? setTimeout(onTimeout, timeoutMs) : null;
+            const clear = () => { if (timer !== null) clearTimeout(timer); };
+            this._pendingAcks.set(replyId, {
+                resolve: (v) => { clear(); resolve(v); },
+                reject:  (e) => { clear(); reject(e); },
+            });
+            try {
+                this._bridge.postMessage({ ...message, replyId });
+            } catch (e) {
+                clear();
+                this._pendingAcks.delete(replyId);
+                reject(e);
+            }
+        });
+    }
+
+    _rejectPendingAcks(err) {
+        // Snapshot then clear: the wrapped reject() doesn't touch the map, so
+        // clearing after the loop is safe and avoids mutate-while-iterate.
+        const pending = [...this._pendingAcks.values()];
+        this._pendingAcks.clear();
+        for (const { reject } of pending) reject(err);
+    }
+
+    _handleBridgeMessage(msg) {
+        if (!msg || typeof msg.kind !== 'string') return;
+        switch (msg.kind) {
+            case 'processingStatus':
+                this._processingStatus = msg.status | 0;
+                // Arm the startup watchdog when the SDK reports
+                // Starting, and disarm on any subsequent transition.
+                // The watchdog catches startup stalls (model load, network
+                // setup, similar) that otherwise present as a silent
+                // "Starting…" UI forever.
+                if (this._processingStatus === PROCESSING_STATUS_STARTING) {
+                    this._armStartupWatchdog();
+                } else {
+                    this._clearStartupWatchdog();
+                }
+                // Once the graph reports Running the camera ISP has had
+                // long enough to converge — match the mobile SDKs by
+                // locking AE/AWB/focus at the converged values so the
+                // signal processor sees a stable exposure. Best-effort:
+                // capabilities vary across Chromium versions and webcams,
+                // and we treat unsupported as graceful degradation
+                // (auto-modes keep running, the graph still works).
+                if (this._processingStatus === PROCESSING_STATUS_RUNNING) {
+                    this._tryLockCameraParameters();
+                }
+                this._emit('processingStatus', this._processingStatus);
+                return;
+            case 'validationStatus':
+                // First validation packet means the graph reached output —
+                // disarm the watchdog regardless of the code value (an
+                // error code is still progress, the graph isn't wedged).
+                this._clearStartupWatchdog();
+                this._emit('validationStatus', msg.code | 0, Number(msg.timestampUs), msg.hint || '');
+                return;
+            case 'metrics':
+                this._emit('metrics', bufFrom(msg.buffer), Number(msg.timestampUs));
+                return;
+            case 'accumulatedMetrics':
+                this._emit('accumulatedMetrics', bufFrom(msg.buffer), Number(msg.timestampUs));
+                return;
+            case 'insight':
+                this._emit('insight', bufFrom(msg.buffer), msg.requestId | 0);
+                return;
+            case 'frameSentThrough':
+                this._emit('frameSentThrough', !!msg.sent, Number(msg.timestampUs));
+                return;
+            case 'error':
+                this._emit('error', msg.code | 0, msg.message || '', !!msg.retryable);
+                return;
+            case 'ack': {
+                const pending = this._pendingAcks.get(msg.replyId);
+                if (!pending) return;
+                this._pendingAcks.delete(msg.replyId);
+                if (msg.ok) pending.resolve(msg.payload || {});
+                else        pending.reject(makeAckError(msg.error));
+                return;
+            }
+        }
+    }
+
+    _emit(event, ...args) {
+        const cb = this._listeners.get(event);
+        if (!cb) return;
+        try { cb(...args); }
+        catch (e) { console.error(`SmartSpectraSDK: listener for '${event}' threw:`, e); }
+    }
+}
+
+function bufFrom(arrayBuffer) {
+    // Renderer-side: Buffer isn't always available, but Uint8Array is the
+    // closest analogue and what most JS protobuf libraries accept.
+    return new Uint8Array(arrayBuffer);
+}
+
+function makeAckError(err) {
+    const e = new Error(err?.message || 'SmartSpectra IPC failure');
+    e.code      = typeof err?.code === 'number' ? err.code : 0;
+    e.retryable = !!err?.retryable;
+    return e;
+}
+
+// Re-export the public value constants alongside the class so the
+// renderer-side consumer can import everything from a single entry point
+// without bundling the koffi/FFI machinery that lives under the main
+// package entry.
+module.exports = Object.assign(
+    { SmartSpectraSDK },
+    require('../constants'),
+);