@smartspectra/node-sdk 3.3.0-rc.4 → 3.3.0-rc.7

package/README.md

@@ -57,9 +57,14 @@ thread-safe trampolines.
 
 | Requirement | Version |
 | --- | --- |
-| Node.js | >= 18 (Node 20 LTS recommended) |
+| Node.js | >= 20 (Node 24 LTS recommended) |
 | Electron (optional) | >= 28 |
 
+You also need an API key from
+[physiology.presagetech.com](https://physiology.presagetech.com/auth/login). An AI assistant
+connected to the [SmartSpectra MCP Server](../docs/mcp-server.md) can fetch it from your account
+for you.
+
 The native runtime ships in per-platform npm packages pulled in automatically
 as dependencies — no install script and no system libraries to install.
 
@@ -105,6 +110,10 @@ the missing package.
 
 ## Headless Node Quickstart
 
+> The snippets below are ES modules (`import` + top-level `await`) — save them as `.mjs`, or
+> set `"type": "module"` in your `package.json`. In a CommonJS project, use `require()` and
+> wrap the `await` calls in an `async` function.
+
 ```ts
 import {
   SmartSpectraSDK, PixelFormat, FrameTransform, ProcessingStatus,

package/js/constants.js

@@ -48,6 +48,7 @@ const ValidationCode = Object.freeze({
     kNoFaceFound:        1,
     kMultipleFacesFound: 2,
     kFaceNotCentered:    3,
+    /** @deprecated Use kFaceTooClose / kFaceTooFar instead. */
     kFaceSizeOutOfRange: 4,
     kTooDark:            5,
     kTooBright:          6,
@@ -55,6 +56,11 @@ const ValidationCode = Object.freeze({
     kCameraTuning:       10,
     kFrameRateTooLow:    11,
     kExcessiveMotion:    12,
+    kFaceTooClose:       13,
+    kFaceTooFar:         14,
+    kFaceTooHigh:        15,
+    kFaceTooLow:         16,
+    kFaceNotForward:       17,
 });
 
 const SmartSpectraErrorCode = Object.freeze({

package/js/ffi.js

@@ -13,6 +13,9 @@
 
 'use strict';
 
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
 const koffi = require('koffi');
 const { resolveNativeLibrary } = require('./resolve-native');
 
@@ -444,21 +447,38 @@ class Session {
                 () => this._teardownNative(),
                 () => this._teardownNative());
         } else {
-            this._teardownNative();
-            this._teardownPromise = Promise.resolve();
+            this._teardownPromise = this._teardownNative();
         }
         return this._teardownPromise;
     }
 
+    // Returns a promise that resolves once native teardown (including any
+    // worker-thread joins inside session_destroy) has completed.
     _teardownNative() {
-        if (this._sess === null) return;
-        // stop → wait → destroy → unregister. session_destroy joins worker
-        // threads, so no SDK thread can call our trampolines after it returns.
+        if (this._sess === null) return Promise.resolve();
+        // stop → wait → destroy → unregister. session_destroy joins every
+        // worker thread SpawnWorker ever started for this session — including
+        // one that's mid-flight relaying an onError/onStatus callback to JS
+        // (e.g. an async graph failure). That relay can only complete once
+        // the JS event loop is free to service it, so running session_destroy
+        // synchronously here would deadlock: this call IS the JS thread, and
+        // it would be blocked joining a thread that's blocked waiting on this
+        // same thread's event loop. Run it on a koffi worker thread instead —
+        // the same reason stopAsync() runs session_stop off-thread above —
+        // so the event loop stays free no matter what a worker is mid-relay
+        // of. _releaseThunks() only runs after the callback fires, matching
+        // the original synchronous ordering (unregister only after the joins
+        // that guarantee no SDK thread can still call our trampolines).
         sessionStop(this._sess);
         sessionWait(this._sess, 0);
-        sessionDestroy(this._sess);
+        const sess = this._sess;
         this._sess = null;
-        this._releaseThunks();
+        return new Promise((resolve) => {
+            sessionDestroy.async(sess, () => {
+                this._releaseThunks();
+                resolve();
+            });
+        });
     }
 
     // ---------- internal ----------------------------------------------------
@@ -490,9 +510,11 @@ function makeFfiError(err) {
     return e;
 }
 
-// Internal one-time SDK initialization. Called by the Electron main-process
-// glue in `@smartspectra/node-sdk/main`. Not part of the package's public
-// exports map — host apps don't reach for it.
+// Internal one-time SDK initialization. Called directly by the Electron
+// main-process glue in `@smartspectra/node-sdk/main` (which namespaces its
+// own cache directory under app.getPath('cache')). Not part of the package's
+// public exports map — host apps don't reach for it; use ensurePreconfigured()
+// below for the plain-Node default instead.
 function preconfigure(sdkDirectory, deviceId) {
     if (typeof sdkDirectory !== 'string' || sdkDirectory.length === 0) {
         throw new TypeError('preconfigure: directory must be a non-empty string');
@@ -502,7 +524,48 @@ function preconfigure(sdkDirectory, deviceId) {
     if (rc !== 0) throw makeFfiError(err);
 }
 
+// Per-OS writable cache directory, used as the default when nothing else
+// (e.g. Electron's app.getPath('cache')) has already resolved one.
+function defaultSdkDirectory() {
+    const base = process.platform === 'darwin'
+        ? path.join(os.homedir(), 'Library', 'Caches')
+        : process.platform === 'win32'
+            ? (process.env.LOCALAPPDATA || path.join(os.homedir(), 'AppData', 'Local'))
+            : (process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache'));
+    return path.join(base, 'SmartSpectraSDK');
+}
+
+let autoPreconfigureAttempted = false;
+
+// Idempotent, best-effort preconfigure for hosts that never call preconfigure()
+// themselves. ARTERIAL_PRESSURE_TRACE, EDA_TRACE, and micromotion metrics need
+// the device-key cache directory Preconfigure() sets up (smartspectra.h); without
+// it their encrypted-model load fails downstream and Session.start*() throws —
+// only Electron's main-process glue (js/main/index.js) called this previously,
+// so a plain Node host requesting one of those metrics had no way to succeed.
+// Runs once per process; failures are logged, not thrown, so metrics that don't
+// need EMD still work. Called from SmartSpectraSDK._ensureSession() so every
+// entry point — plain Node or Electron — gets it before a session can start;
+// Preconfigure() itself only resolves the directory/device-identity once, so a
+// prior, more specific call (e.g. Electron's app-namespaced one) always wins.
+function ensurePreconfigured() {
+    if (autoPreconfigureAttempted) return;
+    autoPreconfigureAttempted = true;
+    const sdkDirectory = defaultSdkDirectory();
+    try {
+        // nosemgrep: detect-non-literal-fs-filename - safe: derived from OS-standard cache path env vars / os.homedir(), not untrusted input.
+        fs.mkdirSync(sdkDirectory, { recursive: true, mode: 0o700 });
+        preconfigure(sdkDirectory);
+    } catch (err) {
+        console.error(
+            `SmartSpectra: automatic preconfigure failed (${err.message || err}). ` +
+            'Arterial pressure, EDA, and micromotion metrics will not be available ' +
+            `until preconfigure() succeeds for ${sdkDirectory}; other metrics still work.`);
+    }
+}
+
 module.exports = {
     Session,
     preconfigure,
+    ensurePreconfigured,
 };

package/js/index.d.ts

@@ -46,6 +46,7 @@ export declare const ValidationCode: {
     readonly kNoFaceFound:        1;
     readonly kMultipleFacesFound: 2;
     readonly kFaceNotCentered:    3;
+    /** @deprecated Use kFaceTooClose / kFaceTooFar instead. */
     readonly kFaceSizeOutOfRange: 4;
     readonly kTooDark:            5;
     readonly kTooBright:          6;
@@ -53,6 +54,11 @@ export declare const ValidationCode: {
     readonly kCameraTuning:       10;
     readonly kFrameRateTooLow:    11;
     readonly kExcessiveMotion:    12;
+    readonly kFaceTooClose:       13;
+    readonly kFaceTooFar:         14;
+    readonly kFaceTooHigh:        15;
+    readonly kFaceTooLow:         16;
+    readonly kFaceNotForward:       17;
 };
 export type ValidationCodeValue = typeof ValidationCode[keyof typeof ValidationCode];
 

package/js/renderer/index.js

@@ -15,6 +15,8 @@
 
 'use strict';
 
+const { FrameTimestampAnchor } = require('./timestamp');
+
 const SUPPORTED_EVENTS = new Set([
     'processingStatus',
     'validationStatus',
@@ -112,13 +114,14 @@ class SmartSpectraSDK {
         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;
+        // Epoch-anchor + monotonic-ratchet for VideoFrame.timestamp. 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. See
+        // ./timestamp.js for why the epoch anchor is needed at all.
+        this._frameTimestamps  = new FrameTimestampAnchor();
         // 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;
@@ -500,13 +503,11 @@ class SmartSpectraSDK {
                     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;
+                    // VideoFrame.timestamp is already in microseconds, but in
+                    // the frame's own media-clock domain — anchor it to the
+                    // Unix epoch and ratchet it monotonic (see
+                    // ./timestamp.js).
+                    const ts = this._frameTimestamps.next(vf.timestamp);
 
                     const ab = imageData.data.buffer;
                     this._bridge.postMessage({

package/js/renderer/timestamp.js

@@ -0,0 +1,56 @@
+// js/renderer/timestamp.js
+// Copyright (C) 2026 Presage Technologies, Inc.
+//
+// SPDX-License-Identifier: LicenseRef-Proprietary
+//
+// Anchors a WebCodecs VideoFrame.timestamp (relative to an unspecified
+// internal media clock, NOT the Unix epoch) to wall-clock epoch
+// microseconds, then ratchets it to guarantee strict monotonicity across
+// stream pauses, re-attaches, and stop()/start() restarts. Extracted from
+// the renderer's frame loop into its own module so the anchor + ratchet
+// math is unit-testable in plain Node — renderer/index.js itself needs
+// OffscreenCanvas/MediaStreamTrackProcessor, which don't exist there.
+//
+// Android/iOS/Linux each apply an equivalent one-time boot/mach-to-epoch
+// offset before a camera frame's timestamp reaches the graph
+// (SmartSpectraVitalsProcessor.kt, avfoundation_camera_source.mm,
+// v4l2_camera_source.cc); this is the Electron/WebCodecs binding's
+// counterpart, so Metrics.timestamp is wall-clock-comparable across every
+// binding instead of only self-consistent within one Electron session.
+
+'use strict';
+
+class FrameTimestampAnchor {
+    constructor() {
+        // Set from the first frame passed to next(); null means "not yet
+        // anchored". Persists for the anchor's lifetime (kept on the
+        // instance, not recomputed per stop()/start(), the same reasoning
+        // as _lastFrameTs below — VideoFrame.timestamp's clock domain is
+        // page-navigation-relative, not per-stream).
+        this._epochOffsetUs = null;
+        // Last timestamp handed out, for the monotonic ratchet.
+        this._lastFrameTs = 0n;
+    }
+
+    /**
+     * @param {number|bigint} rawTimestampUs VideoFrame.timestamp — already
+     *   microseconds, but in its own media-clock domain.
+     * @param {number} [nowMs] Wall-clock epoch milliseconds at the moment of
+     *   the first call. Defaults to Date.now(); overridable so callers (and
+     *   tests) can pin a deterministic anchor.
+     * @returns {bigint} Epoch microseconds, strictly greater than every
+     *   previous value returned by this instance.
+     */
+    next(rawTimestampUs, nowMs = Date.now()) {
+        const raw = BigInt(rawTimestampUs || 0);
+        if (this._epochOffsetUs === null) {
+            this._epochOffsetUs = BigInt(nowMs) * 1000n - raw;
+        }
+        let ts = raw + this._epochOffsetUs;
+        if (ts <= this._lastFrameTs) ts = this._lastFrameTs + 1n;
+        this._lastFrameTs = ts;
+        return ts;
+    }
+}
+
+module.exports = { FrameTimestampAnchor };

package/js/smartspectra.js

@@ -5,7 +5,7 @@
 
 'use strict';
 
-const { Session } = require('./ffi');
+const { Session, ensurePreconfigured } = require('./ffi');
 const {
     ProcessingStatus,
     SmartSpectraLogLevel,
@@ -250,6 +250,10 @@ class SmartSpectraSDK {
 
     _ensureSession() {
         if (this._session) return;
+        // ARTERIAL_PRESSURE_TRACE, EDA_TRACE, and micromotion metrics need the
+        // EMD cache directory Preconfigure() sets up before the graph starts;
+        // best-effort and idempotent, so plain metrics work even if it fails.
+        ensurePreconfigured();
         // Listeners may be added/replaced after start(), so the lookup
         // happens at emit time rather than capture time.
         this._session = new Session(this._options, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@smartspectra/node-sdk",
-  "version": "3.3.0-rc.4",
+  "version": "3.3.0-rc.7",
   "description": "Node.js (Electron) FFI binding for SmartSpectra vitals measurement",
   "author": "Presage Technologies, Inc.",
   "license": "SEE LICENSE IN LICENSE",
@@ -40,7 +40,7 @@
   "scripts": {
     "prepare": "node scripts/gen-proto.cjs",
     "build:proto": "node scripts/gen-proto.cjs",
-    "test": "node test/log-level-pin.js && node test/smoke.js",
+    "test": "node --test test/log-level-pin.js test/renderer-timestamp.js test/smoke.js",
     "test:models-allowlist": "node test/models-allowlist.js"
   },
   "keywords": [
@@ -64,23 +64,23 @@
     "registry": "https://registry.npmjs.org/"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=20.0.0"
   },
   "_nativeRuntime_doc": "Per-platform native packages (@smartspectra/node-sdk-<plat>-<arch>) are injected into dependencies at publish time (absent here so source installs don't fetch them). Why hard deps, not optionalDependencies: see js/resolve-native.js.",
   "dependencies": {
     "koffi": "^2.10.0",
-    "protobufjs": "^7.5.0",
-    "@smartspectra/node-sdk-linux-x64": "3.3.0-rc.4",
-    "@smartspectra/node-sdk-linux-arm64": "3.3.0-rc.4",
-    "@smartspectra/node-sdk-darwin-arm64": "3.3.0-rc.4",
-    "@smartspectra/node-sdk-win32-x64": "3.3.0-rc.4"
+    "protobufjs": "^7.6.5",
+    "@smartspectra/node-sdk-linux-x64": "3.3.0-rc.7",
+    "@smartspectra/node-sdk-linux-arm64": "3.3.0-rc.7",
+    "@smartspectra/node-sdk-darwin-arm64": "3.3.0-rc.7",
+    "@smartspectra/node-sdk-win32-x64": "3.3.0-rc.7"
   },
   "devDependencies": {
-    "@types/node": "^20.0.0",
+    "@types/node": "^24.0.0",
     "protobufjs-cli": "^1.1.3"
   },
-  "_overrides_doc": "tmp is pulled in transitively (protobufjs-cli → tmp) as a build-only devDependency; it is never a runtime dependency and is not shipped to consumers (the published tarball ships js/ + prebuilds only, no node_modules). Pinned to an exact version (not a >= range) to clear GHSA-ph9p-34f9-6g65 (path traversal, affects tmp <0.2.6) AND to keep installs deterministic — an open range would let a future install pull a brand-new, not-yet-vetted release. Bump deliberately. Drop this once protobufjs-cli ships a release whose tmp range is already >=0.2.6.",
+  "_overrides_doc": "tmp is pulled in transitively (protobufjs-cli → tmp) as a build-only devDependency; it is never a runtime dependency and is not shipped to consumers (the published tarball ships js/ + prebuilds only, no node_modules). Pinned to an exact version (not a >= range) to clear GHSA-ph9p-34f9-6g65 (path traversal, affects tmp <0.2.6) and GHSA-7c78-jf6q-g5cm (type-confusion bypass of the 0.2.6 _assertPath guard, affects tmp >=0.2.6) AND to keep installs deterministic — an open range would let a future install pull a brand-new, not-yet-vetted release. Bump deliberately. Drop this once protobufjs-cli ships a release whose tmp range is already >=0.2.7.",
   "overrides": {
-    "tmp": "0.2.6"
+    "tmp": "0.2.7"
   }
 }