@sekyro/web 0.0.0-stage → 0.1.0-rc.2

package/dist/create-verification-EnZ13uY4.d.cts

@@ -0,0 +1,348 @@
+import { h as CaptureState$1, f as CaptureSessionV3Events, g as CaptureSessionV3Options, c as CaptureErrorKind$1 } from './capture-session-v3-CAoWM8iT.cjs';
+import { C as CheckReason, c as HostedSessionView, g as HostedClient, A as AttestationInput, h as SessionView, b as CheckType } from './hosted-client-BpvBqu9f.cjs';
+
+/** Gate guidance code. `'hold'` is emitted while the clip records. */
+type GateHint = "center" | "closer" | "farther" | "light" | "still" | "hold";
+/**
+ * Capture + verification state, as seen by the partner:
+ *  - `idle → starting → gating → recording → captured` is the engine's run;
+ *  - `uploading → checking → done` follows ONLY when the handle was obtained via
+ *    {@link Verification.liveness} (the SDK uploads and submits after `captured`);
+ *  - `error` on a camera / engine failure (see {@link CaptureError}).
+ */
+type CaptureState = "idle" | "starting" | "gating" | "recording" | "captured" | "uploading" | "checking" | "done" | "error";
+/** Declared capture channel — the liveness band is mobile-calibrated. */
+type CaptureChannel = "mobile" | "desktop";
+/** Gate ring update: integrator progress 0..1 and the current guidance code. */
+interface GateUpdate {
+    /** Gate integrator 0..1 — drive the ring off this directly. */
+    progress: number;
+    /** Current guidance code, `null` when no hint applies. */
+    hint: GateHint | null;
+    /**
+     * The detector currently sees a face (a non-zero engine presence factor). `false`
+     * with `hint: 'center'` means "no face in frame" rather than "off-center" —
+     * hosts use it to tell seeking from aligning, and for the no-face copy.
+     */
+    faceDetected: boolean;
+}
+/**
+ * What the engine captured. Fires BEFORE any upload. `clip` is absent only in
+ * the `degraded: 'NO_RECORDER'` case (no MediaRecorder on this browser).
+ */
+interface CapturedArtifacts {
+    /** Mirrored JPEG keyframe (the face_match probe). */
+    keyframe: Blob;
+    /** The 2.5 s liveness clip (MP4-first mime ladder). */
+    clip?: Blob;
+    /** Container mime the clip finalized with — may carry codec params. */
+    clipMime?: string;
+    /** Intrinsic video width at capture time. */
+    width: number;
+    /** Intrinsic video height at capture time. */
+    height: number;
+    /** Recording-start → recording-stop, when known. */
+    clipMs?: number;
+    /** `'mobile'` on phones/tablets (the calibrated channel), else `'desktop'`. */
+    captureChannel: CaptureChannel;
+    /** Set when the browser has no MediaRecorder: a keyframe-only capture. */
+    degraded?: "NO_RECORDER";
+}
+/** Camera / engine failure kinds — collapsed to the public six. */
+type CaptureErrorKind = "permission" | "notfound" | "inuse" | "insecure" | "unsupported" | "generic";
+/** Camera / engine failure payload (`on('error')`). */
+interface CaptureError {
+    kind: CaptureErrorKind;
+    /**
+     * A fresh attempt (`retry()`) can succeed — false for `insecure` (needs
+     * HTTPS) and `unsupported` (the browser cannot capture at all).
+     */
+    retryable: boolean;
+}
+/** Event map of a {@link LivenessCaptureHandle}. */
+interface LivenessCaptureEvents {
+    /** Every state transition. */
+    state: CaptureState;
+    /** Gate ring updates while gating/recording. */
+    gate: GateUpdate;
+    /** The capture result — fires BEFORE any upload. */
+    captured: CapturedArtifacts;
+    /** Camera / engine failure. */
+    error: CaptureError;
+    /**
+     * Clip mode only: the recording window just ended and the keyframe is already
+     * available, BEFORE the clip finalizes (iOS can lag ~1.5 s). Hosts freeze the
+     * display on `previewDataUrl` (a mirrored JPEG data URL) instead of leaving
+     * the live feed running; `captured` follows once the clip lands.
+     */
+    frozen: {
+        previewDataUrl: string;
+    };
+    /**
+     * Device-profile hint, emitted when it changes: `'reduced'` asks the host to
+     * drop decorative animations (a LOW device class needs the frames for
+     * detection). Chrome only — never gate input.
+     */
+    profile: {
+        animations: "full" | "reduced";
+    };
+}
+/** Live capture handle returned by {@link createLivenessCapture} / {@link Verification.liveness}. */
+interface LivenessCaptureHandle {
+    /** Current {@link CaptureState}. */
+    readonly state: CaptureState;
+    /** Subscribe; returns the unsubscribe function. */
+    on<K extends keyof LivenessCaptureEvents>(event: K, handler: (payload: LivenessCaptureEvents[K]) => void): () => void;
+    /** Ask for the camera and start gating. Resolves once the attempt is running or failed. */
+    start(): Promise<void>;
+    /** Fresh attempt: resets the engine and restarts the camera. */
+    retry(): void;
+    /** Toggle user/environment camera (gate restarts from zero). */
+    switchCamera(): void;
+    /** Stop the camera, release the detector, drop all listeners. */
+    destroy(): void;
+}
+/** Options of {@link createLivenessCapture} / {@link Verification.liveness}. */
+interface LivenessCaptureOptions {
+    /** Host-owned `<video playsInline muted>` element. */
+    video: HTMLVideoElement;
+    /** Initial camera; default `'user'`. */
+    facing?: "user" | "environment";
+    /** Base URL of the detector assets (tasks-vision wasm + tflite); default `/models-v3`. */
+    assetBaseUrl?: string;
+}
+/**
+ * SDK-side failure reasons (status `'unavailable'`):
+ *  - `no_recorder` — no MediaRecorder / unsupported clip container;
+ *  - `attestation` — Turnstile failed client-side or `attestation_invalid` after one retry;
+ *  - `network` — transport / API failure after the bounded replays;
+ *  - `nni_unbound` — `population_registry` is the frontier but the session was
+ *    minted WITHOUT a server-bound NNI (`POST /sessions` `input.nni`), so the
+ *    SDK cannot submit it. Mint the session with the NNI (or complete the
+ *    population step yourself) before starting the capture.
+ */
+type SdkFailureReason = "no_recorder" | "attestation" | "network" | "nni_unbound";
+/** Backend reason taxonomy ∪ the SDK-side failure reasons. */
+type ReasonCode = CheckReason | SdkFailureReason;
+/**
+ * - `approved` / `rejected` / `review` — the session's verdict;
+ * - `retry` — a retryable reason with attempts remaining (`autoRetry` on); the
+ *   capture re-arms by itself;
+ * - `unavailable` — v2 could not run this capture (no MediaRecorder,
+ *   attestation failed, network/API failure). Treat as "not completed".
+ */
+type VerificationStatus = "approved" | "rejected" | "review" | "retry" | "unavailable";
+/** The verdict for this session / capture (`on('result')`). */
+interface VerificationResult {
+    sessionId: string;
+    status: VerificationStatus;
+    /** Backend reason, or the SDK-side failure reason for `unavailable`. */
+    reason?: ReasonCode;
+    /**
+     * `retry` (and a `rejected` on a still-parked step): submissions left for
+     * the parked check after this one, for the host's coaching copy.
+     */
+    attemptsRemaining?: number;
+}
+/** Consent locale picklist (mirrors the backend HostedConsentSchema). */
+type VerificationLocale = "ar" | "fr" | "en";
+/** Options of {@link createVerification}. */
+interface VerificationOptions {
+    /** The session's client token (from `POST /api/v2/sessions` → `client_token`). */
+    clientToken: string;
+    /** API origin; default `https://api.sekyro.ai`. */
+    apiOrigin?: string;
+    /** Consent locale (echoed into the auditable consent record). */
+    locale: VerificationLocale;
+    /** Re-arm the capture on retryable reasons while attempts remain. Default `true`. */
+    autoRetry?: boolean;
+    /**
+     * How a `retry` verdict re-arms the capture (`autoRetry` on):
+     *  - `'auto'` (default) — the camera restarts immediately;
+     *  - `'manual'` — the handle settles at `done`; the host shows its coaching
+     *    and calls `retry()` on the handle when the user is ready.
+     */
+    rearm?: "auto" | "manual";
+    /** Injection seam for `fetch` (tests / non-window contexts). */
+    fetch?: typeof globalThis.fetch;
+}
+/** Event map of a {@link Verification}. */
+interface VerificationEvents {
+    /** Verdict per capture (and once when the registry settles the session early). */
+    result: VerificationResult;
+    /** Every hosted-view update the SDK observes (bootstrap, consent, submits). */
+    view: HostedSessionView;
+}
+/** One session's verification, from {@link createVerification}. */
+interface Verification {
+    /** Record consent once (no-op when the session already has it). */
+    consent(): Promise<void>;
+    /**
+     * Submit `population_registry` early with the SERVER-bound NNI (empty input)
+     * when it is the pending frontier. Retries once on `registry_unavailable`.
+     * Never rejects — failures surface through `result`. Idempotent.
+     */
+    startRegistry(): Promise<void>;
+    /** Start a liveness capture bound to this verification; the SDK uploads + submits on `captured`. */
+    liveness(options: LivenessCaptureOptions): LivenessCaptureHandle;
+    /** Subscribe; returns the unsubscribe function. */
+    on<K extends keyof VerificationEvents>(event: K, handler: (payload: VerificationEvents[K]) => void): () => void;
+    /** Destroy the active capture and drop all listeners. */
+    destroy(): void;
+}
+
+/** The engine surface the handle binds — CaptureSessionV3 or a test double. */
+interface CaptureEngine {
+    readonly state: CaptureState$1;
+    on<K extends keyof CaptureSessionV3Events>(event: K, handler: (payload: CaptureSessionV3Events[K]) => void): () => void;
+    start(): Promise<void>;
+    retry(): void;
+    switchCamera(): void;
+    destroy(): void;
+    /** Device-profile chrome hint (LOW class → `'reduced'`); absent on doubles. */
+    readonly animations?: "full" | "reduced";
+}
+/** Internal construction seams (tests; Sekyro's own hosted page). */
+interface LivenessCaptureInternals {
+    /** Replace the engine constructor (default: `new CaptureSessionV3(options)`). */
+    createEngine?: (options: CaptureSessionV3Options) => CaptureEngine;
+    /** Extra engine options merged in (worker offload, warmed detector, telemetry). */
+    engineOptions?: Partial<Pick<CaptureSessionV3Options, "createDetector" | "createWorker" | "telemetry" | "deviceClass">>;
+    /** Clock (default `performance.now`). */
+    now?: () => number;
+}
+/** fcv3.* guidance key → public gate hint code. */
+declare function mapGuidanceHint(key: string): GateHint | null;
+/** Engine state → public state (`preflight|acquiring → starting`, `positioning → gating`). */
+declare function mapEngineState(state: CaptureState$1): CaptureState;
+/** Engine error kinds → the public six (`models|cliptoolarge|recorder|overconstrained → generic`). */
+declare function mapErrorKind(kind: CaptureErrorKind$1): CaptureErrorKind;
+/** Handle + the hooks the verification layer uses to drive the flow states. */
+interface LivenessCaptureInternalHandle {
+    handle: LivenessCaptureHandle;
+    /** Push a post-capture state (`uploading | checking | done`). */
+    setFlowState(state: Extract<CaptureState, "uploading" | "checking" | "done">): void;
+}
+declare function createLivenessCaptureInternal(options: LivenessCaptureOptions, internals?: LivenessCaptureInternals): LivenessCaptureInternalHandle;
+/**
+ * Create a standalone liveness capture (no upload — pair it with your own
+ * submission, or use {@link Verification.liveness} for the full flow).
+ */
+declare function createLivenessCapture(options: LivenessCaptureOptions): LivenessCaptureHandle;
+
+/** The client surface the flow needs — `HostedClient` or a test fake. */
+type HostedClientLike = Pick<HostedClient, "getSession" | "recordConsent" | "presign" | "uploadToSpaces" | "completeMedia" | "submitCheck">;
+/** The presign policy allowlist for `kind: 'clip'` (media.policy.ts mirror). */
+declare const CLIP_MIME_ALLOWLIST: readonly string[];
+/** Same-key transport replays AFTER the first try, and the pause between them. */
+declare const TRANSPORT_REPLAY_ATTEMPTS = 2;
+declare const TRANSPORT_REPLAY_DELAY_MS = 1000;
+/** A Turnstile challenge failed client-side (load / render / error-callback / timeout). */
+declare class AttestationError extends Error {
+    constructor(message: string);
+}
+/** One logical submission: receives the client and ITS idempotency key. */
+type SubmitExecutor = (client: HostedClientLike, idempotencyKey: string) => Promise<SessionView>;
+interface SubmitRuntime {
+    client: HostedClientLike;
+    /** Force-record consent (the server just said it is missing). */
+    ensureConsent(opts: {
+        force: true;
+    }): Promise<void>;
+    sleep(ms: number): Promise<void>;
+    uuid(): string;
+}
+/**
+ * Run one logical submission (ported use-submit semantics):
+ *  - a fresh `crypto.randomUUID()` key per logical submission;
+ *  - a transport-class failure replays the SAME executor under the SAME key
+ *    (bounded) — the backend's IdempotencyInterceptor returns the first
+ *    response instead of burning another attempt;
+ *  - ONE `consent_required` recovery: force-record consent and re-run under a
+ *    FRESH key (the 409 envelope is idempotency-cached under the old one);
+ *  - ONE attestation retry (client-side Turnstile failure or a server
+ *    `attestation_invalid`): `onAttestationInvalid` drops the cached token and
+ *    the executor re-runs under a fresh key.
+ * Throws the final error otherwise.
+ */
+declare function runSubmission(rt: SubmitRuntime, executor: SubmitExecutor, hooks?: {
+    onAttestationInvalid?: () => void;
+}): Promise<SessionView>;
+interface LivenessFlowDeps extends SubmitRuntime {
+    artifacts: CapturedArtifacts;
+    /** Fresh attestation per call (Turnstile execute, or `{sandbox: true}`). */
+    getAttestation(): Promise<AttestationInput>;
+    /** Latest hosted view (frontier decisions). */
+    getView(): HostedSessionView;
+    /** Re-GET the view from the server (after a RESYNC code) and fold it in. */
+    refreshView(): Promise<HostedSessionView>;
+    /** Fold a submit response into the view. */
+    applySubmit(view: SessionView, submitted: CheckType): void;
+    /** Flow-state hook for the capture handle. */
+    onPhase(phase: "uploading" | "checking"): void;
+    /** The verification was destroyed (the only thing that cancels a chain). */
+    isCancelled(): boolean;
+}
+type LivenessFlowOutcome = {
+    kind: "settled";
+} | {
+    kind: "resync";
+} | {
+    kind: "unavailable";
+    reason: SdkFailureReason;
+} | {
+    kind: "cancelled";
+};
+/**
+ * Run the biometric submissions the CURRENT frontier allows, re-evaluating
+ * after every submit and after every RESYNC re-GET:
+ *  - frontier `liveness` → clip upload + attestation + `liveness` (once per capture);
+ *  - frontier `face_match` → keyframe upload + `face_match` (once per capture),
+ *    allowed when liveness was NOT part of this capture (it had already
+ *    settled — any state, incl. `failed`: the selfie-fallback case, where this
+ *    capture only feeds face_match) or settled chainable from this capture
+ *    (passed / review / processing / skipped — or absent);
+ *  - anything else (terminal view, a non-biometric frontier, a check this
+ *    capture already submitted) → `settled` for the caller to map the view.
+ * A RESYNC code re-GETs the view and re-enters (at most {@link RESYNC_REENTRY_MAX}
+ * times); the final RESYNC surfaces as `resync` for the caller to map.
+ */
+declare function runLivenessFlow(deps: LivenessFlowDeps): Promise<LivenessFlowOutcome>;
+
+/** Production API origin — the `apiOrigin` default. */
+declare const DEFAULT_API_ORIGIN = "https://api.sekyro.ai";
+/** Pause before the single `registry_unavailable` re-submit. */
+declare const REGISTRY_RETRY_DELAY_MS = 5000;
+/** Bounded poll while a biometric verdict is still `processing` after the submits. */
+declare const PROCESSING_POLL_DELAY_MS = 1500;
+declare const PROCESSING_POLL_MAX = 10;
+/**
+ * Construction seams — tests and Sekyro's own hosted page (`@sekyro/web/internal`).
+ * Not part of the partner contract.
+ */
+interface VerificationInternals {
+    /** Replace the HTTP client (default: `new HostedClient({...})`). */
+    client?: HostedClientLike;
+    /**
+     * Replace the Turnstile challenge (default: {@link executeTurnstile}). The
+     * `signal` aborts when the verification is destroyed (M1).
+     */
+    getTurnstileToken?: (siteKey: string, opts: {
+        signal: AbortSignal;
+    }) => Promise<string>;
+    /** Capture-engine seams forwarded to {@link createLivenessCaptureInternal}. */
+    capture?: LivenessCaptureInternals;
+    sleep?: (ms: number) => Promise<void>;
+    uuid?: () => string;
+}
+/** `crypto.randomUUID()` with a v4 fallback for hosts that lack it. */
+declare function randomUuid(): string;
+/**
+ * Create a verification bound to one session (spec §3.1):
+ * `consent()` → `startRegistry()` → `liveness({video})` → `on('result')`.
+ */
+declare function createVerification(options: VerificationOptions): Verification;
+/** {@link createVerification} with construction seams (tests / Sekyro-internal hosts). */
+declare function createVerificationInternal(options: VerificationOptions, internals: VerificationInternals): Verification;
+
+export { AttestationError as A, createLivenessCaptureInternal as B, type CaptureChannel as C, DEFAULT_API_ORIGIN as D, createVerificationInternal as E, mapEngineState as F, type GateHint as G, type HostedClientLike as H, mapErrorKind as I, mapGuidanceHint as J, randomUuid as K, type LivenessCaptureEvents as L, runLivenessFlow as M, runSubmission as N, PROCESSING_POLL_DELAY_MS as P, type ReasonCode as R, type SdkFailureReason as S, TRANSPORT_REPLAY_ATTEMPTS as T, type Verification as V, type CaptureError as a, type CaptureErrorKind as b, type CaptureState as c, type CapturedArtifacts as d, type GateUpdate as e, type LivenessCaptureHandle as f, type LivenessCaptureOptions as g, type VerificationEvents as h, type VerificationLocale as i, type VerificationOptions as j, type VerificationResult as k, type VerificationStatus as l, createLivenessCapture as m, createVerification as n, CLIP_MIME_ALLOWLIST as o, type CaptureEngine as p, type LivenessCaptureInternalHandle as q, type LivenessCaptureInternals as r, type LivenessFlowDeps as s, type LivenessFlowOutcome as t, PROCESSING_POLL_MAX as u, REGISTRY_RETRY_DELAY_MS as v, type SubmitExecutor as w, type SubmitRuntime as x, TRANSPORT_REPLAY_DELAY_MS as y, type VerificationInternals as z };

package/dist/detect-worker-CKXHlXx9.d.cts

@@ -0,0 +1,105 @@
+interface FaceObservation {
+    /** Stream-pixel box. */
+    box: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** Stream-pixel eye centers when the tier provides them (native:
+     *  landmarks?, blaze: keypoints). Convention: `left` = smaller x in IMAGE
+     *  coordinates — gate math only uses the midpoint and |roll|, so the
+     *  person-left/image-left distinction never matters. */
+    eyes?: {
+        left: {
+            x: number;
+            y: number;
+        };
+        right: {
+            x: number;
+            y: number;
+        };
+    };
+    score: number;
+}
+interface Detector {
+    readonly tier: "native" | "blaze";
+    /** Why higher tiers were skipped (telemetry) — absent when the first
+     *  preference won. */
+    readonly fallbackReason?: string;
+    /** Detect on a (possibly downscaled) snapshot; `sourceWidth/Height` are the
+     *  STREAM dimensions the observation must be normalized to. Returns the
+     *  single most-confident face or null; NEVER rejects. */
+    detect(source: CanvasImageSource, sourceWidth: number, sourceHeight: number): Promise<FaceObservation | null>;
+    destroy(): void;
+}
+interface CreateDetectorOptions {
+    /** v3 self-hosted assets base (tasks-vision wasm + blaze tflite) — hosted
+     *  serves `/models-v3`, a sha256-manifested directory. */
+    v3AssetBaseUrl?: string;
+    preferred?: Detector["tier"][];
+    /** Test/tuning override for the blaze init deadline. */
+    blazeInitTimeoutMs?: number;
+}
+declare const DEFAULT_V3_ASSET_BASE_URL = "/models-v3";
+declare const DEFAULT_TIER_ORDER: Detector["tier"][];
+/** Thrown by createDetector when the ENTIRE tier ladder is exhausted. Since the
+ *  face-api floor was dropped (2026-07-09) there is no last resort, so blaze
+ *  failing on an already-native-less platform leaves NO detector. Carries the
+ *  joined per-tier reasons ('native:unsupported; blaze:blaze_init_timeout') as
+ *  `fallbackReason` for telemetry. Callers MUST map this to a retryable models
+ *  error — never a hang (CaptureSessionV3.run → error{kind:'models'}). */
+declare class DetectorLadderError extends Error {
+    readonly fallbackReason: string;
+    constructor(fallbackReason: string);
+}
+/** Intrinsic pixel size of a snapshot source (video → videoWidth, image →
+ *  naturalWidth, canvas/bitmap → width). Property-sniffed so worker-side
+ *  sources (OffscreenCanvas, ImageBitmap) work without instanceof. */
+declare function intrinsicSize(source: CanvasImageSource): {
+    width: number;
+    height: number;
+};
+/** Scale a source-space observation to stream px. Exported for adapters. */
+declare function toStreamPixels(observation: FaceObservation, source: CanvasImageSource, streamWidth: number, streamHeight: number): FaceObservation;
+declare function createDetector(options: CreateDetectorOptions): Promise<Detector>;
+
+declare const WORKER_PROTOCOL_VERSION = 1;
+/** The slice of Worker/scope surface the protocol needs — test-stubbable. */
+interface WorkerScopeLike {
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
+    postMessage(data: unknown): void;
+}
+interface WorkerLike {
+    postMessage(data: unknown, transfer?: Transferable[]): void;
+    addEventListener(type: "message", listener: (event: {
+        data: unknown;
+    }) => void): void;
+    removeEventListener(type: "message", listener: (event: {
+        data: unknown;
+    }) => void): void;
+    terminate(): void;
+}
+/** Feature gate: bitmap capture + transfer + workers must all exist. */
+declare function workerOffloadSupported(): boolean;
+/** Worker-side message host. `deps.createDetector` is a test seam. */
+declare function installWorkerDetectorHost(scope: WorkerScopeLike, deps?: {
+    createDetector?: (options: CreateDetectorOptions) => Promise<Detector>;
+}): void;
+/** Main-side Detector over the worker protocol. Same interface as the
+ *  in-thread detectors — Task 10's engine cannot tell the difference. */
+declare class WorkerDetectorProxy implements Detector {
+    readonly tier: Detector["tier"];
+    readonly fallbackReason?: string;
+    private readonly worker;
+    private readonly pending;
+    private nextId;
+    private constructor();
+    static create(worker: WorkerLike, options: CreateDetectorOptions, readyTimeoutMs?: number): Promise<WorkerDetectorProxy>;
+    detect(source: CanvasImageSource, sourceWidth: number, sourceHeight: number): Promise<FaceObservation | null>;
+    destroy(): void;
+}
+
+export { type CreateDetectorOptions as C, DEFAULT_TIER_ORDER as D, type FaceObservation as F, type WorkerLike as W, DEFAULT_V3_ASSET_BASE_URL as a, type Detector as b, DetectorLadderError as c, createDetector as d, WORKER_PROTOCOL_VERSION as e, WorkerDetectorProxy as f, type WorkerScopeLike as g, installWorkerDetectorHost as h, intrinsicSize as i, toStreamPixels as t, workerOffloadSupported as w };

package/dist/detect-worker-CKXHlXx9.d.ts

@@ -0,0 +1,105 @@
+interface FaceObservation {
+    /** Stream-pixel box. */
+    box: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** Stream-pixel eye centers when the tier provides them (native:
+     *  landmarks?, blaze: keypoints). Convention: `left` = smaller x in IMAGE
+     *  coordinates — gate math only uses the midpoint and |roll|, so the
+     *  person-left/image-left distinction never matters. */
+    eyes?: {
+        left: {
+            x: number;
+            y: number;
+        };
+        right: {
+            x: number;
+            y: number;
+        };
+    };
+    score: number;
+}
+interface Detector {
+    readonly tier: "native" | "blaze";
+    /** Why higher tiers were skipped (telemetry) — absent when the first
+     *  preference won. */
+    readonly fallbackReason?: string;
+    /** Detect on a (possibly downscaled) snapshot; `sourceWidth/Height` are the
+     *  STREAM dimensions the observation must be normalized to. Returns the
+     *  single most-confident face or null; NEVER rejects. */
+    detect(source: CanvasImageSource, sourceWidth: number, sourceHeight: number): Promise<FaceObservation | null>;
+    destroy(): void;
+}
+interface CreateDetectorOptions {
+    /** v3 self-hosted assets base (tasks-vision wasm + blaze tflite) — hosted
+     *  serves `/models-v3`, a sha256-manifested directory. */
+    v3AssetBaseUrl?: string;
+    preferred?: Detector["tier"][];
+    /** Test/tuning override for the blaze init deadline. */
+    blazeInitTimeoutMs?: number;
+}
+declare const DEFAULT_V3_ASSET_BASE_URL = "/models-v3";
+declare const DEFAULT_TIER_ORDER: Detector["tier"][];
+/** Thrown by createDetector when the ENTIRE tier ladder is exhausted. Since the
+ *  face-api floor was dropped (2026-07-09) there is no last resort, so blaze
+ *  failing on an already-native-less platform leaves NO detector. Carries the
+ *  joined per-tier reasons ('native:unsupported; blaze:blaze_init_timeout') as
+ *  `fallbackReason` for telemetry. Callers MUST map this to a retryable models
+ *  error — never a hang (CaptureSessionV3.run → error{kind:'models'}). */
+declare class DetectorLadderError extends Error {
+    readonly fallbackReason: string;
+    constructor(fallbackReason: string);
+}
+/** Intrinsic pixel size of a snapshot source (video → videoWidth, image →
+ *  naturalWidth, canvas/bitmap → width). Property-sniffed so worker-side
+ *  sources (OffscreenCanvas, ImageBitmap) work without instanceof. */
+declare function intrinsicSize(source: CanvasImageSource): {
+    width: number;
+    height: number;
+};
+/** Scale a source-space observation to stream px. Exported for adapters. */
+declare function toStreamPixels(observation: FaceObservation, source: CanvasImageSource, streamWidth: number, streamHeight: number): FaceObservation;
+declare function createDetector(options: CreateDetectorOptions): Promise<Detector>;
+
+declare const WORKER_PROTOCOL_VERSION = 1;
+/** The slice of Worker/scope surface the protocol needs — test-stubbable. */
+interface WorkerScopeLike {
+    onmessage: ((event: {
+        data: unknown;
+    }) => void) | null;
+    postMessage(data: unknown): void;
+}
+interface WorkerLike {
+    postMessage(data: unknown, transfer?: Transferable[]): void;
+    addEventListener(type: "message", listener: (event: {
+        data: unknown;
+    }) => void): void;
+    removeEventListener(type: "message", listener: (event: {
+        data: unknown;
+    }) => void): void;
+    terminate(): void;
+}
+/** Feature gate: bitmap capture + transfer + workers must all exist. */
+declare function workerOffloadSupported(): boolean;
+/** Worker-side message host. `deps.createDetector` is a test seam. */
+declare function installWorkerDetectorHost(scope: WorkerScopeLike, deps?: {
+    createDetector?: (options: CreateDetectorOptions) => Promise<Detector>;
+}): void;
+/** Main-side Detector over the worker protocol. Same interface as the
+ *  in-thread detectors — Task 10's engine cannot tell the difference. */
+declare class WorkerDetectorProxy implements Detector {
+    readonly tier: Detector["tier"];
+    readonly fallbackReason?: string;
+    private readonly worker;
+    private readonly pending;
+    private nextId;
+    private constructor();
+    static create(worker: WorkerLike, options: CreateDetectorOptions, readyTimeoutMs?: number): Promise<WorkerDetectorProxy>;
+    detect(source: CanvasImageSource, sourceWidth: number, sourceHeight: number): Promise<FaceObservation | null>;
+    destroy(): void;
+}
+
+export { type CreateDetectorOptions as C, DEFAULT_TIER_ORDER as D, type FaceObservation as F, type WorkerLike as W, DEFAULT_V3_ASSET_BASE_URL as a, type Detector as b, DetectorLadderError as c, createDetector as d, WORKER_PROTOCOL_VERSION as e, WorkerDetectorProxy as f, type WorkerScopeLike as g, installWorkerDetectorHost as h, intrinsicSize as i, toStreamPixels as t, workerOffloadSupported as w };