@pose-tracker/react-native-pose-estimation-light 0.1.0

package/lib/diagnostics/logReport.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Human-readable diagnostic dumps for Metro / adb logcat.
+ * Designed so a host can paste the terminal output into a support chat.
+ */
+import type { AccelerationDiagnostics } from '../types/acceleration';
+/** Always-on console sink — shows up in `npx expo start` / Metro. */
+export declare function defaultDiagnosticLogger(message: string): void;
+export declare function logPlatformBanner(): void;
+/**
+ * Multi-line dump of the warm-up / acceleration verdict. Call after
+ * preload()/warmup() so Android CPU-fallback reasons are visible in Metro.
+ */
+export declare function logAccelerationReport(diag: AccelerationDiagnostics | null, extra?: Record<string, unknown>): void;
+/** Throttled FPS / latency line for the camera loop (Metro-friendly). */
+export declare function logFrameStats(stats: {
+    fps: number;
+    medianLatencyMs: number | null;
+    backend: string;
+    acceleration: string;
+    frames: number;
+    keypointsAbove03: number;
+    meanScore: number;
+}): void;

package/lib/diagnostics/logReport.js

@@ -0,0 +1,102 @@
+"use strict";
+/**
+ * Human-readable diagnostic dumps for Metro / adb logcat.
+ * Designed so a host can paste the terminal output into a support chat.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultDiagnosticLogger = defaultDiagnosticLogger;
+exports.logPlatformBanner = logPlatformBanner;
+exports.logAccelerationReport = logAccelerationReport;
+exports.logFrameStats = logFrameStats;
+const react_native_1 = require("react-native");
+const PREFIX = '[PoseTracker]';
+/** Always-on console sink — shows up in `npx expo start` / Metro. */
+function defaultDiagnosticLogger(message) {
+    // Keep a single prefix so hosts can filter: `npx expo start | grep PoseTracker`
+    console.log(PREFIX, message.startsWith('[posetracker]') ? message : message);
+}
+function logPlatformBanner() {
+    console.log(PREFIX, `platform=${react_native_1.Platform.OS} version=${String(react_native_1.Platform.Version)} ` +
+        `constants=${JSON.stringify({
+            isPad: react_native_1.Platform.isPad ?? null,
+            isTV: react_native_1.Platform.isTV,
+        })}`);
+}
+/**
+ * Multi-line dump of the warm-up / acceleration verdict. Call after
+ * preload()/warmup() so Android CPU-fallback reasons are visible in Metro.
+ */
+function logAccelerationReport(diag, extra) {
+    const lines = [];
+    lines.push('======== ACCELERATION REPORT ========');
+    lines.push(`platform: ${react_native_1.Platform.OS} ${String(react_native_1.Platform.Version)}`);
+    if (!diag) {
+        lines.push('diagnostics: null (warm-up not finished)');
+    }
+    else {
+        lines.push(`state: ${diag.state}`);
+        lines.push(`runtime: ${diag.runtime ?? 'webview'}`);
+        lines.push(`tfjsBackend: ${diag.tfjsBackend ?? 'n/a'}`);
+        if (diag.delegate) {
+            lines.push(`delegate: ${diag.delegate}`);
+        }
+        lines.push(`medianInferenceMs: ${diag.medianInferenceMs != null ? diag.medianInferenceMs.toFixed(1) : 'n/a'}`);
+        lines.push(`warmUpRunsMs: [${diag.inferenceTimesMs.map((ms) => Math.round(ms)).join(', ')}]`);
+        lines.push(`maxAcceptableInferenceMs: ${diag.maxAcceptableInferenceMs}`);
+        lines.push(`contextLossCount: ${diag.contextLossCount}`);
+        const caps = diag.capabilities;
+        if (caps) {
+            lines.push(`GL.renderer: ${caps.renderer ?? 'n/a'}`);
+            lines.push(`GL.vendor: ${caps.vendor ?? 'n/a'}`);
+            lines.push(`GL.version: ${caps.glVersion ?? 'n/a'}`);
+            lines.push(`GL.maxTextureSize: ${caps.maxTextureSize ?? 'n/a'}`);
+            lines.push(`GL.extensions(shimmed=${caps.extensionQueriesShimmed}): ` +
+                `float=${caps.textureFloat} halfFloat=${caps.textureHalfFloat} ` +
+                `colorBufferFloat=${caps.colorBufferFloat} colorBufferHalfFloat=${caps.colorBufferHalfFloat}`);
+        }
+        else {
+            lines.push('GL.capabilities: null (no GL context — typically means tfjs backend=cpu)');
+        }
+        lines.push(`tfjsFlags: ${JSON.stringify(diag.flags)}`);
+        if (diag.reasons.length === 0) {
+            lines.push('reasons: (none)');
+        }
+        else {
+            lines.push('reasons:');
+            for (const reason of diag.reasons) {
+                lines.push(`  - ${reason}`);
+            }
+        }
+        if (diag.state === 'gpu' && diag.runtime === 'vision') {
+            lines.push('INTERPRETATION: Apple Vision (VNDetectHumanBodyPoseRequest) — Neural Engine / GPU. Up to 19 joints.');
+        }
+        else if (diag.runtime === 'webview' || diag.runtime === undefined) {
+            lines.push('INTERPRETATION: offline WebView MoveNet Lightning (ANGLE WebGL, bundled model) — ' +
+                'same stack as the PoseTracker WebView product. Expected real-time on both platforms.');
+        }
+        else if (diag.state === 'cpu-fallback') {
+            lines.push('INTERPRETATION: non-accelerated path (cpu-fallback). Expect low FPS.');
+        }
+        else if (diag.state === 'gpu') {
+            lines.push('INTERPRETATION: GPU path accepted by health check.');
+        }
+        else if (diag.state === 'unavailable') {
+            lines.push('INTERPRETATION: no usable backend — model could not run.');
+        }
+    }
+    if (extra) {
+        lines.push(`extra: ${JSON.stringify(extra)}`);
+    }
+    lines.push('======== END ACCELERATION REPORT ========');
+    for (const line of lines) {
+        console.log(PREFIX, line);
+    }
+}
+/** Throttled FPS / latency line for the camera loop (Metro-friendly). */
+function logFrameStats(stats) {
+    console.log(PREFIX, `FRAMESTATS fps=${stats.fps} ` +
+        `medianMs=${stats.medianLatencyMs != null ? Math.round(stats.medianLatencyMs) : 'n/a'} ` +
+        `backend=${stats.backend} acceleration=${stats.acceleration} ` +
+        `frames=${stats.frames} kp≥0.3=${stats.keypointsAbove03}/17 ` +
+        `meanScore=${stats.meanScore.toFixed(2)}`);
+}

package/lib/engine/EngineLoader.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Remote engine distribution (Sency-style model distribution, applied to the
+ * business-logic bundle):
+ *
+ * 1. The handshake manifest carries a signed, token-gated URL of a versioned
+ *    JS engine bundle plus its SHA-256 digest.
+ * 2. The bundle is cached on the local filesystem, sealed with a secret
+ *    derived from the API token (see `cache/obfuscate.ts`): a device without
+ *    the key cannot read the cached business logic. Integrity is re-validated
+ *    against the manifest digest on every load (corrupted/partial downloads
+ *    are purged, like Sency's `TFL3` magic check on cached TFLite files).
+ * 3. A crash-loop guard (analog of Sency's `TfliteRuntimeGuard`
+ *    PROBING→PASSED/FAILED state machine) marks the bundle as "probing"
+ *    before evaluation; if the app died while probing, the next launch
+ *    skips that exact bundle.
+ * 4. NO business logic ships in the npm package: when no engine can be
+ *    obtained (no network, no valid cache, crash-looping bundle), `load`
+ *    returns null and the SDK runs in keypoints-only mode.
+ */
+import type { EngineBundleDescriptor } from '../types/manifest';
+import type { PoseTrackerEngine } from './types';
+export interface FileStore {
+    read(key: string): Promise<string | null>;
+    write(key: string, contents: string): Promise<void>;
+    remove(key: string): Promise<void>;
+}
+export interface KeyValueStore {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<void>;
+    removeItem(key: string): Promise<void>;
+}
+/** Filesystem-backed store using expo-file-system (optional peer dependency). */
+export declare function createExpoFileStore(dirName?: string): FileStore | null;
+/** Filesystem-backed store using react-native-fs (bare RN, optional). */
+export declare function createRnfsFileStore(dirName: string): FileStore | null;
+/** Filesystem-backed store using react-native-blob-util (bare RN, optional). */
+export declare function createBlobUtilFileStore(dirName: string): FileStore | null;
+/**
+ * In-memory store — last-resort fallback when no filesystem module is
+ * installed (bare RN without expo-file-system / react-native-fs /
+ * react-native-blob-util). The SDK stays fully functional but nothing
+ * persists across app launches: every cold start needs the network again.
+ */
+export declare function createMemoryFileStore(): FileStore;
+/**
+ * Best available persistent file store for the host app:
+ * expo-file-system (Expo / Expo Go) → react-native-fs (bare RN) →
+ * react-native-blob-util (bare RN). Returns null when none is installed —
+ * callers may fall back to {@link createMemoryFileStore}.
+ */
+export declare function createNativeFileStore(dirName: string): FileStore | null;
+/** AsyncStorage-backed store (already a peer dep via tfjs-react-native). */
+export declare function createAsyncKeyValueStore(): KeyValueStore | null;
+export interface EngineLoadResult {
+    engine: PoseTrackerEngine;
+    source: 'remote-cache' | 'remote-download';
+}
+export interface EngineLoaderOptions {
+    fileStore?: FileStore | null;
+    keyValueStore?: KeyValueStore | null;
+    /** Injectable for tests. */
+    fetchFn?: typeof fetch;
+    /** Diagnostic trail (Metro / logcat) — why a load returned null. */
+    onDiagnostic?: (message: string) => void;
+}
+export declare class EngineLoader {
+    private readonly files;
+    private readonly kv;
+    private readonly fetchFn;
+    private readonly onDiagnostic;
+    /** Last load failure detail (surfaced by the client error event). */
+    lastError: string | null;
+    constructor(options?: EngineLoaderOptions);
+    /**
+     * Clear a crash-guard mark so the next {@link load} can retry this bundle
+     * (e.g. after the host taps "Test key").
+     */
+    clearGuard(descriptor: EngineBundleDescriptor | null): Promise<void>;
+    /**
+     * Load the engine described by the manifest. Returns null when no engine
+     * can be obtained (the caller then runs keypoints-only).
+     *
+     * @param cacheSecret secret derived from the API token, used to seal/open
+     *   the cached bundle (`deriveCacheSecret`).
+     */
+    load(descriptor: EngineBundleDescriptor | null, cacheSecret: string, options?: {
+        forceRetry?: boolean;
+    }): Promise<EngineLoadResult | null>;
+    /**
+     * Evaluate an engine bundle (CommonJS-style: the bundle assigns
+     * `module.exports.createEngine`). Wrapped by the crash-loop guard.
+     * Hermes and JSC both support runtime evaluation via `new Function`.
+     */
+    private evaluate;
+}

package/lib/engine/EngineLoader.js

@@ -0,0 +1,347 @@
+"use strict";
+/**
+ * Remote engine distribution (Sency-style model distribution, applied to the
+ * business-logic bundle):
+ *
+ * 1. The handshake manifest carries a signed, token-gated URL of a versioned
+ *    JS engine bundle plus its SHA-256 digest.
+ * 2. The bundle is cached on the local filesystem, sealed with a secret
+ *    derived from the API token (see `cache/obfuscate.ts`): a device without
+ *    the key cannot read the cached business logic. Integrity is re-validated
+ *    against the manifest digest on every load (corrupted/partial downloads
+ *    are purged, like Sency's `TFL3` magic check on cached TFLite files).
+ * 3. A crash-loop guard (analog of Sency's `TfliteRuntimeGuard`
+ *    PROBING→PASSED/FAILED state machine) marks the bundle as "probing"
+ *    before evaluation; if the app died while probing, the next launch
+ *    skips that exact bundle.
+ * 4. NO business logic ships in the npm package: when no engine can be
+ *    obtained (no network, no valid cache, crash-looping bundle), `load`
+ *    returns null and the SDK runs in keypoints-only mode.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EngineLoader = void 0;
+exports.createExpoFileStore = createExpoFileStore;
+exports.createRnfsFileStore = createRnfsFileStore;
+exports.createBlobUtilFileStore = createBlobUtilFileStore;
+exports.createMemoryFileStore = createMemoryFileStore;
+exports.createNativeFileStore = createNativeFileStore;
+exports.createAsyncKeyValueStore = createAsyncKeyValueStore;
+const js_sha256_1 = require("js-sha256");
+const obfuscate_1 = require("../cache/obfuscate");
+function asExpoFileSystemLegacy(mod) {
+    const raw = mod;
+    const fs = (raw?.cacheDirectory != null ? raw : raw?.default);
+    if (fs &&
+        typeof fs.cacheDirectory === 'string' &&
+        typeof fs.readAsStringAsync === 'function' &&
+        typeof fs.writeAsStringAsync === 'function' &&
+        typeof fs.deleteAsync === 'function' &&
+        typeof fs.makeDirectoryAsync === 'function') {
+        return fs;
+    }
+    return null;
+}
+/**
+ * Resolve the Expo FS API that still exposes the classic helpers.
+ * Expo SDK 54+ moved them to `expo-file-system/legacy` — the root export's
+ * `readAsStringAsync` / `writeAsStringAsync` now THROW at runtime.
+ *
+ * Requires MUST be static string literals (Metro rejects `require(id)`).
+ */
+function requireExpoFileSystemLegacy() {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const legacy = asExpoFileSystemLegacy(require('expo-file-system/legacy'));
+        if (legacy)
+            return legacy;
+    }
+    catch {
+        /* not installed / old expo-file-system without /legacy */
+    }
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const root = asExpoFileSystemLegacy(require('expo-file-system'));
+        if (root)
+            return root;
+    }
+    catch {
+        /* expo-file-system not installed */
+    }
+    return null;
+}
+/** Filesystem-backed store using expo-file-system (optional peer dependency). */
+function createExpoFileStore(dirName = 'posetracker-engine') {
+    const FileSystem = requireExpoFileSystemLegacy();
+    if (!FileSystem || !FileSystem.cacheDirectory) {
+        return null;
+    }
+    const dir = `${FileSystem.cacheDirectory}${dirName}/`;
+    const ensureDir = FileSystem.makeDirectoryAsync(dir, { intermediates: true }).catch(() => { });
+    return {
+        async read(key) {
+            try {
+                return await FileSystem.readAsStringAsync(dir + key);
+            }
+            catch {
+                return null;
+            }
+        },
+        async write(key, contents) {
+            await ensureDir;
+            await FileSystem.writeAsStringAsync(dir + key, contents);
+        },
+        async remove(key) {
+            await FileSystem.deleteAsync(dir + key, { idempotent: true });
+        },
+    };
+}
+/** Filesystem-backed store using react-native-fs (bare RN, optional). */
+function createRnfsFileStore(dirName) {
+    let RNFS;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        RNFS = require('react-native-fs');
+        if (!RNFS || typeof RNFS.CachesDirectoryPath !== 'string')
+            return null;
+    }
+    catch {
+        return null;
+    }
+    const dir = `${RNFS.CachesDirectoryPath}/${dirName}`;
+    const ensureDir = RNFS.mkdir(dir).catch(() => { });
+    return {
+        async read(key) {
+            try {
+                return await RNFS.readFile(`${dir}/${key}`, 'utf8');
+            }
+            catch {
+                return null;
+            }
+        },
+        async write(key, contents) {
+            await ensureDir;
+            await RNFS.writeFile(`${dir}/${key}`, contents, 'utf8');
+        },
+        async remove(key) {
+            await RNFS.unlink(`${dir}/${key}`).catch(() => { });
+        },
+    };
+}
+/** Filesystem-backed store using react-native-blob-util (bare RN, optional). */
+function createBlobUtilFileStore(dirName) {
+    let fs;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const mod = require('react-native-blob-util');
+        fs = (mod.default ?? mod).fs;
+        if (!fs || !fs.dirs || typeof fs.dirs.CacheDir !== 'string')
+            return null;
+    }
+    catch {
+        return null;
+    }
+    const dir = `${fs.dirs.CacheDir}/${dirName}`;
+    const ensureDir = fs.mkdir(dir).catch(() => { });
+    return {
+        async read(key) {
+            try {
+                return await fs.readFile(`${dir}/${key}`, 'utf8');
+            }
+            catch {
+                return null;
+            }
+        },
+        async write(key, contents) {
+            await ensureDir;
+            await fs.writeFile(`${dir}/${key}`, contents, 'utf8');
+        },
+        async remove(key) {
+            await fs.unlink(`${dir}/${key}`).catch(() => { });
+        },
+    };
+}
+/**
+ * In-memory store — last-resort fallback when no filesystem module is
+ * installed (bare RN without expo-file-system / react-native-fs /
+ * react-native-blob-util). The SDK stays fully functional but nothing
+ * persists across app launches: every cold start needs the network again.
+ */
+function createMemoryFileStore() {
+    const entries = new Map();
+    return {
+        async read(key) {
+            return entries.has(key) ? entries.get(key) : null;
+        },
+        async write(key, contents) {
+            entries.set(key, contents);
+        },
+        async remove(key) {
+            entries.delete(key);
+        },
+    };
+}
+/**
+ * Best available persistent file store for the host app:
+ * expo-file-system (Expo / Expo Go) → react-native-fs (bare RN) →
+ * react-native-blob-util (bare RN). Returns null when none is installed —
+ * callers may fall back to {@link createMemoryFileStore}.
+ */
+function createNativeFileStore(dirName) {
+    return (createExpoFileStore(dirName) ??
+        createRnfsFileStore(dirName) ??
+        createBlobUtilFileStore(dirName));
+}
+/** AsyncStorage-backed store (already a peer dep via tfjs-react-native). */
+function createAsyncKeyValueStore() {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const AsyncStorage = require('@react-native-async-storage/async-storage').default;
+        return AsyncStorage;
+    }
+    catch {
+        return null;
+    }
+}
+// ---------------------------------------------------------------------------
+// Loader
+// ---------------------------------------------------------------------------
+const GUARD_KEY_PREFIX = 'posetracker.engine.guard.';
+class EngineLoader {
+    constructor(options = {}) {
+        /** Last load failure detail (surfaced by the client error event). */
+        this.lastError = null;
+        this.files =
+            options.fileStore !== undefined
+                ? options.fileStore
+                : createNativeFileStore('posetracker-engine');
+        this.kv =
+            options.keyValueStore !== undefined ? options.keyValueStore : createAsyncKeyValueStore();
+        this.fetchFn = options.fetchFn ?? fetch;
+        this.onDiagnostic = options.onDiagnostic;
+        this.onDiagnostic?.(`[posetracker] EngineLoader fileStore=${this.files ? 'native' : 'none'} ` +
+            `kv=${this.kv ? 'async-storage' : 'none'}`);
+    }
+    /**
+     * Clear a crash-guard mark so the next {@link load} can retry this bundle
+     * (e.g. after the host taps "Test key").
+     */
+    async clearGuard(descriptor) {
+        if (!descriptor || !this.kv)
+            return;
+        const guardKey = `${GUARD_KEY_PREFIX}${descriptor.version}.${descriptor.sha256}`;
+        await this.kv.removeItem(guardKey).catch(() => { });
+    }
+    /**
+     * Load the engine described by the manifest. Returns null when no engine
+     * can be obtained (the caller then runs keypoints-only).
+     *
+     * @param cacheSecret secret derived from the API token, used to seal/open
+     *   the cached bundle (`deriveCacheSecret`).
+     */
+    async load(descriptor, cacheSecret, options) {
+        this.lastError = null;
+        if (!descriptor) {
+            this.lastError = 'manifest has no engine descriptor';
+            return null;
+        }
+        const guardKey = `${GUARD_KEY_PREFIX}${descriptor.version}.${descriptor.sha256}`;
+        if (options?.forceRetry) {
+            await this.kv?.removeItem(guardKey).catch(() => { });
+        }
+        const guardState = (await this.kv?.getItem(guardKey));
+        if (guardState === 'probing' || guardState === 'failed') {
+            // 'probing' left over = the app crashed while evaluating this exact
+            // bundle on a previous launch. Do not retry it automatically.
+            await this.kv?.setItem(guardKey, 'failed');
+            this.lastError =
+                `engine crash-guard blocked version=${descriptor.version} ` +
+                    `(state=${guardState}) — tap Test key to force retry`;
+            this.onDiagnostic?.(`[posetracker] ${this.lastError}`);
+            return null;
+        }
+        const cacheKey = `engine-${descriptor.version}.sealed`;
+        // 1. Cache hit: unseal + integrity check.
+        const sealed = await this.files?.read(cacheKey);
+        if (sealed !== null && sealed !== undefined) {
+            const code = (0, obfuscate_1.openString)(sealed, cacheSecret);
+            if (code !== null && (0, js_sha256_1.sha256)(code) === descriptor.sha256) {
+                const engine = await this.evaluate(code, guardKey);
+                if (engine) {
+                    this.onDiagnostic?.(`[posetracker] engine loaded from cache version=${descriptor.version}`);
+                    return { engine, source: 'remote-cache' };
+                }
+            }
+            else {
+                // Corrupted, partial, or sealed with another token: purge it.
+                this.onDiagnostic?.(`[posetracker] engine cache purged (unseal/integrity mismatch) key=${cacheKey}`);
+                await this.files?.remove(cacheKey);
+            }
+        }
+        // 2. Download → integrity → evaluate. Cache write is best-effort AFTER
+        //    evaluate so a broken FS API (Expo 54 root export) cannot block the
+        //    engine when the download itself succeeded.
+        try {
+            this.onDiagnostic?.(`[posetracker] downloading engine version=${descriptor.version}…`);
+            const response = await this.fetchFn(descriptor.signedUrl);
+            if (!response.ok) {
+                throw new Error(`HTTP ${response.status}`);
+            }
+            const code = await response.text();
+            const digest = (0, js_sha256_1.sha256)(code);
+            if (digest !== descriptor.sha256) {
+                throw new Error(`integrity check failed (got ${digest.slice(0, 12)}… expected ${descriptor.sha256.slice(0, 12)}…, ` +
+                    `bytes=${code.length})`);
+            }
+            const engine = await this.evaluate(code, guardKey);
+            if (engine) {
+                try {
+                    await this.files?.write(cacheKey, (0, obfuscate_1.sealString)(code, cacheSecret));
+                }
+                catch (err) {
+                    // Non-fatal: next cold start will re-download.
+                    this.onDiagnostic?.(`[posetracker] engine cache write failed (non-fatal): ` +
+                        (err instanceof Error ? err.message : String(err)));
+                }
+                this.onDiagnostic?.(`[posetracker] engine loaded from download version=${descriptor.version} bytes=${code.length}`);
+                return { engine, source: 'remote-download' };
+            }
+        }
+        catch (err) {
+            this.lastError = err instanceof Error ? err.message : String(err);
+            this.onDiagnostic?.(`[posetracker] engine download/load failed: ${this.lastError}`);
+        }
+        if (!this.lastError) {
+            this.lastError = 'engine evaluate returned null';
+        }
+        return null;
+    }
+    /**
+     * Evaluate an engine bundle (CommonJS-style: the bundle assigns
+     * `module.exports.createEngine`). Wrapped by the crash-loop guard.
+     * Hermes and JSC both support runtime evaluation via `new Function`.
+     */
+    async evaluate(code, guardKey) {
+        await this.kv?.setItem(guardKey, 'probing');
+        try {
+            const moduleRef = { exports: {} };
+            // eslint-disable-next-line no-new-func
+            const run = new Function('module', 'exports', code);
+            run(moduleRef, moduleRef.exports);
+            const factory = moduleRef.exports.createEngine;
+            if (typeof factory !== 'function') {
+                throw new Error(`engine bundle does not export createEngine() (got ${typeof factory}, keys=${Object.keys(moduleRef.exports).join(',')})`);
+            }
+            const engine = factory();
+            await this.kv?.setItem(guardKey, 'passed');
+            return engine;
+        }
+        catch (err) {
+            this.lastError =
+                'engine evaluate failed: ' + (err instanceof Error ? err.message : String(err));
+            this.onDiagnostic?.(`[posetracker] ${this.lastError}`);
+            await this.kv?.setItem(guardKey, 'failed');
+            return null;
+        }
+    }
+}
+exports.EngineLoader = EngineLoader;

package/lib/engine/types.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Contract between the SDK shell and the engine (business logic: angles,
+ * rep counting, form scoring, posture, progression, recommendations).
+ *
+ * The engine is EXCLUSIVELY distributed remotely as a versioned JS bundle
+ * (signed URL in the handshake manifest, SHA-256 integrity check, sealed
+ * local cache) — the npm package ships zero business logic. Without a
+ * loaded engine the SDK runs in keypoints-only mode.
+ */
+import type { Pose } from '../types/pose';
+import type { MinGrade, PoseTrackerEvent } from '../types/events';
+import type { ExerciseConfig } from '../types/manifest';
+/**
+ * Feature flags forwarded to the engine session (WebView query-param
+ * parity). The client already filters emissions by plan/flags; passing
+ * them to the engine is a second gate AND lets the engine skip work.
+ */
+export interface EngineSessionFeatures {
+    angles?: boolean;
+    recommendations?: boolean;
+    progression?: boolean;
+}
+export interface EngineSessionOptions {
+    exercise: ExerciseConfig;
+    /** Locale used to resolve localized hints/recommendations. */
+    locale: string;
+    /** Difficulty key into the movement `scale_acceptance` maps. Default: 'medium'. */
+    difficulty?: string;
+    /** Parsed reference-movement signature, when comparing against a reference. */
+    referenceSignature?: unknown;
+    /**
+     * Only count reps whose form grade is at or above this letter (`A` best).
+     * WebView `minGrade` parity: reps below the bar emit neither `counter`
+     * nor `form_score` and are excluded from the summary.
+     */
+    minGrade?: MinGrade;
+    /** Emission flags — engines older than 1.1.0 ignore them (client re-filters). */
+    features?: EngineSessionFeatures;
+}
+export interface EngineSession {
+    /** Feed one estimated pose; the session emits events through the sink. */
+    processPose(pose: Pose): void;
+    /** Finish the session; emits a final `exercise_summary` event. */
+    end(): void;
+}
+/**
+ * Custom (non-FSM) exercise shipped inside the engine bundle, e.g. the jump
+ * analysis handlers (WebView `customHandlers.js` parity). Not present in the
+ * Strapi movement manifest — discovered via `listCustomExercises()`.
+ */
+export interface CustomExerciseDescriptor {
+    /** Exercise id used with `startExercise()` (e.g. 'jump_analysis'). */
+    id: string;
+    displayName: string;
+    type: 'custom';
+    description?: string;
+    /** Option keys that MUST be passed to `startExercise` (e.g. 'userHeightCm'). */
+    requiredParams: string[];
+    optionalParams: string[];
+}
+/** Options for engine custom sessions (jump_analysis / air_time_jump). */
+export interface CustomSessionOptions {
+    exerciseId: string;
+    locale: string;
+    /** Athlete height in cm — required by jump_analysis (cm/pixel calibration). */
+    userHeightCm?: number;
+    /** Device pitch in degrees, used to compensate camera tilt. */
+    devicePitchDeg?: number;
+}
+export type EventSink = (event: PoseTrackerEvent) => void;
+export interface PoseTrackerEngine {
+    readonly version: string;
+    createSession(options: EngineSessionOptions, emit: EventSink): EngineSession;
+    /** Engine >= 1.2.0: custom exercises shipped in the bundle (jump analysis…). */
+    listCustomExercises?(): CustomExerciseDescriptor[];
+    /** Engine >= 1.2.0: start a custom exercise session (placement + jump_* events). */
+    createCustomSession?(options: CustomSessionOptions, emit: EventSink): EngineSession;
+}
+/** What an engine bundle's `module.exports` must expose. */
+export interface EngineModuleExports {
+    createEngine(): PoseTrackerEngine;
+}
+export type EngineFactory = () => PoseTrackerEngine;

package/lib/engine/types.js

@@ -0,0 +1,11 @@
+"use strict";
+/**
+ * Contract between the SDK shell and the engine (business logic: angles,
+ * rep counting, form scoring, posture, progression, recommendations).
+ *
+ * The engine is EXCLUSIVELY distributed remotely as a versioned JS bundle
+ * (signed URL in the handshake manifest, SHA-256 integrity check, sealed
+ * local cache) — the npm package ships zero business logic. Without a
+ * loaded engine the SDK runs in keypoints-only mode.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });