tempest-react-sdk 0.35.0 → 0.36.0

package/dist/vision/use-camera-stream.cjs

@@ -1,2 +1,2 @@
-let e=require("react");var t={video:{facingMode:{ideal:`environment`},width:{ideal:1920},height:{ideal:1080}},audio:!1};function n(e){if(typeof window>`u`)return{kind:`unsupported`,message:`Camera is unavailable in this environment.`};if(!window.isSecureContext)return{kind:`insecure`,message:`Camera access requires a secure (HTTPS) connection.`};if(e instanceof DOMException)switch(e.name){case`NotAllowedError`:case`SecurityError`:return{kind:`permission-denied`,message:`Camera permission denied. Enable access in your browser settings.`};case`NotFoundError`:case`OverconstrainedError`:return{kind:`no-camera`,message:`No camera available on this device.`};case`NotReadableError`:case`AbortError`:return{kind:`in-use`,message:`The camera is in use by another app. Close it and try again.`}}return{kind:`unknown`,message:e instanceof Error?e.message:`Unexpected error while accessing the camera.`}}function r(r={}){let[i,a]=(0,e.useState)(`loading`),[o,s]=(0,e.useState)(null),[c,l]=(0,e.useState)(0),u=(0,e.useRef)(null),d=(0,e.useRef)(r.constraints??t);return(0,e.useEffect)(()=>{d.current=r.constraints??t},[r.constraints]),(0,e.useEffect)(()=>{let e=!1,t=null,r=null;async function i(){if(a(`loading`),s(null),typeof navigator>`u`||!navigator.mediaDevices||typeof navigator.mediaDevices.getUserMedia!=`function`){e||(s(typeof window<`u`&&!window.isSecureContext?n(null):{kind:`unsupported`,message:`Camera capture is not supported in this browser.`}),a(`error`));return}try{if(t=await navigator.mediaDevices.getUserMedia(d.current),e){t.getTracks().forEach(e=>e.stop());return}let n=u.current;if(!n){t.getTracks().forEach(e=>e.stop());return}r=n,n.srcObject=t,await n.play().catch(()=>void 0),e||a(`ready`)}catch(t){e||(s(n(t)),a(`error`))}}return i(),()=>{e=!0,t&&t.getTracks().forEach(e=>e.stop()),r&&(r.srcObject=null)}},[c]),{status:i,error:o,videoRef:u,retry:()=>l(e=>e+1)}}exports.useCameraStream=r;
+const e=require("../audio/media-access.cjs");let t=require("react");var n={video:{facingMode:{ideal:`environment`},width:{ideal:1920},height:{ideal:1080}},audio:!1};function r({kind:e,message:t}){return{kind:e===`not-found`?`no-camera`:e,message:t}}function i(t){return r(e.classifyMediaError(t,`camera`))}function a(a={}){let[o,s]=(0,t.useState)(`loading`),[c,l]=(0,t.useState)(null),[u,d]=(0,t.useState)(null),[f,p]=(0,t.useState)(0),m=(0,t.useRef)(null),h=(0,t.useRef)(a.constraints??n);(0,t.useEffect)(()=>{h.current=a.constraints??n},[a.constraints]);let g=a.enabled??!0;return(0,t.useEffect)(()=>{let t=!1,n=null,a=null;async function o(){if(!g){s(`idle`),l(null);return}if(s(`loading`),l(null),typeof navigator>`u`||!navigator.mediaDevices||typeof navigator.mediaDevices.getUserMedia!=`function`){t||(l(r(e.missingCaptureApiError(`camera`))),s(`error`));return}try{if(n=await navigator.mediaDevices.getUserMedia(h.current),t){n.getTracks().forEach(e=>e.stop());return}let e=m.current;if(!e){n.getTracks().forEach(e=>e.stop());return}a=e,e.srcObject=n,d(n),await e.play().catch(()=>void 0),t||s(`ready`)}catch(e){t||(l(i(e)),s(`error`))}}return o(),()=>{t=!0,n&&n.getTracks().forEach(e=>e.stop()),a&&(a.srcObject=null),d(null)}},[f,g]),{status:o,error:c,videoRef:m,stream:u,retry:()=>p(e=>e+1)}}exports.useCameraStream=a;
 //# sourceMappingURL=use-camera-stream.cjs.map

package/dist/vision/use-camera-stream.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"use-camera-stream.cjs","names":[],"sources":["../../src/vision/use-camera-stream.ts"],"sourcesContent":["import { useEffect, useRef, useState, type RefObject } from \"react\";\n\n/** Lifecycle status of the camera stream. */\nexport type CameraStreamStatus = \"idle\" | \"loading\" | \"ready\" | \"error\";\n\n/** Classified reason a camera stream could not be acquired. */\nexport type CameraStreamErrorKind =\n    \"unsupported\" | \"permission-denied\" | \"no-camera\" | \"in-use\" | \"insecure\" | \"unknown\";\n\n/** A classified camera error with a human-readable, English message. */\nexport interface CameraStreamError {\n    kind: CameraStreamErrorKind;\n    message: string;\n}\n\n/** Options for {@link useCameraStream}. */\nexport interface UseCameraStreamOptions {\n    /**\n     * Constraints passed to `getUserMedia`. Defaults to the rear\n     * (\"environment\") camera at Full-HD ideal resolution with audio off.\n     * Read when the stream (re)starts — change it and call `retry()` to apply.\n     */\n    constraints?: MediaStreamConstraints;\n}\n\n/** Value returned by {@link useCameraStream}. */\nexport interface UseCameraStreamApi {\n    /** Current lifecycle status. */\n    status: CameraStreamStatus;\n    /** The classified error, or `null` while not in the `error` status. */\n    error: CameraStreamError | null;\n    /** Attach to a `<video ref={…} />`. The stream is wired to it once ready. */\n    videoRef: RefObject<HTMLVideoElement | null>;\n    /** Manually re-attempt after an error (e.g. the user changed permissions). */\n    retry: () => void;\n}\n\n/** Rear-camera Full-HD defaults used when no `constraints` are supplied. */\nconst DEFAULT_CONSTRAINTS: MediaStreamConstraints = {\n    video: {\n        facingMode: { ideal: \"environment\" },\n        width: { ideal: 1920 },\n        height: { ideal: 1080 },\n    },\n    audio: false,\n};\n\n/**\n * Map an unknown failure into a {@link CameraStreamError}. Secure-context and\n * environment checks run first (they are the reason `getUserMedia` is missing\n * or rejects), then the `DOMException.name` is mapped to a stable `kind`.\n */\nfunction classifyError(err: unknown): CameraStreamError {\n    if (typeof window === \"undefined\") {\n        return { kind: \"unsupported\", message: \"Camera is unavailable in this environment.\" };\n    }\n    if (!window.isSecureContext) {\n        return {\n            kind: \"insecure\",\n            message: \"Camera access requires a secure (HTTPS) connection.\",\n        };\n    }\n    if (err instanceof DOMException) {\n        switch (err.name) {\n            case \"NotAllowedError\":\n            case \"SecurityError\":\n                return {\n                    kind: \"permission-denied\",\n                    message: \"Camera permission denied. Enable access in your browser settings.\",\n                };\n            case \"NotFoundError\":\n            case \"OverconstrainedError\":\n                return {\n                    kind: \"no-camera\",\n                    message: \"No camera available on this device.\",\n                };\n            case \"NotReadableError\":\n            case \"AbortError\":\n                return {\n                    kind: \"in-use\",\n                    message: \"The camera is in use by another app. Close it and try again.\",\n                };\n        }\n    }\n    return {\n        kind: \"unknown\",\n        message:\n            err instanceof Error ? err.message : \"Unexpected error while accessing the camera.\",\n    };\n}\n\n/**\n * Acquire a `MediaStream` via `getUserMedia`, attach it to a `<video>` element,\n * and expose status/error so the page can render permission and error states.\n * The stream is automatically released on unmount or retry.\n *\n * Defaults to the rear (\"environment\") camera; desktops fall back to whatever\n * single camera they expose. Pass `options.constraints` to override.\n *\n * Implementation notes:\n * - Cleanup detaches the stream from a *snapshotted* video node, so it releases\n *   the same element it attached to even if the page remounts the `<video>`.\n * - When `getUserMedia` is missing, an insecure context is the usual cause, so\n *   the hook prefers that (actionable) error; otherwise it reports `unsupported`.\n * - `video.play()` rejections are swallowed: autoplay may be blocked, but the\n *   user gesture that opened the camera usually counts and playback resumes on\n *   the next interaction.\n *\n * @param options - optional configuration (see {@link UseCameraStreamOptions}).\n * @returns The stream status, classified error, a `videoRef` to attach, and a\n *   `retry()` to re-attempt acquisition.\n */\nexport function useCameraStream(options: UseCameraStreamOptions = {}): UseCameraStreamApi {\n    const [status, setStatus] = useState<CameraStreamStatus>(\"loading\");\n    const [error, setError] = useState<CameraStreamError | null>(null);\n    const [retryToken, setRetryToken] = useState(0);\n    const videoRef = useRef<HTMLVideoElement | null>(null);\n    const constraintsRef = useRef<MediaStreamConstraints>(\n        options.constraints ?? DEFAULT_CONSTRAINTS,\n    );\n    useEffect(() => {\n        constraintsRef.current = options.constraints ?? DEFAULT_CONSTRAINTS;\n    }, [options.constraints]);\n\n    useEffect(() => {\n        let cancelled = false;\n        let stream: MediaStream | null = null;\n        let attachedVideo: HTMLVideoElement | null = null;\n\n        async function start(): Promise<void> {\n            setStatus(\"loading\");\n            setError(null);\n\n            if (\n                typeof navigator === \"undefined\" ||\n                !navigator.mediaDevices ||\n                typeof navigator.mediaDevices.getUserMedia !== \"function\"\n            ) {\n                if (!cancelled) {\n                    setError(\n                        typeof window !== \"undefined\" && !window.isSecureContext\n                            ? classifyError(null)\n                            : {\n                                  kind: \"unsupported\",\n                                  message: \"Camera capture is not supported in this browser.\",\n                              },\n                    );\n                    setStatus(\"error\");\n                }\n                return;\n            }\n\n            try {\n                stream = await navigator.mediaDevices.getUserMedia(constraintsRef.current);\n                if (cancelled) {\n                    stream.getTracks().forEach((track) => track.stop());\n                    return;\n                }\n                const video = videoRef.current;\n                if (!video) {\n                    stream.getTracks().forEach((track) => track.stop());\n                    return;\n                }\n                attachedVideo = video;\n                video.srcObject = stream;\n                await video.play().catch(() => undefined);\n                if (!cancelled) setStatus(\"ready\");\n            } catch (err) {\n                if (!cancelled) {\n                    setError(classifyError(err));\n                    setStatus(\"error\");\n                }\n            }\n        }\n\n        void start();\n\n        return () => {\n            cancelled = true;\n            if (stream) {\n                stream.getTracks().forEach((track) => track.stop());\n            }\n            if (attachedVideo) {\n                attachedVideo.srcObject = null;\n            }\n        };\n    }, [retryToken]);\n\n    return {\n        status,\n        error,\n        videoRef,\n        retry: () => setRetryToken((n) => n + 1),\n    };\n}\n"],"mappings":"uBAsCA,IAAM,EAA8C,CAChD,MAAO,CACH,WAAY,CAAE,MAAO,aAAc,EACnC,MAAO,CAAE,MAAO,IAAK,EACrB,OAAQ,CAAE,MAAO,IAAK,CAC1B,EACA,MAAO,EACX,EAOA,SAAS,EAAc,EAAiC,CACpD,GAAI,OAAO,OAAW,IAClB,MAAO,CAAE,KAAM,cAAe,QAAS,4CAA6C,EAExF,GAAI,CAAC,OAAO,gBACR,MAAO,CACH,KAAM,WACN,QAAS,qDACb,EAEJ,GAAI,aAAe,aACf,OAAQ,EAAI,KAAZ,CACI,IAAK,kBACL,IAAK,gBACD,MAAO,CACH,KAAM,oBACN,QAAS,mEACb,EACJ,IAAK,gBACL,IAAK,uBACD,MAAO,CACH,KAAM,YACN,QAAS,qCACb,EACJ,IAAK,mBACL,IAAK,aACD,MAAO,CACH,KAAM,SACN,QAAS,8DACb,CACR,CAEJ,MAAO,CACH,KAAM,UACN,QACI,aAAe,MAAQ,EAAI,QAAU,8CAC7C,CACJ,CAuBA,SAAgB,EAAgB,EAAkC,CAAC,EAAuB,CACtF,GAAM,CAAC,EAAQ,IAAA,EAAA,EAAA,SAAA,CAA0C,SAAS,EAC5D,CAAC,EAAO,IAAA,EAAA,EAAA,SAAA,CAA+C,IAAI,EAC3D,CAAC,EAAY,IAAA,EAAA,EAAA,SAAA,CAA0B,CAAC,EACxC,GAAA,EAAA,EAAA,OAAA,CAA2C,IAAI,EAC/C,GAAA,EAAA,EAAA,OAAA,CACF,EAAQ,aAAe,CAC3B,EAqEA,OApEA,EAAA,EAAA,UAAA,KAAgB,CACZ,EAAe,QAAU,EAAQ,aAAe,CACpD,EAAG,CAAC,EAAQ,WAAW,CAAC,GAExB,EAAA,EAAA,UAAA,KAAgB,CACZ,IAAI,EAAY,GACZ,EAA6B,KAC7B,EAAyC,KAE7C,eAAe,GAAuB,CAIlC,GAHA,EAAU,SAAS,EACnB,EAAS,IAAI,EAGT,OAAO,UAAc,KACrB,CAAC,UAAU,cACX,OAAO,UAAU,aAAa,cAAiB,WACjD,CACO,IACD,EACI,OAAO,OAAW,KAAe,CAAC,OAAO,gBACnC,EAAc,IAAI,EAClB,CACI,KAAM,cACN,QAAS,kDACb,CACV,EACA,EAAU,OAAO,GAErB,MACJ,CAEA,GAAI,CAEA,GADA,EAAS,MAAM,UAAU,aAAa,aAAa,EAAe,OAAO,EACrE,EAAW,CACX,EAAO,UAAU,CAAC,CAAC,QAAS,GAAU,EAAM,KAAK,CAAC,EAClD,MACJ,CACA,IAAM,EAAQ,EAAS,QACvB,GAAI,CAAC,EAAO,CACR,EAAO,UAAU,CAAC,CAAC,QAAS,GAAU,EAAM,KAAK,CAAC,EAClD,MACJ,CACA,EAAgB,EAChB,EAAM,UAAY,EAClB,MAAM,EAAM,KAAK,CAAC,CAAC,UAAY,IAAA,EAAS,EACnC,GAAW,EAAU,OAAO,CACrC,OAAS,EAAK,CACL,IACD,EAAS,EAAc,CAAG,CAAC,EAC3B,EAAU,OAAO,EAEzB,CACJ,CAIA,OAFA,EAAW,MAEE,CACT,EAAY,GACR,GACA,EAAO,UAAU,CAAC,CAAC,QAAS,GAAU,EAAM,KAAK,CAAC,EAElD,IACA,EAAc,UAAY,KAElC,CACJ,EAAG,CAAC,CAAU,CAAC,EAER,CACH,SACA,QACA,WACA,UAAa,EAAe,GAAM,EAAI,CAAC,CAC3C,CACJ"}
+{"version":3,"file":"use-camera-stream.cjs","names":[],"sources":["../../src/vision/use-camera-stream.ts"],"sourcesContent":["import { useEffect, useRef, useState, type RefObject } from \"react\";\n\nimport {\n    classifyMediaError,\n    missingCaptureApiError,\n    type MediaAccessError,\n} from \"@/audio/media-access\";\n\n/** Lifecycle status of the camera stream. */\nexport type CameraStreamStatus = \"idle\" | \"loading\" | \"ready\" | \"error\";\n\n/** Classified reason a camera stream could not be acquired. */\nexport type CameraStreamErrorKind =\n    \"unsupported\" | \"permission-denied\" | \"no-camera\" | \"in-use\" | \"insecure\" | \"unknown\";\n\n/** A classified camera error with a human-readable, English message. */\nexport interface CameraStreamError {\n    kind: CameraStreamErrorKind;\n    message: string;\n}\n\n/** Options for {@link useCameraStream}. */\nexport interface UseCameraStreamOptions {\n    /**\n     * Constraints passed to `getUserMedia`. Defaults to the rear\n     * (\"environment\") camera at Full-HD ideal resolution with audio off.\n     * Read when the stream (re)starts — change it and call `retry()` to apply.\n     */\n    constraints?: MediaStreamConstraints;\n    /**\n     * Hold off acquiring the camera until this is `true`. Default `true`.\n     *\n     * The point is to be able to *not* prompt. A permission prompt costs the user a\n     * decision and, if they refuse, costs the app the feature permanently — so a\n     * surface that already knows it cannot do its job (a barcode scanner in a browser\n     * with no decoder) must not open the camera to then say so. Flipping this to `false`\n     * also releases a stream that is already live.\n     */\n    enabled?: boolean;\n}\n\n/** Value returned by {@link useCameraStream}. */\nexport interface UseCameraStreamApi {\n    /** Current lifecycle status. */\n    status: CameraStreamStatus;\n    /** The classified error, or `null` while not in the `error` status. */\n    error: CameraStreamError | null;\n    /** Attach to a `<video ref={…} />`. The stream is wired to it once ready. */\n    videoRef: RefObject<HTMLVideoElement | null>;\n    /**\n     * The live stream, or `null`.\n     *\n     * Exposed for the things that need the **track** rather than the picture — the LED\n     * torch (`useTorch`), the real frame size from `getSettings()`, recording it with\n     * `useVideoRecorder`. Do not stop it yourself: the hook owns its lifetime and\n     * releases it on unmount and on `retry()`.\n     */\n    stream: MediaStream | null;\n    /** Manually re-attempt after an error (e.g. the user changed permissions). */\n    retry: () => void;\n}\n\n/** Rear-camera Full-HD defaults used when no `constraints` are supplied. */\nconst DEFAULT_CONSTRAINTS: MediaStreamConstraints = {\n    video: {\n        facingMode: { ideal: \"environment\" },\n        width: { ideal: 1920 },\n        height: { ideal: 1080 },\n    },\n    audio: false,\n};\n\n/**\n * Re-label a {@link MediaAccessError} as a {@link CameraStreamError}.\n *\n * The classification itself lives in one place for the whole SDK\n * (`classifyMediaError`), so a microphone and a camera failure are never explained\n * two different ways. Only the name of one kind differs: this surface shipped\n * `\"no-camera\"` where the shared taxonomy says `\"not-found\"`, and renaming a\n * published union member would break every consumer switching on it.\n *\n * @param error - The shared classification.\n * @returns The same error under this module's kind names.\n */\nfunction toCameraError({ kind, message }: MediaAccessError): CameraStreamError {\n    return { kind: kind === \"not-found\" ? \"no-camera\" : kind, message };\n}\n\n/**\n * Map an unknown `getUserMedia` failure into a {@link CameraStreamError}. Secure-context\n * and environment checks run first (they are the reason `getUserMedia` is missing or\n * rejects), then the `DOMException.name` is mapped to a stable `kind`.\n */\nfunction classifyError(err: unknown): CameraStreamError {\n    return toCameraError(classifyMediaError(err, \"camera\"));\n}\n\n/**\n * Acquire a `MediaStream` via `getUserMedia`, attach it to a `<video>` element,\n * and expose status/error so the page can render permission and error states.\n * The stream is automatically released on unmount or retry.\n *\n * Defaults to the rear (\"environment\") camera; desktops fall back to whatever\n * single camera they expose. Pass `options.constraints` to override, or\n * `options.enabled: false` to render the surface without prompting for the camera\n * at all.\n *\n * Implementation notes:\n * - Cleanup detaches the stream from a *snapshotted* video node, so it releases\n *   the same element it attached to even if the page remounts the `<video>`.\n * - When `getUserMedia` is missing, an insecure context is the usual cause, so\n *   the hook prefers that (actionable) error; otherwise it reports `unsupported`.\n * - `video.play()` rejections are swallowed: autoplay may be blocked, but the\n *   user gesture that opened the camera usually counts and playback resumes on\n *   the next interaction.\n *\n * @param options - optional configuration (see {@link UseCameraStreamOptions}).\n * @returns The stream status, classified error, a `videoRef` to attach, the live\n *   `stream` for whatever needs the track itself, and a `retry()` to re-attempt\n *   acquisition.\n */\nexport function useCameraStream(options: UseCameraStreamOptions = {}): UseCameraStreamApi {\n    const [status, setStatus] = useState<CameraStreamStatus>(\"loading\");\n    const [error, setError] = useState<CameraStreamError | null>(null);\n    const [live, setLive] = useState<MediaStream | null>(null);\n    const [retryToken, setRetryToken] = useState(0);\n    const videoRef = useRef<HTMLVideoElement | null>(null);\n    const constraintsRef = useRef<MediaStreamConstraints>(\n        options.constraints ?? DEFAULT_CONSTRAINTS,\n    );\n    useEffect(() => {\n        constraintsRef.current = options.constraints ?? DEFAULT_CONSTRAINTS;\n    }, [options.constraints]);\n\n    const enabled = options.enabled ?? true;\n\n    useEffect(() => {\n        let cancelled = false;\n        let stream: MediaStream | null = null;\n        let attachedVideo: HTMLVideoElement | null = null;\n\n        async function start(): Promise<void> {\n            if (!enabled) {\n                setStatus(\"idle\");\n                setError(null);\n                return;\n            }\n            setStatus(\"loading\");\n            setError(null);\n\n            if (\n                typeof navigator === \"undefined\" ||\n                !navigator.mediaDevices ||\n                typeof navigator.mediaDevices.getUserMedia !== \"function\"\n            ) {\n                if (!cancelled) {\n                    setError(toCameraError(missingCaptureApiError(\"camera\")));\n                    setStatus(\"error\");\n                }\n                return;\n            }\n\n            try {\n                stream = await navigator.mediaDevices.getUserMedia(constraintsRef.current);\n                if (cancelled) {\n                    stream.getTracks().forEach((track) => track.stop());\n                    return;\n                }\n                const video = videoRef.current;\n                if (!video) {\n                    stream.getTracks().forEach((track) => track.stop());\n                    return;\n                }\n                attachedVideo = video;\n                video.srcObject = stream;\n                setLive(stream);\n                await video.play().catch(() => undefined);\n                if (!cancelled) setStatus(\"ready\");\n            } catch (err) {\n                if (!cancelled) {\n                    setError(classifyError(err));\n                    setStatus(\"error\");\n                }\n            }\n        }\n\n        void start();\n\n        return () => {\n            cancelled = true;\n            if (stream) {\n                stream.getTracks().forEach((track) => track.stop());\n            }\n            if (attachedVideo) {\n                attachedVideo.srcObject = null;\n            }\n            setLive(null);\n        };\n    }, [retryToken, enabled]);\n\n    return {\n        status,\n        error,\n        videoRef,\n        stream: live,\n        retry: () => setRetryToken((n) => n + 1),\n    };\n}\n"],"mappings":"oEA+DA,IAAM,EAA8C,CAChD,MAAO,CACH,WAAY,CAAE,MAAO,aAAc,EACnC,MAAO,CAAE,MAAO,IAAK,EACrB,OAAQ,CAAE,MAAO,IAAK,CAC1B,EACA,MAAO,EACX,EAcA,SAAS,EAAc,CAAE,OAAM,WAAgD,CAC3E,MAAO,CAAE,KAAM,IAAS,YAAc,YAAc,EAAM,SAAQ,CACtE,CAOA,SAAS,EAAc,EAAiC,CACpD,OAAO,EAAc,EAAA,mBAAmB,EAAK,QAAQ,CAAC,CAC1D,CA0BA,SAAgB,EAAgB,EAAkC,CAAC,EAAuB,CACtF,GAAM,CAAC,EAAQ,IAAA,EAAA,EAAA,SAAA,CAA0C,SAAS,EAC5D,CAAC,EAAO,IAAA,EAAA,EAAA,SAAA,CAA+C,IAAI,EAC3D,CAAC,EAAM,IAAA,EAAA,EAAA,SAAA,CAAwC,IAAI,EACnD,CAAC,EAAY,IAAA,EAAA,EAAA,SAAA,CAA0B,CAAC,EACxC,GAAA,EAAA,EAAA,OAAA,CAA2C,IAAI,EAC/C,GAAA,EAAA,EAAA,OAAA,CACF,EAAQ,aAAe,CAC3B,GACA,EAAA,EAAA,UAAA,KAAgB,CACZ,EAAe,QAAU,EAAQ,aAAe,CACpD,EAAG,CAAC,EAAQ,WAAW,CAAC,EAExB,IAAM,EAAU,EAAQ,SAAW,GAkEnC,OAhEA,EAAA,EAAA,UAAA,KAAgB,CACZ,IAAI,EAAY,GACZ,EAA6B,KAC7B,EAAyC,KAE7C,eAAe,GAAuB,CAClC,GAAI,CAAC,EAAS,CACV,EAAU,MAAM,EAChB,EAAS,IAAI,EACb,MACJ,CAIA,GAHA,EAAU,SAAS,EACnB,EAAS,IAAI,EAGT,OAAO,UAAc,KACrB,CAAC,UAAU,cACX,OAAO,UAAU,aAAa,cAAiB,WACjD,CACO,IACD,EAAS,EAAc,EAAA,uBAAuB,QAAQ,CAAC,CAAC,EACxD,EAAU,OAAO,GAErB,MACJ,CAEA,GAAI,CAEA,GADA,EAAS,MAAM,UAAU,aAAa,aAAa,EAAe,OAAO,EACrE,EAAW,CACX,EAAO,UAAU,CAAC,CAAC,QAAS,GAAU,EAAM,KAAK,CAAC,EAClD,MACJ,CACA,IAAM,EAAQ,EAAS,QACvB,GAAI,CAAC,EAAO,CACR,EAAO,UAAU,CAAC,CAAC,QAAS,GAAU,EAAM,KAAK,CAAC,EAClD,MACJ,CACA,EAAgB,EAChB,EAAM,UAAY,EAClB,EAAQ,CAAM,EACd,MAAM,EAAM,KAAK,CAAC,CAAC,UAAY,IAAA,EAAS,EACnC,GAAW,EAAU,OAAO,CACrC,OAAS,EAAK,CACL,IACD,EAAS,EAAc,CAAG,CAAC,EAC3B,EAAU,OAAO,EAEzB,CACJ,CAIA,OAFA,EAAW,MAEE,CACT,EAAY,GACR,GACA,EAAO,UAAU,CAAC,CAAC,QAAS,GAAU,EAAM,KAAK,CAAC,EAElD,IACA,EAAc,UAAY,MAE9B,EAAQ,IAAI,CAChB,CACJ,EAAG,CAAC,EAAY,CAAO,CAAC,EAEjB,CACH,SACA,QACA,WACA,OAAQ,EACR,UAAa,EAAe,GAAM,EAAI,CAAC,CAC3C,CACJ"}

package/dist/vision/use-camera-stream.js

@@ -1,6 +1,7 @@
-import { useEffect as e, useRef as t, useState as n } from "react";
+import { classifyMediaError as e, missingCaptureApiError as t } from "../audio/media-access.js";
+import { useEffect as n, useRef as r, useState as i } from "react";
 //#region src/vision/use-camera-stream.ts
-var r = {
+var a = {
 	video: {
 		facingMode: { ideal: "environment" },
 		width: { ideal: 1920 },
@@ -8,77 +9,59 @@ var r = {
 	},
 	audio: !1
 };
-function i(e) {
-	if (typeof window > "u") return {
-		kind: "unsupported",
-		message: "Camera is unavailable in this environment."
-	};
-	if (!window.isSecureContext) return {
-		kind: "insecure",
-		message: "Camera access requires a secure (HTTPS) connection."
-	};
-	if (e instanceof DOMException) switch (e.name) {
-		case "NotAllowedError":
-		case "SecurityError": return {
-			kind: "permission-denied",
-			message: "Camera permission denied. Enable access in your browser settings."
-		};
-		case "NotFoundError":
-		case "OverconstrainedError": return {
-			kind: "no-camera",
-			message: "No camera available on this device."
-		};
-		case "NotReadableError":
-		case "AbortError": return {
-			kind: "in-use",
-			message: "The camera is in use by another app. Close it and try again."
-		};
-	}
+function o({ kind: e, message: t }) {
 	return {
-		kind: "unknown",
-		message: e instanceof Error ? e.message : "Unexpected error while accessing the camera."
+		kind: e === "not-found" ? "no-camera" : e,
+		message: t
 	};
 }
-function a(a = {}) {
-	let [o, s] = n("loading"), [c, l] = n(null), [u, d] = n(0), f = t(null), p = t(a.constraints ?? r);
-	return e(() => {
-		p.current = a.constraints ?? r;
-	}, [a.constraints]), e(() => {
-		let e = !1, t = null, n = null;
-		async function r() {
-			if (s("loading"), l(null), typeof navigator > "u" || !navigator.mediaDevices || typeof navigator.mediaDevices.getUserMedia != "function") {
-				e || (l(typeof window < "u" && !window.isSecureContext ? i(null) : {
-					kind: "unsupported",
-					message: "Camera capture is not supported in this browser."
-				}), s("error"));
+function s(t) {
+	return o(e(t, "camera"));
+}
+function c(e = {}) {
+	let [c, l] = i("loading"), [u, d] = i(null), [f, p] = i(null), [m, h] = i(0), g = r(null), _ = r(e.constraints ?? a);
+	n(() => {
+		_.current = e.constraints ?? a;
+	}, [e.constraints]);
+	let v = e.enabled ?? !0;
+	return n(() => {
+		let e = !1, n = null, r = null;
+		async function i() {
+			if (!v) {
+				l("idle"), d(null);
+				return;
+			}
+			if (l("loading"), d(null), typeof navigator > "u" || !navigator.mediaDevices || typeof navigator.mediaDevices.getUserMedia != "function") {
+				e || (d(o(t("camera"))), l("error"));
 				return;
 			}
 			try {
-				if (t = await navigator.mediaDevices.getUserMedia(p.current), e) {
-					t.getTracks().forEach((e) => e.stop());
+				if (n = await navigator.mediaDevices.getUserMedia(_.current), e) {
+					n.getTracks().forEach((e) => e.stop());
 					return;
 				}
-				let r = f.current;
-				if (!r) {
-					t.getTracks().forEach((e) => e.stop());
+				let t = g.current;
+				if (!t) {
+					n.getTracks().forEach((e) => e.stop());
 					return;
 				}
-				n = r, r.srcObject = t, await r.play().catch(() => void 0), e || s("ready");
+				r = t, t.srcObject = n, p(n), await t.play().catch(() => void 0), e || l("ready");
 			} catch (t) {
-				e || (l(i(t)), s("error"));
+				e || (d(s(t)), l("error"));
 			}
 		}
-		return r(), () => {
-			e = !0, t && t.getTracks().forEach((e) => e.stop()), n && (n.srcObject = null);
+		return i(), () => {
+			e = !0, n && n.getTracks().forEach((e) => e.stop()), r && (r.srcObject = null), p(null);
 		};
-	}, [u]), {
-		status: o,
-		error: c,
-		videoRef: f,
-		retry: () => d((e) => e + 1)
+	}, [m, v]), {
+		status: c,
+		error: u,
+		videoRef: g,
+		stream: f,
+		retry: () => h((e) => e + 1)
 	};
 }
 //#endregion
-export { a as useCameraStream };
+export { c as useCameraStream };
 
 //# sourceMappingURL=use-camera-stream.js.map

package/dist/vision/use-camera-stream.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-camera-stream.js","names":[],"sources":["../../src/vision/use-camera-stream.ts"],"sourcesContent":["import { useEffect, useRef, useState, type RefObject } from \"react\";\n\n/** Lifecycle status of the camera stream. */\nexport type CameraStreamStatus = \"idle\" | \"loading\" | \"ready\" | \"error\";\n\n/** Classified reason a camera stream could not be acquired. */\nexport type CameraStreamErrorKind =\n    \"unsupported\" | \"permission-denied\" | \"no-camera\" | \"in-use\" | \"insecure\" | \"unknown\";\n\n/** A classified camera error with a human-readable, English message. */\nexport interface CameraStreamError {\n    kind: CameraStreamErrorKind;\n    message: string;\n}\n\n/** Options for {@link useCameraStream}. */\nexport interface UseCameraStreamOptions {\n    /**\n     * Constraints passed to `getUserMedia`. Defaults to the rear\n     * (\"environment\") camera at Full-HD ideal resolution with audio off.\n     * Read when the stream (re)starts — change it and call `retry()` to apply.\n     */\n    constraints?: MediaStreamConstraints;\n}\n\n/** Value returned by {@link useCameraStream}. */\nexport interface UseCameraStreamApi {\n    /** Current lifecycle status. */\n    status: CameraStreamStatus;\n    /** The classified error, or `null` while not in the `error` status. */\n    error: CameraStreamError | null;\n    /** Attach to a `<video ref={…} />`. The stream is wired to it once ready. */\n    videoRef: RefObject<HTMLVideoElement | null>;\n    /** Manually re-attempt after an error (e.g. the user changed permissions). */\n    retry: () => void;\n}\n\n/** Rear-camera Full-HD defaults used when no `constraints` are supplied. */\nconst DEFAULT_CONSTRAINTS: MediaStreamConstraints = {\n    video: {\n        facingMode: { ideal: \"environment\" },\n        width: { ideal: 1920 },\n        height: { ideal: 1080 },\n    },\n    audio: false,\n};\n\n/**\n * Map an unknown failure into a {@link CameraStreamError}. Secure-context and\n * environment checks run first (they are the reason `getUserMedia` is missing\n * or rejects), then the `DOMException.name` is mapped to a stable `kind`.\n */\nfunction classifyError(err: unknown): CameraStreamError {\n    if (typeof window === \"undefined\") {\n        return { kind: \"unsupported\", message: \"Camera is unavailable in this environment.\" };\n    }\n    if (!window.isSecureContext) {\n        return {\n            kind: \"insecure\",\n            message: \"Camera access requires a secure (HTTPS) connection.\",\n        };\n    }\n    if (err instanceof DOMException) {\n        switch (err.name) {\n            case \"NotAllowedError\":\n            case \"SecurityError\":\n                return {\n                    kind: \"permission-denied\",\n                    message: \"Camera permission denied. Enable access in your browser settings.\",\n                };\n            case \"NotFoundError\":\n            case \"OverconstrainedError\":\n                return {\n                    kind: \"no-camera\",\n                    message: \"No camera available on this device.\",\n                };\n            case \"NotReadableError\":\n            case \"AbortError\":\n                return {\n                    kind: \"in-use\",\n                    message: \"The camera is in use by another app. Close it and try again.\",\n                };\n        }\n    }\n    return {\n        kind: \"unknown\",\n        message:\n            err instanceof Error ? err.message : \"Unexpected error while accessing the camera.\",\n    };\n}\n\n/**\n * Acquire a `MediaStream` via `getUserMedia`, attach it to a `<video>` element,\n * and expose status/error so the page can render permission and error states.\n * The stream is automatically released on unmount or retry.\n *\n * Defaults to the rear (\"environment\") camera; desktops fall back to whatever\n * single camera they expose. Pass `options.constraints` to override.\n *\n * Implementation notes:\n * - Cleanup detaches the stream from a *snapshotted* video node, so it releases\n *   the same element it attached to even if the page remounts the `<video>`.\n * - When `getUserMedia` is missing, an insecure context is the usual cause, so\n *   the hook prefers that (actionable) error; otherwise it reports `unsupported`.\n * - `video.play()` rejections are swallowed: autoplay may be blocked, but the\n *   user gesture that opened the camera usually counts and playback resumes on\n *   the next interaction.\n *\n * @param options - optional configuration (see {@link UseCameraStreamOptions}).\n * @returns The stream status, classified error, a `videoRef` to attach, and a\n *   `retry()` to re-attempt acquisition.\n */\nexport function useCameraStream(options: UseCameraStreamOptions = {}): UseCameraStreamApi {\n    const [status, setStatus] = useState<CameraStreamStatus>(\"loading\");\n    const [error, setError] = useState<CameraStreamError | null>(null);\n    const [retryToken, setRetryToken] = useState(0);\n    const videoRef = useRef<HTMLVideoElement | null>(null);\n    const constraintsRef = useRef<MediaStreamConstraints>(\n        options.constraints ?? DEFAULT_CONSTRAINTS,\n    );\n    useEffect(() => {\n        constraintsRef.current = options.constraints ?? DEFAULT_CONSTRAINTS;\n    }, [options.constraints]);\n\n    useEffect(() => {\n        let cancelled = false;\n        let stream: MediaStream | null = null;\n        let attachedVideo: HTMLVideoElement | null = null;\n\n        async function start(): Promise<void> {\n            setStatus(\"loading\");\n            setError(null);\n\n            if (\n                typeof navigator === \"undefined\" ||\n                !navigator.mediaDevices ||\n                typeof navigator.mediaDevices.getUserMedia !== \"function\"\n            ) {\n                if (!cancelled) {\n                    setError(\n                        typeof window !== \"undefined\" && !window.isSecureContext\n                            ? classifyError(null)\n                            : {\n                                  kind: \"unsupported\",\n                                  message: \"Camera capture is not supported in this browser.\",\n                              },\n                    );\n                    setStatus(\"error\");\n                }\n                return;\n            }\n\n            try {\n                stream = await navigator.mediaDevices.getUserMedia(constraintsRef.current);\n                if (cancelled) {\n                    stream.getTracks().forEach((track) => track.stop());\n                    return;\n                }\n                const video = videoRef.current;\n                if (!video) {\n                    stream.getTracks().forEach((track) => track.stop());\n                    return;\n                }\n                attachedVideo = video;\n                video.srcObject = stream;\n                await video.play().catch(() => undefined);\n                if (!cancelled) setStatus(\"ready\");\n            } catch (err) {\n                if (!cancelled) {\n                    setError(classifyError(err));\n                    setStatus(\"error\");\n                }\n            }\n        }\n\n        void start();\n\n        return () => {\n            cancelled = true;\n            if (stream) {\n                stream.getTracks().forEach((track) => track.stop());\n            }\n            if (attachedVideo) {\n                attachedVideo.srcObject = null;\n            }\n        };\n    }, [retryToken]);\n\n    return {\n        status,\n        error,\n        videoRef,\n        retry: () => setRetryToken((n) => n + 1),\n    };\n}\n"],"mappings":";;AAsCA,IAAM,IAA8C;CAChD,OAAO;EACH,YAAY,EAAE,OAAO,cAAc;EACnC,OAAO,EAAE,OAAO,KAAK;EACrB,QAAQ,EAAE,OAAO,KAAK;CAC1B;CACA,OAAO;AACX;AAOA,SAAS,EAAc,GAAiC;CACpD,IAAI,OAAO,SAAW,KAClB,OAAO;EAAE,MAAM;EAAe,SAAS;CAA6C;CAExF,IAAI,CAAC,OAAO,iBACR,OAAO;EACH,MAAM;EACN,SAAS;CACb;CAEJ,IAAI,aAAe,cACf,QAAQ,EAAI,MAAZ;EACI,KAAK;EACL,KAAK,iBACD,OAAO;GACH,MAAM;GACN,SAAS;EACb;EACJ,KAAK;EACL,KAAK,wBACD,OAAO;GACH,MAAM;GACN,SAAS;EACb;EACJ,KAAK;EACL,KAAK,cACD,OAAO;GACH,MAAM;GACN,SAAS;EACb;CACR;CAEJ,OAAO;EACH,MAAM;EACN,SACI,aAAe,QAAQ,EAAI,UAAU;CAC7C;AACJ;AAuBA,SAAgB,EAAgB,IAAkC,CAAC,GAAuB;CACtF,IAAM,CAAC,GAAQ,KAAa,EAA6B,SAAS,GAC5D,CAAC,GAAO,KAAY,EAAmC,IAAI,GAC3D,CAAC,GAAY,KAAiB,EAAS,CAAC,GACxC,IAAW,EAAgC,IAAI,GAC/C,IAAiB,EACnB,EAAQ,eAAe,CAC3B;CAqEA,OApEA,QAAgB;EACZ,EAAe,UAAU,EAAQ,eAAe;CACpD,GAAG,CAAC,EAAQ,WAAW,CAAC,GAExB,QAAgB;EACZ,IAAI,IAAY,IACZ,IAA6B,MAC7B,IAAyC;EAE7C,eAAe,IAAuB;GAIlC,IAHA,EAAU,SAAS,GACnB,EAAS,IAAI,GAGT,OAAO,YAAc,OACrB,CAAC,UAAU,gBACX,OAAO,UAAU,aAAa,gBAAiB,YACjD;IACE,AAAK,MACD,EACI,OAAO,SAAW,OAAe,CAAC,OAAO,kBACnC,EAAc,IAAI,IAClB;KACI,MAAM;KACN,SAAS;IACb,CACV,GACA,EAAU,OAAO;IAErB;GACJ;GAEA,IAAI;IAEA,IADA,IAAS,MAAM,UAAU,aAAa,aAAa,EAAe,OAAO,GACrE,GAAW;KACX,EAAO,UAAU,CAAC,CAAC,SAAS,MAAU,EAAM,KAAK,CAAC;KAClD;IACJ;IACA,IAAM,IAAQ,EAAS;IACvB,IAAI,CAAC,GAAO;KACR,EAAO,UAAU,CAAC,CAAC,SAAS,MAAU,EAAM,KAAK,CAAC;KAClD;IACJ;IAIA,AAHA,IAAgB,GAChB,EAAM,YAAY,GAClB,MAAM,EAAM,KAAK,CAAC,CAAC,YAAY,KAAA,CAAS,GACnC,KAAW,EAAU,OAAO;GACrC,SAAS,GAAK;IACV,AAAK,MACD,EAAS,EAAc,CAAG,CAAC,GAC3B,EAAU,OAAO;GAEzB;EACJ;EAIA,OAFA,EAAW,SAEE;GAKT,AAJA,IAAY,IACR,KACA,EAAO,UAAU,CAAC,CAAC,SAAS,MAAU,EAAM,KAAK,CAAC,GAElD,MACA,EAAc,YAAY;EAElC;CACJ,GAAG,CAAC,CAAU,CAAC,GAER;EACH;EACA;EACA;EACA,aAAa,GAAe,MAAM,IAAI,CAAC;CAC3C;AACJ"}
+{"version":3,"file":"use-camera-stream.js","names":[],"sources":["../../src/vision/use-camera-stream.ts"],"sourcesContent":["import { useEffect, useRef, useState, type RefObject } from \"react\";\n\nimport {\n    classifyMediaError,\n    missingCaptureApiError,\n    type MediaAccessError,\n} from \"@/audio/media-access\";\n\n/** Lifecycle status of the camera stream. */\nexport type CameraStreamStatus = \"idle\" | \"loading\" | \"ready\" | \"error\";\n\n/** Classified reason a camera stream could not be acquired. */\nexport type CameraStreamErrorKind =\n    \"unsupported\" | \"permission-denied\" | \"no-camera\" | \"in-use\" | \"insecure\" | \"unknown\";\n\n/** A classified camera error with a human-readable, English message. */\nexport interface CameraStreamError {\n    kind: CameraStreamErrorKind;\n    message: string;\n}\n\n/** Options for {@link useCameraStream}. */\nexport interface UseCameraStreamOptions {\n    /**\n     * Constraints passed to `getUserMedia`. Defaults to the rear\n     * (\"environment\") camera at Full-HD ideal resolution with audio off.\n     * Read when the stream (re)starts — change it and call `retry()` to apply.\n     */\n    constraints?: MediaStreamConstraints;\n    /**\n     * Hold off acquiring the camera until this is `true`. Default `true`.\n     *\n     * The point is to be able to *not* prompt. A permission prompt costs the user a\n     * decision and, if they refuse, costs the app the feature permanently — so a\n     * surface that already knows it cannot do its job (a barcode scanner in a browser\n     * with no decoder) must not open the camera to then say so. Flipping this to `false`\n     * also releases a stream that is already live.\n     */\n    enabled?: boolean;\n}\n\n/** Value returned by {@link useCameraStream}. */\nexport interface UseCameraStreamApi {\n    /** Current lifecycle status. */\n    status: CameraStreamStatus;\n    /** The classified error, or `null` while not in the `error` status. */\n    error: CameraStreamError | null;\n    /** Attach to a `<video ref={…} />`. The stream is wired to it once ready. */\n    videoRef: RefObject<HTMLVideoElement | null>;\n    /**\n     * The live stream, or `null`.\n     *\n     * Exposed for the things that need the **track** rather than the picture — the LED\n     * torch (`useTorch`), the real frame size from `getSettings()`, recording it with\n     * `useVideoRecorder`. Do not stop it yourself: the hook owns its lifetime and\n     * releases it on unmount and on `retry()`.\n     */\n    stream: MediaStream | null;\n    /** Manually re-attempt after an error (e.g. the user changed permissions). */\n    retry: () => void;\n}\n\n/** Rear-camera Full-HD defaults used when no `constraints` are supplied. */\nconst DEFAULT_CONSTRAINTS: MediaStreamConstraints = {\n    video: {\n        facingMode: { ideal: \"environment\" },\n        width: { ideal: 1920 },\n        height: { ideal: 1080 },\n    },\n    audio: false,\n};\n\n/**\n * Re-label a {@link MediaAccessError} as a {@link CameraStreamError}.\n *\n * The classification itself lives in one place for the whole SDK\n * (`classifyMediaError`), so a microphone and a camera failure are never explained\n * two different ways. Only the name of one kind differs: this surface shipped\n * `\"no-camera\"` where the shared taxonomy says `\"not-found\"`, and renaming a\n * published union member would break every consumer switching on it.\n *\n * @param error - The shared classification.\n * @returns The same error under this module's kind names.\n */\nfunction toCameraError({ kind, message }: MediaAccessError): CameraStreamError {\n    return { kind: kind === \"not-found\" ? \"no-camera\" : kind, message };\n}\n\n/**\n * Map an unknown `getUserMedia` failure into a {@link CameraStreamError}. Secure-context\n * and environment checks run first (they are the reason `getUserMedia` is missing or\n * rejects), then the `DOMException.name` is mapped to a stable `kind`.\n */\nfunction classifyError(err: unknown): CameraStreamError {\n    return toCameraError(classifyMediaError(err, \"camera\"));\n}\n\n/**\n * Acquire a `MediaStream` via `getUserMedia`, attach it to a `<video>` element,\n * and expose status/error so the page can render permission and error states.\n * The stream is automatically released on unmount or retry.\n *\n * Defaults to the rear (\"environment\") camera; desktops fall back to whatever\n * single camera they expose. Pass `options.constraints` to override, or\n * `options.enabled: false` to render the surface without prompting for the camera\n * at all.\n *\n * Implementation notes:\n * - Cleanup detaches the stream from a *snapshotted* video node, so it releases\n *   the same element it attached to even if the page remounts the `<video>`.\n * - When `getUserMedia` is missing, an insecure context is the usual cause, so\n *   the hook prefers that (actionable) error; otherwise it reports `unsupported`.\n * - `video.play()` rejections are swallowed: autoplay may be blocked, but the\n *   user gesture that opened the camera usually counts and playback resumes on\n *   the next interaction.\n *\n * @param options - optional configuration (see {@link UseCameraStreamOptions}).\n * @returns The stream status, classified error, a `videoRef` to attach, the live\n *   `stream` for whatever needs the track itself, and a `retry()` to re-attempt\n *   acquisition.\n */\nexport function useCameraStream(options: UseCameraStreamOptions = {}): UseCameraStreamApi {\n    const [status, setStatus] = useState<CameraStreamStatus>(\"loading\");\n    const [error, setError] = useState<CameraStreamError | null>(null);\n    const [live, setLive] = useState<MediaStream | null>(null);\n    const [retryToken, setRetryToken] = useState(0);\n    const videoRef = useRef<HTMLVideoElement | null>(null);\n    const constraintsRef = useRef<MediaStreamConstraints>(\n        options.constraints ?? DEFAULT_CONSTRAINTS,\n    );\n    useEffect(() => {\n        constraintsRef.current = options.constraints ?? DEFAULT_CONSTRAINTS;\n    }, [options.constraints]);\n\n    const enabled = options.enabled ?? true;\n\n    useEffect(() => {\n        let cancelled = false;\n        let stream: MediaStream | null = null;\n        let attachedVideo: HTMLVideoElement | null = null;\n\n        async function start(): Promise<void> {\n            if (!enabled) {\n                setStatus(\"idle\");\n                setError(null);\n                return;\n            }\n            setStatus(\"loading\");\n            setError(null);\n\n            if (\n                typeof navigator === \"undefined\" ||\n                !navigator.mediaDevices ||\n                typeof navigator.mediaDevices.getUserMedia !== \"function\"\n            ) {\n                if (!cancelled) {\n                    setError(toCameraError(missingCaptureApiError(\"camera\")));\n                    setStatus(\"error\");\n                }\n                return;\n            }\n\n            try {\n                stream = await navigator.mediaDevices.getUserMedia(constraintsRef.current);\n                if (cancelled) {\n                    stream.getTracks().forEach((track) => track.stop());\n                    return;\n                }\n                const video = videoRef.current;\n                if (!video) {\n                    stream.getTracks().forEach((track) => track.stop());\n                    return;\n                }\n                attachedVideo = video;\n                video.srcObject = stream;\n                setLive(stream);\n                await video.play().catch(() => undefined);\n                if (!cancelled) setStatus(\"ready\");\n            } catch (err) {\n                if (!cancelled) {\n                    setError(classifyError(err));\n                    setStatus(\"error\");\n                }\n            }\n        }\n\n        void start();\n\n        return () => {\n            cancelled = true;\n            if (stream) {\n                stream.getTracks().forEach((track) => track.stop());\n            }\n            if (attachedVideo) {\n                attachedVideo.srcObject = null;\n            }\n            setLive(null);\n        };\n    }, [retryToken, enabled]);\n\n    return {\n        status,\n        error,\n        videoRef,\n        stream: live,\n        retry: () => setRetryToken((n) => n + 1),\n    };\n}\n"],"mappings":";;;AA+DA,IAAM,IAA8C;CAChD,OAAO;EACH,YAAY,EAAE,OAAO,cAAc;EACnC,OAAO,EAAE,OAAO,KAAK;EACrB,QAAQ,EAAE,OAAO,KAAK;CAC1B;CACA,OAAO;AACX;AAcA,SAAS,EAAc,EAAE,SAAM,cAAgD;CAC3E,OAAO;EAAE,MAAM,MAAS,cAAc,cAAc;EAAM;CAAQ;AACtE;AAOA,SAAS,EAAc,GAAiC;CACpD,OAAO,EAAc,EAAmB,GAAK,QAAQ,CAAC;AAC1D;AA0BA,SAAgB,EAAgB,IAAkC,CAAC,GAAuB;CACtF,IAAM,CAAC,GAAQ,KAAa,EAA6B,SAAS,GAC5D,CAAC,GAAO,KAAY,EAAmC,IAAI,GAC3D,CAAC,GAAM,KAAW,EAA6B,IAAI,GACnD,CAAC,GAAY,KAAiB,EAAS,CAAC,GACxC,IAAW,EAAgC,IAAI,GAC/C,IAAiB,EACnB,EAAQ,eAAe,CAC3B;CACA,QAAgB;EACZ,EAAe,UAAU,EAAQ,eAAe;CACpD,GAAG,CAAC,EAAQ,WAAW,CAAC;CAExB,IAAM,IAAU,EAAQ,WAAW;CAkEnC,OAhEA,QAAgB;EACZ,IAAI,IAAY,IACZ,IAA6B,MAC7B,IAAyC;EAE7C,eAAe,IAAuB;GAClC,IAAI,CAAC,GAAS;IAEV,AADA,EAAU,MAAM,GAChB,EAAS,IAAI;IACb;GACJ;GAIA,IAHA,EAAU,SAAS,GACnB,EAAS,IAAI,GAGT,OAAO,YAAc,OACrB,CAAC,UAAU,gBACX,OAAO,UAAU,aAAa,gBAAiB,YACjD;IACE,AAAK,MACD,EAAS,EAAc,EAAuB,QAAQ,CAAC,CAAC,GACxD,EAAU,OAAO;IAErB;GACJ;GAEA,IAAI;IAEA,IADA,IAAS,MAAM,UAAU,aAAa,aAAa,EAAe,OAAO,GACrE,GAAW;KACX,EAAO,UAAU,CAAC,CAAC,SAAS,MAAU,EAAM,KAAK,CAAC;KAClD;IACJ;IACA,IAAM,IAAQ,EAAS;IACvB,IAAI,CAAC,GAAO;KACR,EAAO,UAAU,CAAC,CAAC,SAAS,MAAU,EAAM,KAAK,CAAC;KAClD;IACJ;IAKA,AAJA,IAAgB,GAChB,EAAM,YAAY,GAClB,EAAQ,CAAM,GACd,MAAM,EAAM,KAAK,CAAC,CAAC,YAAY,KAAA,CAAS,GACnC,KAAW,EAAU,OAAO;GACrC,SAAS,GAAK;IACV,AAAK,MACD,EAAS,EAAc,CAAG,CAAC,GAC3B,EAAU,OAAO;GAEzB;EACJ;EAIA,OAFA,EAAW,SAEE;GAQT,AAPA,IAAY,IACR,KACA,EAAO,UAAU,CAAC,CAAC,SAAS,MAAU,EAAM,KAAK,CAAC,GAElD,MACA,EAAc,YAAY,OAE9B,EAAQ,IAAI;EAChB;CACJ,GAAG,CAAC,GAAY,CAAO,CAAC,GAEjB;EACH;EACA;EACA;EACA,QAAQ;EACR,aAAa,GAAe,MAAM,IAAI,CAAC;CAC3C;AACJ"}

package/dist/vision.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./vision/core/exceptions.cjs"),t=require("./vision/types.cjs"),n=require("./vision/core/timing.cjs"),r=require("./vision/results.cjs"),i=require("./vision/labels.cjs"),a=require("./vision/core/providers.cjs"),o=require("./vision/core/session.cjs"),s=require("./vision/io/image.cjs"),c=require("./vision/preprocess/image.cjs"),l=require("./vision/postprocess/classification.cjs"),u=require("./vision/postprocess/detection.cjs"),d=require("./vision/postprocess/segmentation.cjs"),f=require("./vision/tasks/base.cjs"),p=require("./vision/tasks/classifier.cjs"),m=require("./vision/tasks/detector.cjs"),h=require("./vision/tasks/segmenter.cjs"),g=require("./vision/index.cjs"),_=require("./vision/use-camera-stream.cjs"),v=require("./vision/luminance.cjs"),y=require("./vision/use-live-luminance.cjs");exports.BoundingBox=t.BoundingBox,exports.Boxes=r.Boxes,exports.COCO_CLASSES=i.COCO_CLASSES,exports.ClassificationResults=r.ClassificationResults,exports.Classifier=p.Classifier,exports.DEFAULT_PROVIDERS=a.DEFAULT_PROVIDERS,exports.DetectionResults=r.DetectionResults,exports.Detector=m.Detector,exports.ImageLoadError=e.ImageLoadError,exports.InferenceError=e.InferenceError,exports.LUMINANCE_SAMPLE_MAX_EDGE=v.LUMINANCE_SAMPLE_MAX_EDGE,exports.LabelMapError=e.LabelMapError,exports.LowLuminanceError=v.LowLuminanceError,exports.Mask=t.Mask,exports.Masks=r.Masks,exports.ModelLoadError=e.ModelLoadError,exports.OrtSession=o.OrtSession,exports.OrtVisionError=e.OrtVisionError,exports.Probs=r.Probs,exports.ProviderNotAvailableError=e.ProviderNotAvailableError,exports.RGBImage=t.RGBImage,exports.SegmentationResults=r.SegmentationResults,exports.Segmenter=h.Segmenter,exports.SpeedTimer=n.SpeedTimer,exports.VERSION=g.VERSION,exports.VisionTask=f.VisionTask,exports.batchedNms=u.batchedNms,exports.computeImageLuminance=v.computeImageLuminance,exports.decodeYolo=u.decodeYolo,exports.decodeYoloAnchors=u.decodeYoloAnchors,exports.decodeYoloSeg=d.decodeYoloSeg,exports.decodeYoloV8=u.decodeYoloV8,exports.decodeYoloV8Anchors=u.decodeYoloV8Anchors,exports.decodeYoloV8Seg=d.decodeYoloV8Seg,exports.fromCv2=c.fromCv2,exports.isLuminanceAcceptable=v.isLuminanceAcceptable,exports.letterbox=c.letterbox,exports.loadImage=s.loadImage,exports.nms=u.nms,exports.normalize=c.normalize,exports.resize=c.resize,exports.resolveLabels=i.resolveLabels,exports.resolveProviders=a.resolveProviders,exports.softmax=l.softmax,exports.toCHW=c.toCHW,exports.toCv2=c.toCv2,exports.toFloat32=c.toFloat32,exports.toFloat32Tensor=c.toFloat32Tensor,exports.toTensor=c.toTensor,exports.topK=l.topK,exports.useCameraStream=_.useCameraStream,exports.useLiveLuminance=y.useLiveLuminance;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("./vision/use-camera-stream.cjs"),t=require("./vision/core/exceptions.cjs"),n=require("./vision/types.cjs"),r=require("./vision/core/timing.cjs"),i=require("./vision/results.cjs"),a=require("./vision/labels.cjs"),o=require("./vision/core/providers.cjs"),s=require("./vision/core/session.cjs"),c=require("./vision/io/image.cjs"),l=require("./vision/preprocess/image.cjs"),u=require("./vision/postprocess/classification.cjs"),d=require("./vision/postprocess/detection.cjs"),f=require("./vision/postprocess/segmentation.cjs"),p=require("./vision/tasks/base.cjs"),m=require("./vision/tasks/classifier.cjs"),h=require("./vision/tasks/detector.cjs"),g=require("./vision/tasks/segmenter.cjs"),_=require("./vision/index.cjs"),v=require("./vision/luminance.cjs"),y=require("./vision/use-live-luminance.cjs");exports.BoundingBox=n.BoundingBox,exports.Boxes=i.Boxes,exports.COCO_CLASSES=a.COCO_CLASSES,exports.ClassificationResults=i.ClassificationResults,exports.Classifier=m.Classifier,exports.DEFAULT_PROVIDERS=o.DEFAULT_PROVIDERS,exports.DetectionResults=i.DetectionResults,exports.Detector=h.Detector,exports.ImageLoadError=t.ImageLoadError,exports.InferenceError=t.InferenceError,exports.LUMINANCE_SAMPLE_MAX_EDGE=v.LUMINANCE_SAMPLE_MAX_EDGE,exports.LabelMapError=t.LabelMapError,exports.LowLuminanceError=v.LowLuminanceError,exports.Mask=n.Mask,exports.Masks=i.Masks,exports.ModelLoadError=t.ModelLoadError,exports.OrtSession=s.OrtSession,exports.OrtVisionError=t.OrtVisionError,exports.Probs=i.Probs,exports.ProviderNotAvailableError=t.ProviderNotAvailableError,exports.RGBImage=n.RGBImage,exports.SegmentationResults=i.SegmentationResults,exports.Segmenter=g.Segmenter,exports.SpeedTimer=r.SpeedTimer,exports.VERSION=_.VERSION,exports.VisionTask=p.VisionTask,exports.batchedNms=d.batchedNms,exports.computeImageLuminance=v.computeImageLuminance,exports.decodeYolo=d.decodeYolo,exports.decodeYoloAnchors=d.decodeYoloAnchors,exports.decodeYoloSeg=f.decodeYoloSeg,exports.decodeYoloV8=d.decodeYoloV8,exports.decodeYoloV8Anchors=d.decodeYoloV8Anchors,exports.decodeYoloV8Seg=f.decodeYoloV8Seg,exports.fromCv2=l.fromCv2,exports.isLuminanceAcceptable=v.isLuminanceAcceptable,exports.letterbox=l.letterbox,exports.loadImage=c.loadImage,exports.nms=d.nms,exports.normalize=l.normalize,exports.resize=l.resize,exports.resolveLabels=a.resolveLabels,exports.resolveProviders=o.resolveProviders,exports.softmax=u.softmax,exports.toCHW=l.toCHW,exports.toCv2=l.toCv2,exports.toFloat32=l.toFloat32,exports.toFloat32Tensor=l.toFloat32Tensor,exports.toTensor=l.toTensor,exports.topK=u.topK,exports.useCameraStream=e.useCameraStream,exports.useLiveLuminance=y.useLiveLuminance;

package/dist/vision.d.ts

@@ -1156,7 +1156,9 @@ export declare interface LetterboxResult {
         * The stream is automatically released on unmount or retry.
         *
         * Defaults to the rear ("environment") camera; desktops fall back to whatever
-        * single camera they expose. Pass `options.constraints` to override.
+        * single camera they expose. Pass `options.constraints` to override, or
+        * `options.enabled: false` to render the surface without prompting for the camera
+        * at all.
         *
         * Implementation notes:
         * - Cleanup detaches the stream from a *snapshotted* video node, so it releases
@@ -1168,8 +1170,9 @@ export declare interface LetterboxResult {
         *   the next interaction.
         *
         * @param options - optional configuration (see {@link UseCameraStreamOptions}).
-        * @returns The stream status, classified error, a `videoRef` to attach, and a
-        *   `retry()` to re-attempt acquisition.
+        * @returns The stream status, classified error, a `videoRef` to attach, the live
+        *   `stream` for whatever needs the track itself, and a `retry()` to re-attempt
+        *   acquisition.
         */
        export declare function useCameraStream(options?: UseCameraStreamOptions): UseCameraStreamApi;
 
@@ -1181,6 +1184,15 @@ export declare interface LetterboxResult {
            error: CameraStreamError | null;
            /** Attach to a `<video ref={…} />`. The stream is wired to it once ready. */
            videoRef: RefObject<HTMLVideoElement | null>;
+           /**
+            * The live stream, or `null`.
+            *
+            * Exposed for the things that need the **track** rather than the picture — the LED
+            * torch (`useTorch`), the real frame size from `getSettings()`, recording it with
+            * `useVideoRecorder`. Do not stop it yourself: the hook owns its lifetime and
+            * releases it on unmount and on `retry()`.
+            */
+           stream: MediaStream | null;
            /** Manually re-attempt after an error (e.g. the user changed permissions). */
            retry: () => void;
        }
@@ -1193,6 +1205,16 @@ export declare interface LetterboxResult {
             * Read when the stream (re)starts — change it and call `retry()` to apply.
             */
            constraints?: MediaStreamConstraints;
+           /**
+            * Hold off acquiring the camera until this is `true`. Default `true`.
+            *
+            * The point is to be able to *not* prompt. A permission prompt costs the user a
+            * decision and, if they refuse, costs the app the feature permanently — so a
+            * surface that already knows it cannot do its job (a barcode scanner in a browser
+            * with no decoder) must not open the camera to then say so. Flipping this to `false`
+            * also releases a stream that is already live.
+            */
+           enabled?: boolean;
        }
 
        /**

package/dist/vision.js

@@ -1,21 +1,21 @@
-import { ImageLoadError as e, InferenceError as t, LabelMapError as n, ModelLoadError as r, OrtVisionError as i, ProviderNotAvailableError as a } from "./vision/core/exceptions.js";
-import { BoundingBox as o, Mask as s, RGBImage as c } from "./vision/types.js";
-import { SpeedTimer as l } from "./vision/core/timing.js";
-import { Boxes as u, ClassificationResults as d, DetectionResults as f, Masks as p, Probs as m, SegmentationResults as h } from "./vision/results.js";
-import { COCO_CLASSES as g, resolveLabels as _ } from "./vision/labels.js";
-import { DEFAULT_PROVIDERS as v, resolveProviders as y } from "./vision/core/providers.js";
-import { OrtSession as b } from "./vision/core/session.js";
-import { loadImage as x } from "./vision/io/image.js";
-import { fromCv2 as S, letterbox as C, normalize as w, resize as T, toCHW as E, toCv2 as D, toFloat32 as O, toFloat32Tensor as k, toTensor as A } from "./vision/preprocess/image.js";
-import { softmax as j, topK as M } from "./vision/postprocess/classification.js";
-import { batchedNms as N, decodeYolo as P, decodeYoloAnchors as F, decodeYoloV8 as I, decodeYoloV8Anchors as L, nms as R } from "./vision/postprocess/detection.js";
-import { decodeYoloSeg as z, decodeYoloV8Seg as B } from "./vision/postprocess/segmentation.js";
-import { VisionTask as V } from "./vision/tasks/base.js";
-import { Classifier as H } from "./vision/tasks/classifier.js";
-import { Detector as U } from "./vision/tasks/detector.js";
-import { Segmenter as W } from "./vision/tasks/segmenter.js";
-import { VERSION as G } from "./vision/index.js";
-import { useCameraStream as K } from "./vision/use-camera-stream.js";
+import { useCameraStream as e } from "./vision/use-camera-stream.js";
+import { ImageLoadError as t, InferenceError as n, LabelMapError as r, ModelLoadError as i, OrtVisionError as a, ProviderNotAvailableError as o } from "./vision/core/exceptions.js";
+import { BoundingBox as s, Mask as c, RGBImage as l } from "./vision/types.js";
+import { SpeedTimer as u } from "./vision/core/timing.js";
+import { Boxes as d, ClassificationResults as f, DetectionResults as p, Masks as m, Probs as h, SegmentationResults as g } from "./vision/results.js";
+import { COCO_CLASSES as _, resolveLabels as v } from "./vision/labels.js";
+import { DEFAULT_PROVIDERS as y, resolveProviders as b } from "./vision/core/providers.js";
+import { OrtSession as x } from "./vision/core/session.js";
+import { loadImage as S } from "./vision/io/image.js";
+import { fromCv2 as C, letterbox as w, normalize as T, resize as E, toCHW as D, toCv2 as O, toFloat32 as k, toFloat32Tensor as A, toTensor as j } from "./vision/preprocess/image.js";
+import { softmax as M, topK as N } from "./vision/postprocess/classification.js";
+import { batchedNms as P, decodeYolo as F, decodeYoloAnchors as I, decodeYoloV8 as L, decodeYoloV8Anchors as R, nms as z } from "./vision/postprocess/detection.js";
+import { decodeYoloSeg as B, decodeYoloV8Seg as V } from "./vision/postprocess/segmentation.js";
+import { VisionTask as H } from "./vision/tasks/base.js";
+import { Classifier as U } from "./vision/tasks/classifier.js";
+import { Detector as W } from "./vision/tasks/detector.js";
+import { Segmenter as G } from "./vision/tasks/segmenter.js";
+import { VERSION as K } from "./vision/index.js";
 import { LUMINANCE_SAMPLE_MAX_EDGE as q, LowLuminanceError as J, computeImageLuminance as Y, isLuminanceAcceptable as X } from "./vision/luminance.js";
 import { useLiveLuminance as Z } from "./vision/use-live-luminance.js";
-export { o as BoundingBox, u as Boxes, g as COCO_CLASSES, d as ClassificationResults, H as Classifier, v as DEFAULT_PROVIDERS, f as DetectionResults, U as Detector, e as ImageLoadError, t as InferenceError, q as LUMINANCE_SAMPLE_MAX_EDGE, n as LabelMapError, J as LowLuminanceError, s as Mask, p as Masks, r as ModelLoadError, b as OrtSession, i as OrtVisionError, m as Probs, a as ProviderNotAvailableError, c as RGBImage, h as SegmentationResults, W as Segmenter, l as SpeedTimer, G as VERSION, V as VisionTask, N as batchedNms, Y as computeImageLuminance, P as decodeYolo, F as decodeYoloAnchors, z as decodeYoloSeg, I as decodeYoloV8, L as decodeYoloV8Anchors, B as decodeYoloV8Seg, S as fromCv2, X as isLuminanceAcceptable, C as letterbox, x as loadImage, R as nms, w as normalize, T as resize, _ as resolveLabels, y as resolveProviders, j as softmax, E as toCHW, D as toCv2, O as toFloat32, k as toFloat32Tensor, A as toTensor, M as topK, K as useCameraStream, Z as useLiveLuminance };
+export { s as BoundingBox, d as Boxes, _ as COCO_CLASSES, f as ClassificationResults, U as Classifier, y as DEFAULT_PROVIDERS, p as DetectionResults, W as Detector, t as ImageLoadError, n as InferenceError, q as LUMINANCE_SAMPLE_MAX_EDGE, r as LabelMapError, J as LowLuminanceError, c as Mask, m as Masks, i as ModelLoadError, x as OrtSession, a as OrtVisionError, h as Probs, o as ProviderNotAvailableError, l as RGBImage, g as SegmentationResults, G as Segmenter, u as SpeedTimer, K as VERSION, H as VisionTask, P as batchedNms, Y as computeImageLuminance, F as decodeYolo, I as decodeYoloAnchors, B as decodeYoloSeg, L as decodeYoloV8, R as decodeYoloV8Anchors, V as decodeYoloV8Seg, C as fromCv2, X as isLuminanceAcceptable, w as letterbox, S as loadImage, z as nms, T as normalize, E as resize, v as resolveLabels, b as resolveProviders, M as softmax, D as toCHW, O as toCv2, k as toFloat32, A as toFloat32Tensor, j as toTensor, N as topK, e as useCameraStream, Z as useLiveLuminance };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tempest-react-sdk",
-  "version": "0.35.0",
+  "version": "0.36.0",
   "description": "SDK público da Tempest com componentes, hooks e integrações para projetos React.",
   "type": "module",
   "license": "MIT",