@pose-tracker/react-native-pose-estimation-light 0.2.1 → 0.3.0

package/README.md

@@ -1,5 +1,14 @@
 # PoseTracker React Native — Light (online) Human Pose Estimation SDK
 
+**⭐ Star us on GitHub:** [Movelytics/react-native-pose-estimation-light](https://github.com/Movelytics/react-native-pose-estimation-light) — it helps other React Native and Expo developers find the SDK.
+
+**Try it on your phone (no Xcode / Android Studio):**
+1. Install [Expo Go](https://expo.dev/go)
+2. Open the [Expo Snack](https://snack.expo.dev/@fsepret/posetracker-sdk-light-demo-app) → **Run on device**
+3. Scan the QR — live pose estimation, no API key
+
+Steps and QR: https://docs.posetracker.com/try-expo-go
+
 **PoseTracker Light** is a **human pose estimation SDK for React Native**,
 fully optimized for **iOS and Android** (including **Expo Go**). Same API
 surface as the offline SDK for keypoints + optional API-key exercise engine —
@@ -27,10 +36,10 @@ package stays tiny.
 download at session start.  
 **Choose light** when app install / OTA size matters and devices are online.
 
-Full comparison: [LIGHT_SDK.md](../../docs/LIGHT_SDK.md).
+Full comparison: [LIGHT_SDK.md](docs/LIGHT_SDK.md).
 
 **Agents:** shared UX/API/bugfixes → mirror to offline (or ask first). See
-[`DUAL_SDK_CHANGES.md`](../../docs/DUAL_SDK_CHANGES.md).
+[`DUAL_SDK_CHANGES.md`](docs/DUAL_SDK_CHANGES.md).
 
 ## Install
 
@@ -45,10 +54,10 @@ npx expo install react-native-webview expo-camera
 > **Offline sibling:** [`@pose-tracker/react-native-pose-estimation`](https://www.npmjs.com/package/@pose-tracker/react-native-pose-estimation)
 
 **Required:** host app must declare camera permissions — see
-[PERMISSIONS.md](../../docs/PERMISSIONS.md).
+[PERMISSIONS.md](docs/PERMISSIONS.md).
 
 **Media inputs (v0.2):** camera (default), uploaded video, still image — host
-picks the file. See [MEDIA_SOURCES.md](../../docs/MEDIA_SOURCES.md) and
+picks the file. See [MEDIA_SOURCES.md](docs/MEDIA_SOURCES.md) and
 https://docs.posetracker.com/media-sources.
 
 ## Quick start (keypoints — needs network, no API key)
@@ -135,11 +144,11 @@ Same contract as the offline SDK / web tracking URL:
 
 | Doc | Topic |
 |-----|--------|
-| [LIGHT_SDK.md](../../docs/LIGHT_SDK.md) | Offline vs light, sizes, model URL |
-| [PERMISSIONS.md](../../docs/PERMISSIONS.md) | Camera permission setup (required) |
-| [PRELOAD.md](../../docs/PRELOAD.md) | Preload / warm-up / lifecycle |
-| [FEATURES.md](../../docs/FEATURES.md) | Plan gating, watermark, loading text |
-| [EVENTS.md](../../docs/EVENTS.md) | Typed events + classic `onMessage` |
+| [LIGHT_SDK.md](docs/LIGHT_SDK.md) | Offline vs light, sizes, model URL |
+| [PERMISSIONS.md](docs/PERMISSIONS.md) | Camera permission setup (required) |
+| [PRELOAD.md](docs/PRELOAD.md) | Preload / warm-up / lifecycle |
+| [FEATURES.md](docs/FEATURES.md) | Plan gating, watermark, loading text |
+| [EVENTS.md](docs/EVENTS.md) | Typed events + classic `onMessage` |
 
 ## FAQ
 
@@ -168,6 +177,8 @@ see [`THIRD_PARTY_NOTICES.md`](./THIRD_PARTY_NOTICES.md).
 ## Links
 
 - Product: https://www.posetracker.com  
-- API docs: https://posetracker.gitbook.io/posetracker-api  
-- Offline SDK: https://github.com/Movelytics/react-native-pose-estimation  
+- Docs: https://docs.posetracker.com  
+- Try on your phone: https://docs.posetracker.com/try-expo-go  
+- Expo Snack: https://snack.expo.dev/@fsepret/posetracker-sdk-light-demo-app  
 - Light demo: https://github.com/Movelytics/react-native-pose-estimation-light-demo  
+- Offline SDK: https://github.com/Movelytics/react-native-pose-estimation  

package/lib/PoseTrackerProvider.d.ts

@@ -83,12 +83,17 @@ export interface PoseTrackerContextValue {
 export interface PoseTrackerProviderProps {
     /** Optional: without a token the SDK runs in keypoints-only mode. */
     apiToken?: string;
+    /**
+     * Opt-in V4 engine (`'v4'`). Default `'v3'` — production FSM, unchanged.
+     * Merged into `options.engine` when both are set, this prop wins.
+     */
+    engine?: 'v3' | 'v4';
     options?: PoseTrackerClientOptions;
     /** Start preloading as soon as the provider mounts. Default: false. */
     autoPreload?: boolean;
     children: React.ReactNode;
 }
-export declare function PoseTrackerProvider({ apiToken, options, autoPreload, children, }: PoseTrackerProviderProps): React.JSX.Element;
+export declare function PoseTrackerProvider({ apiToken, engine, options, autoPreload, children, }: PoseTrackerProviderProps): React.JSX.Element;
 /**
  * Access the PoseTracker pipeline and subscribe to typed events.
  *

package/lib/PoseTrackerProvider.js

@@ -22,10 +22,13 @@ const jsx_runtime_1 = require("react/jsx-runtime");
 const react_1 = require("react");
 const client_1 = require("./client");
 const PoseTrackerContext = (0, react_1.createContext)(null);
-function PoseTrackerProvider({ apiToken, options, autoPreload = false, children, }) {
+function PoseTrackerProvider({ apiToken, engine, options, autoPreload = false, children, }) {
     const clientRef = (0, react_1.useRef)(null);
     if (!clientRef.current) {
-        clientRef.current = new client_1.PoseTrackerClient(apiToken, options);
+        clientRef.current = new client_1.PoseTrackerClient(apiToken, {
+            ...options,
+            engine: engine ?? options?.engine,
+        });
     }
     const client = clientRef.current;
     const [status, setStatus] = (0, react_1.useState)(client.getStatus());

package/lib/api/configure.d.ts

@@ -11,6 +11,7 @@
  */
 import { SDK_VERSION } from '../sdkVersion';
 import type { ConfigureRequest, PoseModelProfile, SdkManifest } from '../types/manifest';
+import type { EngineChannel } from '../engineChannel';
 export declare const SDK_NAME: "posetracker-rn-light";
 export { SDK_VERSION };
 /** Overridable for staging/self-hosted backends. */
@@ -21,6 +22,11 @@ export interface ConfigureOptions {
     locale?: string;
     /** Local cache versions, so the backend can answer `upToDate` per module. */
     localVersions?: ConfigureRequest['localVersions'];
+    /**
+     * Opt-in V4 heuristic engine. Default `'v3'` (production FSM).
+     * Set `'v4'` at init — the handshake downloads `engine-v4.bundle.js`.
+     */
+    engine?: EngineChannel;
 }
 export declare class ConfigureError extends Error {
     readonly code: 'invalid_token' | 'quota_exceeded' | 'network' | 'internal';

package/lib/api/configure.js

@@ -37,6 +37,7 @@ async function configure(apiToken, options = {}) {
         poseModelProfile: options.poseModelProfile ?? 'AdaptiveChoice',
         locale: options.locale,
         localVersions: options.localVersions,
+        engineChannel: options.engine === 'v4' ? 'v4' : 'v3',
     };
     let response;
     try {

package/lib/client.d.ts

@@ -28,6 +28,7 @@ import { EngineLoader, type EngineLoadResult, type FileStore } from './engine/En
 import { type OnlineRuntimeParts } from './backends/webview/onlineRuntime';
 import type { CustomExerciseDescriptor } from './engine/types';
 import type { PoseBackend, PoseInputFrame } from './backends/PoseBackend';
+import { type EngineChannel } from './engineChannel';
 import type { ExerciseConfig, SdkManifest } from './types/manifest';
 import type { ColdStartMode, PreloadOptions } from './types/preload';
 import type { SkeletonDefinition } from './types/skeleton';
@@ -103,9 +104,8 @@ export interface PoseTrackerClientOptions extends ConfigureOptions {
      */
     onDiagnostic?: (message: string) => void;
     /**
-     * When true, exercise sessions request `engine_debug` snapshots from the
-     * remote engine (bundle ≥ 1.2.4). Overridable per call via
-     * `startExercise(id, { debug: true|false })`.
+     * @internal PoseTracker QA only — not a supported public API.
+     * See `.private/ENGINE_DEBUG_QA.md` (do not document in Mintlify).
      */
     debugEngine?: boolean;
 }
@@ -125,8 +125,8 @@ export interface StartExerciseOptions {
     /** Device pitch in degrees — jump exercises compensate camera tilt. */
     devicePitchDeg?: number;
     /**
-     * Request throttled `engine_debug` events for this session (movement FSM
-     * QA). Defaults to {@link PoseTrackerClientOptions.debugEngine}.
+     * @internal PoseTracker QA only — not a supported public API.
+     * Defaults to {@link PoseTrackerClientOptions.debugEngine}.
      */
     debug?: boolean;
 }
@@ -327,6 +327,8 @@ export declare class PoseTrackerClient {
     private validateRequestedFeatures;
     private resolveModel;
     getAvailableExercises(): ExerciseConfig[];
+    getEngineChannel(): EngineChannel;
+    private v4ExerciseConfig;
     /**
      * Custom exercises shipped inside the engine bundle (jump_analysis,
      * air_time_jump — WebView `customHandlers.js` parity). Empty in
@@ -334,6 +336,7 @@ export declare class PoseTrackerClient {
      */
     getAvailableCustomExercises(): CustomExerciseDescriptor[];
     startExercise(exerciseId: string, options?: StartExerciseOptions): void;
+    private beginEngineSession;
     /** Custom engine session (jump_analysis / air_time_jump). */
     private startCustomExercise;
     /**

package/lib/client.js

@@ -34,6 +34,7 @@ const obfuscate_1 = require("./cache/obfuscate");
 const VisionPoseBackend_1 = require("./backends/vision/VisionPoseBackend");
 const WebViewPoseBackend_1 = require("./backends/webview/WebViewPoseBackend");
 const aliases_1 = require("./exercises/aliases");
+const engineChannel_1 = require("./engineChannel");
 const skeleton_1 = require("./api/skeleton");
 const logReport_1 = require("./diagnostics/logReport");
 const AdaptiveQualityController_1 = require("./quality/AdaptiveQualityController");
@@ -755,7 +756,32 @@ class PoseTrackerClient {
     // Exercise sessions (full-engine mode only)
     // -------------------------------------------------------------------------
     getAvailableExercises() {
-        return this.mode === 'full-engine' ? this.manifest?.exercises ?? [] : [];
+        if (this.mode !== 'full-engine')
+            return [];
+        if ((0, engineChannel_1.normalizeEngineChannel)(this.options.engine) === 'v4') {
+            const listed = this.engine?.listExercises?.() ?? [];
+            if (listed.length)
+                return listed.map((e) => this.v4ExerciseConfig(e));
+        }
+        return this.manifest?.exercises ?? [];
+    }
+    getEngineChannel() {
+        return (0, engineChannel_1.normalizeEngineChannel)(this.options.engine);
+    }
+    v4ExerciseConfig(entry) {
+        const type = entry.type === 'static' ? 'static' : 'dynamic';
+        return {
+            id: entry.id,
+            name: entry.displayName || entry.id,
+            type,
+            movement: {
+                name: entry.id,
+                type,
+                scale_acceptance: {},
+                movement_steps: [],
+                movement_initial_posture: null,
+            },
+        };
     }
     /**
      * Custom exercises shipped inside the engine bundle (jump_analysis,
@@ -798,6 +824,29 @@ class PoseTrackerClient {
                 throw new Error(features_1.FREE_PLAN_FEATURES_MESSAGE);
             }
         }
+        if ((0, engineChannel_1.requiresEngineV4)(exerciseId) && (0, engineChannel_1.normalizeEngineChannel)(this.options.engine) !== 'v4') {
+            const message = `Exercise '${exerciseId}' requires engine: 'v4'`;
+            this.reportError({ type: 'error', code: 'invalid_exercise', message });
+            throw new Error(message);
+        }
+        if ((0, engineChannel_1.normalizeEngineChannel)(this.options.engine) === 'v4') {
+            const listed = this.engine.listExercises?.() ?? [];
+            const v4Hit = listed.find((e) => e.id === exerciseId);
+            if (v4Hit) {
+                this.beginEngineSession(this.v4ExerciseConfig(v4Hit), options);
+                return;
+            }
+            const customs = this.getAvailableCustomExercises();
+            const custom = customs.find((e) => e.id === exerciseId) ??
+                (0, aliases_1.findExerciseByIdOrAlias)(exerciseId, customs);
+            if (custom) {
+                this.startCustomExercise(custom, options);
+                return;
+            }
+            const message = `Exercise '${exerciseId}' is not available in V4 engine`;
+            this.reportError({ type: 'error', code: 'invalid_exercise', message });
+            throw new Error(message);
+        }
         const available = this.getAvailableExercises();
         const exercise = (0, aliases_1.findExerciseByIdOrAlias)(exerciseId, available);
         if (!exercise) {
@@ -815,8 +864,13 @@ class PoseTrackerClient {
             this.reportError({ type: 'error', code: 'invalid_exercise', message });
             throw new Error(message);
         }
+        this.beginEngineSession(exercise, options);
+    }
+    beginEngineSession(exercise, options) {
+        if (!this.engine)
+            return;
         this.stopExercise();
-        this.currentExerciseId = exerciseId;
+        this.currentExerciseId = exercise.id;
         this.keypointsSuppressionLogged = false;
         const debug = options.debug ?? this.options.debugEngine === true;
         this.session = this.engine.createSession({

package/lib/engine/types.d.ts

@@ -37,8 +37,8 @@ export interface EngineSessionOptions {
     /** Emission flags — engines older than 1.1.0 ignore them (client re-filters). */
     features?: EngineSessionFeatures;
     /**
-     * When true, the engine emits throttled `engine_debug` events (movement
-     * FSM snapshot). Requires engine bundle ≥ 1.2.4. Ignored by older engines.
+     * @internal PoseTracker QA only — not a supported public API.
+     * Ignored by older engines.
      */
     debug?: boolean;
 }
@@ -78,6 +78,13 @@ export interface PoseTrackerEngine {
     createSession(options: EngineSessionOptions, emit: EventSink): EngineSession;
     /** Engine >= 1.2.0: custom exercises shipped in the bundle (jump analysis…). */
     listCustomExercises?(): CustomExerciseDescriptor[];
+    /** Engine V4 catalog (opt-in channel). Absent on V3 bundles. */
+    listExercises?(): Array<{
+        id: string;
+        displayName: string;
+        type: string;
+        description?: string;
+    }>;
     /** Engine >= 1.2.0: start a custom exercise session (placement + jump_* events). */
     createCustomSession?(options: CustomSessionOptions, emit: EventSink): EngineSession;
 }

package/lib/engineChannel.d.ts

@@ -0,0 +1,6 @@
+/** Opt-in remote engine channel. Default is production V3. */
+export type EngineChannel = 'v3' | 'v4';
+/** Movements that exist only in the V4 catalog (not in V3 FSM / Strapi). */
+export declare const V4_ONLY_EXERCISE_IDS: readonly ["shoulder_roll", "shoulder_deep_breath", "chair_forward_fold"];
+export declare function normalizeEngineChannel(raw?: string | null): EngineChannel;
+export declare function requiresEngineV4(exerciseId: string): boolean;

package/lib/engineChannel.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.V4_ONLY_EXERCISE_IDS = void 0;
+exports.normalizeEngineChannel = normalizeEngineChannel;
+exports.requiresEngineV4 = requiresEngineV4;
+/** Movements that exist only in the V4 catalog (not in V3 FSM / Strapi). */
+exports.V4_ONLY_EXERCISE_IDS = [
+    'shoulder_roll',
+    'shoulder_deep_breath',
+    'chair_forward_fold',
+];
+function normalizeEngineChannel(raw) {
+    return raw === 'v4' ? 'v4' : 'v3';
+}
+function requiresEngineV4(exerciseId) {
+    return exports.V4_ONLY_EXERCISE_IDS.includes(exerciseId);
+}

package/lib/index.d.ts

@@ -25,6 +25,8 @@ export { DEFAULT_MOVENET_LIGHTNING_URL, originFromModelUrl, resolvePoseModel, }
 export type { PoseModelAlias, PoseModelKind, ResolvePoseModelOptions, ResolvedPoseModel, } from './models/poseModels';
 export { PoseTrackerClient } from './client';
 export type { PoseTrackerClientOptions, PreferredBackend, StartExerciseOptions } from './client';
+export type { EngineChannel } from './engineChannel';
+export { V4_ONLY_EXERCISE_IDS, normalizeEngineChannel, requiresEngineV4 } from './engineChannel';
 export type { ColdStartMode, PreloadOptions } from './types/preload';
 export type { SkeletonAnglesStyle, SkeletonCirclesStyle, SkeletonDefinition, SkeletonLinesStyle, } from './types/skeleton';
 export { DEFAULT_SKELETON_DEFINITION } from './types/skeleton';

package/lib/index.js

@@ -28,8 +28,8 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.logAccelerationReport = exports.defaultDiagnosticLogger = exports.createNativeFileStore = exports.createMemoryFileStore = exports.createBlobUtilFileStore = exports.createRnfsFileStore = exports.createExpoFileStore = exports.EngineLoader = exports.isExpoGo = exports.PoseCameraView = exports.VISION_JOINT_TO_SDK = exports.poseFromVisionPluginResult = exports.VISION_BODY_POSE_PLUGIN_NAME = exports.isVisionPoseCameraAvailable = exports.isVisionBackendAvailable = exports.VisionUnavailableError = exports.VisionPoseBackend = exports.POSETRACKER_LOGO_DATA_URL = exports.POSE_HTML_BUILD = exports.DEFAULT_LOADING_TEXT = exports.buildPoseHtml = exports.WebViewPoseView = exports.isWebViewPoseBackend = exports.WebViewPoseBackend = exports.usePoseTracker = exports.PoseTrackerProvider = exports.SkeletonFetchError = exports.fetchSkeletonDefinition = exports.DEFAULT_SKELETON_DEFINITION = exports.PoseTrackerClient = exports.resolvePoseModel = exports.originFromModelUrl = exports.DEFAULT_MOVENET_LIGHTNING_URL = exports.ONLINE_POSE_DETECTION_VERSION = exports.ONLINE_TFJS_VERSION = exports.defaultPoseDetectionCdnUrl = exports.defaultOnlineRuntimeUrls = exports.getOnlineRuntimeVersion = exports.getOnlineRuntimeParts = exports.RuntimeCache = exports.TrackError = exports.UsageTracker = exports.resolveExerciseName = exports.findExerciseByIdOrAlias = exports.EXERCISE_ALIASES = exports.SDK_VERSION = exports.SDK_NAME = exports.DEFAULT_BASE_URL = exports.ConfigureError = exports.configure = void 0;
-exports.resolveFeatures = exports.shouldShowWatermark = exports.isPaidPlan = exports.freeBlockedFeatures = exports.featureNotSupportedMessage = exports.COMBINED_REFERENCE_EXERCISE_MESSAGE = exports.INVALID_TOKEN_MESSAGE = exports.FREE_PLAN_FEATURES_MESSAGE = exports.DEFAULT_FEATURES = exports.RuntimeGuard = exports.scoreDeviceCapability = exports.profileFromScore = exports.isMaliRenderer = exports.ENABLE_MALI_HARD_CAP = exports.CAPTURE_CONSTRAINT_MODE = exports.ANDROID_SOFT_CAP_PROFILE = exports.ANDROID_PREPROCESS_PATH = exports.ANDROID_PERF_DEBUG = exports.ANDROID_MIN_TARGET_FPS = exports.ANDROID_INFER_FRAME_SKIP = exports.profileFromWarmupMedianMs = exports.nextLowerQualityProfile = exports.minMedianMsForMinTarget = exports.lowerQualityProfile = exports.isQualityProfileId = exports.getQualityProfile = exports.getMinTargetFps = exports.getIdealFpsRange = exports.getCriticalFpsThreshold = exports.estimatedFpsFromMedianMs = exports.currentQualityPlatform = exports.TARGET_MEDIAN_MS = exports.TARGET_FPS = exports.QUALITY_PROFILES = exports.QUALITY_LADDER = exports.MIN_TARGET_FPS_IOS = exports.MIN_TARGET_FPS_DEFAULT = exports.MIN_TARGET_FPS_ANDROID = exports.QUALITY_SETTLE_MS = exports.LOW_FPS_STREAK_BEFORE_DOWNGRADE = exports.IDEAL_FPS_RANGE_IOS = exports.IDEAL_FPS_RANGE_ANDROID = exports.CRITICAL_FPS_THRESHOLD = exports.AdaptiveQualityController = exports.toClassicNativeMessage = exports.logPlatformBanner = exports.logFrameStats = void 0;
+exports.createMemoryFileStore = exports.createBlobUtilFileStore = exports.createRnfsFileStore = exports.createExpoFileStore = exports.EngineLoader = exports.isExpoGo = exports.PoseCameraView = exports.VISION_JOINT_TO_SDK = exports.poseFromVisionPluginResult = exports.VISION_BODY_POSE_PLUGIN_NAME = exports.isVisionPoseCameraAvailable = exports.isVisionBackendAvailable = exports.VisionUnavailableError = exports.VisionPoseBackend = exports.POSETRACKER_LOGO_DATA_URL = exports.POSE_HTML_BUILD = exports.DEFAULT_LOADING_TEXT = exports.buildPoseHtml = exports.WebViewPoseView = exports.isWebViewPoseBackend = exports.WebViewPoseBackend = exports.usePoseTracker = exports.PoseTrackerProvider = exports.SkeletonFetchError = exports.fetchSkeletonDefinition = exports.DEFAULT_SKELETON_DEFINITION = exports.requiresEngineV4 = exports.normalizeEngineChannel = exports.V4_ONLY_EXERCISE_IDS = exports.PoseTrackerClient = exports.resolvePoseModel = exports.originFromModelUrl = exports.DEFAULT_MOVENET_LIGHTNING_URL = exports.ONLINE_POSE_DETECTION_VERSION = exports.ONLINE_TFJS_VERSION = exports.defaultPoseDetectionCdnUrl = exports.defaultOnlineRuntimeUrls = exports.getOnlineRuntimeVersion = exports.getOnlineRuntimeParts = exports.RuntimeCache = exports.TrackError = exports.UsageTracker = exports.resolveExerciseName = exports.findExerciseByIdOrAlias = exports.EXERCISE_ALIASES = exports.SDK_VERSION = exports.SDK_NAME = exports.DEFAULT_BASE_URL = exports.ConfigureError = exports.configure = void 0;
+exports.resolveFeatures = exports.shouldShowWatermark = exports.isPaidPlan = exports.freeBlockedFeatures = exports.featureNotSupportedMessage = exports.COMBINED_REFERENCE_EXERCISE_MESSAGE = exports.INVALID_TOKEN_MESSAGE = exports.FREE_PLAN_FEATURES_MESSAGE = exports.DEFAULT_FEATURES = exports.RuntimeGuard = exports.scoreDeviceCapability = exports.profileFromScore = exports.isMaliRenderer = exports.ENABLE_MALI_HARD_CAP = exports.CAPTURE_CONSTRAINT_MODE = exports.ANDROID_SOFT_CAP_PROFILE = exports.ANDROID_PREPROCESS_PATH = exports.ANDROID_PERF_DEBUG = exports.ANDROID_MIN_TARGET_FPS = exports.ANDROID_INFER_FRAME_SKIP = exports.profileFromWarmupMedianMs = exports.nextLowerQualityProfile = exports.minMedianMsForMinTarget = exports.lowerQualityProfile = exports.isQualityProfileId = exports.getQualityProfile = exports.getMinTargetFps = exports.getIdealFpsRange = exports.getCriticalFpsThreshold = exports.estimatedFpsFromMedianMs = exports.currentQualityPlatform = exports.TARGET_MEDIAN_MS = exports.TARGET_FPS = exports.QUALITY_PROFILES = exports.QUALITY_LADDER = exports.MIN_TARGET_FPS_IOS = exports.MIN_TARGET_FPS_DEFAULT = exports.MIN_TARGET_FPS_ANDROID = exports.QUALITY_SETTLE_MS = exports.LOW_FPS_STREAK_BEFORE_DOWNGRADE = exports.IDEAL_FPS_RANGE_IOS = exports.IDEAL_FPS_RANGE_ANDROID = exports.CRITICAL_FPS_THRESHOLD = exports.AdaptiveQualityController = exports.toClassicNativeMessage = exports.logPlatformBanner = exports.logFrameStats = exports.logAccelerationReport = exports.defaultDiagnosticLogger = exports.createNativeFileStore = void 0;
 // Handshake + usage tracking
 var configure_1 = require("./api/configure");
 Object.defineProperty(exports, "configure", { enumerable: true, get: function () { return configure_1.configure; } });
@@ -61,6 +61,10 @@ Object.defineProperty(exports, "resolvePoseModel", { enumerable: true, get: func
 // Orchestrator + React layer
 var client_1 = require("./client");
 Object.defineProperty(exports, "PoseTrackerClient", { enumerable: true, get: function () { return client_1.PoseTrackerClient; } });
+var engineChannel_1 = require("./engineChannel");
+Object.defineProperty(exports, "V4_ONLY_EXERCISE_IDS", { enumerable: true, get: function () { return engineChannel_1.V4_ONLY_EXERCISE_IDS; } });
+Object.defineProperty(exports, "normalizeEngineChannel", { enumerable: true, get: function () { return engineChannel_1.normalizeEngineChannel; } });
+Object.defineProperty(exports, "requiresEngineV4", { enumerable: true, get: function () { return engineChannel_1.requiresEngineV4; } });
 var skeleton_1 = require("./types/skeleton");
 Object.defineProperty(exports, "DEFAULT_SKELETON_DEFINITION", { enumerable: true, get: function () { return skeleton_1.DEFAULT_SKELETON_DEFINITION; } });
 var skeleton_2 = require("./api/skeleton");

package/lib/sdkVersion.d.ts

@@ -1,2 +1,2 @@
 /** AUTO-GENERATED by scripts/sync-sdk-version.mjs — do not edit. */
-export declare const SDK_VERSION = "0.2.1";
+export declare const SDK_VERSION = "0.3.0";

package/lib/sdkVersion.js

@@ -2,4 +2,4 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SDK_VERSION = void 0;
 /** AUTO-GENERATED by scripts/sync-sdk-version.mjs — do not edit. */
-exports.SDK_VERSION = '0.2.1';
+exports.SDK_VERSION = '0.3.0';

package/lib/types/events.d.ts

@@ -155,8 +155,8 @@ export interface ProgressionEvent {
     timestampMs: number;
 }
 /**
- * Throttled movement / rep-FSM snapshot for QA (engine ≥ 1.2.4).
- * Enable via `PoseTrackerClientOptions.debugEngine` or `startExercise(..., { debug: true })`.
+ * @internal PoseTracker QA only — not a supported public API (do not document in Mintlify).
+ * Throttled movement / rep-FSM snapshot. See `.private/ENGINE_DEBUG_QA.md`.
  */
 export interface EngineDebugEvent {
     type: 'engine_debug';

package/lib/types/manifest.d.ts

@@ -126,6 +126,8 @@ export interface EngineBundleDescriptor {
     minSdkVersion: string;
     /** True when the version sent in `localVersions.engine` is already current. */
     upToDate?: boolean;
+    /** Which interpreter this descriptor is. Absent on older backends = v3. */
+    channel?: 'v3' | 'v4';
 }
 export interface PoseRuntimePartDescriptor {
     /** Download URL of this part (`GET /api/sdk/pose-runtime?part=...&v=...`). */
@@ -166,6 +168,11 @@ export interface ConfigureRequest {
         poseRuntime?: string | null;
         engine?: string | null;
     };
+    /**
+     * Which remote engine to download. Default / omitted = v3 (production).
+     * `v4` is opt-in (heuristic catalog: squat, shoulder_roll, …).
+     */
+    engineChannel?: 'v3' | 'v4';
 }
 export interface PlanInfo {
     plan: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pose-tracker/react-native-pose-estimation-light",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Human pose estimation SDK for React Native (light / online) — MoveNet Lightning via CDN + model URL each session, no bundled weights. iOS & Android (Expo Go). Optional API-key exercise engine.",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",

package/src/PoseTrackerProvider.tsx

@@ -106,6 +106,11 @@ const PoseTrackerContext = createContext<PoseTrackerContextValue | null>(null);
 export interface PoseTrackerProviderProps {
   /** Optional: without a token the SDK runs in keypoints-only mode. */
   apiToken?: string;
+  /**
+   * Opt-in V4 engine (`'v4'`). Default `'v3'` — production FSM, unchanged.
+   * Merged into `options.engine` when both are set, this prop wins.
+   */
+  engine?: 'v3' | 'v4';
   options?: PoseTrackerClientOptions;
   /** Start preloading as soon as the provider mounts. Default: false. */
   autoPreload?: boolean;
@@ -114,13 +119,17 @@ export interface PoseTrackerProviderProps {
 
 export function PoseTrackerProvider({
   apiToken,
+  engine,
   options,
   autoPreload = false,
   children,
 }: PoseTrackerProviderProps): React.JSX.Element {
   const clientRef = useRef<PoseTrackerClient | null>(null);
   if (!clientRef.current) {
-    clientRef.current = new PoseTrackerClient(apiToken, options);
+    clientRef.current = new PoseTrackerClient(apiToken, {
+      ...options,
+      engine: engine ?? options?.engine,
+    });
   }
   const client = clientRef.current;
 

package/src/api/configure.ts

@@ -14,6 +14,7 @@ import { Platform } from 'react-native';
 
 import { SDK_VERSION } from '../sdkVersion';
 import type { ConfigureRequest, PoseModelProfile, SdkManifest } from '../types/manifest';
+import type { EngineChannel } from '../engineChannel';
 
 export const SDK_NAME = 'posetracker-rn-light' as const;
 export { SDK_VERSION };
@@ -28,6 +29,11 @@ export interface ConfigureOptions {
   locale?: string;
   /** Local cache versions, so the backend can answer `upToDate` per module. */
   localVersions?: ConfigureRequest['localVersions'];
+  /**
+   * Opt-in V4 heuristic engine. Default `'v3'` (production FSM).
+   * Set `'v4'` at init — the handshake downloads `engine-v4.bundle.js`.
+   */
+  engine?: EngineChannel;
 }
 
 export class ConfigureError extends Error {
@@ -53,6 +59,7 @@ export async function configure(
     poseModelProfile: options.poseModelProfile ?? 'AdaptiveChoice',
     locale: options.locale,
     localVersions: options.localVersions,
+    engineChannel: options.engine === 'v4' ? 'v4' : 'v3',
   };
 
   let response: Response;

package/src/client.ts

@@ -38,6 +38,7 @@ import type { PoseBackend, PoseInputFrame } from './backends/PoseBackend';
 import { VisionPoseBackend } from './backends/vision/VisionPoseBackend';
 import { WebViewPoseBackend } from './backends/webview/WebViewPoseBackend';
 import { findExerciseByIdOrAlias } from './exercises/aliases';
+import { normalizeEngineChannel, requiresEngineV4, type EngineChannel } from './engineChannel';
 import { fetchSkeletonDefinition } from './api/skeleton';
 import type { ExerciseConfig, ModelDescriptor, SdkManifest } from './types/manifest';
 import type { ColdStartMode, PreloadOptions } from './types/preload';
@@ -164,9 +165,8 @@ export interface PoseTrackerClientOptions extends ConfigureOptions {
    */
   onDiagnostic?: (message: string) => void;
   /**
-   * When true, exercise sessions request `engine_debug` snapshots from the
-   * remote engine (bundle ≥ 1.2.4). Overridable per call via
-   * `startExercise(id, { debug: true|false })`.
+   * @internal PoseTracker QA only — not a supported public API.
+   * See `.private/ENGINE_DEBUG_QA.md` (do not document in Mintlify).
    */
   debugEngine?: boolean;
 }
@@ -187,8 +187,8 @@ export interface StartExerciseOptions {
   /** Device pitch in degrees — jump exercises compensate camera tilt. */
   devicePitchDeg?: number;
   /**
-   * Request throttled `engine_debug` events for this session (movement FSM
-   * QA). Defaults to {@link PoseTrackerClientOptions.debugEngine}.
+   * @internal PoseTracker QA only — not a supported public API.
+   * Defaults to {@link PoseTrackerClientOptions.debugEngine}.
    */
   debug?: boolean;
 }
@@ -980,7 +980,32 @@ export class PoseTrackerClient {
   // -------------------------------------------------------------------------
 
   getAvailableExercises(): ExerciseConfig[] {
-    return this.mode === 'full-engine' ? this.manifest?.exercises ?? [] : [];
+    if (this.mode !== 'full-engine') return [];
+    if (normalizeEngineChannel(this.options.engine) === 'v4') {
+      const listed = this.engine?.listExercises?.() ?? [];
+      if (listed.length) return listed.map((e) => this.v4ExerciseConfig(e));
+    }
+    return this.manifest?.exercises ?? [];
+  }
+
+  getEngineChannel(): EngineChannel {
+    return normalizeEngineChannel(this.options.engine);
+  }
+
+  private v4ExerciseConfig(entry: { id: string; displayName?: string; type?: string }): ExerciseConfig {
+    const type = entry.type === 'static' ? 'static' : 'dynamic';
+    return {
+      id: entry.id,
+      name: entry.displayName || entry.id,
+      type,
+      movement: {
+        name: entry.id,
+        type,
+        scale_acceptance: {},
+        movement_steps: [],
+        movement_initial_posture: null,
+      },
+    };
   }
 
   /**
@@ -1029,6 +1054,30 @@ export class PoseTrackerClient {
         throw new Error(FREE_PLAN_FEATURES_MESSAGE);
       }
     }
+    if (requiresEngineV4(exerciseId) && normalizeEngineChannel(this.options.engine) !== 'v4') {
+      const message = `Exercise '${exerciseId}' requires engine: 'v4'`;
+      this.reportError({ type: 'error', code: 'invalid_exercise', message });
+      throw new Error(message);
+    }
+    if (normalizeEngineChannel(this.options.engine) === 'v4') {
+      const listed = this.engine.listExercises?.() ?? [];
+      const v4Hit = listed.find((e) => e.id === exerciseId);
+      if (v4Hit) {
+        this.beginEngineSession(this.v4ExerciseConfig(v4Hit), options);
+        return;
+      }
+      const customs = this.getAvailableCustomExercises();
+      const custom =
+        customs.find((e) => e.id === exerciseId) ??
+        findExerciseByIdOrAlias(exerciseId, customs);
+      if (custom) {
+        this.startCustomExercise(custom, options);
+        return;
+      }
+      const message = `Exercise '${exerciseId}' is not available in V4 engine`;
+      this.reportError({ type: 'error', code: 'invalid_exercise', message });
+      throw new Error(message);
+    }
     const available = this.getAvailableExercises();
     const exercise = findExerciseByIdOrAlias(exerciseId, available);
     if (!exercise) {
@@ -1047,8 +1096,13 @@ export class PoseTrackerClient {
       this.reportError({ type: 'error', code: 'invalid_exercise', message });
       throw new Error(message);
     }
+    this.beginEngineSession(exercise, options);
+  }
+
+  private beginEngineSession(exercise: ExerciseConfig, options: StartExerciseOptions): void {
+    if (!this.engine) return;
     this.stopExercise();
-    this.currentExerciseId = exerciseId;
+    this.currentExerciseId = exercise.id;
     this.keypointsSuppressionLogged = false;
     const debug = options.debug ?? this.options.debugEngine === true;
     this.session = this.engine.createSession(

package/src/engine/types.ts

@@ -40,8 +40,8 @@ export interface EngineSessionOptions {
   /** Emission flags — engines older than 1.1.0 ignore them (client re-filters). */
   features?: EngineSessionFeatures;
   /**
-   * When true, the engine emits throttled `engine_debug` events (movement
-   * FSM snapshot). Requires engine bundle ≥ 1.2.4. Ignored by older engines.
+   * @internal PoseTracker QA only — not a supported public API.
+   * Ignored by older engines.
    */
   debug?: boolean;
 }
@@ -86,6 +86,13 @@ export interface PoseTrackerEngine {
   createSession(options: EngineSessionOptions, emit: EventSink): EngineSession;
   /** Engine >= 1.2.0: custom exercises shipped in the bundle (jump analysis…). */
   listCustomExercises?(): CustomExerciseDescriptor[];
+  /** Engine V4 catalog (opt-in channel). Absent on V3 bundles. */
+  listExercises?(): Array<{
+    id: string;
+    displayName: string;
+    type: string;
+    description?: string;
+  }>;
   /** Engine >= 1.2.0: start a custom exercise session (placement + jump_* events). */
   createCustomSession?(options: CustomSessionOptions, emit: EventSink): EngineSession;
 }

package/src/engineChannel.ts

@@ -0,0 +1,17 @@
+/** Opt-in remote engine channel. Default is production V3. */
+export type EngineChannel = 'v3' | 'v4';
+
+/** Movements that exist only in the V4 catalog (not in V3 FSM / Strapi). */
+export const V4_ONLY_EXERCISE_IDS = [
+  'shoulder_roll',
+  'shoulder_deep_breath',
+  'chair_forward_fold',
+] as const;
+
+export function normalizeEngineChannel(raw?: string | null): EngineChannel {
+  return raw === 'v4' ? 'v4' : 'v3';
+}
+
+export function requiresEngineV4(exerciseId: string): boolean {
+  return (V4_ONLY_EXERCISE_IDS as readonly string[]).includes(exerciseId);
+}

package/src/index.ts

@@ -59,6 +59,8 @@ export type {
 // Orchestrator + React layer
 export { PoseTrackerClient } from './client';
 export type { PoseTrackerClientOptions, PreferredBackend, StartExerciseOptions } from './client';
+export type { EngineChannel } from './engineChannel';
+export { V4_ONLY_EXERCISE_IDS, normalizeEngineChannel, requiresEngineV4 } from './engineChannel';
 export type { ColdStartMode, PreloadOptions } from './types/preload';
 export type {
   SkeletonAnglesStyle,

package/src/sdkVersion.ts

@@ -1,2 +1,2 @@
 /** AUTO-GENERATED by scripts/sync-sdk-version.mjs — do not edit. */
-export const SDK_VERSION = '0.2.1';
+export const SDK_VERSION = '0.3.0';

package/src/types/events.ts

@@ -199,8 +199,8 @@ export interface ProgressionEvent {
 }
 
 /**
- * Throttled movement / rep-FSM snapshot for QA (engine ≥ 1.2.4).
- * Enable via `PoseTrackerClientOptions.debugEngine` or `startExercise(..., { debug: true })`.
+ * @internal PoseTracker QA only — not a supported public API (do not document in Mintlify).
+ * Throttled movement / rep-FSM snapshot. See `.private/ENGINE_DEBUG_QA.md`.
  */
 export interface EngineDebugEvent {
   type: 'engine_debug';

package/src/types/manifest.ts

@@ -146,6 +146,8 @@ export interface EngineBundleDescriptor {
   minSdkVersion: string;
   /** True when the version sent in `localVersions.engine` is already current. */
   upToDate?: boolean;
+  /** Which interpreter this descriptor is. Absent on older backends = v3. */
+  channel?: 'v3' | 'v4';
 }
 
 // ---------------------------------------------------------------------------
@@ -197,6 +199,11 @@ export interface ConfigureRequest {
     poseRuntime?: string | null;
     engine?: string | null;
   };
+  /**
+   * Which remote engine to download. Default / omitted = v3 (production).
+   * `v4` is opt-in (heuristic catalog: squat, shoulder_roll, …).
+   */
+  engineChannel?: 'v3' | 'v4';
 }
 
 export interface PlanInfo {