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

package/lib/types/acceleration.d.ts

@@ -0,0 +1,86 @@
+/**
+ * GPU-acceleration status types.
+ *
+ * Historical context (see docs/ANDROID_GL_ACCELERATION.md): on Android the
+ * previous product generation had to run TF.js inside a WebView because it
+ * was the only reliable way to get a working WebGL backend. The native path
+ * (tfjs-react-native over expo-gl) can silently degrade — the platform
+ * adapter *shims* float-texture extension queries, so TF.js may believe the
+ * GPU supports float32 render targets when it does not, and expo-gl contexts
+ * die on Android when the surface is backgrounded. These types exist so the
+ * SDK reports an explicit acceleration verdict instead of failing silently
+ * into a 1-2 fps CPU fallback.
+ */
+/**
+ * - 'unknown':       warm-up has not completed yet.
+ * - 'gpu':           rn-webgl (expo-gl) active and the warm-up health check
+ *                    produced sane outputs within the latency budget.
+ * - 'cpu-fallback':  inference works but is NOT GPU-accelerated (rn-webgl
+ *                    failed to initialize, produced NaN/garbage, or was
+ *                    pathologically slow — i.e. software rendering).
+ * - 'unavailable':   no backend could run the model at all (fatal; the
+ *                    client also reports status 'error').
+ */
+export type AccelerationState = 'unknown' | 'gpu' | 'cpu-fallback' | 'unavailable';
+/** Raw GL context facts, gathered best-effort after backend init. */
+export interface GlCapabilities {
+    /** e.g. "OpenGL ES 3.0 ..." */
+    glVersion: string | null;
+    /** e.g. "Adreno (TM) 640", "Mali-G78", "PowerVR ..." — key for triage. */
+    renderer: string | null;
+    vendor: string | null;
+    maxTextureSize: number | null;
+    /**
+     * Extension presence *as reported to TF.js*. WARNING: on rn-webgl the
+     * tfjs-react-native platform adapter shims `getExtension` and always
+     * reports EXT_color_buffer_float (Android) / EXT_color_buffer_half_float
+     * as present, so `true` here does NOT prove hardware support. That lie is
+     * exactly why the SDK forces f16 textures on Android and validates real
+     * outputs in the health check.
+     */
+    colorBufferFloat: boolean;
+    colorBufferHalfFloat: boolean;
+    textureFloat: boolean;
+    textureHalfFloat: boolean;
+    /** True when the extension answers above come from the shimmed adapter. */
+    extensionQueriesShimmed: boolean;
+}
+/** Snapshot of the TF.js WebGL flags that matter for Android stability. */
+export type TfjsFlagSnapshot = Record<string, boolean | number | string | null>;
+/**
+ * Inference runtime that produced the acceleration verdict:
+ * - 'webview': TF.js MoveNet inside a Chromium/WKWebView (ANGLE WebGL) —
+ *              the SDK's base runtime, offline, same stack as the
+ *              PoseTracker WebView product.
+ * - 'vision':  Apple Vision (`VNDetectHumanBodyPoseRequest`) — iOS only.
+ */
+export type InferenceRuntime = 'webview' | 'vision';
+/** Native accelerator label (Apple Vision). */
+export type VisionDelegateLabel = 'apple-vision';
+export type NativeDelegateLabel = VisionDelegateLabel;
+export interface AccelerationDiagnostics {
+    state: AccelerationState;
+    /** Active TF.js backend after init/fallbacks: 'rn-webgl' | 'cpu' | null. */
+    tfjsBackend: string | null;
+    /** Which runtime produced this verdict (absent = 'tfjs', pre-TFLite SDKs). */
+    runtime?: InferenceRuntime;
+    /** Active native accelerator; null/absent for the TF.js backend. */
+    delegate?: NativeDelegateLabel | null;
+    /** Median duration of the timed warm-up inferences, in ms. */
+    medianInferenceMs: number | null;
+    /** Individual timed warm-up runs, in ms (first run includes shader compilation). */
+    inferenceTimesMs: number[];
+    /** Latency budget used by the health check to accept the GPU path. */
+    maxAcceptableInferenceMs: number;
+    capabilities: GlCapabilities | null;
+    flags: TfjsFlagSnapshot;
+    /** Number of GL context losses recovered since init (Android lifecycle). */
+    contextLossCount: number;
+    /**
+     * Human-readable trail of every downgrade / recovery decision, e.g.
+     * "rn-webgl produced NaN outputs — falling back to CPU".
+     */
+    reasons: string[];
+}
+/** Callback for host apps that want SDK diagnostics in their own logger. */
+export type DiagnosticListener = (message: string) => void;

package/lib/types/acceleration.js

@@ -0,0 +1,15 @@
+"use strict";
+/**
+ * GPU-acceleration status types.
+ *
+ * Historical context (see docs/ANDROID_GL_ACCELERATION.md): on Android the
+ * previous product generation had to run TF.js inside a WebView because it
+ * was the only reliable way to get a working WebGL backend. The native path
+ * (tfjs-react-native over expo-gl) can silently degrade — the platform
+ * adapter *shims* float-texture extension queries, so TF.js may believe the
+ * GPU supports float32 render targets when it does not, and expo-gl contexts
+ * die on Android when the surface is backgrounded. These types exist so the
+ * SDK reports an explicit acceleration verdict instead of failing silently
+ * into a 1-2 fps CPU fallback.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/types/events.d.ts

@@ -0,0 +1,345 @@
+/**
+ * SDK event types.
+ *
+ * These mirror the postMessage payloads of the existing PoseTracker WebView
+ * API (keypoints, angles, counter, posture, progression, recommendations,
+ * form_score, exercise_summary) so existing integrations can migrate with
+ * minimal changes: the WebView `onMessage` JSON becomes a typed callback.
+ */
+import type { Keypoint } from './pose';
+import type { AccelerationState } from './acceleration';
+import type { QualityProfile, QualityProfileId } from '../quality/profiles';
+export type PoseTrackerStatus = 'idle' | 'configuring' | 'downloading' | 'warming' | 'ready' | 'error';
+/**
+ * Operating mode (commercial boundary):
+ * - 'keypoints-only': no validated API key/session — the SDK provides its
+ *   core value only (bundled MoveNet, warm-up, camera pipeline) and streams
+ *   raw `keypoints` events. No business events (counter, angles, posture,
+ *   progression, recommendations, form_score, exercise_summary).
+ * - 'full-engine': a handshake succeeded (live or from the encrypted local
+ *   session cache) and the engine bundle is loaded — all events available.
+ *
+ * The mode can upgrade at runtime (keypoints-only → full-engine) without
+ * restarting the camera pipeline, via `configure()` or a preload retry.
+ */
+export type PoseTrackerMode = 'keypoints-only' | 'full-engine';
+export type InitializationStep = 'configuring' | 'downloading' | 'warming' | 'accessing_webcam' | 'loading_pose_model' | 'ready';
+export interface InitializationEvent {
+    type: 'initialization';
+    /**
+     * Machine step. Classic PoseTracker used free-form `message` strings
+     * ("accessing webcam", "loading pose model", "running"); both are set.
+     */
+    step: InitializationStep;
+    /** Human-readable status (PoseTracker WebView parity). */
+    message: string;
+    ready: boolean;
+    /** Present on the `ready` step. */
+    mode?: PoseTrackerMode;
+    /**
+     * Present on the `ready` step: GPU-acceleration verdict from the warm-up
+     * health check ('gpu' | 'cpu-fallback' | 'unavailable'). See
+     * docs/ANDROID_GL_ACCELERATION.md.
+     */
+    acceleration?: AccelerationState;
+}
+export interface ErrorEvent {
+    type: 'error';
+    code: 'invalid_token' | 'quota_exceeded' | 'network'
+    /**
+     * First launch, no network, empty runtime cache: the pose runtime cannot
+     * be initialized without downloading the payload once. Fatal.
+     */
+     | 'network_required'
+    /**
+     * Offline with an API key: metered features (engine/exercises) are
+     * refused because PoseTracker cannot count their usage. Non-fatal —
+     * keypoints-only keeps running from the cache.
+     */
+     | 'offline_metered'
+    /**
+     * The `free` plan requested developer features (angles, recommendations,
+     * progression, or keypoints combined with an exercise). Same message as
+     * the PoseTracker WebView (`TrackingAppV3`). Non-fatal: keypoints-only
+     * pose estimation keeps running.
+     */
+     | 'free_plan_feature_blocked'
+    /**
+     * A WebView-only option was requested (blazepose, poseEngine,
+     * mediapipeModel, …): this SDK ships MoveNet Lightning only.
+     */
+     | 'feature_not_supported'
+    /** Unknown exercise id (WebView parity: `invalid_exercise`). */
+     | 'invalid_exercise'
+    /** jump_analysis requires `userHeightCm` (WebView parity). */
+     | 'jump_analysis_missing_height' | 'model_load_failed' | 'engine_load_failed' | 'integrity_check_failed' | 'webview_error' | 'device_too_slow' | 'backend_fallback_wasm' | 'internal';
+    message: string;
+}
+/**
+ * Non-fatal warning the host can surface (telemetry / soft UX).
+ * Classic WebView sometimes used `type: "warning"`; V3 degradations often
+ * reuse `type: "error"` with a code — see {@link PerformanceWarningEvent}.
+ */
+export interface WarningEvent {
+    type: 'warning';
+    code: 'quality_downgraded' | 'backend_fallback_wasm' | 'webview' | 'internal';
+    message: string;
+    timestampMs: number;
+}
+export interface KeypointsEvent {
+    type: 'keypoints';
+    keypoints: Keypoint[];
+    /** Mean confidence of the pose. */
+    score: number;
+    timestampMs: number;
+}
+export interface AngleValue {
+    /** Angle id from the exercise config, e.g. "left_knee". */
+    id: string;
+    side: 'left' | 'right' | 'center';
+    degrees: number;
+    /** Min confidence of the three keypoints defining the angle. */
+    score: number;
+}
+export interface AnglesEvent {
+    type: 'angles';
+    angles: AngleValue[];
+    timestampMs: number;
+}
+/**
+ * Letter grade for a 0–100 form score (GitBook / Front BaseExercise):
+ * A ≥ 90, B ≥ 80, C ≥ 70, D ≥ 60, F < 60.
+ */
+export type FormGrade = 'A' | 'B' | 'C' | 'D' | 'F';
+/** Valid `minGrade` filter values (F is not a valid minGrade config). */
+export type MinGrade = 'A' | 'B' | 'C' | 'D';
+/**
+ * Nested form score on a counted rep — GitBook / WebView V3
+ * `counter.form_score` (authoritative grade for that rep).
+ */
+export interface CounterFormScore {
+    /** Score of the rep that was just counted, 0–100. */
+    score: number;
+    /** Running average across counted reps, 0–100. */
+    average: number;
+    grade: FormGrade;
+}
+export interface CounterEvent {
+    type: 'counter';
+    count: number;
+    /**
+     * Authoritative form score for the counted rep (WebView
+     * `counter.form_score`). Prefer this over a standalone `form_score` event
+     * when mirroring the tracking endpoint.
+     */
+    formScore?: CounterFormScore;
+    /** Similarity score vs. reference movement for the last rep, when a reference is active. */
+    referenceScore?: number;
+    timestampMs: number;
+}
+export interface PostureEvent {
+    type: 'posture';
+    /** True when the user placement satisfies the exercise posture requirements. */
+    ready: boolean;
+    /** Localized human hint ("Face the camera", "Get ready…"). */
+    hint: string;
+    /** WebView parity: placement direction hint ("in-frame", "face-camera", "profile-camera"). */
+    direction?: string;
+    missingKeypoints: string[];
+    timestampMs: number;
+}
+export interface ProgressionEvent {
+    type: 'progression';
+    /** Movement progression within the current rep, 0–100. */
+    value: number;
+    timestampMs: number;
+}
+export interface RecommendationsEvent {
+    type: 'recommendations';
+    /** Localized form advice strings. */
+    recommendations: string[];
+    timestampMs: number;
+}
+export interface FormScoreEvent {
+    type: 'form_score';
+    /** Score of the last completed rep, 0–100. */
+    score: number;
+    /** Running average across the session, 0–100. */
+    average: number;
+    grade: FormGrade;
+    timestampMs: number;
+}
+export interface RepSummary {
+    index: number;
+    formScore: number;
+    durationMs: number;
+    referenceScore?: number;
+}
+export interface ExerciseSummaryEvent {
+    type: 'exercise_summary';
+    exercise: string;
+    counter: number;
+    averageFormScore: number;
+    averageSimilarity?: number;
+    grade: FormGrade;
+    history: RepSummary[];
+    durationMs: number;
+    timestampMs: number;
+}
+export interface VisibleHipsInfo {
+    left: boolean;
+    right: boolean;
+}
+/** jump_analysis only: cm/pixel calibration established from userHeightCm. */
+export interface JumpCalibrationEvent {
+    type: 'jump_calibration';
+    calibrated: true;
+    cmPerPixel: number;
+    baselineY: number | null;
+    visibleHips: VisibleHipsInfo;
+    /** WebView literal: "Calibration complete - ready to jump". */
+    message: string;
+    timestampMs: number;
+}
+/** Push-off detected — measurement in progress. */
+export interface JumpStartedEvent {
+    type: 'jump_started';
+    /** WebView literal: "Jump detected - measuring height". */
+    message: string;
+    timestampMs: number;
+}
+/** Live/final jump height. `final: true` closes the jump (see JumpResultEvent). */
+export interface JumpHeightEvent {
+    type: 'jump_height';
+    jumpHeightCm: number;
+    baselineY?: number | null;
+    minY?: number | null;
+    measuring: boolean;
+    landed: boolean;
+    final?: boolean;
+    deltaPixels?: number;
+    sideUsed?: string | null;
+    airTimeMs?: number;
+    airTimeSeconds?: number;
+    visibleHips?: VisibleHipsInfo;
+    timestampMs: number;
+}
+/** Detection aborted (approach toward camera, timeout, tracking lost…). */
+export interface JumpDiscardedEvent {
+    type: 'jump_discarded';
+    reason: string;
+    userMessage: string;
+    timestampMs: number;
+}
+/** One completed jump (final height for jump N). */
+export interface JumpResultEvent {
+    type: 'jump_result';
+    jumpNumber: number;
+    jumpHeightCm: number;
+    airTimeMs?: number;
+    airTimeSeconds?: number;
+    baselineY?: number | null;
+    minY?: number | null;
+    deltaPixels?: number;
+    sideUsed?: string | null;
+    visibleHips?: VisibleHipsInfo;
+    timestampMs: number;
+}
+export interface JumpSummaryEntry {
+    jumpNumber: number;
+    jumpHeightCm: number;
+    airTimeMs?: number;
+    airTimeSeconds?: number;
+}
+/** Running summary of all completed jumps (emitted after each jump_result). */
+export interface JumpSummaryEvent {
+    type: 'jump_summary';
+    totalJumps: number;
+    avgJumpHeight: number;
+    maxJumpHeight: number;
+    minJumpHeight: number;
+    avgAirTimeSeconds?: number;
+    jumps: JumpSummaryEntry[];
+    timestampMs: number;
+}
+/**
+ * Camera / preprocess quality tier changed (AdaptiveChoice auto-downgrade,
+ * crash-guard recovery, or GL capability hint). English, for app developers.
+ */
+export interface QualityChangedEvent {
+    type: 'quality_changed';
+    previousProfile: QualityProfileId;
+    activeProfile: QualityProfileId;
+    reason: 'low_fps' | 'device_capability' | 'crash_guard' | 'warmup_estimate' | 'manual';
+    detail: string;
+    profile: QualityProfile;
+    /** Present when reason is warmup_estimate / low_fps. */
+    estimatedFps?: number | null;
+    medianInferenceMs?: number | null;
+    timestampMs: number;
+}
+/**
+ * Fired when mean inference FPS stays critically low. English developer alert —
+ * surface in your own telemetry / support tooling; do not show raw to end users
+ * unless you localize it.
+ */
+export interface PerformanceWarningEvent {
+    type: 'performance_warning';
+    code: 'device_too_slow';
+    message: string;
+    meanFps: number;
+    thresholdFps: number;
+    activeProfile: QualityProfileId;
+    medianInferenceMs: number | null;
+    videoSize?: string;
+    timestampMs: number;
+}
+/**
+ * Download progress of the pose-runtime payload (first preload, or version
+ * update). Lets the host app show a loader/progress bar during the initial
+ * ~9 MB download; never fired when the cache is already up-to-date.
+ */
+export interface RuntimeDownloadProgressEvent {
+    type: 'runtime_download_progress';
+    /** Part being downloaded (tfjs, tfjs-wasm, model, weights, pipeline, runtime). */
+    part: string;
+    completedParts: number;
+    totalParts: number;
+    /** Size of the current part, from the signed manifest. */
+    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 PoseTrackerEventType = PoseTrackerEvent['type'];
+export type PoseTrackerEventListener = (event: PoseTrackerEvent) => void;
+/**
+ * Typed per-event callbacks, convenient for `usePoseTracker({ onCounter, ... })`.
+ * Also accepts {@link onMessage} for classic PoseTracker WebView JSON parity.
+ */
+export interface PoseTrackerCallbacks {
+    onInitialization?: (event: InitializationEvent) => void;
+    onError?: (event: ErrorEvent) => void;
+    onWarning?: (event: WarningEvent) => void;
+    onKeypoints?: (event: KeypointsEvent) => void;
+    onAngles?: (event: AnglesEvent) => void;
+    onCounter?: (event: CounterEvent) => void;
+    onPosture?: (event: PostureEvent) => void;
+    onProgression?: (event: ProgressionEvent) => void;
+    onRecommendations?: (event: RecommendationsEvent) => void;
+    onFormScore?: (event: FormScoreEvent) => void;
+    onExerciseSummary?: (event: ExerciseSummaryEvent) => void;
+    onJumpCalibration?: (event: JumpCalibrationEvent) => void;
+    onJumpStarted?: (event: JumpStartedEvent) => void;
+    onJumpHeight?: (event: JumpHeightEvent) => void;
+    onJumpDiscarded?: (event: JumpDiscardedEvent) => void;
+    onJumpResult?: (event: JumpResultEvent) => void;
+    onJumpSummary?: (event: JumpSummaryEvent) => void;
+    onQualityChanged?: (event: QualityChangedEvent) => void;
+    onPerformanceWarning?: (event: PerformanceWarningEvent) => void;
+    onRuntimeDownloadProgress?: (event: RuntimeDownloadProgressEvent) => void;
+    /**
+     * Classic PoseTracker `sendDataToNative` JSON stream (same `type` / field
+     * names as the WebView product). Fires for every typed event.
+     */
+    onMessage?: (message: import('../events/classicMessage').ClassicNativeMessage) => void;
+}

package/lib/types/events.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * SDK event types.
+ *
+ * These mirror the postMessage payloads of the existing PoseTracker WebView
+ * API (keypoints, angles, counter, posture, progression, recommendations,
+ * form_score, exercise_summary) so existing integrations can migrate with
+ * minimal changes: the WebView `onMessage` JSON becomes a typed callback.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/lib/types/features.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Host-selectable tracking features — SDK port of the PoseTracker WebView
+ * query params (`/pose_tracker/tracking?angles=true&…`) with the SAME plan
+ * gating and the SAME error messages as `TrackingAppV3`.
+ *
+ * Rules (mirroring the WebView product):
+ * - Without an API key the SDK always runs keypoints-only (offline, free,
+ *   no gating) — pose-only mode streams `keypoints` unconditionally.
+ * - `angles`, `recommendations`, `progression` require a PAID plan
+ *   (anything but `free`).
+ * - `keypoints` DURING an exercise session requires a paid plan too
+ *   (free may stream keypoints only in pose-only mode, i.e. no exercise).
+ * - `blazepose` / `poseEngine` / `mediapipeModel` / `poseBackend` /
+ *   `runInWorker` are NOT part of this SDK (MoveNet Lightning only) and are
+ *   rejected with a clear error.
+ */
+import type { MinGrade } from './events';
+export interface PoseTrackerFeatures {
+    /**
+     * Stream `angles` events during an exercise session. Default `false`
+     * (WebView parity: `angles="false"`). Paid plans only.
+     */
+    angles?: boolean;
+    /**
+     * Stream `recommendations` events (form advice) during an exercise
+     * session. Default `false`. Paid plans only.
+     */
+    recommendations?: boolean;
+    /**
+     * Stream `progression` events (0–100 within the rep) during an exercise
+     * session. Default `false`. Paid plans only.
+     */
+    progression?: boolean;
+    /**
+     * Stream raw `keypoints` events DURING an exercise session. Default
+     * `false` (WebView parity: free plans cannot combine keypoints with an
+     * exercise). Outside a session (pose-only mode) keypoints always stream —
+     * that is the SDK's free offline base and is never gated.
+     */
+    keypoints?: boolean;
+    /**
+     * Only count reps whose form grade is at or above this letter (`A` best).
+     * WebView parity: `minGrade` query param (`A`…`D` only). Works on all
+     * plans that can run the exercise.
+     */
+    minGrade?: MinGrade;
+}
+/** Feature keys after defaults are applied. */
+export interface ResolvedFeatures {
+    angles: boolean;
+    recommendations: boolean;
+    progression: boolean;
+    keypoints: boolean;
+    minGrade: MinGrade | null;
+}
+/** WebView-parity defaults: everything opt-in, like the query params. */
+export declare const DEFAULT_FEATURES: ResolvedFeatures;
+/** Free plan requested developer features (angles/recommendations/progression/keypoints+exercise). */
+export declare const FREE_PLAN_FEATURES_MESSAGE = "You cannot use developer features. (visit: https://posetracker.gitbook.io/posetracker-api/tracking-endpoint)";
+/** Missing/invalid API token when key-gated features are requested. */
+export declare const INVALID_TOKEN_MESSAGE = "Invalid params. Please refer to the documentation and set token=YOUR API_KEY et exercise=A correct exercise. (visit: https://posetracker.gitbook.io/posetracker-api/tracking-endpoint)";
+/** Reference movement and exercise are mutually exclusive (Phase 2 surface). */
+export declare const COMBINED_REFERENCE_EXERCISE_MESSAGE = "You cannot combine reference & exercise. Please check the documentation.";
+/** SDK-specific: the requested WebView feature does not exist in this SDK. */
+export declare function featureNotSupportedMessage(key: string): string;
+/**
+ * Apply WebView-parity defaults and detect unsupported keys passed by
+ * untyped JS hosts (e.g. `{ blazepose: true }`).
+ */
+export declare function resolveFeatures(input: PoseTrackerFeatures | undefined): {
+    features: ResolvedFeatures;
+    unsupportedKeys: string[];
+};
+/**
+ * Which requested features a `free` plan is NOT allowed to use — exact port
+ * of the TrackingAppV3 condition (keypoints only blocked when an exercise
+ * is involved; pose-only keypoints stay free).
+ */
+export declare function freeBlockedFeatures(features: ResolvedFeatures, options: {
+    withExercise: boolean;
+}): string[];
+/** True for every plan type except `free` (developer / company / custom). */
+export declare function isPaidPlan(planType: string | null | undefined): boolean;
+/**
+ * Whether the live camera overlay should show the PoseTracker watermark.
+ * Shown for keyless (null), `free`, and any non-paid plan. Hidden for paid
+ * plans (`developer`, `company`, `enterprise`, custom, …) — same rule as
+ * {@link isPaidPlan}.
+ */
+export declare function shouldShowWatermark(planType: string | null | undefined): boolean;

package/lib/types/features.js

@@ -0,0 +1,122 @@
+"use strict";
+/**
+ * Host-selectable tracking features — SDK port of the PoseTracker WebView
+ * query params (`/pose_tracker/tracking?angles=true&…`) with the SAME plan
+ * gating and the SAME error messages as `TrackingAppV3`.
+ *
+ * Rules (mirroring the WebView product):
+ * - Without an API key the SDK always runs keypoints-only (offline, free,
+ *   no gating) — pose-only mode streams `keypoints` unconditionally.
+ * - `angles`, `recommendations`, `progression` require a PAID plan
+ *   (anything but `free`).
+ * - `keypoints` DURING an exercise session requires a paid plan too
+ *   (free may stream keypoints only in pose-only mode, i.e. no exercise).
+ * - `blazepose` / `poseEngine` / `mediapipeModel` / `poseBackend` /
+ *   `runInWorker` are NOT part of this SDK (MoveNet Lightning only) and are
+ *   rejected with a clear error.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COMBINED_REFERENCE_EXERCISE_MESSAGE = exports.INVALID_TOKEN_MESSAGE = exports.FREE_PLAN_FEATURES_MESSAGE = exports.DEFAULT_FEATURES = void 0;
+exports.featureNotSupportedMessage = featureNotSupportedMessage;
+exports.resolveFeatures = resolveFeatures;
+exports.freeBlockedFeatures = freeBlockedFeatures;
+exports.isPaidPlan = isPaidPlan;
+exports.shouldShowWatermark = shouldShowWatermark;
+/** WebView-parity defaults: everything opt-in, like the query params. */
+exports.DEFAULT_FEATURES = {
+    angles: false,
+    recommendations: false,
+    progression: false,
+    keypoints: false,
+    minGrade: null,
+};
+const KNOWN_FEATURE_KEYS = new Set([
+    'angles',
+    'recommendations',
+    'progression',
+    'keypoints',
+    'minGrade',
+]);
+/**
+ * WebView params that this SDK deliberately does NOT ship (one SDK, one
+ * model: MoveNet Lightning). Passing them (possible from untyped JS hosts)
+ * produces a clear `feature_not_supported` error.
+ */
+const UNSUPPORTED_FEATURE_HINTS = {
+    blazepose: 'BlazePose',
+    poseEngine: 'pose engine selection (MediaPipe/PoseLandmarker)',
+    mediapipeModel: 'MediaPipe model selection',
+    poseBackend: 'pose backend selection',
+    runInWorker: 'worker thread selection',
+};
+// ---------------------------------------------------------------------------
+// Error messages — EXACT copies of PoseTrackerFront/components/v3/TrackingAppV3.js
+// so hosts migrating from the WebView see identical strings.
+// ---------------------------------------------------------------------------
+/** Free plan requested developer features (angles/recommendations/progression/keypoints+exercise). */
+exports.FREE_PLAN_FEATURES_MESSAGE = 'You cannot use developer features. (visit: https://posetracker.gitbook.io/posetracker-api/tracking-endpoint)';
+/** Missing/invalid API token when key-gated features are requested. */
+exports.INVALID_TOKEN_MESSAGE = 'Invalid params. Please refer to the documentation and set token=YOUR API_KEY et exercise=A correct exercise. (visit: https://posetracker.gitbook.io/posetracker-api/tracking-endpoint)';
+/** Reference movement and exercise are mutually exclusive (Phase 2 surface). */
+exports.COMBINED_REFERENCE_EXERCISE_MESSAGE = 'You cannot combine reference & exercise. Please check the documentation.';
+/** SDK-specific: the requested WebView feature does not exist in this SDK. */
+function featureNotSupportedMessage(key) {
+    const hint = UNSUPPORTED_FEATURE_HINTS[key] ?? `'${key}'`;
+    return (`The '${key}' option (${hint}) is not available in this SDK. ` +
+        'This SDK ships MoveNet Lightning only — pose engine and model cannot be changed. ' +
+        'Remove the option, or use the PoseTracker WebView product if you need it. ' +
+        '(visit: https://posetracker.gitbook.io/posetracker-api/tracking-endpoint)');
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/**
+ * Apply WebView-parity defaults and detect unsupported keys passed by
+ * untyped JS hosts (e.g. `{ blazepose: true }`).
+ */
+function resolveFeatures(input) {
+    if (!input) {
+        return { features: { ...exports.DEFAULT_FEATURES }, unsupportedKeys: [] };
+    }
+    const unsupportedKeys = Object.keys(input).filter((k) => !KNOWN_FEATURE_KEYS.has(k));
+    return {
+        features: {
+            angles: input.angles === true,
+            recommendations: input.recommendations === true,
+            progression: input.progression === true,
+            keypoints: input.keypoints === true,
+            minGrade: input.minGrade ?? null,
+        },
+        unsupportedKeys,
+    };
+}
+/**
+ * Which requested features a `free` plan is NOT allowed to use — exact port
+ * of the TrackingAppV3 condition (keypoints only blocked when an exercise
+ * is involved; pose-only keypoints stay free).
+ */
+function freeBlockedFeatures(features, options) {
+    const blocked = [];
+    if (features.angles)
+        blocked.push('angles');
+    if (features.recommendations)
+        blocked.push('recommendations');
+    if (features.progression)
+        blocked.push('progression');
+    if (features.keypoints && options.withExercise)
+        blocked.push('keypoints');
+    return blocked;
+}
+/** True for every plan type except `free` (developer / company / custom). */
+function isPaidPlan(planType) {
+    return typeof planType === 'string' && planType.length > 0 && planType !== 'free';
+}
+/**
+ * Whether the live camera overlay should show the PoseTracker watermark.
+ * Shown for keyless (null), `free`, and any non-paid plan. Hidden for paid
+ * plans (`developer`, `company`, `enterprise`, custom, …) — same rule as
+ * {@link isPaidPlan}.
+ */
+function shouldShowWatermark(planType) {
+    return !isPaidPlan(planType);
+}