@pose-tracker/pose-estimation-web 0.1.0 → 0.2.0

package/dist/index.cjs

@@ -3,7 +3,7 @@
 var jsSha256 = require('js-sha256');
 
 // src/version.ts
-var SDK_VERSION = "0.1.0";
+var SDK_VERSION = "0.2.0";
 var SDK_NAME = "posetracker-web";
 
 // src/api/configure.ts
@@ -461,6 +461,131 @@ function stopMediaStream(stream) {
   }
 }
 
+// src/media/resolveMedia.ts
+function isVideoElement(v) {
+  return typeof HTMLVideoElement !== "undefined" && v instanceof HTMLVideoElement;
+}
+function isImageElement(v) {
+  return typeof HTMLImageElement !== "undefined" && v instanceof HTMLImageElement;
+}
+function isImageBitmap(v) {
+  return typeof ImageBitmap !== "undefined" && v instanceof ImageBitmap;
+}
+function mediaSize(el) {
+  if (isImageBitmap(el)) {
+    return { width: el.width || 0, height: el.height || 0 };
+  }
+  if (isVideoElement(el)) {
+    return { width: el.videoWidth || 0, height: el.videoHeight || 0 };
+  }
+  return {
+    width: el.naturalWidth || el.width || 0,
+    height: el.naturalHeight || el.height || 0
+  };
+}
+async function resolveObjectUrl(src) {
+  if (typeof src === "string") {
+    return { url: src, revoke: () => void 0 };
+  }
+  const url = URL.createObjectURL(src);
+  return {
+    url,
+    revoke: () => {
+      try {
+        URL.revokeObjectURL(url);
+      } catch {
+      }
+    }
+  };
+}
+function waitForVideoReady(video, timeoutMs = 15e3) {
+  return new Promise((resolve, reject) => {
+    if (video.readyState >= 2 && video.videoWidth > 0) {
+      resolve();
+      return;
+    }
+    const onReady = () => {
+      cleanup();
+      resolve();
+    };
+    const onError = () => {
+      cleanup();
+      reject(new Error("Failed to load video source"));
+    };
+    const timer = setTimeout(() => {
+      cleanup();
+      reject(new Error("Timed out waiting for video metadata"));
+    }, timeoutMs);
+    const cleanup = () => {
+      clearTimeout(timer);
+      video.removeEventListener("loadeddata", onReady);
+      video.removeEventListener("error", onError);
+    };
+    video.addEventListener("loadeddata", onReady);
+    video.addEventListener("error", onError);
+  });
+}
+function waitForImageReady(img, timeoutMs = 15e3) {
+  return new Promise((resolve, reject) => {
+    if (img.complete && img.naturalWidth > 0) {
+      resolve();
+      return;
+    }
+    const onReady = () => {
+      cleanup();
+      resolve();
+    };
+    const onError = () => {
+      cleanup();
+      reject(new Error("Failed to load image source"));
+    };
+    const timer = setTimeout(() => {
+      cleanup();
+      reject(new Error("Timed out waiting for image"));
+    }, timeoutMs);
+    const cleanup = () => {
+      clearTimeout(timer);
+      img.removeEventListener("load", onReady);
+      img.removeEventListener("error", onError);
+    };
+    img.addEventListener("load", onReady);
+    img.addEventListener("error", onError);
+  });
+}
+async function imageBitmapToObjectUrl(bitmap) {
+  const canvas = document.createElement("canvas");
+  canvas.width = bitmap.width;
+  canvas.height = bitmap.height;
+  const ctx = canvas.getContext("2d");
+  if (!ctx) throw new Error("2d context unavailable");
+  ctx.drawImage(bitmap, 0, 0);
+  const blob = await new Promise((resolve, reject) => {
+    canvas.toBlob((b) => b ? resolve(b) : reject(new Error("toBlob failed")), "image/png");
+  });
+  return resolveObjectUrl(blob);
+}
+
+// src/types/source.ts
+function normalizePoseSource(source, extras) {
+  if (source && typeof source === "object" && "type" in source) {
+    return source;
+  }
+  const kind = source === "video" || source === "image" || source === "camera" ? source : "camera";
+  if (kind === "camera") {
+    return { type: "camera", facingMode: extras?.facingMode };
+  }
+  const src = extras?.sourceFile ?? extras?.sourceUrl;
+  if (!src) {
+    throw new Error(
+      `PoseSource type "${kind}" requires sourceUrl or sourceFile (or pass a full PoseSource object)`
+    );
+  }
+  if (kind === "video") {
+    return { type: "video", src };
+  }
+  return { type: "image", src };
+}
+
 // src/exercises/aliases.ts
 var EXERCISE_ALIASES = {
   face_squat: "squat",
@@ -913,6 +1038,18 @@ async function resolvePoseDetection(options) {
 }
 
 // src/models/adapters/blazepose.ts
+function blazeInputSize(input) {
+  if (typeof HTMLVideoElement !== "undefined" && input instanceof HTMLVideoElement) {
+    return { vw: input.videoWidth || 0, vh: input.videoHeight || 0 };
+  }
+  if (typeof HTMLImageElement !== "undefined" && input instanceof HTMLImageElement) {
+    return { vw: input.naturalWidth || input.width || 0, vh: input.naturalHeight || input.height || 0 };
+  }
+  if (typeof HTMLCanvasElement !== "undefined" && input instanceof HTMLCanvasElement) {
+    return { vw: input.width || 0, vh: input.height || 0 };
+  }
+  return { vw: input.width || 0, vh: input.height || 0 };
+}
 var BLAZE_TO_COCO = {
   nose: "nose",
   left_eye: "left_eye",
@@ -956,11 +1093,12 @@ var BlazePoseAdapter = class {
       }
     );
   }
-  async estimate(video, options) {
+  async estimate(input, options) {
     if (!this.detector) throw new Error("BlazePose adapter not loaded");
-    if (!(video.videoWidth > 0 && video.videoHeight > 0)) return null;
+    const size = blazeInputSize(input);
+    if (!(size.vw > 0 && size.vh > 0)) return null;
     const t0 = performance.now();
-    const poses = await this.detector.estimatePoses(video, {
+    const poses = await this.detector.estimatePoses(input, {
       flipHorizontal: false,
       maxPoses: 1
     });
@@ -980,15 +1118,15 @@ var BlazePoseAdapter = class {
         letterbox: {
           offsetX: 0,
           offsetY: 0,
-          drawW: video.videoWidth,
-          drawH: video.videoHeight,
-          vw: video.videoWidth,
-          vh: video.videoHeight
+          drawW: size.vw,
+          drawH: size.vh,
+          vw: size.vw,
+          vh: size.vh
         }
       };
     }
-    const vw = video.videoWidth || 1;
-    const vh = video.videoHeight || 1;
+    const vw = size.vw || 1;
+    const vh = size.vh || 1;
     const dispW = options.displayWidth || 1;
     const dispH = options.displayHeight || 1;
     const byName = /* @__PURE__ */ new Map();
@@ -1054,6 +1192,18 @@ var BlazePoseAdapter = class {
 };
 
 // src/models/adapters/movenet.ts
+function inputSize(input) {
+  if (typeof HTMLVideoElement !== "undefined" && input instanceof HTMLVideoElement) {
+    return { vw: input.videoWidth || 0, vh: input.videoHeight || 0 };
+  }
+  if (typeof HTMLImageElement !== "undefined" && input instanceof HTMLImageElement) {
+    return { vw: input.naturalWidth || input.width || 0, vh: input.naturalHeight || input.height || 0 };
+  }
+  if (typeof HTMLCanvasElement !== "undefined" && input instanceof HTMLCanvasElement) {
+    return { vw: input.width || 0, vh: input.height || 0 };
+  }
+  return { vw: input.width || 0, vh: input.height || 0 };
+}
 var INPUT_SIZE = 192;
 var SMOOTH_ALPHA = 0.5;
 function modelNormToVideo(xNorm, yNorm, lb) {
@@ -1117,9 +1267,10 @@ var MoveNetGraphAdapter = class {
     if (!this.offCtx) throw new Error("2d context unavailable");
     return this.offCtx;
   }
-  prepareInput(video) {
-    const vw = video.videoWidth || 1;
-    const vh = video.videoHeight || 1;
+  prepareInput(input) {
+    const { vw: rawW, vh: rawH } = inputSize(input);
+    const vw = rawW || 1;
+    const vh = rawH || 1;
     const scale = Math.min(INPUT_SIZE / vw, INPUT_SIZE / vh);
     const drawW = vw * scale;
     const drawH = vh * scale;
@@ -1129,7 +1280,7 @@ var MoveNetGraphAdapter = class {
     const c2d = this.poseCanvasCtx();
     c2d.fillStyle = "#000";
     c2d.fillRect(0, 0, INPUT_SIZE, INPUT_SIZE);
-    c2d.drawImage(video, 0, 0, vw, vh, offsetX, offsetY, drawW, drawH);
+    c2d.drawImage(input, 0, 0, vw, vh, offsetX, offsetY, drawW, drawH);
     return this.offscreen;
   }
   smooth(raw) {
@@ -1145,16 +1296,19 @@ var MoveNetGraphAdapter = class {
     }
     return this.smoothed;
   }
-  async estimate(video, options) {
+  async estimate(input, options) {
     if (!this.tf || !this.model) throw new Error("MoveNet adapter not loaded");
-    if (!(video.videoWidth > 0 && video.videoHeight > 0)) return null;
+    const size = inputSize(input);
+    if (!(size.vw > 0 && size.vh > 0)) return null;
     const t0 = performance.now();
-    const canvas = this.prepareInput(video);
-    const input = this.tf.tidy(() => this.tf.expandDims(this.tf.browser.fromPixels(canvas), 0));
-    const out = this.model.execute(input);
+    const canvas = this.prepareInput(input);
+    const tensorIn = this.tf.tidy(
+      () => this.tf.expandDims(this.tf.browser.fromPixels(canvas), 0)
+    );
+    const out = this.model.execute(tensorIn);
     const tensor = Array.isArray(out) ? out[0] : out;
     const data = tensor.dataSync();
-    input.dispose();
+    tensorIn.dispose();
     if (Array.isArray(out)) out.forEach((t) => t.dispose());
     else out.dispose();
     const inferenceMs = performance.now() - t0;
@@ -1283,11 +1437,11 @@ var SHELL_CSS = `
   position: relative; width: 100%; height: 100%; min-height: 240px;
   background: #000; overflow: hidden; isolation: isolate;
 }
-.pt-root video, .pt-root canvas.pt-overlay {
+.pt-root video, .pt-root img.pt-still, .pt-root canvas.pt-overlay {
   position: absolute; inset: 0; width: 100%; height: 100%;
   object-fit: cover; opacity: 0; transition: opacity 180ms ease-out;
 }
-.pt-root video { z-index: 1; background: #000; }
+.pt-root video, .pt-root img.pt-still { z-index: 1; background: #000; }
 .pt-root canvas.pt-overlay { z-index: 2; pointer-events: none; }
 .pt-boot {
   position: absolute; inset: 0; z-index: 4;
@@ -1361,6 +1515,7 @@ function mountDomShell(host, options = {}) {
   root.className = "pt-root";
   root.innerHTML = `
     <video playsinline muted autoplay></video>
+    <img class="pt-still" alt="" draggable="false" />
     <canvas class="pt-overlay"></canvas>
     <div class="pt-boot">
       <div class="pt-boot-powered">Powered by</div>
@@ -1377,6 +1532,7 @@ function mountDomShell(host, options = {}) {
   `;
   host.appendChild(root);
   const video = root.querySelector("video");
+  const image = root.querySelector("img.pt-still");
   const canvas = root.querySelector("canvas.pt-overlay");
   const boot = root.querySelector(".pt-boot");
   const bootMsg = root.querySelector(".pt-boot-msg");
@@ -1386,6 +1542,7 @@ function mountDomShell(host, options = {}) {
   return {
     root,
     video,
+    image,
     canvas,
     boot,
     bootMsg,
@@ -1397,10 +1554,21 @@ function mountDomShell(host, options = {}) {
       bootMsg.classList.toggle("is-error", isError);
     },
     setCameraVisible(visible) {
-      video.style.opacity = visible ? "1" : "0";
-      canvas.style.opacity = visible ? "1" : "0";
-      boot.classList.toggle("hide", visible);
-      if (!visible) {
+      if (visible) {
+        this.setMediaMode(image.src ? "image" : "video");
+      } else {
+        this.setMediaMode("none");
+      }
+    },
+    setMediaMode(mode) {
+      const showVideo = mode === "video";
+      const showImage = mode === "image";
+      const showMedia = showVideo || showImage;
+      video.style.opacity = showVideo ? "1" : "0";
+      image.style.opacity = showImage ? "1" : "0";
+      canvas.style.opacity = showMedia ? "1" : "0";
+      boot.classList.toggle("hide", showMedia);
+      if (!showMedia) {
         bootMsg.textContent = loadingText;
         bootMsg.classList.remove("is-error");
       }
@@ -1425,6 +1593,7 @@ function mountDomShell(host, options = {}) {
     applyMirror(facingMode) {
       const t = facingMode === "user" ? "scaleX(-1)" : "none";
       video.style.transform = t;
+      image.style.transform = "none";
       canvas.style.transform = t;
     },
     destroy() {
@@ -1628,6 +1797,10 @@ var PoseTrackerClient = class {
     this.keypointsSuppressionLogged = false;
     this.shell = null;
     this.stream = null;
+    this.poseSource = { type: "camera" };
+    this.objectUrlRevoke = null;
+    this.estimateInput = null;
+    this.imageShotPending = false;
     this.adapter = null;
     this.running = false;
     this.busy = false;
@@ -1654,6 +1827,15 @@ var PoseTrackerClient = class {
     this.resolved = resolvePoseModel({ model: options.model, modelUrl: options.modelUrl });
     this.skeletonDef = options.skeletonDef ?? null;
     this.coldStartMode = options.coldStart === "full" ? "full" : "basic";
+    try {
+      this.poseSource = normalizePoseSource(options.source, {
+        sourceUrl: options.sourceUrl,
+        sourceFile: options.sourceFile,
+        facingMode: facingFromOptions(options)
+      });
+    } catch {
+      this.poseSource = { type: "camera", facingMode: facingFromOptions(options) };
+    }
     this.files = options.fileStore !== void 0 ? options.fileStore : createWebFileStore();
     this.engineLoader = options.engineLoader ?? new EngineLoader({
       fileStore: this.files,
@@ -1700,6 +1882,10 @@ var PoseTrackerClient = class {
   getColdStartMode() {
     return this.coldStartMode;
   }
+  /** Active pose input source (`camera` | `video` | `image`). */
+  getSource() {
+    return this.poseSource;
+  }
   addEventListener(listener) {
     this.listeners.add(listener);
     return () => this.listeners.delete(listener);
@@ -1763,31 +1949,98 @@ var PoseTrackerClient = class {
   warmup(options) {
     return this.preload(options);
   }
-  /** Mount + load model + open camera + start loop (camera-screen convenience). */
+  /**
+   * Mount + load model + open source + start inference.
+   * Camera / video stream continuously; image runs a single shot (re-run with {@link analyze}).
+   */
   async start() {
     if (this.disposed) throw new Error("PoseTracker disposed");
     if (!this.shell) throw new Error("Call mount() before start()");
-    await this.preload({ coldStart: this.opts.coldStart === "basic" ? "basic" : "full" });
-    if (this.coldStartMode === "basic") {
-      await this.ensureColdStartMode("full");
+    const needsMedia = this.poseSource.type === "camera" || this.poseSource.type === "video" || this.poseSource.type === "image";
+    await this.preload({
+      coldStart: this.opts.coldStart === "basic" && this.poseSource.type === "camera" ? "basic" : needsMedia ? "full" : "basic"
+    });
+    if (this.coldStartMode === "basic" || !this.estimateInput) {
+      await this.ensureSource();
+    }
+    if (this.poseSource.type === "image") {
+      this.imageShotPending = true;
     }
     this.beginLoop();
   }
+  /**
+   * Switch input source. Stops the current media, attaches the new source, and
+   * restarts the loop when previously running.
+   */
+  async setSource(source, extras) {
+    if (this.disposed) throw new Error("PoseTracker disposed");
+    const wasRunning = this.running;
+    this.stopMediaOnly();
+    this.poseSource = normalizePoseSource(source, {
+      sourceUrl: extras?.sourceUrl ?? this.opts.sourceUrl,
+      sourceFile: extras?.sourceFile ?? this.opts.sourceFile,
+      facingMode: extras?.facingMode ?? facingFromOptions(this.opts)
+    });
+    this.opts.source = this.poseSource;
+    if (this.poseSource.type === "camera" && this.poseSource.facingMode) {
+      this.opts.facingMode = this.poseSource.facingMode;
+    }
+    if (!this.shell) return;
+    await this.ensureSource();
+    if (wasRunning || this.poseSource.type === "image") {
+      if (this.poseSource.type === "image") this.imageShotPending = true;
+      this.beginLoop();
+    }
+  }
+  /**
+   * Re-run pose estimation on the current still image (no-op for camera/video
+   * while the loop is already running — for those, call {@link start}).
+   */
+  async analyze() {
+    if (this.disposed) throw new Error("PoseTracker disposed");
+    if (!this.shell) throw new Error("Call mount() before analyze()");
+    await this.ensureAdapter();
+    if (!this.estimateInput) await this.ensureSource();
+    if (this.poseSource.type === "image") {
+      this.imageShotPending = true;
+      if (!this.running) this.beginLoop();
+      return null;
+    }
+    return this.runOneFrame();
+  }
   stop() {
     this.running = false;
     this.loopToken += 1;
     this.busy = false;
-    stopMediaStream(this.stream);
-    this.stream = null;
+    this.imageShotPending = false;
+    this.stopMediaOnly();
     if (this.shell) {
-      this.shell.video.srcObject = null;
-      this.shell.setCameraVisible(false);
+      this.shell.setMediaMode("none");
       this.shell.setPlacementVisible(false);
       this.cameraRevealed = false;
       this.applyWatermark();
     }
     if (this.status !== "error") this.setStatus("idle");
   }
+  stopMediaOnly() {
+    stopMediaStream(this.stream);
+    this.stream = null;
+    this.estimateInput = null;
+    if (this.objectUrlRevoke) {
+      this.objectUrlRevoke();
+      this.objectUrlRevoke = null;
+    }
+    if (this.shell) {
+      try {
+        this.shell.video.pause();
+      } catch {
+      }
+      this.shell.video.removeAttribute("src");
+      this.shell.video.srcObject = null;
+      this.shell.video.load();
+      this.shell.image.removeAttribute("src");
+    }
+  }
   async dispose() {
     this.stopExercise();
     this.stop();
@@ -2056,7 +2309,7 @@ var PoseTrackerClient = class {
   async ensureColdStartMode(mode) {
     if (mode !== "full") return;
     if (!this.shell) return;
-    await this.ensureCamera();
+    await this.ensureSource();
   }
   async ensureAdapter() {
     if (this.adapter) return;
@@ -2073,48 +2326,102 @@ var PoseTrackerClient = class {
     this.adapter = createPoseAdapter({ resolved: this.resolved });
     await this.adapter.load();
   }
-  async ensureCamera() {
-    if (!this.shell) throw new Error("Call mount() before opening the camera");
-    if (this.stream) return;
+  async ensureSource() {
+    if (!this.shell) throw new Error("Call mount() before opening a pose source");
+    const src = this.poseSource;
+    if (src.type === "camera") {
+      if (this.stream && this.estimateInput) return;
+      this.emit({
+        type: "initialization",
+        step: "accessing_webcam",
+        message: "accessing webcam (source=camera)",
+        ready: false
+      });
+      try {
+        this.stream = await openCameraStream({
+          facingMode: src.facingMode ?? facingFromOptions(this.opts),
+          idealWidth: this.opts.idealWidth,
+          idealHeight: this.opts.idealHeight
+        });
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        const denied = /NotAllowed|Permission|denied/i.test(msg);
+        this.reportError({
+          type: "error",
+          code: denied ? "camera_denied" : "camera_unavailable",
+          message: msg
+        });
+        this.shell.setBootMessage(
+          denied ? "Camera permission denied \u2014 allow access in the browser" : "Camera unavailable",
+          true
+        );
+        throw err;
+      }
+      this.shell.video.srcObject = this.stream;
+      this.shell.applyMirror(src.facingMode ?? facingFromOptions(this.opts));
+      this.shell.setMediaMode("video");
+      try {
+        await this.shell.video.play();
+      } catch {
+      }
+      this.estimateInput = this.shell.video;
+      this.scheduleReveal("camera");
+      void this.handleCameraStart({
+        backend: this.acceleration.backend ?? "webgl",
+        profileId: null
+      });
+      return;
+    }
+    if (src.type === "video") {
+      this.emit({
+        type: "initialization",
+        step: "loading_media",
+        message: "loading video (source=video)",
+        ready: false
+      });
+      try {
+        await this.attachVideoSource(src.src, {
+          autoplay: src.autoplay !== false,
+          loop: src.loop !== false,
+          muted: src.muted !== false
+        });
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        this.reportError({ type: "error", code: "media_load_failed", message: msg });
+        this.shell.setBootMessage("Could not load video source", true);
+        throw err;
+      }
+      this.shell.applyMirror("none");
+      this.shell.setMediaMode("video");
+      this.scheduleReveal("video");
+      return;
+    }
     this.emit({
       type: "initialization",
-      step: "accessing_webcam",
-      message: "accessing webcam",
+      step: "loading_media",
+      message: "loading image (source=image)",
       ready: false
     });
     try {
-      this.stream = await openCameraStream({
-        facingMode: facingFromOptions(this.opts),
-        idealWidth: this.opts.idealWidth,
-        idealHeight: this.opts.idealHeight
-      });
+      await this.attachImageSource(src.src);
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
-      const denied = /NotAllowed|Permission|denied/i.test(msg);
-      this.reportError({
-        type: "error",
-        code: denied ? "camera_denied" : "camera_unavailable",
-        message: msg
-      });
-      this.shell.setBootMessage(
-        denied ? "Camera permission denied \u2014 allow access in the browser" : "Camera unavailable",
-        true
-      );
+      this.reportError({ type: "error", code: "media_load_failed", message: msg });
+      this.shell.setBootMessage("Could not load image source", true);
       throw err;
     }
-    this.shell.video.srcObject = this.stream;
-    this.shell.applyMirror(facingFromOptions(this.opts));
-    try {
-      await this.shell.video.play();
-    } catch {
-    }
+    this.shell.applyMirror("none");
+    this.shell.setMediaMode("image");
+    this.scheduleReveal("image");
+  }
+  scheduleReveal(kind) {
     const started = Date.now();
     const tick = () => {
       this.revealCamera();
       if (this.cameraRevealed) return;
       if (Date.now() - started > 8e3) {
         this.shell?.setBootMessage(
-          "camera started but preview is empty \u2014 check permissions",
+          `${kind} loaded but preview is empty \u2014 check the file or CORS`,
           true
         );
         return;
@@ -2122,88 +2429,182 @@ var PoseTrackerClient = class {
       setTimeout(tick, 120);
     };
     setTimeout(tick, 60);
-    void this.handleCameraStart({
-      backend: this.acceleration.backend ?? "webgl",
-      profileId: null
-    });
+  }
+  async attachVideoSource(src, opts) {
+    if (!this.shell) throw new Error("no shell");
+    const video = this.shell.video;
+    if (isVideoElement(src)) {
+      if (src.parentElement && src !== video) {
+        this.estimateInput = src;
+        if (opts.autoplay) {
+          try {
+            await src.play();
+          } catch {
+          }
+        }
+        await waitForVideoReady(src);
+        return;
+      }
+      if (src.srcObject) {
+        video.srcObject = src.srcObject;
+      } else if (src.currentSrc || src.src) {
+        video.src = src.currentSrc || src.src;
+      }
+    } else {
+      const resolved = await resolveObjectUrl(src);
+      this.objectUrlRevoke = resolved.revoke;
+      video.src = resolved.url;
+    }
+    video.loop = opts.loop;
+    video.muted = opts.muted;
+    video.playsInline = true;
+    await waitForVideoReady(video);
+    if (opts.autoplay) {
+      try {
+        await video.play();
+      } catch {
+      }
+    }
+    this.estimateInput = video;
+  }
+  async attachImageSource(src) {
+    if (!this.shell) throw new Error("no shell");
+    if (isImageBitmap(src)) {
+      const resolved2 = await imageBitmapToObjectUrl(src);
+      this.objectUrlRevoke = resolved2.revoke;
+      this.shell.image.src = resolved2.url;
+      await waitForImageReady(this.shell.image);
+      this.estimateInput = src;
+      return;
+    }
+    if (isImageElement(src)) {
+      if (src.complete && src.naturalWidth > 0) {
+        this.shell.image.src = src.currentSrc || src.src;
+        this.estimateInput = src;
+        return;
+      }
+      await waitForImageReady(src);
+      this.shell.image.src = src.currentSrc || src.src;
+      this.estimateInput = src;
+      return;
+    }
+    const resolved = await resolveObjectUrl(src);
+    this.objectUrlRevoke = resolved.revoke;
+    this.shell.image.src = resolved.url;
+    await waitForImageReady(this.shell.image);
+    this.estimateInput = this.shell.image;
   }
   beginLoop() {
     this.running = true;
     this.fpsTimer = performance.now();
     void this.loop(++this.loopToken);
   }
+  frameReady(input) {
+    const size = mediaSize(
+      input
+    );
+    if (!(size.width > 0 && size.height > 0)) return false;
+    if (isVideoElement(input)) {
+      if (input.readyState < 2) return false;
+      if (this.poseSource.type === "video" && (input.paused || input.ended)) return false;
+    }
+    return true;
+  }
+  async runOneFrame() {
+    if (!this.adapter || !this.shell || !this.estimateInput) return null;
+    if (!this.frameReady(this.estimateInput)) return null;
+    const input = this.estimateInput;
+    const dispW = this.shell.canvas.clientWidth || this.shell.root.clientWidth || 1;
+    const dispH = this.shell.canvas.clientHeight || this.shell.root.clientHeight || 1;
+    const facing = this.poseSource.type === "camera" ? facingFromOptions(this.opts) : "environment";
+    const result = await this.adapter.estimate(input, {
+      facingMode: facing,
+      displayWidth: dispW,
+      displayHeight: dispH
+    });
+    if (!result) return null;
+    const ctx = this.shell.canvas.getContext("2d");
+    if (ctx && this.opts.drawSkeleton !== false) {
+      const mapped = mapVideoKeypointsToDisplay(
+        result.videoKeypoints,
+        result.letterbox,
+        dispW,
+        dispH
+      );
+      drawSkeleton(ctx, mapped, dispW, dispH, true, this.skeletonDef);
+    } else if (ctx && this.opts.drawSkeleton === false) {
+      ctx.clearRect(0, 0, dispW, dispH);
+    }
+    const pose = {
+      keypoints: result.keypoints,
+      score: result.score,
+      timestampMs: Date.now()
+    };
+    this.ingestPose(pose);
+    this.inferMs.push(result.inferenceMs);
+    if (this.inferMs.length > 30) this.inferMs.shift();
+    this.fpsWindow += 1;
+    const now = performance.now();
+    if (now - this.fpsTimer >= 1e3) {
+      const fps = this.fpsWindow;
+      this.fpsWindow = 0;
+      this.fpsTimer = now;
+      const med = median(this.inferMs);
+      this.acceleration.medianInferenceMs = med;
+      const above = result.keypoints.filter((k) => k.score >= 0.3).length;
+      const backend = "getBackend" in this.adapter && typeof this.adapter.getBackend === "function" ? this.adapter.getBackend() : null;
+      this.acceleration.backend = backend;
+      const size = mediaSize(input);
+      if (this.opts.debugHud) {
+        this.shell.setHud(
+          `${this.resolved.modelId} \xB7 ${this.poseSource.type} \xB7 ${backend ?? "?"} \xB7 ${fps} fps \xB7 ${med != null ? Math.round(med) + " ms" : "?"} \xB7 kp\u22650.3=${above}/17`,
+          true
+        );
+      }
+      this.emit({
+        type: "stats",
+        fps,
+        medianInferenceMs: med,
+        backend,
+        keypointsAbove03: above,
+        meanScore: result.score,
+        videoSize: `${size.width}x${size.height}`,
+        timestampMs: Date.now()
+      });
+    }
+    this.revealCamera();
+    return pose;
+  }
   async loop(token) {
     if (token !== this.loopToken || !this.running || !this.adapter || !this.shell || this.disposed) {
       return;
     }
-    const video = this.shell.video;
-    if (!this.busy && video.readyState >= 2 && video.videoWidth > 0) {
+    const input = this.estimateInput;
+    const shouldInfer = !!input && !this.busy && this.frameReady(input) && (this.poseSource.type !== "image" || this.imageShotPending);
+    if (shouldInfer) {
       this.busy = true;
       try {
-        const dispW = this.shell.canvas.clientWidth || this.shell.root.clientWidth || 1;
-        const dispH = this.shell.canvas.clientHeight || this.shell.root.clientHeight || 1;
-        const result = await this.adapter.estimate(video, {
-          facingMode: facingFromOptions(this.opts),
-          displayWidth: dispW,
-          displayHeight: dispH
-        });
-        if (result) {
-          const ctx = this.shell.canvas.getContext("2d");
-          if (ctx && this.opts.drawSkeleton !== false) {
-            const mapped = mapVideoKeypointsToDisplay(
-              result.videoKeypoints,
-              result.letterbox,
-              dispW,
-              dispH
-            );
-            drawSkeleton(ctx, mapped, dispW, dispH, true, this.skeletonDef);
-          } else if (ctx && this.opts.drawSkeleton === false) {
-            ctx.clearRect(0, 0, dispW, dispH);
-          }
-          const pose = {
-            keypoints: result.keypoints,
-            score: result.score,
-            timestampMs: Date.now()
-          };
-          this.ingestPose(pose);
-          this.inferMs.push(result.inferenceMs);
-          if (this.inferMs.length > 30) this.inferMs.shift();
-          this.fpsWindow += 1;
-          const now = performance.now();
-          if (now - this.fpsTimer >= 1e3) {
-            const fps = this.fpsWindow;
-            this.fpsWindow = 0;
-            this.fpsTimer = now;
-            const med = median(this.inferMs);
-            this.acceleration.medianInferenceMs = med;
-            const above = result.keypoints.filter((k) => k.score >= 0.3).length;
-            const backend = "getBackend" in this.adapter && typeof this.adapter.getBackend === "function" ? this.adapter.getBackend() : null;
-            this.acceleration.backend = backend;
-            if (this.opts.debugHud) {
-              this.shell.setHud(
-                `${this.resolved.modelId} \xB7 ${backend ?? "?"} \xB7 ${fps} fps \xB7 ${med != null ? Math.round(med) + " ms" : "?"} \xB7 kp\u22650.3=${above}/17`,
-                true
-              );
-            }
-            this.emit({
-              type: "stats",
-              fps,
-              medianInferenceMs: med,
-              backend,
-              keypointsAbove03: above,
-              meanScore: result.score,
-              videoSize: `${video.videoWidth}x${video.videoHeight}`,
-              timestampMs: Date.now()
-            });
-          }
+        await this.runOneFrame();
+        if (this.poseSource.type === "image") {
+          this.imageShotPending = false;
+          this.running = false;
+          this.busy = false;
+          return;
         }
-        this.revealCamera();
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         this.emit({ type: "error", code: "internal", message: `inference: ${message}` });
       }
       this.busy = false;
     }
+    if (token !== this.loopToken || !this.running) return;
+    const videoEl = input && isVideoElement(input) ? input : this.shell.video;
+    if (this.poseSource.type !== "image" && typeof videoEl.requestVideoFrameCallback === "function" && (this.poseSource.type === "video" || this.poseSource.type === "camera")) {
+      videoEl.requestVideoFrameCallback(() => {
+        void this.loop(token);
+      });
+      return;
+    }
     requestAnimationFrame(() => {
       void this.loop(token);
     });
@@ -2460,14 +2861,19 @@ var PoseTrackerClient = class {
   }
   revealCamera() {
     if (!this.shell || this.cameraRevealed) return;
-    const v = this.shell.video;
-    if (!(v.videoWidth > 0 && v.videoHeight > 0)) return;
+    const input = this.estimateInput;
+    if (!input) return;
+    const size = mediaSize(input);
+    if (!(size.width > 0 && size.height > 0)) return;
     requestAnimationFrame(() => {
       requestAnimationFrame(() => {
         if (this.cameraRevealed || !this.shell) return;
-        if (!(this.shell.video.videoWidth > 0)) return;
         this.cameraRevealed = true;
-        this.shell.setCameraVisible(true);
+        if (this.poseSource.type === "image") {
+          this.shell.setMediaMode("image");
+        } else {
+          this.shell.setMediaMode("video");
+        }
         this.applyWatermark();
       });
     });
@@ -2594,6 +3000,7 @@ exports.initWebGlBackend = initWebGlBackend;
 exports.isPaidPlan = isPaidPlan;
 exports.mapVideoKeypointsToDisplay = mapVideoKeypointsToDisplay;
 exports.mountDomShell = mountDomShell;
+exports.normalizePoseSource = normalizePoseSource;
 exports.openCameraStream = openCameraStream;
 exports.resolveExerciseName = resolveExerciseName;
 exports.resolveFeatures = resolveFeatures;