@pose-tracker/react-native-pose-estimation-light 0.3.4 → 0.3.6

package/lib/index.d.ts

@@ -33,7 +33,7 @@ export { DEFAULT_SKELETON_DEFINITION } from './types/skeleton';
 export { fetchSkeletonDefinition, SkeletonFetchError } from './api/skeleton';
 export type { FetchSkeletonOptions } from './api/skeleton';
 export { PoseTrackerProvider, usePoseTracker } from './PoseTrackerProvider';
-export type { PoseTrackerContextValue, PoseTrackerProviderProps } from './PoseTrackerProvider';
+export type { PoseTrackerContextValue, PoseTrackerProviderProps, ProcessFrameFn, } from './PoseTrackerProvider';
 export type { PoseBackend, PoseBackendInitOptions, PoseInputFrame } from './backends/PoseBackend';
 export { WebViewPoseBackend, isWebViewPoseBackend } from './backends/webview/WebViewPoseBackend';
 export type { WebViewPoseBackendOptions, WebViewPoseMessage } from './backends/webview/WebViewPoseBackend';
@@ -72,3 +72,4 @@ export type { PoseTrackerFeatures, ResolvedFeatures } from './types/features';
 export * from './types/events';
 export * from './types/manifest';
 export * from './types/pose';
+export * from './types/externalFrame';

package/lib/index.js

@@ -181,3 +181,4 @@ Object.defineProperty(exports, "resolveFeatures", { enumerable: true, get: funct
 __exportStar(require("./types/events"), exports);
 __exportStar(require("./types/manifest"), exports);
 __exportStar(require("./types/pose"), exports);
+__exportStar(require("./types/externalFrame"), exports);

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

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.3.4';
+exports.SDK_VERSION = '0.3.6';

package/lib/types/externalFrame.d.ts

@@ -0,0 +1,41 @@
+/**
+ * External frames: the host app owns the camera and the preview, and pushes
+ * frames to {@link PoseTrackerClient.processFrame}. The SDK infers, runs the
+ * active exercise engine, and returns data. It draws nothing.
+ */
+import type { PoseTrackerEvent } from './events';
+import type { Pose } from './pose';
+export interface ExternalFrame {
+    /** Encoded image (JPEG / PNG) without the `data:` prefix. */
+    base64?: string;
+    /** `file://`, `data:` or `https:` URL the WebView can load. */
+    uri?: string;
+    /** Width of the frame you send. Keep the longest side at 256 px or less. */
+    width: number;
+    height: number;
+    /** Capture time of the frame. The exercise engine uses it for timing. */
+    timestampMs: number;
+    /**
+     * Mirror keypoints horizontally, as for a selfie preview. Default `true`.
+     * Pass `false` for a back camera or an unmirrored preview.
+     */
+    mirrored?: boolean;
+    /** MIME type of `base64`. Default `image/jpeg`. */
+    mime?: string;
+}
+export interface ExternalFrameResult {
+    /** True when a previous frame was still running. Nothing was inferred. */
+    dropped: boolean;
+    /**
+     * Pose for this frame, or the last pose when `dropped`. Keypoints are
+     * normalized 0–1 to the frame you sent.
+     */
+    pose: Pose | null;
+    /**
+     * Events produced by this frame (keypoints, counter, posture, angles,
+     * form score, …), in emission order. They are also delivered to the
+     * existing listeners. Empty when `dropped`.
+     */
+    events: PoseTrackerEvent[];
+}
+export declare function isExternalFrame(frame: unknown): frame is ExternalFrame;

package/lib/types/externalFrame.js

@@ -0,0 +1,16 @@
+"use strict";
+/**
+ * External frames: the host app owns the camera and the preview, and pushes
+ * frames to {@link PoseTrackerClient.processFrame}. The SDK infers, runs the
+ * active exercise engine, and returns data. It draws nothing.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isExternalFrame = isExternalFrame;
+function isExternalFrame(frame) {
+    if (frame == null || typeof frame !== 'object')
+        return false;
+    const f = frame;
+    return ((typeof f.base64 === 'string' || typeof f.uri === 'string') &&
+        typeof f.width === 'number' &&
+        typeof f.height === 'number');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pose-tracker/react-native-pose-estimation-light",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "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",
@@ -20,6 +20,7 @@
   "scripts": {
     "build": "node scripts/sync-sdk-version.mjs && node scripts/embed-pose-runtime.mjs && tsc -p tsconfig.json && node scripts/copy-pose-runtime-source.mjs",
     "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --test \"test/*.test.cjs\"",
     "embed:runtime": "node scripts/embed-pose-runtime.mjs",
     "prepack": "npm run build",
     "pack:dry": "npm pack --dry-run"

package/src/PoseTrackerProvider.tsx

@@ -25,8 +25,13 @@ import React, {
   useState,
 } from 'react';
 
+import { StyleSheet, View } from 'react-native';
+
 import { PoseTrackerClient, type PoseTrackerClientOptions, type StartExerciseOptions } from './client';
 import type { PoseInputFrame } from './backends/PoseBackend';
+import { WebViewPoseBackend } from './backends/webview/WebViewPoseBackend';
+import type { WebViewPoseViewProps } from './camera/WebViewPoseView';
+import type { ExternalFrame, ExternalFrameResult } from './types/externalFrame';
 import type { ExerciseConfig, SdkManifest } from './types/manifest';
 import type { PreloadOptions } from './types/preload';
 import type {
@@ -90,7 +95,18 @@ export interface PoseTrackerContextValue {
   startExercise: (exerciseId: string, options?: StartExerciseOptions) => void;
   stopExercise: () => void;
   estimatePose: (frame: PoseInputFrame) => Promise<Pose | null>;
-  processFrame: (frame: PoseInputFrame) => Promise<Pose | null>;
+  /**
+   * Pass `{ base64 | uri, width, height, timestampMs }` from your own camera
+   * after {@link warmupExternal}: resolves `{ dropped, pose, events }`.
+   * Any other frame keeps the original pose + engine behaviour.
+   */
+  processFrame: ProcessFrameFn;
+  /**
+   * Opt-in: load the model for frames from your own camera. Mounts a hidden
+   * 1×1 basic WebView (no camera, nothing drawn). Not needed with
+   * `WebViewPoseView`.
+   */
+  warmupExternal: () => Promise<void>;
   addEventListener: (listener: PoseTrackerEventListener) => () => void;
   /**
    * Classic PoseTracker WebView JSON stream (`sendDataToNative` shape).
@@ -101,6 +117,11 @@ export interface PoseTrackerContextValue {
   ) => () => void;
 }
 
+export interface ProcessFrameFn {
+  (frame: ExternalFrame): Promise<ExternalFrameResult>;
+  (frame: PoseInputFrame): Promise<Pose | null>;
+}
+
 const PoseTrackerContext = createContext<PoseTrackerContextValue | null>(null);
 
 export interface PoseTrackerProviderProps {
@@ -143,9 +164,21 @@ export function PoseTrackerProvider({
   const [accelerationDiagnostics, setAccelerationDiagnostics] =
     useState<AccelerationDiagnostics | null>(client.getAccelerationDiagnostics());
   const [quality, setQuality] = useState<QualityState>(client.getQualityState());
+  /** Hidden warmer for external frames; false unless warmupExternal() ran. */
+  const [mountExternalWarmer, setMountExternalWarmer] = useState(false);
 
   useEffect(() => {
     const offState = client.onStateChange(() => {
+      if (client.isExternalWarmerRequested()) {
+        setMountExternalWarmer((mounted) => {
+          if (mounted) return true;
+          const backend = client.getBackend();
+          // Reuse a WebViewPoseView the host already mounted.
+          return backend instanceof WebViewPoseBackend && !backend.isAttached();
+        });
+      } else {
+        setMountExternalWarmer(false);
+      }
       setStatus(client.getStatus());
       setMode(client.getMode());
       setError(client.getError());
@@ -186,9 +219,10 @@ export function PoseTrackerProvider({
     [client],
   );
   const processFrame = useCallback(
-    (frame: PoseInputFrame) => client.processFrame(frame),
+    ((frame: PoseInputFrame) => client.processFrame(frame)) as ProcessFrameFn,
     [client],
   );
+  const warmupExternal = useCallback(() => client.warmupExternal(), [client]);
   const addEventListener = useCallback(
     (listener: PoseTrackerEventListener) => client.addEventListener(listener),
     [client],
@@ -217,6 +251,7 @@ export function PoseTrackerProvider({
       stopExercise,
       estimatePose,
       processFrame,
+      warmupExternal,
       addEventListener,
       addMessageListener,
     }),
@@ -236,14 +271,50 @@ export function PoseTrackerProvider({
       stopExercise,
       estimatePose,
       processFrame,
+      warmupExternal,
       addEventListener,
       addMessageListener,
     ],
   );
 
-  return <PoseTrackerContext.Provider value={value}>{children}</PoseTrackerContext.Provider>;
+  return (
+    <PoseTrackerContext.Provider value={value}>
+      {children}
+      {mountExternalWarmer ? <ExternalFramesWarmer /> : null}
+    </PoseTrackerContext.Provider>
+  );
 }
 
+declare function require(name: string): unknown;
+
+/** Hidden basic page for external frames: no camera, nothing drawn. */
+function ExternalFramesWarmer(): React.JSX.Element {
+  // Required lazily: WebViewPoseView itself imports this module.
+  const { WebViewPoseView } = require('./camera/WebViewPoseView') as {
+    WebViewPoseView: React.ComponentType<WebViewPoseViewProps>;
+  };
+  return (
+    <View pointerEvents="none" style={styles.externalWarmer}>
+      <WebViewPoseView
+        coldStart="basic"
+        drawSkeleton={false}
+        drawPlacementBox={false}
+        showWatermark={false}
+      />
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  externalWarmer: {
+    position: 'absolute',
+    width: 1,
+    height: 1,
+    opacity: 0,
+    overflow: 'hidden',
+  },
+});
+
 /**
  * Access the PoseTracker pipeline and subscribe to typed events.
  *

package/src/backends/webview/WebViewPoseBackend.ts

@@ -7,9 +7,10 @@
  * only one real-time across the whole Android park in Expo Go. Fully
  * offline: TF.js and the model ship inside the npm package (poseHtml.ts).
  *
- * The WebView owns the camera (`getUserMedia`). Frames are NOT pushed from
- * React Native — `estimatePose()` returns the latest pose posted by the page.
- * Mount {@link WebViewPoseView} (or a 1×1 warmer) to attach the runtime.
+ * By default the WebView owns the camera (`getUserMedia`) and
+ * `estimatePose()` returns the latest pose posted by the page. Mount
+ * {@link WebViewPoseView} (or a 1×1 warmer) to attach the runtime.
+ * Opt-in: {@link pushFrame} infers host-provided frames on a basic warmer.
  */
 
 import type { PoseBackend, PoseBackendInitOptions, PoseInputFrame } from '../PoseBackend';
@@ -20,6 +21,7 @@ import type {
   DiagnosticListener,
 } from '../../types/acceleration';
 import type { PoseTrackerEvent } from '../../types/events';
+import type { ExternalFrame } from '../../types/externalFrame';
 
 export type WebViewPoseMessage =
   | {
@@ -55,7 +57,10 @@ export type WebViewPoseMessage =
       score: number;
       inferenceTimeMs: number;
       timestampMs: number;
+      /** Set when the pose answers a pushed external frame. */
+      frameId?: number;
     }
+  | { type: 'frame_result'; id: number; dropped: boolean; error?: string }
   | {
       type: 'stats';
       fps: number;
@@ -155,6 +160,15 @@ type ReadyResolver = {
   reject: (err: Error) => void;
 };
 
+type PendingFrame = {
+  pose: Pose | null;
+  resolve: (result: { dropped: boolean; pose: Pose | null }) => void;
+  reject: (err: Error) => void;
+  timer: ReturnType<typeof setTimeout>;
+};
+
+const PUSH_FRAME_TIMEOUT_MS = 10_000;
+
 export class WebViewPoseBackend implements PoseBackend {
   readonly name = 'webview-movenet';
 
@@ -165,6 +179,9 @@ export class WebViewPoseBackend implements PoseBackend {
   /** True after the page successfully opened getUserMedia. */
   private cameraOpened = false;
   private openCameraHandler: (() => void) | undefined;
+  private pushFrameHandler: ((payload: string) => void) | undefined;
+  private frameSeq = 0;
+  private readonly pendingFrames = new Map<number, PendingFrame>();
   private lastPose: Pose | null = null;
   private inferenceTimesMs: number[] = [];
   private medianInferenceMs: number | null = null;
@@ -207,9 +224,24 @@ export class WebViewPoseBackend implements PoseBackend {
       // Drop stale GPU verdict from a previous warmer/page so the host does
       // not show acceleration=gpu while the next WebView is still booting.
       this.setAcceleration('unknown');
+      this.pushFrameHandler = undefined;
+      this.rejectPendingFrames('WebView detached while a frame was in flight.');
     }
   }
 
+  isAttached(): boolean {
+    return this.attached;
+  }
+
+  /** Model warm in the attached page (basic or full cold-start). */
+  isWarm(): boolean {
+    return this.warm;
+  }
+
+  getLastPose(): Pose | null {
+    return this.lastPose;
+  }
+
   setOnPose(handler: ((pose: Pose, inferenceTimeMs: number) => void) | undefined): void {
     this.onPose = handler;
   }
@@ -401,8 +433,71 @@ export class WebViewPoseBackend implements PoseBackend {
         timestampMs: msg.timestampMs,
       };
       this.lastPose = pose;
+      if (msg.frameId != null) {
+        const pending = this.pendingFrames.get(msg.frameId);
+        if (pending) pending.pose = pose;
+      }
       this.onPose?.(pose, msg.inferenceTimeMs);
+      return;
+    }
+
+    if (msg.type === 'frame_result') {
+      const pending = this.pendingFrames.get(msg.id);
+      if (!pending) return;
+      this.pendingFrames.delete(msg.id);
+      clearTimeout(pending.timer);
+      if (msg.error) {
+        pending.reject(new Error(`processFrame: ${msg.error}`));
+      } else {
+        pending.resolve({ dropped: msg.dropped === true, pose: pending.pose });
+      }
+    }
+  }
+
+  /** Host view injects `__PT_PUSH_FRAME` with the JSON payload. */
+  setPushFrameHandler(handler: ((payload: string) => void) | undefined): void {
+    this.pushFrameHandler = handler;
+  }
+
+  /**
+   * Infer one host-provided frame in the attached page. Resolves after the
+   * page posted the pose (already forwarded to `onPose`, hence the engine).
+   */
+  pushFrame(frame: ExternalFrame): Promise<{ dropped: boolean; pose: Pose | null }> {
+    const handler = this.pushFrameHandler;
+    if (!handler) {
+      return Promise.reject(
+        new Error('processFrame: no WebViewPoseView is attached. Call warmupExternal() first.'),
+      );
+    }
+    const id = ++this.frameSeq;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pendingFrames.delete(id);
+        reject(new Error('processFrame: timed out waiting for the pose runtime.'));
+      }, PUSH_FRAME_TIMEOUT_MS);
+      this.pendingFrames.set(id, { pose: null, resolve, reject, timer });
+      handler(
+        JSON.stringify({
+          id,
+          base64: frame.base64 ?? null,
+          uri: frame.uri ?? null,
+          mime: frame.mime ?? null,
+          width: frame.width,
+          height: frame.height,
+          timestampMs: frame.timestampMs,
+          mirrored: frame.mirrored !== false,
+        }),
+      );
+    });
+  }
+
+  private rejectPendingFrames(message: string): void {
+    for (const pending of this.pendingFrames.values()) {
+      clearTimeout(pending.timer);
+      pending.reject(new Error(`processFrame: ${message}`));
     }
+    this.pendingFrames.clear();
   }
 
   async init(_options: PoseBackendInitOptions): Promise<void> {
@@ -503,6 +598,8 @@ export class WebViewPoseBackend implements PoseBackend {
     this.cameraOpened = false;
     this.attached = false;
     this.openCameraHandler = undefined;
+    this.pushFrameHandler = undefined;
+    this.rejectPendingFrames('client disposed.');
     this.lastPose = null;
     this.acceleration = 'unknown';
     this.readyWaiters = [];

package/src/camera/WebViewPoseView.tsx

@@ -76,8 +76,9 @@ export interface WebViewPoseViewProps {
    */
   drawSkeleton?: boolean;
   /**
-   * Show a placement guide box (WebView `postureBox` parity) while the
+   * Show the placement zone (iframe `placementOverlay` parity) while the
    * active exercise reports `posture.ready === false`. Default `true`.
+   * Gray masks sit outside the box; the frame is the PoseTracker stroke.
    * Drawn as an RN sibling overlay (reliable on iOS; Android WebView may
    * composite above it — hosts can also render from `onPosture`).
    */
@@ -364,6 +365,12 @@ export function WebViewPoseView(props: WebViewPoseViewProps): React.ReactElement
         'window.__PT_OPEN_CAMERA && window.__PT_OPEN_CAMERA(); true;',
       );
     });
+    backend.setPushFrameHandler((payload) => {
+      const safe = payload.replace(/\u2028/g, '\\u2028').replace(/\u2029/g, '\\u2029');
+      webRef.current?.injectJavaScript?.(
+        `window.__PT_PUSH_FRAME && window.__PT_PUSH_FRAME(${safe}); true;`,
+      );
+    });
     // Live downgrades restart getUserMedia without remounting the WebView.
     client.setQualityApplyHandler((next) => {
       injectQuality(webRef, next);
@@ -371,6 +378,7 @@ export function WebViewPoseView(props: WebViewPoseViewProps): React.ReactElement
     return () => {
       backend.setOnPose(undefined);
       backend.setOpenCameraHandler(undefined);
+      backend.setPushFrameHandler(undefined);
       backend.setAttached(false);
       client.setQualityApplyHandler(undefined);
     };
@@ -475,18 +483,7 @@ export function WebViewPoseView(props: WebViewPoseViewProps): React.ReactElement
         }}
       />
       {showPlacementBox ? (
-        <View
-          pointerEvents="none"
-          style={[
-            styles.placementBox,
-            {
-              top: `${placementPaddingPercent}%`,
-              bottom: `${placementPaddingPercent}%`,
-              left: `${placementPaddingPercent}%`,
-              right: `${placementPaddingPercent}%`,
-            },
-          ]}
-        />
+        <PlacementZone paddingPercent={placementPaddingPercent} />
       ) : null}
       {/* Optional RN overlay (works on iOS; usually hidden under Android WebView surface). */}
       {props.children}
@@ -494,16 +491,40 @@ export function WebViewPoseView(props: WebViewPoseViewProps): React.ReactElement
   );
 }
 
+/** Iframe V4 placement: outside dim `#000` at 0.55, demo frame `#4DD21D`. */
+const PLACEMENT_DIM = 'rgba(0,0,0,0.55)';
+const PLACEMENT_STROKE = '#4DD21D';
+
+function PlacementZone({ paddingPercent }: { paddingPercent: number }) {
+  const pad = `${paddingPercent}%` as `${number}%`;
+  return (
+    <View pointerEvents="none" style={StyleSheet.absoluteFill}>
+      <View style={[styles.placementDim, { top: 0, left: 0, right: 0, height: pad }]} />
+      <View style={[styles.placementDim, { bottom: 0, left: 0, right: 0, height: pad }]} />
+      <View style={[styles.placementDim, { top: pad, bottom: pad, left: 0, width: pad }]} />
+      <View style={[styles.placementDim, { top: pad, bottom: pad, right: 0, width: pad }]} />
+      <View
+        style={[
+          styles.placementBox,
+          { top: pad, bottom: pad, left: pad, right: pad },
+        ]}
+      />
+    </View>
+  );
+}
+
 const styles = StyleSheet.create({
   fill: { flex: 1, backgroundColor: '#000' },
   center: { alignItems: 'center', justifyContent: 'center', padding: 16 },
   error: { color: '#FE8370', textAlign: 'center', fontSize: 13 },
-  /** Front drawPostureBox stroke `#FE8370`. */
+  placementDim: {
+    position: 'absolute',
+    backgroundColor: PLACEMENT_DIM,
+  },
   placementBox: {
     position: 'absolute',
-    borderWidth: 3,
-    borderColor: '#FE8370',
-    borderRadius: 8,
+    borderWidth: 2,
+    borderColor: PLACEMENT_STROKE,
     backgroundColor: 'transparent',
   },
 });

package/src/client.ts

@@ -58,6 +58,11 @@ import type {
   PoseTrackerStatus,
 } from './types/events';
 import type { Pose } from './types/pose';
+import {
+  isExternalFrame,
+  type ExternalFrame,
+  type ExternalFrameResult,
+} from './types/externalFrame';
 import type { AccelerationDiagnostics, AccelerationState } from './types/acceleration';
 import {
   defaultDiagnosticLogger,
@@ -237,6 +242,16 @@ export class PoseTrackerClient {
   /** Consecutive engine processPose failures (see SESSION_ERROR_STREAK_LIMIT). */
   private sessionErrorStreak = 0;
 
+  /**
+   * External frames (opt-in): the provider mounts a hidden basic warmer only
+   * when this is true. Never set on the default camera path.
+   */
+  private externalWarmerRequested = false;
+  private externalReady = false;
+  private externalInFlight = false;
+  /** Events emitted while one external frame is in flight. */
+  private externalCollector: PoseTrackerEvent[] | null = null;
+
   /** Requested tracking features with WebView-parity defaults applied. */
   private readonly features: ResolvedFeatures;
   /** WebView-only keys passed by untyped hosts (blazepose, poseEngine, …). */
@@ -1242,12 +1257,55 @@ export class PoseTrackerClient {
     return this.backend.estimatePose(frame);
   }
 
+  // -------------------------------------------------------------------------
+  // External frames (opt-in: the host app owns the camera)
+  // -------------------------------------------------------------------------
+
+  /** True once {@link warmupExternal} was called (provider mounts the warmer). */
+  isExternalWarmerRequested(): boolean {
+    return this.externalWarmerRequested;
+  }
+
+  /**
+   * Load the pose model for {@link processFrame} with external frames. Never
+   * opens the camera. Idempotent. With `PoseTrackerProvider`, a hidden 1×1
+   * basic WebView is mounted for this, unless a `WebViewPoseView` is already
+   * attached, in which case that view is reused.
+   */
+  async warmupExternal(): Promise<void> {
+    const backend = this.backend;
+    if (!(backend instanceof WebViewPoseBackend)) {
+      throw new Error('warmupExternal() requires the WebView backend (preferredBackend auto or webview).');
+    }
+    if (!this.externalWarmerRequested) {
+      this.externalWarmerRequested = true;
+      this.notifyState();
+    }
+    if (this.preloadPromise) {
+      await this.preloadPromise;
+    } else {
+      await this.preload({ coldStart: 'basic' });
+    }
+    await backend.warmup();
+    this.externalReady = true;
+  }
+
   /**
-   * Full pipeline for one camera frame: pose estimation + `keypoints` event
-   * (both modes), then engine processing when a session is active
-   * (full-engine mode). Mode upgrades take effect transparently here.
+   * External frame (`{ base64 | uri, width, height, timestampMs }`): infer it
+   * on the warm session and run the active exercise engine. Resolves with
+   * the pose and the events this frame produced; those events also reach
+   * the regular listeners. Nothing is drawn. One frame in flight: a call
+   * made while one is running resolves `{ dropped: true }` at once.
+   *
+   * Any other argument keeps the original behaviour: pose estimation +
+   * engine for a backend-specific frame.
    */
-  async processFrame(frame: PoseInputFrame): Promise<Pose | null> {
+  processFrame(frame: ExternalFrame): Promise<ExternalFrameResult>;
+  processFrame(frame: PoseInputFrame): Promise<Pose | null>;
+  async processFrame(frame: PoseInputFrame | ExternalFrame): Promise<Pose | null | ExternalFrameResult> {
+    if (isExternalFrame(frame)) {
+      return this.processExternalFrame(frame);
+    }
     const pose = await this.estimatePose(frame);
     if (!pose) {
       return null;
@@ -1256,6 +1314,37 @@ export class PoseTrackerClient {
     return pose;
   }
 
+  private async processExternalFrame(frame: ExternalFrame): Promise<ExternalFrameResult> {
+    const backend = this.backend;
+    if (!(backend instanceof WebViewPoseBackend)) {
+      throw new Error('processFrame: external frames require the WebView backend.');
+    }
+    if (!this.externalReady || !backend.isWarm()) {
+      throw new Error('processFrame: call warmupExternal() and wait for it to resolve first.');
+    }
+    if (backend.isCameraOpened()) {
+      throw new Error(
+        'processFrame: the SDK camera is open on this client. External frames and the SDK camera cannot run together.',
+      );
+    }
+    if (this.externalInFlight) {
+      return { dropped: true, pose: backend.getLastPose(), events: [] };
+    }
+    this.externalInFlight = true;
+    const events: PoseTrackerEvent[] = [];
+    this.externalCollector = events;
+    try {
+      const result = await backend.pushFrame(frame);
+      if (result.dropped) {
+        return { dropped: true, pose: backend.getLastPose(), events: [] };
+      }
+      return { dropped: false, pose: result.pose, events };
+    } finally {
+      this.externalCollector = null;
+      this.externalInFlight = false;
+    }
+  }
+
   /**
    * Feed an externally-estimated pose into the pipeline: `keypoints` event
    * (both modes) + engine processing when a session is active. This is how
@@ -1329,6 +1418,10 @@ export class PoseTrackerClient {
     this.lastCameraStartInfo = null;
     this.featureGateReported = { unsupported: false, freeBlock: false, missingToken: false };
     this.keypointsSuppressionLogged = false;
+    this.externalWarmerRequested = false;
+    this.externalReady = false;
+    this.externalInFlight = false;
+    this.externalCollector = null;
     this.engine = null;
     this.engineSource = null;
     this.manifest = null;
@@ -1375,6 +1468,7 @@ export class PoseTrackerClient {
   }
 
   private emit(event: PoseTrackerEvent): void {
+    this.externalCollector?.push(event);
     // A throwing host listener must never break other listeners or the frame
     // pipeline (emit is called from the per-frame ingest path).
     this.listeners.forEach((l) => {

package/src/index.ts

@@ -81,7 +81,11 @@ export { DEFAULT_SKELETON_DEFINITION } from './types/skeleton';
 export { fetchSkeletonDefinition, SkeletonFetchError } from './api/skeleton';
 export type { FetchSkeletonOptions } from './api/skeleton';
 export { PoseTrackerProvider, usePoseTracker } from './PoseTrackerProvider';
-export type { PoseTrackerContextValue, PoseTrackerProviderProps } from './PoseTrackerProvider';
+export type {
+  PoseTrackerContextValue,
+  PoseTrackerProviderProps,
+  ProcessFrameFn,
+} from './PoseTrackerProvider';
 
 // Inference backends
 export type { PoseBackend, PoseBackendInitOptions, PoseInputFrame } from './backends/PoseBackend';
@@ -256,3 +260,4 @@ export type { PoseTrackerFeatures, ResolvedFeatures } from './types/features';
 export * from './types/events';
 export * from './types/manifest';
 export * from './types/pose';
+export * from './types/externalFrame';

package/src/sdkVersion.ts

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