@framefields/vision 0.0.0-stage → 2.0.3

package/dist/index-CoAN0xxG.d.mts

@@ -0,0 +1,1198 @@
+import { n as __reExport, t as __exportAll } from "./chunk-CFhWmker.mjs";
+import { CanonicalBoneDef as SkeletonBone, PoseSkeletonOptions } from "@framefields/tensor-webgpu";
+import * as _framefields_core0 from "@framefields/core";
+import { DetectedObject, FrameContext, Landmark3D, ObjectBoundingBox, ProgrammaticSignal, TensorData, TrackedObject, VisionConfig, VisionNodeSpec, VisionTask, VisionVariant } from "@framefields/core";
+
+//#region src/model/registry.d.ts
+
+declare const VISION_TASKS: readonly VisionTask[];
+declare const VISION_VARIANTS: readonly VisionVariant[];
+type VisionModelKey = "rtmdet-ins-t" | "rtmdet-ins-s" | "rtmdet-ins-m" | "rtmo-t" | "rtmo-s" | "rtmo-m" | "selfie-square" | "selfie-landscape";
+/** Which decoder a model's outputs feed (see runner/vision-runner.ts). */
+type VisionModelFamily = "rtmdet-ins" | "rtmo" | "selfie";
+interface VisionModelDescriptor {
+  readonly key: VisionModelKey;
+  readonly family: VisionModelFamily;
+  /** Cache filename (also the path appended to a custom `baseUrl`). */
+  readonly filename: string;
+  /** Pinned download URL (immutable revision). */
+  readonly url: string;
+  /** Exact byte size of the pinned file. */
+  readonly bytes: number;
+  /** Hex SHA-256 of the pinned file. */
+  readonly sha256: string;
+  /** Model input size, `[width, height]` — must match the ONNX graph's input shape. */
+  readonly input: readonly [number, number];
+  /** Upstream project and license, surfaced in docs and errors. */
+  readonly source: string;
+}
+declare const VISION_MODELS: Readonly<Record<VisionModelKey, VisionModelDescriptor>>;
+/**
+ * Resolves the model for a task. `detect` and `segment` share RTMDet-Ins (one forward pass
+ * yields both); `matte` picks the landscape Selfie Segmenter for wide frames.
+ */
+declare function modelKeyFor(task: VisionTask, variant?: VisionVariant, aspect?: number): VisionModelKey;
+/** COCO 80 class names — index order matches the RTMDet-Ins `labels` output. */
+declare const COCO_CLASSES: readonly ["person", "bicycle", "car", "motorcycle", "airplane", "bus", "train", "truck", "boat", "traffic light", "fire hydrant", "stop sign", "parking meter", "bench", "bird", "cat", "dog", "horse", "sheep", "cow", "elephant", "bear", "zebra", "giraffe", "backpack", "umbrella", "handbag", "tie", "suitcase", "frisbee", "skis", "snowboard", "sports ball", "kite", "baseball bat", "baseball glove", "skateboard", "surfboard", "tennis racket", "bottle", "wine glass", "cup", "fork", "knife", "spoon", "bowl", "banana", "apple", "sandwich", "orange", "broccoli", "carrot", "hot dog", "pizza", "donut", "cake", "chair", "couch", "potted plant", "bed", "dining table", "toilet", "tv", "laptop", "mouse", "remote", "keyboard", "cell phone", "microwave", "oven", "toaster", "sink", "refrigerator", "book", "clock", "vase", "scissors", "teddy bear", "hair drier", "toothbrush"];
+type CocoClass = (typeof COCO_CLASSES)[number];
+//#endregion
+//#region src/model/model-store.d.ts
+type ModelDownloadStatus = "pending" | "downloading" | "ready" | "error";
+interface VisionModelStoreOptions {
+  readonly modelsDir?: string;
+  /**
+   * Mirror origin: models are fetched from `<baseUrl>/<filename>` instead of their pinned
+   * Hugging Face URLs. Defaults to `$FRAMEFIELDS_MODELS_BASE_URL` when set.
+   */
+  readonly baseUrl?: string;
+  readonly timeoutMs?: number;
+  /** Extra attempts after a network error, HTTP 429 or 5xx. Default 2. */
+  readonly retries?: number;
+  /** Base backoff between attempts (doubles each retry). Default 1000 ms. */
+  readonly retryDelayMs?: number;
+  /**
+   * Verify byte size + SHA-256 against the registry (default true). Only offline tests
+   * that serve fake bytes should turn this off.
+   */
+  readonly verify?: boolean;
+  /** Injectable fetch — offline unit tests inject a mock. */
+  readonly fetchImpl?: typeof fetch;
+  readonly onProgress?: (key: VisionModelKey, bytesLoaded: number, totalBytes: number) => void;
+}
+/**
+ * Resolves the default model cache directory:
+ * 1. `FRAMEFIELDS_MODELS_DIR`
+ * 2. `~/.cache/framefields/models`
+ */
+declare function getDefaultModelsDir(): string;
+/**
+ * Lazy model store. The constructor performs ZERO I/O; the only entry that can hit the
+ * network is `ensure(key)`, called by an inference function the first time it runs.
+ * Concurrent callers of the same key share a single in-flight download (promise dedupe),
+ * downloads are written atomically (temp + rename), and verified files on disk are reused
+ * across processes.
+ */
+declare class VisionModelStore {
+  private readonly _modelsDir;
+  private readonly _baseUrl?;
+  private readonly _timeoutMs?;
+  private readonly _retries;
+  private readonly _retryDelayMs;
+  private readonly _verify;
+  private readonly _fetch;
+  private readonly _onProgress?;
+  private _inflight;
+  private _buffers;
+  private _status;
+  constructor(options?: VisionModelStoreOptions);
+  get modelsDir(): string;
+  pathFor(key: VisionModelKey): string;
+  descriptor(key: VisionModelKey): VisionModelDescriptor;
+  /** The URL `ensure(key)` downloads from (mirror when `baseUrl` is set). */
+  urlFor(key: VisionModelKey): string;
+  /** True when a complete cached file exists (exact registry size when verifying). */
+  has(key: VisionModelKey): boolean;
+  /** Drops a cached model (file + memory) so the next `ensure` re-downloads it. */
+  evict(key: VisionModelKey): Promise<void>;
+  status(key: VisionModelKey): ModelDownloadStatus;
+  /** Snapshot of every tracked model's status (empty until anything is fetched). */
+  statuses(): ReadonlyMap<VisionModelKey, ModelDownloadStatus>;
+  /** True when the model is resident in memory (loaded or downloaded this process). */
+  isLoaded(key: VisionModelKey): boolean;
+  /**
+   * THE only download entry point. Returns the model bytes from memory (cached),
+   * loading from disk or fetching from the registry URL as needed.
+   */
+  ensure(key: VisionModelKey): Promise<Uint8Array>;
+  /** Explicit warm-up — fetch multiple models ahead of use (agents, renderers). */
+  preload(keys: readonly VisionModelKey[]): Promise<void>;
+  private load;
+  /** Fetches with retries on transient failures (network errors, HTTP 429/5xx). */
+  private download;
+  private verifyBytes;
+  private readBuffer;
+  /** Drops in-memory buffers (model stays on disk for the next run). */
+  clearMemoryCache(): void;
+}
+//#endregion
+//#region src/runtime/session-provider.d.ts
+/**
+ * Minimal ONNX Runtime surface — isolates the ORT API to exactly two files so the decode
+ * and signals layers never touch it. Node path uses onnxruntime-node (CPU EP); the web
+ * entry can swap in a WebGPU-backed provider with the same interface.
+ */
+/** Model output tensor. Integer outputs (e.g. RTMDet-Ins `labels`) arrive as BigInt64Array. */
+interface VisionTensor {
+  readonly data: Float32Array | BigInt64Array | Int32Array;
+  readonly dims: readonly number[];
+}
+interface VisionTensorInput {
+  readonly name: string;
+  readonly data: Float32Array;
+  readonly dims: readonly number[];
+}
+type VisionTensorOutputs = Readonly<Record<string, VisionTensor>>;
+interface VisionSession {
+  run(input: VisionTensorInput): Promise<VisionTensorOutputs>;
+  release(): void;
+}
+interface SessionProvider {
+  readonly kind: "node" | "webgpu";
+  createSession(modelBytes: Uint8Array): Promise<VisionSession>;
+}
+/**
+ * Sets the provider runners use when none is passed, for hosts that create
+ * runners indirectly (e.g. a browser player rendering vision nodes). `undefined`
+ * restores the default, onnxruntime-node.
+ */
+declare function setDefaultSessionProvider(factory: (() => SessionProvider) | undefined): void;
+/**
+ * Prefers the GPU (onnxruntime-web's WebGPU EP on the process's WebGPU device —
+ * the Dawn device the renderer already creates, or one this ensures) and falls
+ * back to the CPU provider (onnxruntime-node) when a WebGPU session cannot be
+ * created: no device, no Dawn, or the EP unavailable. The choice is made on the
+ * first session and reused for the runner's lifetime.
+ */
+declare class AutoSessionProvider implements SessionProvider {
+  private _resolved?;
+  get kind(): "node" | "webgpu";
+  createSession(modelBytes: Uint8Array): Promise<VisionSession>;
+}
+/**
+ * The provider for a runner created without one: GPU if possible, otherwise CPU.
+ */
+declare function createDefaultSessionProvider(): SessionProvider;
+/** onnxruntime-node provider. The native module is imported lazily on first session. */
+declare class NodeSessionProvider implements SessionProvider {
+  readonly kind: "node";
+  private ortPromise?;
+  private ort;
+  createSession(modelBytes: Uint8Array): Promise<VisionSession>;
+}
+declare namespace types_d_exports {
+  export { InstanceMask, LandmarkCoordinateSignals, ObjectAnchorName, PersonMatte, PinToLandmarkOptions, PinToObjectOptions, PoseKeypoint, PosePerson, PoseResult, SegmentationResult, VisionAnalysisClassSummary, VisionAnalysisReport, VisionAnalysisTrackSummary, VisionImageInput, VisionInputSource, VisionSummary };
+}
+import * as import__framefields_core from "@framefields/core";
+type VisionInputSource = string | {
+  inputHandleId?: string;
+  id?: string;
+  [key: string]: unknown;
+};
+/** RGBA pixel buffer accepted by the runner. */
+interface VisionImageInput {
+  readonly data: Uint8ClampedArray | Uint8Array;
+  readonly width: number;
+  readonly height: number;
+}
+/** Instance segmentation mask aligned to the ORIGINAL source frame. */
+interface InstanceMask {
+  readonly category: string;
+  readonly mask: Uint8Array;
+  readonly width: number;
+  readonly height: number;
+  readonly area: number;
+  readonly coverage: number;
+  /** Index of the detection this mask belongs to (see segmentation result detections). */
+  readonly detectionIndex: number;
+  /** Assigned by the caller (renderer) after temporal tracking — matches TrackedObject.trackId. */
+  readonly trackId?: number;
+}
+interface SegmentationResult {
+  readonly detections: readonly DetectedObject[];
+  readonly masks: readonly InstanceMask[];
+}
+/** Person-vs-background alpha (Selfie Segmenter), aligned to the ORIGINAL source frame. */
+interface PersonMatte {
+  readonly mask: Uint8Array;
+  readonly width: number;
+  readonly height: number;
+  readonly coverage: number;
+}
+interface PoseKeypoint {
+  readonly x: number;
+  readonly y: number;
+  readonly visibility: number;
+}
+interface PosePerson {
+  readonly score: number;
+  readonly boundingBox: ObjectBoundingBox;
+  /** 17 keypoints in COCO-17 order (see COCO17_KEYPOINTS). */
+  readonly keypoints: readonly PoseKeypoint[];
+  readonly trackId?: number;
+}
+interface PoseResult {
+  readonly people: readonly PosePerson[];
+}
+/**
+ * Deterministic, serializable snapshot of one frame's signals.
+ * Built synchronously from the per-frame caches, so it is safe to call inside a frame hook.
+ */
+interface VisionSummary {
+  readonly frame: number;
+  readonly objects: ReadonlyArray<{
+    readonly trackId: number;
+    readonly category: string;
+    readonly score: number;
+    /** Source-space pixel center, `[x, y]`. */
+    readonly center: readonly [number, number];
+    readonly speed: number;
+    readonly active: boolean;
+  }>;
+  readonly classes: readonly string[];
+  /** Per-class instance count for the frame (only non-zero classes present). */
+  readonly masks: Readonly<Record<string, number>>;
+}
+/** Per-track aggregate in an analysis report. */
+interface VisionAnalysisTrackSummary {
+  readonly trackId: number;
+  readonly category: string;
+  /** Inclusive frame range the track was active over, `[start, end]`. */
+  readonly frames: readonly [number, number];
+  readonly speedMeanPxS: number;
+  /** Center path sampled every `pathStride` frames, `[x, y]` pairs. */
+  readonly centerPath: ReadonlyArray<readonly [number, number]>;
+}
+interface VisionAnalysisClassSummary {
+  readonly framesPresent: number;
+  readonly totalFrames: number;
+  readonly maxConfidence: number;
+  readonly tracks: number;
+}
+interface VisionAnalysisReport {
+  readonly source: string;
+  readonly totalFrames: number;
+  readonly fps: number;
+  readonly durationSec: number;
+  readonly tasks: readonly string[];
+  /** What was fetched, and how long it took — surfaced so agents can budget cold starts. */
+  readonly modelDownloads: Readonly<Record<string, {
+    readonly bytes: number;
+    readonly ms: number;
+  }>>;
+  readonly inferenceMs: number;
+  readonly trackCount: number;
+  readonly classes: Readonly<Record<string, VisionAnalysisClassSummary>>;
+  readonly tracks: readonly VisionAnalysisTrackSummary[];
+  readonly masks: Readonly<Record<string, {
+    readonly meanCoverage: number;
+  }>>;
+}
+interface PinToLandmarkOptions {
+  readonly offsetX?: number;
+  readonly offsetY?: number;
+  readonly offsetZ?: number;
+  readonly trackRotation?: boolean;
+  readonly scaleWithPerspective?: boolean;
+}
+interface LandmarkCoordinateSignals {
+  readonly x: _framefields_core0.ProgrammaticSignal;
+  readonly y: _framefields_core0.ProgrammaticSignal;
+  readonly z: _framefields_core0.ProgrammaticSignal;
+  readonly screenX: _framefields_core0.ProgrammaticSignal;
+  readonly screenY: _framefields_core0.ProgrammaticSignal;
+}
+type ObjectAnchorName = "center" | "topCenter" | "bottomCenter" | "topLeft" | "topRight" | "centerLeft" | "centerRight" | "bottomLeft" | "bottomRight";
+interface PinToObjectOptions extends PinToLandmarkOptions {
+  readonly anchor?: ObjectAnchorName;
+  readonly matchWidth?: boolean;
+  readonly matchHeight?: boolean;
+  readonly smoothFrames?: number;
+  readonly hideWhenLost?: boolean;
+}
+//#endregion
+//#region src/runner/vision-runner.d.ts
+interface VisionRunnerOptions {
+  /** Model size for detect/segment/pose. Default "s". */
+  readonly variant?: VisionVariant;
+  /** Minimum detection / person score, 0..1. Default 0.3. */
+  readonly confidence?: number;
+  /** COCO class-name filter for detect/segment (all classes when omitted). */
+  readonly classes?: readonly string[];
+  readonly maskThreshold?: number;
+  readonly featherRadius?: number;
+  readonly modelsDir?: string;
+  /** Mirror origin for model downloads (see VisionModelStore). */
+  readonly baseUrl?: string;
+  readonly timeoutMs?: number;
+  /** Session backend. Default: onnxruntime-node (CPU). Browser: `createWebGPUProvider()`. */
+  readonly provider?: SessionProvider;
+  /** Inject a model store (tests, shared caches). Overrides modelsDir/baseUrl/timeoutMs. */
+  readonly store?: VisionModelStore;
+  readonly onProgress?: (key: VisionModelKey, bytesLoaded: number, totalBytes: number) => void;
+}
+/**
+ * Lazy vision runner.
+ *
+ * `create()` performs ZERO I/O: no downloads, no sessions. Each inference method downloads
+ * its model and warms its session on FIRST USE ONLY, then reuses them for the process
+ * lifetime. `detect()` and `segment()` share one RTMDet-Ins forward pass per frame.
+ * Call `close()` to release sessions.
+ */
+declare class VisionRunner {
+  readonly variant: VisionVariant;
+  readonly confidence: number;
+  readonly classes?: readonly string[];
+  readonly maskThreshold: number;
+  readonly featherRadius?: number;
+  private readonly _store;
+  private readonly _provider;
+  private readonly _sessions;
+  private readonly _tensorScratch;
+  /** One RTMDet-Ins pass per frame buffer, shared by detect() and segment(). */
+  private _instancePass?;
+  private constructor();
+  /** Cheap: no downloads, no sessions, no side effects. */
+  static create(options?: VisionRunnerOptions): VisionRunner;
+  get modelsDir(): string;
+  /** Every registry model keyed to its current download state (downloaded → "ready"). */
+  get downloadStatus(): ReadonlyMap<VisionModelKey, ModelDownloadStatus>;
+  /** The model serving `task` (matte depends on frame aspect; defaults to square). */
+  modelKeyFor(task: VisionTask, aspect?: number): VisionModelKey;
+  /**
+   * Explicit warm-up: downloads + sessions for the given tasks, ahead of first use.
+   * `matte` warms both aspect variants (the frame aspect is unknown until inference).
+   */
+  preload(tasks?: readonly VisionTask[]): Promise<void>;
+  /** COCO-80 boxes (sorted by score, source pixels). Masks are not decoded. */
+  detect(image: VisionImageInput): Promise<readonly DetectedObject[]>;
+  /** COCO-80 boxes plus a frame-aligned soft mask per instance. */
+  segment(image: VisionImageInput): Promise<SegmentationResult>;
+  /** COCO-17 keypoints per person (source pixels), highest score first. */
+  pose(image: VisionImageInput): Promise<PoseResult>;
+  /** Person-vs-background alpha for the whole frame (Selfie Segmenter). */
+  matte(image: VisionImageInput): Promise<PersonMatte>;
+  close(): void;
+  private instancePass;
+  private instanceDecodeOptions;
+  private infer;
+  private session;
+}
+//#endregion
+//#region src/analysis/analyze-sequence.d.ts
+/**
+ * One-shot, ffmpeg-free sequence analysis.
+ *
+ * Pure frame-iterable analyzer: it never decodes media itself, so it stays engine-only and
+ * offline-testable. Callers (e.g. the framefields ingestion adapter) supply decoded frames.
+ * Model loading remains lazy — the runner downloads each task's model on the first frame
+ * that actually runs that task, and only the tasks requested here are ever touched.
+ */
+interface AnalyzeSequenceOptions {
+  readonly runner: VisionRunner;
+  /** Label for the report ("clip.mp4" or similar). Defaults to "frames". */
+  readonly source?: string;
+  readonly fps?: number;
+  /** Tasks to run. Defaults to `["detect"]`. Only these models are ever downloaded. */
+  readonly tasks?: readonly VisionTask[];
+  /** Restrict class summaries to these categories (all when omitted). */
+  readonly categories?: readonly string[];
+  /** Tracker box-association IoU. Default 0.25. */
+  readonly iouThreshold?: number;
+  readonly maxMissedFrames?: number;
+  /** Sample the per-track center path every N frames. Default: ~50 points across the clip. */
+  readonly pathStride?: number;
+  /** Also aggregate instance-mask coverage (requires the `segment` task). Default false. */
+  readonly includeMasks?: boolean;
+}
+declare function analyzeSequence(frames: AsyncIterable<VisionImageInput> | Iterable<VisionImageInput>, options: AnalyzeSequenceOptions): Promise<VisionAnalysisReport>;
+//#endregion
+//#region src/decode/preprocess.d.ts
+/**
+ * Image → NCHW float tensor preprocessing, plus the inverse mapping back to source pixels.
+ *
+ * Each model family was exported with its own preprocessing contract:
+ *
+ * | Model       | Resize                       | Pad  | Channels | Values                     |
+ * | ----------- | ---------------------------- | ---- | -------- | -------------------------- |
+ * | RTMDet-Ins  | keep ratio, content top-left | 114  | BGR      | (v − mean) / std (ImageNet) |
+ * | RTMO        | keep ratio, content centered | 114  | BGR      | raw 0..255                 |
+ * | Selfie      | stretch to input             | —    | RGB      | v / 255                    |
+ *
+ * Getting any of these wrong does not crash — it silently degrades accuracy — so the specs
+ * live here and every runner path goes through `imageToTensor`. Input sizes differ per model
+ * (RTMO-t is 416², the rest of RTMO 640²), so they come from the registry, never from here.
+ */
+interface RgbaImage {
+  readonly data: Uint8ClampedArray | Uint8Array;
+  readonly width: number;
+  readonly height: number;
+}
+interface PreprocessSpec {
+  /** Model input size in pixels. */
+  readonly width: number;
+  readonly height: number;
+  /** `topLeft` / `center` keep aspect ratio and pad; `stretch` fills the input. */
+  readonly fit: "topLeft" | "center" | "stretch";
+  readonly channels: "rgb" | "bgr";
+  /** Per-channel mean, in output channel order, on the 0..255 scale. */
+  readonly mean: readonly [number, number, number];
+  /** Per-channel std, in output channel order, on the 0..255 scale. */
+  readonly std: readonly [number, number, number];
+  /** Padding value on the 0..255 scale (normalized like any other pixel). */
+  readonly padValue: number;
+}
+/** Maps model-input pixels back to source pixels: `src = (input − offset) / scale`. */
+interface InputTransform {
+  readonly scaleX: number;
+  readonly scaleY: number;
+  readonly offsetX: number;
+  readonly offsetY: number;
+  readonly inputWidth: number;
+  readonly inputHeight: number;
+}
+type Normalization = Omit<PreprocessSpec, "width" | "height">;
+/** Per-family normalization; the input size always comes from the model's registry entry. */
+declare const PREPROCESS_BY_FAMILY: Readonly<Record<"rtmdet-ins" | "rtmo" | "selfie", Normalization>>;
+declare function preprocessSpec(family: keyof typeof PREPROCESS_BY_FAMILY, input: readonly [number, number]): PreprocessSpec;
+declare function computeInputTransform(srcW: number, srcH: number, spec: Pick<PreprocessSpec, "width" | "height" | "fit">): InputTransform;
+/** Model-input point → source pixel point. */
+declare function toSourcePoint(x: number, y: number, t: InputTransform): {
+  x: number;
+  y: number;
+};
+/**
+ * Resizes RGBA → NCHW float32 `[1, 3, height, width]` with bilinear sampling, padding,
+ * channel reordering and normalization per `spec`. Reuses `out` when large enough
+ * (hot-path frame loop).
+ */
+declare function imageToTensor(image: RgbaImage, spec: PreprocessSpec, out?: Float32Array): {
+  tensor: Float32Array;
+  transform: InputTransform;
+};
+//#endregion
+//#region src/decode/rtmdet-ins.d.ts
+/**
+ * RTMDet-Ins decode (mmdeploy end2end export — NMS and mask assembly are baked into the graph).
+ *
+ * Outputs:
+ *   dets   [1, N, 5]        x0, y0, x1, y1 (input px), score
+ *   labels [1, N]           COCO-80 class index (int64)
+ *   masks  [1, N, Hm, Wm]   per-instance probabilities (already sigmoided), input-aligned
+ */
+interface RtmdetInsOutputs {
+  readonly dets: ArrayLike<number>;
+  readonly labels: ArrayLike<number | bigint>;
+  /** Omit to decode boxes only (detection without masks). */
+  readonly masks?: ArrayLike<number>;
+  readonly count: number;
+  readonly maskWidth: number;
+  readonly maskHeight: number;
+}
+interface RtmdetInsDecodeOptions {
+  readonly confidence: number;
+  /** Class-name filter, case-insensitive (all classes when omitted). */
+  readonly classes?: readonly string[];
+  readonly classNames: readonly string[];
+  readonly transform: InputTransform;
+  readonly sourceWidth: number;
+  readonly sourceHeight: number;
+  /** Mask probability threshold. Default 0.5. */
+  readonly maskThreshold?: number;
+  /** Soft-edge band around the threshold. Default 0.05. */
+  readonly featherRadius?: number;
+}
+declare function decodeRtmdetIns(out: RtmdetInsOutputs, opts: RtmdetInsDecodeOptions): SegmentationResult;
+/**
+ * Probability → 0..255 alpha. A hard threshold when `feather` is 0, otherwise a linear ramp
+ * across `[threshold − feather, threshold + feather]` for anti-aliased edges.
+ */
+declare function probabilityToAlpha(threshold: number, feather: number): (p: number) => number;
+//#endregion
+//#region src/decode/rtmo.d.ts
+/**
+ * RTMO decode (one-stage multi-person pose; NMS is baked into the export).
+ *
+ * Outputs:
+ *   dets      [1, N, 5]        x0, y0, x1, y1 (input px), person score
+ *   keypoints [1, N, 17, 3]    x, y (input px), keypoint score — COCO-17 order
+ */
+interface RtmoOutputs {
+  readonly dets: ArrayLike<number>;
+  readonly keypoints: ArrayLike<number>;
+  readonly count: number;
+  /** Values per keypoint (3 for x, y, score). */
+  readonly keypointStride: number;
+}
+interface RtmoDecodeOptions {
+  readonly confidence: number;
+  readonly transform: InputTransform;
+  readonly sourceWidth: number;
+  readonly sourceHeight: number;
+  /** Drop people with fewer keypoints at visibility ≥ 0.3. Default 3. */
+  readonly minVisibleKeypoints?: number;
+  /** Suppress a person whose box overlaps a higher-scored one above this IoU. Default 0.6. */
+  readonly iouThreshold?: number;
+}
+declare const COCO17_KEYPOINT_COUNT = 17;
+declare function decodeRtmo(out: RtmoOutputs, opts: RtmoDecodeOptions): PoseResult;
+//#endregion
+//#region src/decode/selfie.d.ts
+/**
+ * Selfie Segmenter decode: `alphas [1, 1, h, w]` person probability (stretched input) →
+ * frame-sized 0..255 alpha, bilinear-upsampled to the source resolution.
+ */
+interface SelfieDecodeOptions {
+  readonly sourceWidth: number;
+  readonly sourceHeight: number;
+  /** Probability threshold. Default 0.5. */
+  readonly maskThreshold?: number;
+  /** Soft-edge band; the low-res matte reads best with a wide one. Default 0.2. */
+  readonly featherRadius?: number;
+}
+declare function decodeSelfie(alphas: ArrayLike<number>, matteWidth: number, matteHeight: number, opts: SelfieDecodeOptions): PersonMatte;
+//#endregion
+//#region src/gpu/pose-skeleton-renderer.d.ts
+/**
+ * WebGPU skeleton renderer for pose results.
+ *
+ * Rasterizes the primary person's COCO-17 keypoints into an OpenPose-style
+ * conditioning texture natively in VRAM, using the COCO-17 bone set.
+ */
+declare class PoseSkeletonRenderer {
+  private pipeline;
+  constructor(device: GPUDevice);
+  renderToTexture(keypoints: readonly PoseKeypoint[], options: PoseSkeletonOptions, bones?: readonly [{
+    readonly from: 0;
+    readonly to: 5;
+    readonly color: readonly [0, 1, 1, 1];
+  }, {
+    readonly from: 0;
+    readonly to: 6;
+    readonly color: readonly [0, 1, 1, 1];
+  }, {
+    readonly from: 5;
+    readonly to: 6;
+    readonly color: readonly [1, 0, 0, 1];
+  }, {
+    readonly from: 5;
+    readonly to: 7;
+    readonly color: readonly [1, 0.333, 0, 1];
+  }, {
+    readonly from: 7;
+    readonly to: 9;
+    readonly color: readonly [1, 0.667, 0, 1];
+  }, {
+    readonly from: 6;
+    readonly to: 8;
+    readonly color: readonly [1, 1, 0, 1];
+  }, {
+    readonly from: 8;
+    readonly to: 10;
+    readonly color: readonly [0.667, 1, 0, 1];
+  }, {
+    readonly from: 5;
+    readonly to: 11;
+    readonly color: readonly [0.333, 1, 0, 1];
+  }, {
+    readonly from: 6;
+    readonly to: 12;
+    readonly color: readonly [0, 1, 0, 1];
+  }, {
+    readonly from: 11;
+    readonly to: 12;
+    readonly color: readonly [0, 1, 0.333, 1];
+  }, {
+    readonly from: 11;
+    readonly to: 13;
+    readonly color: readonly [0, 1, 0.667, 1];
+  }, {
+    readonly from: 13;
+    readonly to: 15;
+    readonly color: readonly [0, 1, 1, 1];
+  }, {
+    readonly from: 12;
+    readonly to: 14;
+    readonly color: readonly [0, 0.667, 1, 1];
+  }, {
+    readonly from: 14;
+    readonly to: 16;
+    readonly color: readonly [0, 0.333, 1, 1];
+  }]): GPUTexture;
+  destroy(): void;
+}
+//#endregion
+//#region src/gpu/segmentation-texture-pool.d.ts
+interface SegmentationTextureOptions {
+  readonly width: number;
+  readonly height: number;
+  readonly format?: "r8unorm" | "rgba8unorm";
+  readonly label?: string;
+}
+declare class SegmentationTexturePool {
+  private device;
+  private pool;
+  constructor(device: GPUDevice);
+  getOrCreateTexture(key: string, options: SegmentationTextureOptions): GPUTexture;
+  uploadMask(key: string, maskData: Uint8Array | Float32Array, width: number, height: number): GPUTexture;
+  destroy(): void;
+}
+//#endregion
+//#region src/pose/keypoints.d.ts
+/** COCO-17 keypoint indices (RTMO output order). */
+declare const COCO17_KEYPOINTS: {
+  readonly NOSE: 0;
+  readonly LEFT_EYE: 1;
+  readonly RIGHT_EYE: 2;
+  readonly LEFT_EAR: 3;
+  readonly RIGHT_EAR: 4;
+  readonly LEFT_SHOULDER: 5;
+  readonly RIGHT_SHOULDER: 6;
+  readonly LEFT_ELBOW: 7;
+  readonly RIGHT_ELBOW: 8;
+  readonly LEFT_WRIST: 9;
+  readonly RIGHT_WRIST: 10;
+  readonly LEFT_HIP: 11;
+  readonly RIGHT_HIP: 12;
+  readonly LEFT_KNEE: 13;
+  readonly RIGHT_KNEE: 14;
+  readonly LEFT_ANKLE: 15;
+  readonly RIGHT_ANKLE: 16;
+};
+declare const COCO17_KEYPOINT_NAMES: readonly ["nose", "leftEye", "rightEye", "leftEar", "rightEar", "leftShoulder", "rightShoulder", "leftElbow", "rightElbow", "leftWrist", "rightWrist", "leftHip", "rightHip", "leftKnee", "rightKnee", "leftAnkle", "rightAnkle"];
+/** COCO-17 skeleton bones for the WebGPU skeleton renderer (indices above). */
+declare const COCO17_BONES: readonly [{
+  readonly from: 0;
+  readonly to: 5;
+  readonly color: readonly [0, 1, 1, 1];
+}, {
+  readonly from: 0;
+  readonly to: 6;
+  readonly color: readonly [0, 1, 1, 1];
+}, {
+  readonly from: 5;
+  readonly to: 6;
+  readonly color: readonly [1, 0, 0, 1];
+}, {
+  readonly from: 5;
+  readonly to: 7;
+  readonly color: readonly [1, 0.333, 0, 1];
+}, {
+  readonly from: 7;
+  readonly to: 9;
+  readonly color: readonly [1, 0.667, 0, 1];
+}, {
+  readonly from: 6;
+  readonly to: 8;
+  readonly color: readonly [1, 1, 0, 1];
+}, {
+  readonly from: 8;
+  readonly to: 10;
+  readonly color: readonly [0.667, 1, 0, 1];
+}, {
+  readonly from: 5;
+  readonly to: 11;
+  readonly color: readonly [0.333, 1, 0, 1];
+}, {
+  readonly from: 6;
+  readonly to: 12;
+  readonly color: readonly [0, 1, 0, 1];
+}, {
+  readonly from: 11;
+  readonly to: 12;
+  readonly color: readonly [0, 1, 0.333, 1];
+}, {
+  readonly from: 11;
+  readonly to: 13;
+  readonly color: readonly [0, 1, 0.667, 1];
+}, {
+  readonly from: 13;
+  readonly to: 15;
+  readonly color: readonly [0, 1, 1, 1];
+}, {
+  readonly from: 12;
+  readonly to: 14;
+  readonly color: readonly [0, 0.667, 1, 1];
+}, {
+  readonly from: 14;
+  readonly to: 16;
+  readonly color: readonly [0, 0.333, 1, 1];
+}];
+//#endregion
+//#region src/runner/canonical-baselines.d.ts
+/** Neutral fallbacks so signal evaluators always have a well-formed frame to read. */
+declare function createNeutralObjectResult(): {
+  readonly objects: readonly TrackedObject[];
+  readonly rawDetections: readonly DetectedObject[];
+};
+declare function createNeutralPoseResult(): PoseResult;
+/** 17 neutral COCO keypoints at frame center — used by pose signals when nobody is detected. */
+declare function createNeutralLandmarks(): readonly Landmark3D[];
+//#endregion
+//#region src/runtime/webgpu-provider.d.ts
+/** Minimal structural view of the `onnxruntime-web` module — isolates the ORT API surface. */
+interface OrtWebTensor {
+  readonly data: Float32Array | BigInt64Array | Int32Array;
+  readonly dims: readonly number[];
+}
+interface OrtWebSession {
+  readonly inputNames: readonly string[];
+  run(feeds: Record<string, unknown>): Promise<Record<string, OrtWebTensor>>;
+  release(): Promise<void>;
+}
+interface OrtWebModule {
+  readonly InferenceSession: {
+    create(modelBytes: Uint8Array, options: {
+      executionProviders: string[];
+      graphOptimizationLevel?: "disabled" | "basic" | "extended" | "all";
+      /** 0 verbose … 4 fatal. */
+      logSeverityLevel?: 0 | 1 | 2 | 3 | 4;
+    }): Promise<OrtWebSession>;
+  };
+  /** ORT tensor constructor (called with `new`). */
+  readonly Tensor: new (type: "float32", data: Float32Array, dims: readonly number[]) => unknown;
+}
+interface WebGPUProviderOptions {
+  /** Injected ORT loader — defaults to a dynamic `import("onnxruntime-web")`. */
+  readonly loader?: () => Promise<OrtWebModule>;
+  /** Execution providers in priority order. Defaults to `["webgpu", "wasm"]`. */
+  readonly executionProviders?: readonly string[];
+  /** Fall back to WASM automatically if the WebGPU session fails to create. Default true. */
+  readonly wasmFallback?: boolean;
+}
+declare class WebGPUProvider implements SessionProvider {
+  readonly kind: "webgpu";
+  private readonly _loader;
+  private readonly _providers;
+  private readonly _wasmFallback;
+  private _ortPromise?;
+  constructor(options?: WebGPUProviderOptions);
+  private ort;
+  createSession(modelBytes: Uint8Array): Promise<VisionSession>;
+}
+/**
+ * Convenience factory: a `SessionProvider` type guard for the browser entry. Kept tiny so
+ * `@framefields/vision/web` stays tree-shakeable.
+ */
+declare function createWebGPUProvider(options?: WebGPUProviderOptions): WebGPUProvider;
+/** True when the environment exposes a WebGPU device (synchronous capability probe). */
+declare function hasWebGPU(): boolean;
+//#endregion
+//#region src/runtime/node-webgpu-provider.d.ts
+/**
+ * Ensure `globalThis.navigator.gpu` exists. In the renderer this is already the
+ * Dawn device; otherwise imports the `webgpu` (Dawn) package and installs its
+ * globals plus an adapter, which is what onnxruntime-web's WebGPU EP needs.
+ */
+declare function ensureNodeWebGPU(): Promise<void>;
+/** Options mirror the browser provider; the loader is overridden for Node. */
+type NodeWebGPUProviderOptions = WebGPUProviderOptions;
+declare class NodeWebGPUProvider implements SessionProvider {
+  readonly kind: "webgpu";
+  private readonly _inner;
+  constructor(options?: NodeWebGPUProviderOptions);
+  createSession(modelBytes: Uint8Array): Promise<VisionSession>;
+}
+declare function createNodeWebGPUProvider(options?: NodeWebGPUProviderOptions): NodeWebGPUProvider;
+//#endregion
+//#region src/segmentation/subject.d.ts
+/**
+ * The frame's primary instance: the largest person when present, else the most confident
+ * instance (lowest `detectionIndex` — detections are score-sorted). Size alone is a poor
+ * signal without a person: the largest instance is usually a backdrop ("dining table").
+ */
+declare function selectSubjectMask(masks: readonly InstanceMask[]): InstanceMask | undefined;
+interface MaskBounds {
+  readonly x0: number;
+  readonly y0: number;
+  readonly x1: number;
+  readonly y1: number;
+}
+/** Tight pixel bounds of a mask's non-zero alpha, or null when empty. */
+declare function maskBounds(mask: InstanceMask): MaskBounds | null;
+/**
+ * Builds the full subject silhouette: the primary instance plus every comparably sized
+ * instance whose bounds sit mostly inside or across it (`overlap` = intersection / smaller
+ * box area; `maxGrowth` caps a part's box area relative to the subject's).
+ *
+ * COCO has no "clothing" class, so a flowing dress, a held guitar or a ridden bike comes back
+ * as its own instance (often mislabeled) — merging them keeps the whole figure in the cutout.
+ * The size cap keeps containers out: a small figure inside a tunnel or window detected as a
+ * huge "clock" must not drag the whole frame into the subject.
+ */
+declare function mergeSubjectMask(masks: readonly InstanceMask[], overlap?: number, maxGrowth?: number): InstanceMask | undefined;
+//#endregion
+//#region src/signals/vision-bundle.d.ts
+interface VisionBundleOptions {
+  readonly totalFrames?: number;
+  readonly fps?: number;
+  readonly width?: number;
+  readonly height?: number;
+  readonly cameraFov?: number;
+  readonly config?: types_d_exports.VisionConfig;
+}
+/** Named pose landmarks (COCO-17) plus numeric proxy access to any of the 17 keypoints. */
+interface PoseLandmarkSignals {
+  readonly shoulder: LandmarkCoordinateSignals;
+  readonly leftShoulder: LandmarkCoordinateSignals;
+  readonly rightShoulder: LandmarkCoordinateSignals;
+  readonly leftElbow: LandmarkCoordinateSignals;
+  readonly rightElbow: LandmarkCoordinateSignals;
+  readonly leftWrist: LandmarkCoordinateSignals;
+  readonly rightWrist: LandmarkCoordinateSignals;
+  readonly leftHip: LandmarkCoordinateSignals;
+  readonly rightHip: LandmarkCoordinateSignals;
+  readonly leftKnee: LandmarkCoordinateSignals;
+  readonly rightKnee: LandmarkCoordinateSignals;
+  readonly leftAnkle: LandmarkCoordinateSignals;
+  readonly rightAnkle: LandmarkCoordinateSignals;
+  readonly nose: LandmarkCoordinateSignals;
+  readonly leftEye: LandmarkCoordinateSignals;
+  readonly rightEye: LandmarkCoordinateSignals;
+  readonly leftEar: LandmarkCoordinateSignals;
+  readonly rightEar: LandmarkCoordinateSignals;
+  get(keypointIndex: number): LandmarkCoordinateSignals;
+}
+interface TrackPoseSignals extends PoseLandmarkSignals {
+  readonly hasPose: ProgrammaticSignal;
+  readonly wristSpeed: ProgrammaticSignal;
+  readonly handRaised: ProgrammaticSignal;
+  readonly bodyTiltAngle: ProgrammaticSignal;
+}
+interface ObjectBoundingBoxSignals {
+  readonly x: ProgrammaticSignal;
+  readonly y: ProgrammaticSignal;
+  readonly width: ProgrammaticSignal;
+  readonly height: ProgrammaticSignal;
+  readonly screenX: ProgrammaticSignal;
+  readonly screenY: ProgrammaticSignal;
+  readonly screenWidth: ProgrammaticSignal;
+  readonly screenHeight: ProgrammaticSignal;
+  readonly aspectRatio: ProgrammaticSignal;
+  readonly area: ProgrammaticSignal;
+}
+interface ObjectAnchorsSignals {
+  readonly topLeft: LandmarkCoordinateSignals;
+  readonly topCenter: LandmarkCoordinateSignals;
+  readonly topRight: LandmarkCoordinateSignals;
+  readonly centerLeft: LandmarkCoordinateSignals;
+  readonly center: LandmarkCoordinateSignals;
+  readonly centerRight: LandmarkCoordinateSignals;
+  readonly bottomLeft: LandmarkCoordinateSignals;
+  readonly bottomCenter: LandmarkCoordinateSignals;
+  readonly bottomRight: LandmarkCoordinateSignals;
+}
+interface ObjectKinematicsSignals {
+  readonly vx: ProgrammaticSignal;
+  readonly vy: ProgrammaticSignal;
+  readonly speed: ProgrammaticSignal;
+  readonly acceleration: ProgrammaticSignal;
+  readonly headingRad: ProgrammaticSignal;
+  readonly headingDeg: ProgrammaticSignal;
+}
+interface ObjectTrackSignals {
+  readonly trackId: number;
+  readonly category: string;
+  readonly bounds: ObjectBoundingBoxSignals;
+  readonly anchors: ObjectAnchorsSignals;
+  readonly kinematics: ObjectKinematicsSignals;
+  readonly confidence: ProgrammaticSignal;
+  readonly active: ProgrammaticSignal;
+  readonly isCoasting: ProgrammaticSignal;
+  readonly age: ProgrammaticSignal;
+  readonly pose: TrackPoseSignals;
+  readonly center: LandmarkCoordinateSignals;
+  readonly topCenter: LandmarkCoordinateSignals;
+  readonly bottomCenter: LandmarkCoordinateSignals;
+  readonly topLeft: LandmarkCoordinateSignals;
+  readonly bottomLeft: LandmarkCoordinateSignals;
+  readonly [key: string]: unknown;
+}
+interface MaskTrackSignals {
+  readonly trackId: number;
+  readonly category: string;
+  readonly area: ProgrammaticSignal;
+  readonly coverage: ProgrammaticSignal;
+  readonly solidity: ProgrammaticSignal;
+  readonly bboxFill: ProgrammaticSignal;
+  /** Frame-sized {0,255} mask for the current frame (renderer-populated). */
+  data?: Uint8Array;
+  /** GPU-resident silhouette texture (renderer-populated via SegmentationTexturePool). */
+  texture?: GPUTexture;
+}
+interface MaskCollectionSignals {
+  get(trackId: number): MaskTrackSignals;
+  /** Largest instance of the current frame (person preferred when present). */
+  readonly subject: MaskTrackSignals;
+  readonly count: ProgrammaticSignal;
+}
+interface SegmentationSignals {
+  readonly humanSilhouette: MaskTrackSignals;
+  readonly subject: MaskTrackSignals;
+  readonly instanceMasks: MaskCollectionSignals;
+  /** Person-vs-background alpha from the Selfie Segmenter (`enableMatte`). */
+  readonly matte: PersonMatteSignals;
+  readonly stencilTexture?: GPUTexture;
+}
+interface PersonMatteSignals {
+  /** Mean person alpha over the frame, 0..1 (0 when no matte has run). */
+  readonly coverage: ProgrammaticSignal;
+  /** Frame-sized 0..255 alpha for the given frame, if a matte has run. */
+  at(frame: number): PersonMatte | undefined;
+}
+interface ClassSignals {
+  readonly count: ProgrammaticSignal;
+  readonly maxConfidence: ProgrammaticSignal;
+  readonly present: ProgrammaticSignal;
+  readonly primary: ObjectTrackSignals;
+}
+interface ClassCollectionSignals {
+  /** Cached per-class signals (stable identity). */
+  get(name: string): ClassSignals;
+  /** Sorted active category names for the current frame. */
+  readonly names: readonly string[];
+  readonly histogram: {
+    get(ctx?: FrameContext): TensorData;
+    readonly value: TensorData;
+  };
+}
+interface ObjectCollectionSignals {
+  get(trackId: number): ObjectTrackSignals;
+  byCategory(category: string, rank?: number): ObjectTrackSignals;
+  readonly primary: ObjectTrackSignals;
+  readonly count: ProgrammaticSignal;
+  hasCategory(category: string): ProgrammaticSignal;
+  getActiveTracks(frame: number): readonly TrackedObject[];
+  readonly detectedCategories: readonly string[];
+}
+declare class VisionBundle {
+  readonly objects: ObjectCollectionSignals;
+  readonly poseLandmarks: PoseLandmarkSignals;
+  readonly masks: MaskCollectionSignals;
+  readonly segmentation: SegmentationSignals;
+  readonly classes: ClassCollectionSignals;
+  readonly poseLandmarksTensor: {
+    get(ctx?: FrameContext): TensorData;
+    readonly value: TensorData;
+  };
+  readonly objectsTensor: {
+    get(ctx?: FrameContext): TensorData;
+    readonly value: TensorData;
+  };
+  readonly masksTensor: {
+    get(ctx?: FrameContext): TensorData;
+    readonly value: TensorData;
+  };
+  /** Per-class detection histogram [nc] — top-level convenience mirror of `classes.histogram`. */
+  readonly histogramTensor: {
+    get(ctx?: FrameContext): TensorData;
+    readonly value: TensorData;
+  };
+  private _totalFrames;
+  private _fps;
+  private _width;
+  private _height;
+  private _transformer;
+  private _stencilTexture?;
+  private _poseCache;
+  private _objectCache;
+  private _maskCache;
+  private _matteCache;
+  private _poseLmCache;
+  private _trackCache;
+  private _categoryCache;
+  private _classCache;
+  private _maskTrackCache;
+  private _registeredSignals;
+  constructor(options?: VisionBundleOptions);
+  setStencilTexture(texture: GPUTexture): void;
+  get stencilTexture(): GPUTexture | undefined;
+  /**
+   * Reads the most recent result at or before `frame`. Vision results are written one
+   * frame behind the plate (the node renderer reads back the previous frame to infer),
+   * and pinned-signal layout runs before the current frame's inference, so a strict
+   * per-frame lookup would always miss. Walking back a few frames keeps signals live at
+   * a stable one-frame lag instead of snapping to neutral defaults.
+   */
+  private latestAtOrBefore;
+  invalidateSignals(): void;
+  setPoseResult(frame: number, result: PoseResult): void;
+  getPoseResult(frame: number): PoseResult;
+  setObjectResult(frame: number, result: {
+    objects: readonly TrackedObject[];
+    rawDetections?: readonly DetectedObject[];
+  } | readonly TrackedObject[]): void;
+  getObjectResult(frame: number): {
+    objects: readonly TrackedObject[];
+    rawDetections: readonly DetectedObject[];
+  };
+  setMaskResult(frame: number, masks: readonly InstanceMask[]): void;
+  getMaskResult(frame: number): readonly InstanceMask[];
+  setMatteResult(frame: number, matte: PersonMatte): void;
+  getMatteResult(frame: number): PersonMatte | undefined;
+  /**
+   * Serializable snapshot of one frame's object / class / mask signals.
+   * Synchronous — reads only the per-frame caches, never triggers inference.
+   */
+  summary(frame?: number): VisionSummary;
+  /** Primary person's 17 keypoints as a [17, 3] float32 tensor. */
+  getPoseLandmarksTensor(frame: number): TensorData;
+  /** Up to 16 active tracks as [16, 8]: [active, categoryHash, x, y, w, h, vx, vy]. */
+  getObjectsTensor(frame: number, maxObjects?: number): TensorData;
+  /** Per-mask coverage + solidity as [16, 2]. */
+  getMasksTensor(frame: number, maxMasks?: number): TensorData;
+  /** Per-class detection histogram for the frame as [nc] float32 (COCO 80 by default). */
+  getClassHistogramTensor(frame: number, nc?: number): TensorData;
+  private clamp;
+}
+declare function createVisionBundle(options?: VisionBundleOptions): VisionBundle;
+//#endregion
+//#region src/spatial/camera-space-transformer.d.ts
+interface Camera3DSpec {
+  readonly width: number;
+  readonly height: number;
+  readonly fov?: number;
+  readonly cameraDistance?: number;
+}
+interface ProjectedScreenCoordinate {
+  readonly x: number;
+  readonly y: number;
+  readonly z: number;
+  readonly scale: number;
+}
+declare class SpatialLandmarkTransformer {
+  private width;
+  private height;
+  private fovRad;
+  private focalDistance;
+  constructor(camera: Camera3DSpec);
+  /**
+   * Projects a normalized landmark [0, 1] into 2D/3D canvas coordinates.
+   */
+  projectNormalizedLandmark(landmark: Landmark3D, offsetZ?: number): ProjectedScreenCoordinate;
+  /**
+   * Projects a metric world landmark [X_w, Y_w, Z_w] in meters into canvas space.
+   */
+  projectWorldLandmark(worldLandmark: Landmark3D, subjectDistanceMeters?: number, scaleMetersToPixels?: number): ProjectedScreenCoordinate;
+}
+//#endregion
+//#region src/spatial/spatial-pin.d.ts
+declare function pinNodeToLandmark<T extends {
+  x?: unknown;
+  y?: unknown;
+  z?: unknown;
+  [key: string]: unknown;
+}>(node: T, target: LandmarkCoordinateSignals | {
+  x: number;
+  y: number;
+  z?: number;
+  screenX?: number;
+  screenY?: number;
+}, options?: PinToLandmarkOptions): T;
+declare function pinNodeToObject<T extends {
+  x?: unknown;
+  y?: unknown;
+  z?: unknown;
+  width?: unknown;
+  height?: unknown;
+  opacity?: unknown;
+  [key: string]: unknown;
+}>(node: T, target: ObjectTrackSignals | LandmarkCoordinateSignals | {
+  x: number;
+  y: number;
+  z?: number;
+  screenX?: number;
+  screenY?: number;
+}, options?: PinToObjectOptions): T;
+//#endregion
+//#region src/tracking/temporal-object-tracker.d.ts
+interface TemporalTrackerOptions {
+  /** Minimum Intersection-over-Union to associate a detection with an existing track. Default: 0.25 */
+  readonly iouThreshold?: number;
+  /** Number of frames a lost track is coasted via velocity extrapolation before deletion. Default: 15 */
+  readonly maxMissedFrames?: number;
+  /** Minimum consecutive hits before a tentative track is confirmed active. Default: 1 */
+  readonly minHits?: number;
+  /** Position smoothing weight [0, 1] where 1.0 is instantaneous and 0.0 is fully damped. Default: 0.75 */
+  readonly positionSmoothing?: number;
+  /** Whether tracks remain marked active during coasting frames. Default: true */
+  readonly activeDuringCoast?: boolean;
+}
+/** Axis-aligned box in any consistent unit (pixels or normalized). */
+type PixelBox = Pick<ObjectBoundingBox, "originX" | "originY" | "width" | "height">;
+declare function computeIoU(boxA: PixelBox, boxB: PixelBox): number;
+declare class TemporalObjectTracker {
+  private _nextTrackId;
+  private _tracks;
+  private _iouThreshold;
+  private _maxMissedFrames;
+  private _minHits;
+  private _positionSmoothing;
+  private _activeDuringCoast;
+  constructor(options?: TemporalTrackerOptions);
+  /**
+   * Updates the multi-object tracker with new detections for the current frame.
+   *
+   * @param detections Raw detections found on the current frame
+   * @param frame Current frame index
+   * @param fps Video framerate (used for physical velocity estimation)
+   * @returns Stable, temporal list of TrackedObjects
+   */
+  update(detections: readonly DetectedObject[], _frame: number, fps?: number): TrackedObject[];
+  /**
+   * Tracks objects across a full sequence of frames with gap interpolation,
+   * boundary extrapolation (ensuring frame 0 through end are tracked),
+   * and temporal Gaussian smoothing.
+   *
+   * Guarantees zero flicker, zero drift, and frame-accurate stability across the entire video.
+   */
+  trackSequence(perFrameDetections: readonly (readonly DetectedObject[])[], totalFrames: number, fps?: number): TrackedObject[][];
+  /**
+   * Resets all internal track state.
+   */
+  reset(): void;
+}
+//#endregion
+//#region src/tracking/pose-track-matcher.d.ts
+declare function getPersonBoundingBox(person: PosePerson): PixelBox;
+/**
+ * Matches detected pose people with active person tracks using greedy bipartite IoU.
+ *
+ * Annotates each person with the matched trackId.
+ */
+declare function matchPoseToTracks(people: readonly PosePerson[], trackedObjects: readonly TrackedObject[], minIoU?: number): PosePerson[];
+//#endregion
+//#region src/vision-node.d.ts
+/**
+ * Bundle returned by `VisionNode.attach()`: the reactive signals surface plus the lazy lifecycle
+ * helpers (all zero-I/O until `runner()` really needs a model).
+ */
+interface VisionAttachedBundle extends VisionBundle {
+  readonly node: VisionNodeSpec;
+  /** Warm the enabled tasks' models/sessions ahead of first use. */
+  ready(): Promise<VisionRunner>;
+  /** Lazily-created runner (downloads happen on first real inference). */
+  runner(): VisionRunner;
+  /** Release this node's runner/sessions. */
+  close(): void;
+}
+/**
+ * Vision node.
+ *
+ * LAZY BY CONSTRUCTION: creating a VisionNode performs ZERO I/O — no model downloads, no
+ * sessions, no file probes. The first inference call (or an explicit `await vision.ready()`)
+ * downloads the required models.
+ */
+declare class VisionNode {
+  readonly id: string;
+  readonly kind: "vision";
+  readonly source: VisionInputSource;
+  readonly config: VisionConfig;
+  readonly vision: VisionBundle;
+  private _runner?;
+  /** Runner construction options (modelsDir, provider, store, …) — injectable for tests/agents. */
+  private readonly _runnerOptions;
+  constructor(source: VisionInputSource, config?: VisionConfig, bundleOptions?: VisionBundleOptions, runnerOptions?: VisionRunnerOptions);
+  /** Lazily-created runner; downloads happen on its first inference. */
+  runner(): VisionRunner;
+  /** Explicit warm-up — downloads the models for the enabled tasks, ahead of first inference. */
+  ready(): Promise<VisionRunner>;
+  close(): void;
+  static attach(source: VisionInputSource, config?: VisionConfig, bundleOptions?: VisionBundleOptions): VisionAttachedBundle;
+  toNode(): VisionNodeSpec;
+}
+declare namespace index_d_exports {
+  export { AnalyzeSequenceOptions, AutoSessionProvider, COCO17_BONES, COCO17_KEYPOINTS, COCO17_KEYPOINT_COUNT, COCO17_KEYPOINT_NAMES, COCO_CLASSES, Camera3DSpec, ClassCollectionSignals, ClassSignals, CocoClass, InputTransform, InstanceMask, LandmarkCoordinateSignals, MaskBounds, MaskCollectionSignals, MaskTrackSignals, ModelDownloadStatus, NodeSessionProvider, NodeWebGPUProvider, NodeWebGPUProviderOptions, ObjectAnchorName, ObjectAnchorsSignals, ObjectBoundingBoxSignals, ObjectCollectionSignals, ObjectKinematicsSignals, ObjectTrackSignals, PREPROCESS_BY_FAMILY, PersonMatte, PersonMatteSignals, PinToLandmarkOptions, PinToObjectOptions, PixelBox, PoseKeypoint, PoseLandmarkSignals, PosePerson, PoseResult, PoseSkeletonOptions, PoseSkeletonRenderer, PreprocessSpec, ProjectedScreenCoordinate, RgbaImage, RtmdetInsDecodeOptions, RtmdetInsOutputs, RtmoDecodeOptions, RtmoOutputs, SegmentationResult, SegmentationSignals, SegmentationTextureOptions, SegmentationTexturePool, SelfieDecodeOptions, SessionProvider, SkeletonBone, SpatialLandmarkTransformer, TemporalObjectTracker, TemporalTrackerOptions, TrackPoseSignals, VISION_MODELS, VISION_TASKS, VISION_VARIANTS, VisionAnalysisClassSummary, VisionAnalysisReport, VisionAnalysisTrackSummary, VisionAttachedBundle, VisionBundle, VisionBundleOptions, VisionImageInput, VisionInputSource, VisionModelDescriptor, VisionModelFamily, VisionModelKey, VisionModelStore, VisionModelStoreOptions, VisionNode, VisionRunner, VisionRunnerOptions, VisionSession, VisionSummary, VisionTask, VisionTensor, VisionTensorInput, VisionTensorOutputs, VisionVariant, analyzeSequence, computeInputTransform, computeIoU, createDefaultSessionProvider, createNeutralLandmarks, createNeutralObjectResult, createNeutralPoseResult, createNodeWebGPUProvider, createVisionBundle, decodeRtmdetIns, decodeRtmo, decodeSelfie, ensureNodeWebGPU, getDefaultModelsDir, getPersonBoundingBox, imageToTensor, maskBounds, matchPoseToTracks, mergeSubjectMask, modelKeyFor, pinNodeToLandmark, pinNodeToObject, preprocessSpec, probabilityToAlpha, selectSubjectMask, setDefaultSessionProvider, toSourcePoint };
+}
+//#endregion
+export { SegmentationTexturePool as $, getDefaultModelsDir as $t, createVisionBundle as A, PinToObjectOptions as At, OrtWebSession as B, VisionSummary as Bt, ObjectTrackSignals as C, VisionRunner as Ct, TrackPoseSignals as D, ObjectAnchorName as Dt, SegmentationSignals as E, LandmarkCoordinateSignals as Et, NodeWebGPUProvider as F, VisionAnalysisClassSummary as Ft, hasWebGPU as G, VisionTensor as Gt, WebGPUProvider as H, NodeSessionProvider as Ht, NodeWebGPUProviderOptions as I, VisionAnalysisReport as It, createNeutralPoseResult as J, createDefaultSessionProvider as Jt, createNeutralLandmarks as K, VisionTensorInput as Kt, createNodeWebGPUProvider as L, VisionAnalysisTrackSummary as Lt, maskBounds as M, PosePerson as Mt, mergeSubjectMask as N, PoseResult as Nt, VisionBundle as O, PersonMatte as Ot, selectSubjectMask as P, SegmentationResult as Pt, SegmentationTextureOptions as Q, VisionModelStoreOptions as Qt, ensureNodeWebGPU as R, VisionImageInput as Rt, ObjectKinematicsSignals as S, analyzeSequence as St, PoseLandmarkSignals as T, InstanceMask as Tt, WebGPUProviderOptions as U, SessionProvider as Ut, OrtWebTensor as V, AutoSessionProvider as Vt, createWebGPUProvider as W, VisionSession as Wt, COCO17_KEYPOINTS as X, ModelDownloadStatus as Xt, COCO17_BONES as Y, setDefaultSessionProvider as Yt, COCO17_KEYPOINT_NAMES as Z, VisionModelStore as Zt, MaskCollectionSignals as _, computeInputTransform as _t, matchPoseToTracks as a, VisionModelDescriptor as an, COCO17_KEYPOINT_COUNT as at, ObjectBoundingBoxSignals as b, toSourcePoint as bt, TemporalTrackerOptions as c, VisionTask as cn, decodeRtmo as ct, pinNodeToObject as d, decodeRtmdetIns as dt, COCO_CLASSES as en, PoseSkeletonOptions as et, Camera3DSpec as f, probabilityToAlpha as ft, ClassSignals as g, RgbaImage as gt, ClassCollectionSignals as h, PreprocessSpec as ht, getPersonBoundingBox as i, VISION_VARIANTS as in, decodeSelfie as it, MaskBounds as j, PoseKeypoint as jt, VisionBundleOptions as k, PinToLandmarkOptions as kt, computeIoU as l, VisionVariant as ln, RtmdetInsDecodeOptions as lt, SpatialLandmarkTransformer as m, PREPROCESS_BY_FAMILY as mt, VisionAttachedBundle as n, VISION_MODELS as nn, SkeletonBone as nt, PixelBox as o, VisionModelFamily as on, RtmoDecodeOptions as ot, ProjectedScreenCoordinate as p, InputTransform as pt, createNeutralObjectResult as q, VisionTensorOutputs as qt, VisionNode as r, VISION_TASKS as rn, SelfieDecodeOptions as rt, TemporalObjectTracker as s, VisionModelKey as sn, RtmoOutputs as st, index_d_exports as t, CocoClass as tn, PoseSkeletonRenderer as tt, pinNodeToLandmark as u, modelKeyFor as un, RtmdetInsOutputs as ut, MaskTrackSignals as v, imageToTensor as vt, PersonMatteSignals as w, VisionRunnerOptions as wt, ObjectCollectionSignals as x, AnalyzeSequenceOptions as xt, ObjectAnchorsSignals as y, preprocessSpec as yt, OrtWebModule as z, VisionInputSource as zt };
+//# sourceMappingURL=index-CoAN0xxG.d.mts.map