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

package/lib/types/manifest.d.ts

@@ -0,0 +1,197 @@
+/**
+ * Types for the `POST /api/sdk/configure` handshake response ("manifest").
+ *
+ * The manifest is the single source of truth for server-driven behavior:
+ * exercise definitions (angle thresholds, rep state machines), reference
+ * movements, engine bundle distribution and model profiles. Updating the
+ * manifest server-side changes SDK behavior without republishing the app.
+ */
+/**
+ * Model profiles (Sency-style). In v1 every profile maps to the bundled
+ * MoveNet SinglePose Lightning model; the fields below exist so the backend
+ * can later distribute per-profile models (e.g. Thunder for Prime, custom
+ * TFLite for native backends) without breaking older SDKs.
+ */
+export type PoseModelProfile = 'UltraLite' | 'Lite' | 'Pro' | 'Prime' | 'AdaptiveChoice';
+export type ModelFormat = 'tfjs-graph-model' | 'tflite' | 'coreml';
+export interface ModelDescriptor {
+    /** Stable identifier, e.g. "movenet-singlepose-lightning". */
+    modelId: string;
+    format: ModelFormat;
+    /** Square input resolution in pixels (192 for MoveNet Lightning). */
+    inputSize: number;
+    /**
+     * Signed (token-gated) download URL for a standalone model archive, or
+     * null/absent when the model is delivered by another channel (stub-loader
+     * architecture: MoveNet ships inside the `pose-runtime` payload).
+     */
+    signedUrl?: string | null;
+    /** SHA-256 hex digest of the downloadable archive (null when signedUrl is null). */
+    sha256?: string | null;
+    /** Delivery channel; 'pose-runtime' = part of the public runtime payload. */
+    deliveredBy?: 'pose-runtime';
+    version: string;
+}
+/** Maps each profile to a model. v1: all profiles point to the same MoveNet entry. */
+export type ModelsByProfile = Record<Exclude<PoseModelProfile, 'AdaptiveChoice'>, ModelDescriptor>;
+/**
+ * Full movement definition, mirroring the Strapi content-types
+ * (`api::movement.movement` + steps/parameters/recommendations/initial
+ * posture) that already drive the WebView engine. The remote engine bundle
+ * consumes this structure as-is, so movements/exercises created or tuned in
+ * the dashboard update SDK behavior without any republish.
+ */
+export interface MovementStepParameter {
+    /** Keypoint/angle selector; `a||b` accepts either side (front convention). */
+    name: string;
+    type: 'angle' | 'upper_y' | 'matching_y' | 'same_y' | 'matching_x' | 'same_x' | 'distance_y';
+    /** Weight of this parameter within the step (0–100). */
+    percentage: number;
+    operator?: string;
+    value?: number;
+    reference?: string;
+    /** When true, the parameter is included in `step_completion` payloads. */
+    public?: boolean;
+    /** Per-difficulty acceptance values (e.g. { easy: 90, medium: 100 }). */
+    scale_acceptance?: Record<string, number>;
+    /** Acceptance values when the camera point of view is elevated. */
+    upper_scale_acceptance?: Record<string, number>;
+}
+export interface MovementRecommendation {
+    name: string;
+    type: 'angle' | 'body_axe_without_arms' | 'upper_y' | 'matching_x';
+    operator: string;
+    value?: number;
+    reference?: string;
+    recommendation_text: string;
+    scale_acceptance?: Record<string, number>;
+    upper_scale_acceptance?: Record<string, number>;
+}
+export interface MovementStep {
+    name: string;
+    /** Order of the step within the movement (0-based). */
+    position: number;
+    /** Contribution of this step to the overall 0–100 progression. */
+    percentage: number;
+    /** Per-difficulty completion threshold to validate the step. */
+    scale_acceptance: Record<string, number>;
+    movement_parameters: MovementStepParameter[];
+    movement_recommendations: MovementRecommendation[];
+}
+export interface InitialPosture {
+    /** Expected orientation: 'face' or 'profile'. */
+    type: string;
+    /** Keypoints that must be visible inside the placement box. */
+    required_points: string[];
+    /** Placement box paddings, in % of the frame. */
+    padding_horizontal?: number | string;
+    padding_vertical?: number | string;
+}
+export interface MovementDefinition {
+    name: string;
+    type: 'dynamic' | 'static';
+    scale_acceptance: Record<string, number>;
+    movement_steps: MovementStep[];
+    movement_initial_posture: InitialPosture | null;
+    custom_skeleton?: string | null;
+    silhouette_image_url?: string | null;
+}
+export interface ExerciseConfig {
+    /** Stable identifier, e.g. "squat". */
+    id: string;
+    name: string;
+    type: 'dynamic' | 'static';
+    /**
+     * Full server-driven definition, consumed by the remote engine bundle.
+     * Exercise configs only ever exist behind a validated handshake (live or
+     * encrypted session cache) — the npm package ships zero movement
+     * intelligence (commercial boundary, see ARCHITECTURE.md §Modes).
+     */
+    movement: MovementDefinition;
+}
+export interface ReferenceMovementDescriptor {
+    uuid: string;
+    name: string;
+    /** Signed URL to the movement signature JSON (angles/ratios/deltas over time). */
+    signedSignatureUrl: string;
+    sha256: string;
+}
+export interface EngineBundleDescriptor {
+    version: string;
+    /** Signed, token-gated URL of the JS engine bundle. */
+    signedUrl: string;
+    /** SHA-256 hex digest used for integrity validation after download. */
+    sha256: string;
+    /** Minimum SDK version able to run this bundle (semver). */
+    minSdkVersion: string;
+    /** True when the version sent in `localVersions.engine` is already current. */
+    upToDate?: boolean;
+}
+export interface PoseRuntimePartDescriptor {
+    /** Download URL of this part (`GET /api/sdk/pose-runtime?part=...&v=...`). */
+    url: string;
+    /** SHA-256 hex digest, verified BEFORE the part is committed to the cache. */
+    sha256: string;
+    bytes: number;
+}
+/**
+ * Descriptor of the public pose estimation payload (TF.js + MoveNet +
+ * proprietary pipeline wasm + page runtime). No API key required: pose
+ * estimation is the free tier; the movement engine stays key-gated.
+ */
+export interface PoseRuntimeDescriptor {
+    version: string;
+    /** True when the version sent in `localVersions.poseRuntime` is current. */
+    upToDate?: boolean;
+    baseUrl?: string;
+    /** Parts by name: tfjs, tfjs-wasm, model, weights, pipeline, runtime. */
+    parts: Record<string, PoseRuntimePartDescriptor>;
+}
+export interface ConfigureRequest {
+    /** Optional: keyless handshakes get the public manifest (pose-runtime only). */
+    apiToken?: string;
+    sdkName: 'posetracker-rn' | 'posetracker-rn-light';
+    sdkVersion: string;
+    targetPlatform: 'ios' | 'android';
+    /** Requested profile; the backend may downgrade it based on plan. */
+    poseModelProfile: PoseModelProfile;
+    /** Locale for localized strings in configs (hints, recommendations). */
+    locale?: string;
+    /**
+     * Versions currently committed to the local caches; the backend answers
+     * with `upToDate` flags per module so unchanged payloads are not
+     * re-downloaded.
+     */
+    localVersions?: {
+        poseRuntime?: string | null;
+        engine?: string | null;
+    };
+}
+export interface PlanInfo {
+    plan: string;
+    /** Remaining API calls for the current period; null = unlimited. */
+    remainingCalls: number | null;
+    commercialUse: boolean;
+}
+export interface SdkManifest {
+    /**
+     * Short-lived session token for follow-up SDK requests (downloads, usage
+     * pings). Null on keyless handshakes (public manifest).
+     */
+    sessionToken: string | null;
+    /** Null on keyless handshakes. */
+    plan: PlanInfo | null;
+    models: ModelsByProfile;
+    /** Profile the backend resolved for this device/plan. */
+    resolvedProfile: Exclude<PoseModelProfile, 'AdaptiveChoice'>;
+    /** Public pose estimation payload (always present, key or not). */
+    poseRuntime: PoseRuntimeDescriptor | null;
+    /** Null on keyless handshakes or when no engine bundle is deployed. */
+    engine: EngineBundleDescriptor | null;
+    exercises: ExerciseConfig[];
+    referenceMovements: ReferenceMovementDescriptor[];
+    /** Revocation signal: when true the SDK purges its sealed engine cache. */
+    revoked?: boolean;
+    /** Unix epoch ms after which the SDK should re-run the handshake. */
+    expiresAt: number;
+}

package/lib/types/manifest.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Types for the `POST /api/sdk/configure` handshake response ("manifest").
+ *
+ * The manifest is the single source of truth for server-driven behavior:
+ * exercise definitions (angle thresholds, rep state machines), reference
+ * movements, engine bundle distribution and model profiles. Updating the
+ * manifest server-side changes SDK behavior without republishing the app.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/types/pose.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Backend-agnostic pose types.
+ *
+ * MoveNet backends emit the 17-point COCO topology. Apple Vision
+ * (`VNDetectHumanBodyPoseRequest`) emits those 17 plus two extras
+ * (`neck`, `root`) — see `VISION_EXTRA_KEYPOINT_NAMES` and
+ * docs/NATIVE_POSE_BACKENDS.md. Downstream engine code that only knows
+ * COCO safely ignores unknown names.
+ */
+export type CocoKeypointName = 'nose' | 'left_eye' | 'right_eye' | 'left_ear' | 'right_ear' | 'left_shoulder' | 'right_shoulder' | 'left_elbow' | 'right_elbow' | 'left_wrist' | 'right_wrist' | 'left_hip' | 'right_hip' | 'left_knee' | 'right_knee' | 'left_ankle' | 'right_ankle';
+/** Extra joints from Apple Vision body pose (not in COCO-17 / MoveNet). */
+export type VisionExtraKeypointName = 'neck' | 'root';
+export type KeypointName = CocoKeypointName | VisionExtraKeypointName;
+export declare const COCO_KEYPOINT_NAMES: readonly CocoKeypointName[];
+/** Vision-only joints appended after the COCO-aligned 17. */
+export declare const VISION_EXTRA_KEYPOINT_NAMES: readonly VisionExtraKeypointName[];
+/** Full Apple Vision body-pose set (19): COCO-17 + neck + root. */
+export declare const VISION_KEYPOINT_NAMES: readonly KeypointName[];
+export interface Keypoint {
+    name: KeypointName;
+    /** Horizontal position, normalized to [0, 1] relative to the input image width. */
+    x: number;
+    /** Vertical position, normalized to [0, 1] relative to the input image height. */
+    y: number;
+    /** Optional depth (reserved for future 3D-capable backends). */
+    z?: number;
+    /** Confidence score in [0, 1]. */
+    score: number;
+}
+export interface Pose {
+    keypoints: Keypoint[];
+    /** Overall pose confidence in [0, 1] (mean of keypoint scores for MoveNet). */
+    score: number;
+    /** Capture timestamp in milliseconds (host clock). */
+    timestampMs: number;
+}

package/lib/types/pose.js

@@ -0,0 +1,41 @@
+"use strict";
+/**
+ * Backend-agnostic pose types.
+ *
+ * MoveNet backends emit the 17-point COCO topology. Apple Vision
+ * (`VNDetectHumanBodyPoseRequest`) emits those 17 plus two extras
+ * (`neck`, `root`) — see `VISION_EXTRA_KEYPOINT_NAMES` and
+ * docs/NATIVE_POSE_BACKENDS.md. Downstream engine code that only knows
+ * COCO safely ignores unknown names.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.VISION_KEYPOINT_NAMES = exports.VISION_EXTRA_KEYPOINT_NAMES = exports.COCO_KEYPOINT_NAMES = void 0;
+exports.COCO_KEYPOINT_NAMES = [
+    'nose',
+    'left_eye',
+    'right_eye',
+    'left_ear',
+    'right_ear',
+    'left_shoulder',
+    'right_shoulder',
+    'left_elbow',
+    'right_elbow',
+    'left_wrist',
+    'right_wrist',
+    'left_hip',
+    'right_hip',
+    'left_knee',
+    'right_knee',
+    'left_ankle',
+    'right_ankle',
+];
+/** Vision-only joints appended after the COCO-aligned 17. */
+exports.VISION_EXTRA_KEYPOINT_NAMES = [
+    'neck',
+    'root',
+];
+/** Full Apple Vision body-pose set (19): COCO-17 + neck + root. */
+exports.VISION_KEYPOINT_NAMES = [
+    ...exports.COCO_KEYPOINT_NAMES,
+    ...exports.VISION_EXTRA_KEYPOINT_NAMES,
+];

package/lib/types/preload.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Cold-start / preload modes for {@link PoseTrackerClient.preload}.
+ *
+ * - `basic` (default): load MoveNet + warm TF.js/WebGL with zero tensors.
+ *   Does **not** call `getUserMedia` — no unexpected camera permission prompt.
+ * - `full`: also open the camera during warm-up (legacy behaviour). Only use
+ *   when the host UI is already in a camera context the user expects.
+ */
+export type ColdStartMode = 'basic' | 'full';
+export interface PreloadOptions {
+    /**
+     * Cold-start depth. Default `basic`.
+     * Pass `full` only when you intentionally want getUserMedia during preload
+     * (e.g. a visible camera screen that also warms the model).
+     */
+    coldStart?: ColdStartMode;
+}

package/lib/types/preload.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Cold-start / preload modes for {@link PoseTrackerClient.preload}.
+ *
+ * - `basic` (default): load MoveNet + warm TF.js/WebGL with zero tensors.
+ *   Does **not** call `getUserMedia` — no unexpected camera permission prompt.
+ * - `full`: also open the camera during warm-up (legacy behaviour). Only use
+ *   when the host UI is already in a camera context the user expects.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/types/skeleton.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Skeleton overlay definition — same JSON shape as Strapi `api::skeleton.skeleton`
+ * / PoseTrackerFront `DEFAULT_SKELETON` (WebView `?skeleton=<api_uuid>`).
+ */
+export interface SkeletonCirclesStyle {
+    circleFillColor: string;
+    circleStrokeColor: string;
+    strokeWidth: string | number;
+    radius: string | number;
+}
+export interface SkeletonLinesStyle {
+    lineStrokeColor: string;
+    strokeWidth: string | number;
+}
+export interface SkeletonAnglesStyle {
+    fontColor?: string;
+    strokeColor?: string;
+}
+export interface SkeletonDefinition {
+    keypoints: string[];
+    /** Named pairs `"left_hip||left_knee"`. */
+    keypoint_lines: string[];
+    keypoint_angles?: string[];
+    circles: SkeletonCirclesStyle;
+    lines: SkeletonLinesStyle;
+    angles?: SkeletonAnglesStyle;
+}
+/** PoseTracker API default (navy `#010A73` + gold `#FFC300`). */
+export declare const DEFAULT_SKELETON_DEFINITION: SkeletonDefinition;

package/lib/types/skeleton.js

@@ -0,0 +1,52 @@
+"use strict";
+/**
+ * Skeleton overlay definition — same JSON shape as Strapi `api::skeleton.skeleton`
+ * / PoseTrackerFront `DEFAULT_SKELETON` (WebView `?skeleton=<api_uuid>`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_SKELETON_DEFINITION = void 0;
+/** PoseTracker API default (navy `#010A73` + gold `#FFC300`). */
+exports.DEFAULT_SKELETON_DEFINITION = {
+    keypoints: [
+        'nose',
+        'left_eye',
+        'right_eye',
+        'left_ear',
+        'right_ear',
+        'left_shoulder',
+        'right_shoulder',
+        'left_elbow',
+        'right_elbow',
+        'left_wrist',
+        'right_wrist',
+        'left_hip',
+        'right_hip',
+        'left_knee',
+        'right_knee',
+        'left_ankle',
+        'right_ankle',
+    ],
+    keypoint_lines: [
+        'right_shoulder||left_shoulder',
+        'right_hip||left_hip',
+        'right_hip||right_shoulder',
+        'right_hip||right_knee',
+        'right_ankle||right_knee',
+        'right_shoulder||right_elbow',
+        'right_wrist||right_elbow',
+        'left_hip||left_shoulder',
+        'left_hip||left_knee',
+        'left_ankle||left_knee',
+        'left_shoulder||left_elbow',
+        'left_wrist||left_elbow',
+    ],
+    keypoint_angles: [],
+    angles: { fontColor: '#000000', strokeColor: '#FFC300' },
+    circles: {
+        circleFillColor: '#010A73',
+        circleStrokeColor: '#FFC300',
+        strokeWidth: '4',
+        radius: '8',
+    },
+    lines: { lineStrokeColor: '#010A73', strokeWidth: '4' },
+};

package/package.json

@@ -0,0 +1,92 @@
+{
+  "name": "@pose-tracker/react-native-pose-estimation-light",
+  "version": "0.1.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",
+  "source": "src/index.ts",
+  "react-native": "lib/index.js",
+  "files": [
+    "lib",
+    "src",
+    "!src/backends/webview/poseRuntimeSource.js",
+    "ios",
+    "PoseTrackerVision.podspec",
+    "react-native.config.js",
+    "README.md",
+    "LICENSE",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "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",
+    "embed:runtime": "node scripts/embed-pose-runtime.mjs",
+    "prepack": "npm run build",
+    "pack:dry": "npm pack --dry-run"
+  },
+  "keywords": [
+    "human-pose-estimation",
+    "pose-estimation",
+    "react-native",
+    "react-native-pose-estimation",
+    "ios",
+    "android",
+    "expo",
+    "expo-go",
+    "movenet",
+    "computer-vision",
+    "fitness",
+    "exercise-tracking",
+    "keypoints",
+    "posetracker",
+    "online-ai",
+    "light-sdk",
+    "webview",
+    "sdk"
+  ],
+  "author": {
+    "name": "Movelytics SAS",
+    "email": "hello@posetracker.com",
+    "url": "https://www.posetracker.com"
+  },
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://github.com/Movelytics/react-native-pose-estimation-light#readme",
+  "bugs": {
+    "url": "https://github.com/Movelytics/react-native-pose-estimation-light/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Movelytics/react-native-pose-estimation-light.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "js-sha256": "^0.11.0"
+  },
+  "peerDependencies": {
+    "expo-file-system": ">=15.0.0",
+    "react": ">=18.0.0",
+    "react-native": ">=0.72.0",
+    "react-native-blob-util": ">=0.19.0",
+    "react-native-fs": ">=2.20.0",
+    "react-native-webview": ">=13.0.0"
+  },
+  "peerDependenciesMeta": {
+    "expo-file-system": {
+      "optional": true
+    },
+    "react-native-fs": {
+      "optional": true
+    },
+    "react-native-blob-util": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^18.2.0",
+    "react": "^18.2.0",
+    "react-native": "^0.74.0",
+    "typescript": "^5.4.0"
+  }
+}

package/react-native.config.js

@@ -0,0 +1,12 @@
+/**
+ * Autolinking: Apple Vision frame-processor plugin is iOS-only.
+ * Android hosts skip the native project (JS falls back to TFLite / TF.js).
+ */
+module.exports = {
+  dependency: {
+    platforms: {
+      android: null,
+      ios: {},
+    },
+  },
+};