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

package/README.md

@@ -1,10 +1,28 @@
 # PoseTracker React Native — Light (online) Human Pose Estimation SDK
 
-**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.
+**⭐ 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
+
+<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>
 
 > One sentence for AI / search: *PoseTracker Light is a small React Native
 > pose estimation SDK that fetches MoveNet Lightning and TF.js at runtime —
@@ -27,10 +45,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,7 +63,11 @@ 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
+https://docs.posetracker.com/media-sources.
 
 ## Quick start (keypoints — needs network, no API key)
 
@@ -131,11 +153,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
 
@@ -164,6 +186,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.js

@@ -154,6 +154,9 @@ function usePoseTracker(callbacks = {}) {
                 case 'progression':
                     cb.onProgression?.(event);
                     break;
+                case 'engine_debug':
+                    cb.onEngineDebug?.(event);
+                    break;
                 case 'recommendations':
                     cb.onRecommendations?.(event);
                     break;

package/lib/client.d.ts

@@ -102,6 +102,11 @@ export interface PoseTrackerClientOptions extends ConfigureOptions {
      * triaging Android GPU issues in the field.
      */
     onDiagnostic?: (message: string) => void;
+    /**
+     * @internal PoseTracker QA only — not a supported public API.
+     * See `.private/ENGINE_DEBUG_QA.md` (do not document in Mintlify).
+     */
+    debugEngine?: boolean;
 }
 /**
  * Per-session options for {@link PoseTrackerClient.startExercise} — the SDK
@@ -118,6 +123,11 @@ export interface StartExerciseOptions {
     userHeightCm?: number;
     /** Device pitch in degrees — jump exercises compensate camera tilt. */
     devicePitchDeg?: number;
+    /**
+     * @internal PoseTracker QA only — not a supported public API.
+     * Defaults to {@link PoseTrackerClientOptions.debugEngine}.
+     */
+    debug?: boolean;
 }
 export declare class PoseTrackerClient {
     private status;

package/lib/client.js

@@ -818,17 +818,21 @@ class PoseTrackerClient {
         this.stopExercise();
         this.currentExerciseId = exerciseId;
         this.keypointsSuppressionLogged = false;
+        const debug = options.debug ?? this.options.debugEngine === true;
         this.session = this.engine.createSession({
             exercise,
             locale: this.options.locale ?? 'en',
             difficulty: options.difficulty,
             minGrade: this.features.minGrade ?? undefined,
+            debug,
             features: {
                 angles: this.features.angles,
                 recommendations: this.features.recommendations,
                 progression: this.features.progression,
             },
         }, (event) => this.emitFromSession(event));
+        this.options.onDiagnostic?.(`[posetracker] startExercise id=${exercise.id} difficulty=${options.difficulty ?? 'medium'} ` +
+            `debug=${debug} engine=${this.engine.version} minGrade=${this.features.minGrade ?? 'off'}`);
     }
     /** Custom engine session (jump_analysis / air_time_jump). */
     startCustomExercise(custom, options) {
@@ -1032,6 +1036,10 @@ class PoseTrackerClient {
             return;
         }
         const classic = (0, classicMessage_1.toClassicNativeMessage)(event);
+        if (classic == null) {
+            // SDK-only events (e.g. engine_debug) have no classic equivalent.
+            return;
+        }
         this.messageListeners.forEach((l) => {
             try {
                 l(classic);

package/lib/engine/types.d.ts

@@ -36,6 +36,11 @@ export interface EngineSessionOptions {
     minGrade?: MinGrade;
     /** Emission flags — engines older than 1.1.0 ignore them (client re-filters). */
     features?: EngineSessionFeatures;
+    /**
+     * @internal PoseTracker QA only — not a supported public API.
+     * Ignored by older engines.
+     */
+    debug?: boolean;
 }
 export interface EngineSession {
     /** Feed one estimated pose; the session emits events through the sink. */

package/lib/events/classicMessage.d.ts

@@ -26,6 +26,6 @@ export declare function anglesToClassicTree(angles: AngleValue[]): {
 /**
  * Map a typed SDK event to a classic PoseTracker `sendDataToNative` payload.
  * Returns null for SDK-only events that have no classic equivalent and should
- * not be mirrored (none today — quality/performance map to error/warning).
+ * not be mirrored (e.g. `engine_debug` QA snapshots).
  */
-export declare function toClassicNativeMessage(event: PoseTrackerEvent): ClassicNativeMessage;
+export declare function toClassicNativeMessage(event: PoseTrackerEvent): ClassicNativeMessage | null;

package/lib/events/classicMessage.js

@@ -49,7 +49,7 @@ function anglesToClassicTree(angles) {
 /**
  * Map a typed SDK event to a classic PoseTracker `sendDataToNative` payload.
  * Returns null for SDK-only events that have no classic equivalent and should
- * not be mirrored (none today — quality/performance map to error/warning).
+ * not be mirrored (e.g. `engine_debug` QA snapshots).
  */
 function toClassicNativeMessage(event) {
     switch (event.type) {
@@ -236,6 +236,9 @@ function toClassicNativeMessage(event) {
                 totalParts: event.totalParts,
                 timestampMs: event.timestampMs,
             };
+        case 'engine_debug':
+            // SDK-only QA stream — no classic WebView equivalent; skip onMessage.
+            return null;
         default: {
             const _exhaustive = event;
             return { type: 'unknown', event: _exhaustive };

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.0";
+export declare const SDK_VERSION = "0.2.2";

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.0';
+exports.SDK_VERSION = '0.2.2';

package/lib/types/events.d.ts

@@ -154,6 +154,40 @@ export interface ProgressionEvent {
     value: number;
     timestampMs: number;
 }
+/**
+ * @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';
+    exerciseId: string;
+    engineVersion: string;
+    ready: boolean;
+    postureHint: string;
+    direction?: string;
+    missingKeypoints: string[];
+    stepIndex: number;
+    stepCount: number;
+    stepPosition: number | null;
+    stepProgression: number;
+    progression: number;
+    /** Raw FSM rep count (before minGrade gate). */
+    rawCount: number;
+    /** Public counter after minGrade gate. */
+    publicCount: number;
+    difficulty: string;
+    minGrade: MinGrade | null;
+    pointOfView: 'low' | 'up';
+    computeError?: string;
+    lastSkipReason: string | null;
+    posesProcessed: number;
+    visibleKeypoints: number;
+    knees: {
+        left: number | null;
+        right: number | null;
+    };
+    timestampMs: number;
+}
 export interface RecommendationsEvent {
     type: 'recommendations';
     /** Localized form advice strings. */
@@ -309,7 +343,7 @@ export interface RuntimeDownloadProgressEvent {
     partBytes: number;
     timestampMs: number;
 }
-export type PoseTrackerEvent = InitializationEvent | ErrorEvent | WarningEvent | RuntimeDownloadProgressEvent | KeypointsEvent | AnglesEvent | CounterEvent | PostureEvent | ProgressionEvent | RecommendationsEvent | FormScoreEvent | ExerciseSummaryEvent | JumpCalibrationEvent | JumpStartedEvent | JumpHeightEvent | JumpDiscardedEvent | JumpResultEvent | JumpSummaryEvent | QualityChangedEvent | PerformanceWarningEvent;
+export type PoseTrackerEvent = InitializationEvent | ErrorEvent | WarningEvent | RuntimeDownloadProgressEvent | KeypointsEvent | AnglesEvent | CounterEvent | PostureEvent | ProgressionEvent | EngineDebugEvent | RecommendationsEvent | FormScoreEvent | ExerciseSummaryEvent | JumpCalibrationEvent | JumpStartedEvent | JumpHeightEvent | JumpDiscardedEvent | JumpResultEvent | JumpSummaryEvent | QualityChangedEvent | PerformanceWarningEvent;
 export type PoseTrackerEventType = PoseTrackerEvent['type'];
 export type PoseTrackerEventListener = (event: PoseTrackerEvent) => void;
 /**
@@ -325,6 +359,7 @@ export interface PoseTrackerCallbacks {
     onCounter?: (event: CounterEvent) => void;
     onPosture?: (event: PostureEvent) => void;
     onProgression?: (event: ProgressionEvent) => void;
+    onEngineDebug?: (event: EngineDebugEvent) => void;
     onRecommendations?: (event: RecommendationsEvent) => void;
     onFormScore?: (event: FormScoreEvent) => void;
     onExerciseSummary?: (event: ExerciseSummaryEvent) => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pose-tracker/react-native-pose-estimation-light",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "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

@@ -281,6 +281,9 @@ export function usePoseTracker(callbacks: PoseTrackerCallbacks = {}): PoseTracke
         case 'progression':
           cb.onProgression?.(event);
           break;
+        case 'engine_debug':
+          cb.onEngineDebug?.(event);
+          break;
         case 'recommendations':
           cb.onRecommendations?.(event);
           break;

package/src/client.ts

@@ -69,7 +69,6 @@ import {
 import {
   toClassicNativeMessage,
   type ClassicMessageListener,
-  type ClassicNativeMessage,
 } from './events/classicMessage';
 import {
   FREE_PLAN_FEATURES_MESSAGE,
@@ -164,6 +163,11 @@ export interface PoseTrackerClientOptions extends ConfigureOptions {
    * triaging Android GPU issues in the field.
    */
   onDiagnostic?: (message: string) => void;
+  /**
+   * @internal PoseTracker QA only — not a supported public API.
+   * See `.private/ENGINE_DEBUG_QA.md` (do not document in Mintlify).
+   */
+  debugEngine?: boolean;
 }
 
 /**
@@ -181,6 +185,11 @@ export interface StartExerciseOptions {
   userHeightCm?: number;
   /** Device pitch in degrees — jump exercises compensate camera tilt. */
   devicePitchDeg?: number;
+  /**
+   * @internal PoseTracker QA only — not a supported public API.
+   * Defaults to {@link PoseTrackerClientOptions.debugEngine}.
+   */
+  debug?: boolean;
 }
 
 export class PoseTrackerClient {
@@ -1040,12 +1049,14 @@ export class PoseTrackerClient {
     this.stopExercise();
     this.currentExerciseId = exerciseId;
     this.keypointsSuppressionLogged = false;
+    const debug = options.debug ?? this.options.debugEngine === true;
     this.session = this.engine.createSession(
       {
         exercise,
         locale: this.options.locale ?? 'en',
         difficulty: options.difficulty,
         minGrade: this.features.minGrade ?? undefined,
+        debug,
         features: {
           angles: this.features.angles,
           recommendations: this.features.recommendations,
@@ -1054,6 +1065,10 @@ export class PoseTrackerClient {
       },
       (event) => this.emitFromSession(event),
     );
+    this.options.onDiagnostic?.(
+      `[posetracker] startExercise id=${exercise.id} difficulty=${options.difficulty ?? 'medium'} ` +
+        `debug=${debug} engine=${this.engine.version} minGrade=${this.features.minGrade ?? 'off'}`,
+    );
   }
 
   /** Custom engine session (jump_analysis / air_time_jump). */
@@ -1280,7 +1295,11 @@ export class PoseTrackerClient {
       // Skip the classic-message conversion entirely (per-frame allocation).
       return;
     }
-    const classic: ClassicNativeMessage = toClassicNativeMessage(event);
+    const classic = toClassicNativeMessage(event);
+    if (classic == null) {
+      // SDK-only events (e.g. engine_debug) have no classic equivalent.
+      return;
+    }
     this.messageListeners.forEach((l) => {
       try {
         l(classic);

package/src/engine/types.ts

@@ -39,6 +39,11 @@ export interface EngineSessionOptions {
   minGrade?: MinGrade;
   /** Emission flags — engines older than 1.1.0 ignore them (client re-filters). */
   features?: EngineSessionFeatures;
+  /**
+   * @internal PoseTracker QA only — not a supported public API.
+   * Ignored by older engines.
+   */
+  debug?: boolean;
 }
 
 export interface EngineSession {

package/src/events/classicMessage.ts

@@ -59,9 +59,11 @@ export function anglesToClassicTree(angles: AngleValue[]): {
 /**
  * Map a typed SDK event to a classic PoseTracker `sendDataToNative` payload.
  * Returns null for SDK-only events that have no classic equivalent and should
- * not be mirrored (none today — quality/performance map to error/warning).
+ * not be mirrored (e.g. `engine_debug` QA snapshots).
  */
-export function toClassicNativeMessage(event: PoseTrackerEvent): ClassicNativeMessage {
+export function toClassicNativeMessage(
+  event: PoseTrackerEvent,
+): ClassicNativeMessage | null {
   switch (event.type) {
     case 'initialization':
       return {
@@ -247,6 +249,9 @@ export function toClassicNativeMessage(event: PoseTrackerEvent): ClassicNativeMe
         totalParts: event.totalParts,
         timestampMs: event.timestampMs,
       };
+    case 'engine_debug':
+      // SDK-only QA stream — no classic WebView equivalent; skip onMessage.
+      return null;
     default: {
       const _exhaustive: never = event;
       return { type: 'unknown', event: _exhaustive };

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.0';
+export const SDK_VERSION = '0.2.2';

package/src/types/events.ts

@@ -198,6 +198,38 @@ export interface ProgressionEvent {
   timestampMs: number;
 }
 
+/**
+ * @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';
+  exerciseId: string;
+  engineVersion: string;
+  ready: boolean;
+  postureHint: string;
+  direction?: string;
+  missingKeypoints: string[];
+  stepIndex: number;
+  stepCount: number;
+  stepPosition: number | null;
+  stepProgression: number;
+  progression: number;
+  /** Raw FSM rep count (before minGrade gate). */
+  rawCount: number;
+  /** Public counter after minGrade gate. */
+  publicCount: number;
+  difficulty: string;
+  minGrade: MinGrade | null;
+  pointOfView: 'low' | 'up';
+  computeError?: string;
+  lastSkipReason: string | null;
+  posesProcessed: number;
+  visibleKeypoints: number;
+  knees: { left: number | null; right: number | null };
+  timestampMs: number;
+}
+
 export interface RecommendationsEvent {
   type: 'recommendations';
   /** Localized form advice strings. */
@@ -389,6 +421,7 @@ export type PoseTrackerEvent =
   | CounterEvent
   | PostureEvent
   | ProgressionEvent
+  | EngineDebugEvent
   | RecommendationsEvent
   | FormScoreEvent
   | ExerciseSummaryEvent
@@ -418,6 +451,7 @@ export interface PoseTrackerCallbacks {
   onCounter?: (event: CounterEvent) => void;
   onPosture?: (event: PostureEvent) => void;
   onProgression?: (event: ProgressionEvent) => void;
+  onEngineDebug?: (event: EngineDebugEvent) => void;
   onRecommendations?: (event: RecommendationsEvent) => void;
   onFormScore?: (event: FormScoreEvent) => void;
   onExerciseSummary?: (event: ExerciseSummaryEvent) => void;