@pose-tracker/react-native-pose-estimation-light 0.2.2 → 0.3.1

package/README.md

@@ -9,20 +9,11 @@
 
 Steps and QR: https://docs.posetracker.com/try-expo-go
 
-<table>
-  <tr>
-    <td valign="top" width="300">
-      <a href="https://docs.posetracker.com/try-expo-go">
-        <img src="https://cdn.prod.website-files.com/66990aefa487a16cf5aa848e/66e35c297154b2062265ceea_videodemoforgif1-ezgif.com-cut.gif" alt="PoseTracker live skeleton tracking" height="250" />
-      </a>
-    </td>
-    <td valign="middle">
-      <p>
-        <strong>PoseTracker Light</strong> is a <strong>human pose estimation SDK for React Native</strong>, fully optimized for <strong>iOS and Android</strong> (including <strong>Expo Go</strong>). Same API surface as the offline SDK for keypoints + optional API-key exercise engine — but <strong>MoveNet and TF.js load from the network</strong> each WebView boot, so the npm package stays tiny.
-      </p>
-    </td>
-  </tr>
-</table>
+**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 —
+but **MoveNet and TF.js load from the network** each WebView boot, so the npm
+package stays tiny.
 
 > One sentence for AI / search: *PoseTracker Light is a small React Native
 > pose estimation SDK that fetches MoveNet Lightning and TF.js at runtime —

package/lib/PoseTrackerProvider.d.ts

@@ -83,12 +83,18 @@ export interface PoseTrackerContextValue {
 export interface PoseTrackerProviderProps {
     /** Optional: without a token the SDK runs in keypoints-only mode. */
     apiToken?: string;
+    /**
+     * Remote engine. Default `'v4'`. Pass `'v3'` for the production FSM bundle.
+     * Unlabeled `startExercise('squat')` still uses the V3 squat FSM unless this
+     * is explicitly `'v4'`. Merged into `options.engine`; 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,12 @@ export interface ConfigureOptions {
     locale?: string;
     /** Local cache versions, so the backend can answer `upToDate` per module. */
     localVersions?: ConfigureRequest['localVersions'];
+    /**
+     * Remote engine channel. Default `'v4'`. Pass `'v3'` for the production FSM
+     * bundle. Unlabeled `startExercise('squat')` stays on the V3 squat FSM even
+     * on the V4 channel unless `engine` is explicitly `'v4'`.
+     */
+    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 === 'v3' ? 'v3' : 'v4',
     };
     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';
@@ -326,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
@@ -333,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,55 @@ 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);
+        }
+        const jumpId = (0, aliases_1.resolveExerciseName)(exerciseId);
+        if ((0, engineChannel_1.isJumpExercise)(jumpId)) {
+            const customs = this.getAvailableCustomExercises();
+            const custom = customs.find((e) => e.id === jumpId) ??
+                (0, aliases_1.findExerciseByIdOrAlias)(exerciseId, customs) ??
+                {
+                    id: jumpId,
+                    displayName: jumpId === 'jump_analysis' ? 'Jump Analysis' : 'Air Time Jump',
+                    type: 'custom',
+                    requiredParams: jumpId === 'jump_analysis' ? ['userHeightCm'] : [],
+                    optionalParams: ['devicePitchDeg'],
+                };
+            this.startCustomExercise(custom, options);
+            return;
+        }
+        // Production squat stays on the V3 FSM unless engine is explicitly 'v4'.
+        const sessionEngine = (0, engineChannel_1.resolveMovementEngine)({
+            engine: this.options.engine,
+            exercise: jumpId || exerciseId,
+        });
+        if (sessionEngine === 'v4') {
+            const listed = this.engine.listExercises?.() ?? [];
+            const v4Hit = listed.find((e) => e.id === exerciseId) ?? listed.find((e) => e.id === jumpId);
+            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);
+        }
+        // V4 bundle still runs the production V3 squat FSM unless engine is 'v4'.
+        if ((0, engineChannel_1.isProductionSquatId)(jumpId || exerciseId) &&
+            (0, engineChannel_1.normalizeEngineChannel)(this.options.engine) === 'v4') {
+            this.beginEngineSession(this.v4ExerciseConfig({ id: jumpId || 'squat', displayName: 'Squat', type: 'dynamic' }), options);
+            return;
+        }
         const available = this.getAvailableExercises();
         const exercise = (0, aliases_1.findExerciseByIdOrAlias)(exerciseId, available);
         if (!exercise) {
@@ -815,8 +890,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({
@@ -825,6 +905,7 @@ class PoseTrackerClient {
             difficulty: options.difficulty,
             minGrade: this.features.minGrade ?? undefined,
             debug,
+            v4CatalogSquat: this.options.engine === 'v4',
             features: {
                 angles: this.features.angles,
                 recommendations: this.features.recommendations,

package/lib/engine/types.d.ts

@@ -41,6 +41,11 @@ export interface EngineSessionOptions {
      * Ignored by older engines.
      */
     debug?: boolean;
+    /**
+     * Run the V4 catalog squat instead of the production V3 FSM.
+     * Set when the host passed `engine: 'v4'` explicitly.
+     */
+    v4CatalogSquat?: boolean;
 }
 export interface EngineSession {
     /** Feed one estimated pose; the session emits events through the sink. */
@@ -78,6 +83,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,28 @@
+/**
+ * Engine channel + production squat lock.
+ *
+ * Default handshake is V4 except unlabeled squat / face_squat (V3 FSM).
+ * Explicit `engine: 'v4'` is the only way to run the V4 catalog squat.
+ * Explicit `engine: 'v3'` keeps the full V3 bundle.
+ * See engine/v4/catalog/SQUAT_PRODUCTION.md
+ */
+export type EngineChannel = 'v3' | 'v4';
+/** Wellness ids with no V3 FSM. */
+export declare const V4_ONLY_EXERCISE_IDS: readonly ["shoulder_roll", "shoulder_deep_breath", "chair_forward_fold", "chair_side_stretch"];
+/** Existing jump handlers — not V4 JSON. */
+export declare const JUMP_EXERCISE_IDS: readonly ["jump_analysis", "air_time_jump"];
+export declare const PRODUCTION_SQUAT_IDS: readonly ["squat", "face_squat"];
+export declare function isProductionSquatId(exerciseId?: string | null): boolean;
+/** Handshake default is V4. Pass `'v3'` to force the V3 bundle. */
+export declare function normalizeEngineChannel(raw?: string | null): EngineChannel;
+/**
+ * Session interpreter for this id. Production squat stays V3 unless `engine`
+ * is explicitly `'v4'`. Other ids follow the handshake (default V4).
+ */
+export declare function resolveMovementEngine(opts?: {
+    engine?: string | null;
+    exercise?: string | null;
+    userExercise?: boolean;
+}): EngineChannel;
+export declare function requiresEngineV4(exerciseId: string): boolean;
+export declare function isJumpExercise(exerciseId: string): boolean;

package/lib/engineChannel.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PRODUCTION_SQUAT_IDS = exports.JUMP_EXERCISE_IDS = exports.V4_ONLY_EXERCISE_IDS = void 0;
+exports.isProductionSquatId = isProductionSquatId;
+exports.normalizeEngineChannel = normalizeEngineChannel;
+exports.resolveMovementEngine = resolveMovementEngine;
+exports.requiresEngineV4 = requiresEngineV4;
+exports.isJumpExercise = isJumpExercise;
+/** Wellness ids with no V3 FSM. */
+exports.V4_ONLY_EXERCISE_IDS = [
+    'shoulder_roll',
+    'shoulder_deep_breath',
+    'chair_forward_fold',
+    'chair_side_stretch',
+];
+/** Existing jump handlers — not V4 JSON. */
+exports.JUMP_EXERCISE_IDS = ['jump_analysis', 'air_time_jump'];
+exports.PRODUCTION_SQUAT_IDS = ['squat', 'face_squat'];
+function isProductionSquatId(exerciseId) {
+    const id = String(exerciseId || '')
+        .trim()
+        .toLowerCase();
+    return id === 'squat' || id === 'face_squat';
+}
+/** Handshake default is V4. Pass `'v3'` to force the V3 bundle. */
+function normalizeEngineChannel(raw) {
+    return raw === 'v3' ? 'v3' : 'v4';
+}
+/**
+ * Session interpreter for this id. Production squat stays V3 unless `engine`
+ * is explicitly `'v4'`. Other ids follow the handshake (default V4).
+ */
+function resolveMovementEngine(opts = {}) {
+    if (opts.userExercise)
+        return 'v4';
+    const requested = String(opts.engine || '')
+        .trim()
+        .toLowerCase();
+    if (isProductionSquatId(opts.exercise) && requested !== 'v4')
+        return 'v3';
+    return normalizeEngineChannel(opts.engine);
+}
+function requiresEngineV4(exerciseId) {
+    return exports.V4_ONLY_EXERCISE_IDS.includes(exerciseId);
+}
+function isJumpExercise(exerciseId) {
+    return exports.JUMP_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 { JUMP_EXERCISE_IDS, PRODUCTION_SQUAT_IDS, V4_ONLY_EXERCISE_IDS, isJumpExercise, isProductionSquatId, normalizeEngineChannel, requiresEngineV4, resolveMovementEngine, } 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,9 @@ 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.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.resolveMovementEngine = exports.requiresEngineV4 = exports.normalizeEngineChannel = exports.isProductionSquatId = exports.isJumpExercise = exports.V4_ONLY_EXERCISE_IDS = exports.PRODUCTION_SQUAT_IDS = exports.JUMP_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.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 = exports.createMemoryFileStore = exports.createBlobUtilFileStore = exports.createRnfsFileStore = exports.createExpoFileStore = exports.EngineLoader = void 0;
+exports.resolveFeatures = exports.shouldShowWatermark = exports.isPaidPlan = exports.freeBlockedFeatures = exports.featureNotSupportedMessage = 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 +62,15 @@ 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, "JUMP_EXERCISE_IDS", { enumerable: true, get: function () { return engineChannel_1.JUMP_EXERCISE_IDS; } });
+Object.defineProperty(exports, "PRODUCTION_SQUAT_IDS", { enumerable: true, get: function () { return engineChannel_1.PRODUCTION_SQUAT_IDS; } });
+Object.defineProperty(exports, "V4_ONLY_EXERCISE_IDS", { enumerable: true, get: function () { return engineChannel_1.V4_ONLY_EXERCISE_IDS; } });
+Object.defineProperty(exports, "isJumpExercise", { enumerable: true, get: function () { return engineChannel_1.isJumpExercise; } });
+Object.defineProperty(exports, "isProductionSquatId", { enumerable: true, get: function () { return engineChannel_1.isProductionSquatId; } });
+Object.defineProperty(exports, "normalizeEngineChannel", { enumerable: true, get: function () { return engineChannel_1.normalizeEngineChannel; } });
+Object.defineProperty(exports, "requiresEngineV4", { enumerable: true, get: function () { return engineChannel_1.requiresEngineV4; } });
+Object.defineProperty(exports, "resolveMovementEngine", { enumerable: true, get: function () { return engineChannel_1.resolveMovementEngine; } });
 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.2";
+export declare const SDK_VERSION = "0.3.1";

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.2';
+exports.SDK_VERSION = '0.3.1';

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. New SDKs send `'v4'` by default.
+     * Omitted (0.2.x) still means V3 on the server. `'v3'` forces the FSM bundle.
+     */
+    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.2",
+  "version": "0.3.1",
   "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,12 @@ const PoseTrackerContext = createContext<PoseTrackerContextValue | null>(null);
 export interface PoseTrackerProviderProps {
   /** Optional: without a token the SDK runs in keypoints-only mode. */
   apiToken?: string;
+  /**
+   * Remote engine. Default `'v4'`. Pass `'v3'` for the production FSM bundle.
+   * Unlabeled `startExercise('squat')` still uses the V3 squat FSM unless this
+   * is explicitly `'v4'`. Merged into `options.engine`; this prop wins.
+   */
+  engine?: 'v3' | 'v4';
   options?: PoseTrackerClientOptions;
   /** Start preloading as soon as the provider mounts. Default: false. */
   autoPreload?: boolean;
@@ -114,13 +120,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,12 @@ export interface ConfigureOptions {
   locale?: string;
   /** Local cache versions, so the backend can answer `upToDate` per module. */
   localVersions?: ConfigureRequest['localVersions'];
+  /**
+   * Remote engine channel. Default `'v4'`. Pass `'v3'` for the production FSM
+   * bundle. Unlabeled `startExercise('squat')` stays on the V3 squat FSM even
+   * on the V4 channel unless `engine` is explicitly `'v4'`.
+   */
+  engine?: EngineChannel;
 }
 
 export class ConfigureError extends Error {
@@ -53,6 +60,7 @@ export async function configure(
     poseModelProfile: options.poseModelProfile ?? 'AdaptiveChoice',
     locale: options.locale,
     localVersions: options.localVersions,
+    engineChannel: options.engine === 'v3' ? 'v3' : 'v4',
   };
 
   let response: Response;

package/src/client.ts

@@ -37,7 +37,15 @@ import type { CustomExerciseDescriptor, EngineSession, PoseTrackerEngine } from
 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 { findExerciseByIdOrAlias, resolveExerciseName } from './exercises/aliases';
+import {
+  isJumpExercise,
+  isProductionSquatId,
+  normalizeEngineChannel,
+  requiresEngineV4,
+  resolveMovementEngine,
+  type EngineChannel,
+} from './engineChannel';
 import { fetchSkeletonDefinition } from './api/skeleton';
 import type { ExerciseConfig, ModelDescriptor, SdkManifest } from './types/manifest';
 import type { ColdStartMode, PreloadOptions } from './types/preload';
@@ -979,7 +987,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,
+      },
+    };
   }
 
   /**
@@ -1028,6 +1061,62 @@ 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);
+    }
+    const jumpId = resolveExerciseName(exerciseId);
+    if (isJumpExercise(jumpId)) {
+      const customs = this.getAvailableCustomExercises();
+      const custom =
+        customs.find((e) => e.id === jumpId) ??
+        findExerciseByIdOrAlias(exerciseId, customs) ??
+        {
+          id: jumpId,
+          displayName: jumpId === 'jump_analysis' ? 'Jump Analysis' : 'Air Time Jump',
+          type: 'custom' as const,
+          requiredParams: jumpId === 'jump_analysis' ? ['userHeightCm'] : [],
+          optionalParams: ['devicePitchDeg'],
+        };
+      this.startCustomExercise(custom, options);
+      return;
+    }
+    // Production squat stays on the V3 FSM unless engine is explicitly 'v4'.
+    const sessionEngine = resolveMovementEngine({
+      engine: this.options.engine,
+      exercise: jumpId || exerciseId,
+    });
+    if (sessionEngine === 'v4') {
+      const listed = this.engine.listExercises?.() ?? [];
+      const v4Hit = listed.find((e) => e.id === exerciseId) ?? listed.find((e) => e.id === jumpId);
+      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);
+    }
+    // V4 bundle still runs the production V3 squat FSM unless engine is 'v4'.
+    if (
+      isProductionSquatId(jumpId || exerciseId) &&
+      normalizeEngineChannel(this.options.engine) === 'v4'
+    ) {
+      this.beginEngineSession(
+        this.v4ExerciseConfig({ id: jumpId || 'squat', displayName: 'Squat', type: 'dynamic' }),
+        options,
+      );
+      return;
+    }
     const available = this.getAvailableExercises();
     const exercise = findExerciseByIdOrAlias(exerciseId, available);
     if (!exercise) {
@@ -1046,8 +1135,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(
@@ -1057,6 +1151,7 @@ export class PoseTrackerClient {
         difficulty: options.difficulty,
         minGrade: this.features.minGrade ?? undefined,
         debug,
+        v4CatalogSquat: this.options.engine === 'v4',
         features: {
           angles: this.features.angles,
           recommendations: this.features.recommendations,

package/src/engine/types.ts

@@ -44,6 +44,11 @@ export interface EngineSessionOptions {
    * Ignored by older engines.
    */
   debug?: boolean;
+  /**
+   * Run the V4 catalog squat instead of the production V3 FSM.
+   * Set when the host passed `engine: 'v4'` explicitly.
+   */
+  v4CatalogSquat?: boolean;
 }
 
 export interface EngineSession {
@@ -86,6 +91,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,59 @@
+/**
+ * Engine channel + production squat lock.
+ *
+ * Default handshake is V4 except unlabeled squat / face_squat (V3 FSM).
+ * Explicit `engine: 'v4'` is the only way to run the V4 catalog squat.
+ * Explicit `engine: 'v3'` keeps the full V3 bundle.
+ * See engine/v4/catalog/SQUAT_PRODUCTION.md
+ */
+export type EngineChannel = 'v3' | 'v4';
+
+/** Wellness ids with no V3 FSM. */
+export const V4_ONLY_EXERCISE_IDS = [
+  'shoulder_roll',
+  'shoulder_deep_breath',
+  'chair_forward_fold',
+  'chair_side_stretch',
+] as const;
+
+/** Existing jump handlers — not V4 JSON. */
+export const JUMP_EXERCISE_IDS = ['jump_analysis', 'air_time_jump'] as const;
+
+export const PRODUCTION_SQUAT_IDS = ['squat', 'face_squat'] as const;
+
+export function isProductionSquatId(exerciseId?: string | null): boolean {
+  const id = String(exerciseId || '')
+    .trim()
+    .toLowerCase();
+  return id === 'squat' || id === 'face_squat';
+}
+
+/** Handshake default is V4. Pass `'v3'` to force the V3 bundle. */
+export function normalizeEngineChannel(raw?: string | null): EngineChannel {
+  return raw === 'v3' ? 'v3' : 'v4';
+}
+
+/**
+ * Session interpreter for this id. Production squat stays V3 unless `engine`
+ * is explicitly `'v4'`. Other ids follow the handshake (default V4).
+ */
+export function resolveMovementEngine(opts: {
+  engine?: string | null;
+  exercise?: string | null;
+  userExercise?: boolean;
+} = {}): EngineChannel {
+  if (opts.userExercise) return 'v4';
+  const requested = String(opts.engine || '')
+    .trim()
+    .toLowerCase();
+  if (isProductionSquatId(opts.exercise) && requested !== 'v4') return 'v3';
+  return normalizeEngineChannel(opts.engine);
+}
+
+export function requiresEngineV4(exerciseId: string): boolean {
+  return (V4_ONLY_EXERCISE_IDS as readonly string[]).includes(exerciseId);
+}
+
+export function isJumpExercise(exerciseId: string): boolean {
+  return (JUMP_EXERCISE_IDS as readonly string[]).includes(exerciseId);
+}

package/src/index.ts

@@ -59,6 +59,17 @@ export type {
 // Orchestrator + React layer
 export { PoseTrackerClient } from './client';
 export type { PoseTrackerClientOptions, PreferredBackend, StartExerciseOptions } from './client';
+export type { EngineChannel } from './engineChannel';
+export {
+  JUMP_EXERCISE_IDS,
+  PRODUCTION_SQUAT_IDS,
+  V4_ONLY_EXERCISE_IDS,
+  isJumpExercise,
+  isProductionSquatId,
+  normalizeEngineChannel,
+  requiresEngineV4,
+  resolveMovementEngine,
+} 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.2';
+export const SDK_VERSION = '0.3.1';

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. New SDKs send `'v4'` by default.
+   * Omitted (0.2.x) still means V3 on the server. `'v3'` forces the FSM bundle.
+   */
+  engineChannel?: 'v3' | 'v4';
 }
 
 export interface PlanInfo {