tempest-react-sdk 0.78.0 → 0.79.0

package/dist/imaging/encode.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"encode.cjs","names":[],"sources":["../../src/imaging/encode.ts"],"sourcesContent":["/**\n * Getting bytes back out, and knowing which bytes you got.\n *\n * The trap here is silent: `canvas.toBlob(cb, \"image/avif\")` does not throw\n * on a browser without an AVIF encoder. It hands back a **PNG** with the\n * requested type ignored, and an app that trusted the request uploads\n * several megabytes where it planned for a few hundred kilobytes. Every\n * function here reports the type actually produced, and\n * :func:`supportsImageType` answers the question up front.\n */\n\nimport { getContext, type Surface } from \"./canvas\";\nimport { ImageEncodeError } from \"./exceptions\";\nimport type { EncodeOptions, ImageType, ProcessedImage } from \"./types\";\n\n/** Quality used when the caller does not choose. */\nexport const DEFAULT_QUALITY = 0.85;\n\n/** Format used when the caller does not choose. */\nexport const DEFAULT_TYPE: ImageType = \"image/jpeg\";\n\nconst supportCache = new Map<string, boolean>();\n\n/**\n * Encode a surface into image bytes.\n *\n * @param surface The canvas to encode.\n * @param options Format and quality.\n * @returns The blob plus the dimensions and the type actually produced.\n * @throws {@link ImageEncodeError} when the canvas produces nothing.\n */\nexport async function encodeImage(\n    surface: Surface,\n    options: EncodeOptions = {},\n): Promise<ProcessedImage> {\n    const type = options.type ?? DEFAULT_TYPE;\n    const quality = options.quality ?? DEFAULT_QUALITY;\n\n    const blob = await surfaceToBlob(surface, type, quality);\n    if (blob === null) {\n        throw new ImageEncodeError(\n            `The canvas produced no bytes for ${type}. The image may be too large ` +\n                \"for this browser's canvas limits.\",\n        );\n    }\n\n    return {\n        blob,\n        width: surface.width,\n        height: surface.height,\n        type: blob.type || type,\n        bytes: blob.size,\n    };\n}\n\n/**\n * Encode a surface, whichever kind it is.\n *\n * `OffscreenCanvas` and `HTMLCanvasElement` disagree on how to hand back\n * bytes — one returns a promise, the other takes a callback.\n *\n * @param surface The canvas.\n * @param type MIME type to request.\n * @param quality Quality for lossy formats.\n * @returns The blob, or `null` when the canvas produced nothing.\n */\nasync function surfaceToBlob(\n    surface: Surface,\n    type: string,\n    quality: number,\n): Promise<Blob | null> {\n    if (\"convertToBlob\" in surface) {\n        return await surface.convertToBlob({ type, quality });\n    }\n    return await new Promise<Blob | null>((resolve) => {\n        surface.toBlob((blob) => resolve(blob), type, quality);\n    });\n}\n\n/**\n * Whether this browser can actually encode a format.\n *\n * Asks for a 1x1 image in that type and checks what came back, because\n * that is the only answer that counts: a browser that \"supports\" WebP for\n * display may still not encode it.\n *\n * @example\n * ```ts\n * const type = (await supportsImageType(\"image/webp\")) ? \"image/webp\" : \"image/jpeg\";\n * const resized = await resizeImage(file, { width: 1200, type });\n * ```\n *\n * @param type The format to test.\n * @returns Whether encoding produces that type. Cached per type.\n */\nexport async function supportsImageType(type: ImageType): Promise<boolean> {\n    const cached = supportCache.get(type);\n    if (cached !== undefined) return cached;\n\n    let supported: boolean;\n    try {\n        const { createSurface } = await import(\"./canvas\");\n        const surface = createSurface(1, 1);\n        getContext(surface);\n        const blob = await surfaceToBlob(surface, type, 0.5);\n        supported = blob !== null && blob.type === type;\n    } catch {\n        supported = false;\n    }\n\n    supportCache.set(type, supported);\n    return supported;\n}\n\n/**\n * Pick the smallest format this browser can actually produce.\n *\n * @example\n * ```ts\n * const type = await bestSupportedType([\"image/avif\", \"image/webp\", \"image/jpeg\"]);\n * ```\n *\n * @param preferences Formats in preference order.\n * @returns The first supported one, falling back to `image/jpeg`, which\n *   every canvas implementation encodes.\n */\nexport async function bestSupportedType(\n    preferences: readonly ImageType[] = [\"image/webp\", \"image/jpeg\"],\n): Promise<ImageType> {\n    for (const type of preferences) {\n        if (await supportsImageType(type)) return type;\n    }\n    return \"image/jpeg\";\n}\n\n/**\n * Clear the format-support cache.\n *\n * Only useful in tests: browser support does not change at runtime.\n */\nexport function resetImageTypeSupportCache(): void {\n    supportCache.clear();\n}\n"],"mappings":"8DAgBA,IAAa,EAAkB,IAGlB,EAA0B,aAEjC,EAAe,IAAI,IAUzB,eAAsB,EAClB,EACA,EAAyB,CAAC,EACH,CACvB,IAAM,EAAO,EAAQ,MAAA,aAGf,EAAO,MAAM,EAAc,EAAS,EAF1B,EAAQ,SAAA,GAE+B,EACvD,GAAI,IAAS,KACT,MAAM,IAAI,EAAA,iBACN,oCAAoC,EAAK,+DAE7C,EAGJ,MAAO,CACH,OACA,MAAO,EAAQ,MACf,OAAQ,EAAQ,OAChB,KAAM,EAAK,MAAQ,EACnB,MAAO,EAAK,IAChB,CACJ,CAaA,eAAe,EACX,EACA,EACA,EACoB,CAIpB,MAHI,kBAAmB,EACZ,MAAM,EAAQ,cAAc,CAAE,OAAM,SAAQ,CAAC,EAEjD,MAAM,IAAI,QAAsB,GAAY,CAC/C,EAAQ,OAAQ,GAAS,EAAQ,CAAI,EAAG,EAAM,CAAO,CACzD,CAAC,CACL,CAkBA,eAAsB,EAAkB,EAAmC,CACvE,IAAM,EAAS,EAAa,IAAI,CAAI,EACpC,GAAI,IAAW,IAAA,GAAW,OAAO,EAEjC,IAAI,EACJ,GAAI,CACA,GAAM,CAAE,iBAAkB,MAAA,QAAA,QAAA,CAAA,CAAA,SAAA,QAAM,cAAA,CAAA,EAC1B,EAAU,EAAc,EAAG,CAAC,EAClC,EAAA,WAAW,CAAO,EAClB,IAAM,EAAO,MAAM,EAAc,EAAS,EAAM,EAAG,EACnD,EAAY,IAAS,MAAQ,EAAK,OAAS,CAC/C,MAAQ,CACJ,EAAY,EAChB,CAGA,OADA,EAAa,IAAI,EAAM,CAAS,EACzB,CACX,CAcA,eAAsB,EAClB,EAAoC,CAAC,aAAc,YAAY,EAC7C,CAClB,IAAK,IAAM,KAAQ,EACf,GAAI,MAAM,EAAkB,CAAI,EAAG,OAAO,EAE9C,MAAO,YACX"}
+{"version":3,"file":"encode.cjs","names":["ImageEncodeError","require_exceptions","require_canvas","DEFAULT_QUALITY","DEFAULT_TYPE","supportCache","encodeImage","type","options","blob","surfaceToBlob","surface","resolve","quality","supportsImageType","cached","supported","createSurface","bestSupportedType","preferences"],"sources":["../../src/imaging/encode.ts"],"sourcesContent":["/**\n * Getting bytes back out, and knowing which bytes you got.\n *\n * The trap here is silent: `canvas.toBlob(cb, \"image/avif\")` does not throw\n * on a browser without an AVIF encoder. It hands back a **PNG** with the\n * requested type ignored, and an app that trusted the request uploads\n * several megabytes where it planned for a few hundred kilobytes. Every\n * function here reports the type actually produced, and\n * :func:`supportsImageType` answers the question up front.\n */\n\nimport { getContext, type Surface } from \"./canvas\";\nimport { ImageEncodeError } from \"./exceptions\";\nimport type { EncodeOptions, ImageType, ProcessedImage } from \"./types\";\n\n/** Quality used when the caller does not choose. */\nexport const DEFAULT_QUALITY = 0.85;\n\n/** Format used when the caller does not choose. */\nexport const DEFAULT_TYPE: ImageType = \"image/jpeg\";\n\nconst supportCache = new Map<string, boolean>();\n\n/**\n * Encode a surface into image bytes.\n *\n * @param surface The canvas to encode.\n * @param options Format and quality.\n * @returns The blob plus the dimensions and the type actually produced.\n * @throws {@link ImageEncodeError} when the canvas produces nothing.\n */\nexport async function encodeImage(\n    surface: Surface,\n    options: EncodeOptions = {},\n): Promise<ProcessedImage> {\n    const type = options.type ?? DEFAULT_TYPE;\n    const quality = options.quality ?? DEFAULT_QUALITY;\n\n    const blob = await surfaceToBlob(surface, type, quality);\n    if (blob === null) {\n        throw new ImageEncodeError(\n            `The canvas produced no bytes for ${type}. The image may be too large ` +\n                \"for this browser's canvas limits.\",\n        );\n    }\n\n    return {\n        blob,\n        width: surface.width,\n        height: surface.height,\n        type: blob.type || type,\n        bytes: blob.size,\n    };\n}\n\n/**\n * Encode a surface, whichever kind it is.\n *\n * `OffscreenCanvas` and `HTMLCanvasElement` disagree on how to hand back\n * bytes — one returns a promise, the other takes a callback.\n *\n * @param surface The canvas.\n * @param type MIME type to request.\n * @param quality Quality for lossy formats.\n * @returns The blob, or `null` when the canvas produced nothing.\n */\nasync function surfaceToBlob(\n    surface: Surface,\n    type: string,\n    quality: number,\n): Promise<Blob | null> {\n    if (\"convertToBlob\" in surface) {\n        return await surface.convertToBlob({ type, quality });\n    }\n    return await new Promise<Blob | null>((resolve) => {\n        surface.toBlob((blob) => resolve(blob), type, quality);\n    });\n}\n\n/**\n * Whether this browser can actually encode a format.\n *\n * Asks for a 1x1 image in that type and checks what came back, because\n * that is the only answer that counts: a browser that \"supports\" WebP for\n * display may still not encode it.\n *\n * @example\n * ```ts\n * const type = (await supportsImageType(\"image/webp\")) ? \"image/webp\" : \"image/jpeg\";\n * const resized = await resizeImage(file, { width: 1200, type });\n * ```\n *\n * @param type The format to test.\n * @returns Whether encoding produces that type. Cached per type.\n */\nexport async function supportsImageType(type: ImageType): Promise<boolean> {\n    const cached = supportCache.get(type);\n    if (cached !== undefined) return cached;\n\n    let supported: boolean;\n    try {\n        const { createSurface } = await import(\"./canvas\");\n        const surface = createSurface(1, 1);\n        getContext(surface);\n        const blob = await surfaceToBlob(surface, type, 0.5);\n        supported = blob !== null && blob.type === type;\n    } catch {\n        supported = false;\n    }\n\n    supportCache.set(type, supported);\n    return supported;\n}\n\n/**\n * Pick the smallest format this browser can actually produce.\n *\n * @example\n * ```ts\n * const type = await bestSupportedType([\"image/avif\", \"image/webp\", \"image/jpeg\"]);\n * ```\n *\n * @param preferences Formats in preference order.\n * @returns The first supported one, falling back to `image/jpeg`, which\n *   every canvas implementation encodes.\n */\nexport async function bestSupportedType(\n    preferences: readonly ImageType[] = [\"image/webp\", \"image/jpeg\"],\n): Promise<ImageType> {\n    for (const type of preferences) {\n        if (await supportsImageType(type)) return type;\n    }\n    return \"image/jpeg\";\n}\n\n/**\n * Clear the format-support cache.\n *\n * Only useful in tests: browser support does not change at runtime.\n */\nexport function resetImageTypeSupportCache(): void {\n    supportCache.clear();\n}\n"],"mappings":"A,8DAgBA,IAAaG,EAAkB,IAGlBC,EAA0B,aAEjCC,EAAe,IAAI,IAUzB,eAAsBC,EAClB,EACA,EAAyB,CAAC,EACH,CACvB,IAAMC,EAAOC,EAAQ,MAAA,aAGfC,EAAO,MAAMC,EAAcC,EAASJ,EAF1BC,EAAQ,SAAA,GAE+B,EACvD,GAAIC,IAAS,KACT,MAAM,IAAIT,EAAAA,iBACN,oCAAoCO,EAAK,+DAE7C,EAGJ,MAAO,CACH,OACA,MAAOI,EAAQ,MACf,OAAQA,EAAQ,OAChB,KAAMF,EAAK,MAAQF,EACnB,MAAOE,EAAK,IAChB,CACJ,CAaA,eAAeC,EACX,EACA,EACA,EACoB,CAIpB,MAHI,kBAAmBC,EACZ,MAAMA,EAAQ,cAAc,CAAE,OAAM,SAAQ,CAAC,EAEjD,MAAM,IAAI,QAAsB,GAAY,CAC/CA,EAAQ,OAAQ,GAASC,EAAQH,CAAI,EAAGF,EAAMM,CAAO,CACzD,CAAC,CACL,CAkBA,eAAsBC,EAAkB,EAAmC,CACvE,IAAMC,EAASV,EAAa,IAAIE,CAAI,EACpC,GAAIQ,IAAW,IAAA,GAAW,OAAOA,EAEjC,IAAIC,EACJ,GAAI,CACA,GAAM,CAAE,iBAAkB,MAAA,QAAA,QAAA,CAAA,CAAA,SAAA,QAAM,cAAA,CAAA,EAC1BL,EAAUM,EAAc,EAAG,CAAC,EAClCf,EAAA,WAAWS,CAAO,EAClB,IAAMF,EAAO,MAAMC,EAAcC,EAASJ,EAAM,EAAG,EACnD,EAAYE,IAAS,MAAQA,EAAK,OAASF,CAC/C,MAAQ,CACJ,EAAY,EAChB,CAGA,OADAF,EAAa,IAAIE,EAAMS,CAAS,EACzBA,CACX,CAcA,eAAsBE,EAClB,EAAoC,CAAC,aAAc,YAAY,EAC7C,CAClB,IAAK,IAAMX,KAAQY,EACf,GAAI,MAAML,EAAkBP,CAAI,EAAG,OAAOA,EAE9C,MAAO,YACX,C"}

package/dist/imaging/encode.js.map

@@ -1 +1 @@
-{"version":3,"file":"encode.js","names":[],"sources":["../../src/imaging/encode.ts"],"sourcesContent":["/**\n * Getting bytes back out, and knowing which bytes you got.\n *\n * The trap here is silent: `canvas.toBlob(cb, \"image/avif\")` does not throw\n * on a browser without an AVIF encoder. It hands back a **PNG** with the\n * requested type ignored, and an app that trusted the request uploads\n * several megabytes where it planned for a few hundred kilobytes. Every\n * function here reports the type actually produced, and\n * :func:`supportsImageType` answers the question up front.\n */\n\nimport { getContext, type Surface } from \"./canvas\";\nimport { ImageEncodeError } from \"./exceptions\";\nimport type { EncodeOptions, ImageType, ProcessedImage } from \"./types\";\n\n/** Quality used when the caller does not choose. */\nexport const DEFAULT_QUALITY = 0.85;\n\n/** Format used when the caller does not choose. */\nexport const DEFAULT_TYPE: ImageType = \"image/jpeg\";\n\nconst supportCache = new Map<string, boolean>();\n\n/**\n * Encode a surface into image bytes.\n *\n * @param surface The canvas to encode.\n * @param options Format and quality.\n * @returns The blob plus the dimensions and the type actually produced.\n * @throws {@link ImageEncodeError} when the canvas produces nothing.\n */\nexport async function encodeImage(\n    surface: Surface,\n    options: EncodeOptions = {},\n): Promise<ProcessedImage> {\n    const type = options.type ?? DEFAULT_TYPE;\n    const quality = options.quality ?? DEFAULT_QUALITY;\n\n    const blob = await surfaceToBlob(surface, type, quality);\n    if (blob === null) {\n        throw new ImageEncodeError(\n            `The canvas produced no bytes for ${type}. The image may be too large ` +\n                \"for this browser's canvas limits.\",\n        );\n    }\n\n    return {\n        blob,\n        width: surface.width,\n        height: surface.height,\n        type: blob.type || type,\n        bytes: blob.size,\n    };\n}\n\n/**\n * Encode a surface, whichever kind it is.\n *\n * `OffscreenCanvas` and `HTMLCanvasElement` disagree on how to hand back\n * bytes — one returns a promise, the other takes a callback.\n *\n * @param surface The canvas.\n * @param type MIME type to request.\n * @param quality Quality for lossy formats.\n * @returns The blob, or `null` when the canvas produced nothing.\n */\nasync function surfaceToBlob(\n    surface: Surface,\n    type: string,\n    quality: number,\n): Promise<Blob | null> {\n    if (\"convertToBlob\" in surface) {\n        return await surface.convertToBlob({ type, quality });\n    }\n    return await new Promise<Blob | null>((resolve) => {\n        surface.toBlob((blob) => resolve(blob), type, quality);\n    });\n}\n\n/**\n * Whether this browser can actually encode a format.\n *\n * Asks for a 1x1 image in that type and checks what came back, because\n * that is the only answer that counts: a browser that \"supports\" WebP for\n * display may still not encode it.\n *\n * @example\n * ```ts\n * const type = (await supportsImageType(\"image/webp\")) ? \"image/webp\" : \"image/jpeg\";\n * const resized = await resizeImage(file, { width: 1200, type });\n * ```\n *\n * @param type The format to test.\n * @returns Whether encoding produces that type. Cached per type.\n */\nexport async function supportsImageType(type: ImageType): Promise<boolean> {\n    const cached = supportCache.get(type);\n    if (cached !== undefined) return cached;\n\n    let supported: boolean;\n    try {\n        const { createSurface } = await import(\"./canvas\");\n        const surface = createSurface(1, 1);\n        getContext(surface);\n        const blob = await surfaceToBlob(surface, type, 0.5);\n        supported = blob !== null && blob.type === type;\n    } catch {\n        supported = false;\n    }\n\n    supportCache.set(type, supported);\n    return supported;\n}\n\n/**\n * Pick the smallest format this browser can actually produce.\n *\n * @example\n * ```ts\n * const type = await bestSupportedType([\"image/avif\", \"image/webp\", \"image/jpeg\"]);\n * ```\n *\n * @param preferences Formats in preference order.\n * @returns The first supported one, falling back to `image/jpeg`, which\n *   every canvas implementation encodes.\n */\nexport async function bestSupportedType(\n    preferences: readonly ImageType[] = [\"image/webp\", \"image/jpeg\"],\n): Promise<ImageType> {\n    for (const type of preferences) {\n        if (await supportsImageType(type)) return type;\n    }\n    return \"image/jpeg\";\n}\n\n/**\n * Clear the format-support cache.\n *\n * Only useful in tests: browser support does not change at runtime.\n */\nexport function resetImageTypeSupportCache(): void {\n    supportCache.clear();\n}\n"],"mappings":";;;AAgBA,IAAa,IAAkB,KAGlB,IAA0B,cAEjC,oBAAe,IAAI,IAAqB;AAU9C,eAAsB,EAClB,GACA,IAAyB,CAAC,GACH;CACvB,IAAM,IAAO,EAAQ,QAAA,cAGf,IAAO,MAAM,EAAc,GAAS,GAF1B,EAAQ,WAAA,GAE+B;CACvD,IAAI,MAAS,MACT,MAAM,IAAI,EACN,oCAAoC,EAAK,+DAE7C;CAGJ,OAAO;EACH;EACA,OAAO,EAAQ;EACf,QAAQ,EAAQ;EAChB,MAAM,EAAK,QAAQ;EACnB,OAAO,EAAK;CAChB;AACJ;AAaA,eAAe,EACX,GACA,GACA,GACoB;CAIpB,OAHI,mBAAmB,IACZ,MAAM,EAAQ,cAAc;EAAE;EAAM;CAAQ,CAAC,IAEjD,MAAM,IAAI,SAAsB,MAAY;EAC/C,EAAQ,QAAQ,MAAS,EAAQ,CAAI,GAAG,GAAM,CAAO;CACzD,CAAC;AACL;AAkBA,eAAsB,EAAkB,GAAmC;CACvE,IAAM,IAAS,EAAa,IAAI,CAAI;CACpC,IAAI,MAAW,KAAA,GAAW,OAAO;CAEjC,IAAI;CACJ,IAAI;EACA,IAAM,EAAE,qBAAkB,MAAM,OAAO,gBACjC,IAAU,EAAc,GAAG,CAAC;EAClC,EAAW,CAAO;EAClB,IAAM,IAAO,MAAM,EAAc,GAAS,GAAM,EAAG;EACnD,IAAY,MAAS,QAAQ,EAAK,SAAS;CAC/C,QAAQ;EACJ,IAAY;CAChB;CAGA,OADA,EAAa,IAAI,GAAM,CAAS,GACzB;AACX;AAcA,eAAsB,EAClB,IAAoC,CAAC,cAAc,YAAY,GAC7C;CAClB,KAAK,IAAM,KAAQ,GACf,IAAI,MAAM,EAAkB,CAAI,GAAG,OAAO;CAE9C,OAAO;AACX"}
+{"version":3,"file":"encode.js","names":["DEFAULT_QUALITY","DEFAULT_TYPE","supportCache","encodeImage","type","options","blob","surfaceToBlob","surface","ImageEncodeError","resolve","quality","supportsImageType","cached","supported","createSurface","bestSupportedType","preferences"],"sources":["../../src/imaging/encode.ts"],"sourcesContent":["/**\n * Getting bytes back out, and knowing which bytes you got.\n *\n * The trap here is silent: `canvas.toBlob(cb, \"image/avif\")` does not throw\n * on a browser without an AVIF encoder. It hands back a **PNG** with the\n * requested type ignored, and an app that trusted the request uploads\n * several megabytes where it planned for a few hundred kilobytes. Every\n * function here reports the type actually produced, and\n * :func:`supportsImageType` answers the question up front.\n */\n\nimport { getContext, type Surface } from \"./canvas\";\nimport { ImageEncodeError } from \"./exceptions\";\nimport type { EncodeOptions, ImageType, ProcessedImage } from \"./types\";\n\n/** Quality used when the caller does not choose. */\nexport const DEFAULT_QUALITY = 0.85;\n\n/** Format used when the caller does not choose. */\nexport const DEFAULT_TYPE: ImageType = \"image/jpeg\";\n\nconst supportCache = new Map<string, boolean>();\n\n/**\n * Encode a surface into image bytes.\n *\n * @param surface The canvas to encode.\n * @param options Format and quality.\n * @returns The blob plus the dimensions and the type actually produced.\n * @throws {@link ImageEncodeError} when the canvas produces nothing.\n */\nexport async function encodeImage(\n    surface: Surface,\n    options: EncodeOptions = {},\n): Promise<ProcessedImage> {\n    const type = options.type ?? DEFAULT_TYPE;\n    const quality = options.quality ?? DEFAULT_QUALITY;\n\n    const blob = await surfaceToBlob(surface, type, quality);\n    if (blob === null) {\n        throw new ImageEncodeError(\n            `The canvas produced no bytes for ${type}. The image may be too large ` +\n                \"for this browser's canvas limits.\",\n        );\n    }\n\n    return {\n        blob,\n        width: surface.width,\n        height: surface.height,\n        type: blob.type || type,\n        bytes: blob.size,\n    };\n}\n\n/**\n * Encode a surface, whichever kind it is.\n *\n * `OffscreenCanvas` and `HTMLCanvasElement` disagree on how to hand back\n * bytes — one returns a promise, the other takes a callback.\n *\n * @param surface The canvas.\n * @param type MIME type to request.\n * @param quality Quality for lossy formats.\n * @returns The blob, or `null` when the canvas produced nothing.\n */\nasync function surfaceToBlob(\n    surface: Surface,\n    type: string,\n    quality: number,\n): Promise<Blob | null> {\n    if (\"convertToBlob\" in surface) {\n        return await surface.convertToBlob({ type, quality });\n    }\n    return await new Promise<Blob | null>((resolve) => {\n        surface.toBlob((blob) => resolve(blob), type, quality);\n    });\n}\n\n/**\n * Whether this browser can actually encode a format.\n *\n * Asks for a 1x1 image in that type and checks what came back, because\n * that is the only answer that counts: a browser that \"supports\" WebP for\n * display may still not encode it.\n *\n * @example\n * ```ts\n * const type = (await supportsImageType(\"image/webp\")) ? \"image/webp\" : \"image/jpeg\";\n * const resized = await resizeImage(file, { width: 1200, type });\n * ```\n *\n * @param type The format to test.\n * @returns Whether encoding produces that type. Cached per type.\n */\nexport async function supportsImageType(type: ImageType): Promise<boolean> {\n    const cached = supportCache.get(type);\n    if (cached !== undefined) return cached;\n\n    let supported: boolean;\n    try {\n        const { createSurface } = await import(\"./canvas\");\n        const surface = createSurface(1, 1);\n        getContext(surface);\n        const blob = await surfaceToBlob(surface, type, 0.5);\n        supported = blob !== null && blob.type === type;\n    } catch {\n        supported = false;\n    }\n\n    supportCache.set(type, supported);\n    return supported;\n}\n\n/**\n * Pick the smallest format this browser can actually produce.\n *\n * @example\n * ```ts\n * const type = await bestSupportedType([\"image/avif\", \"image/webp\", \"image/jpeg\"]);\n * ```\n *\n * @param preferences Formats in preference order.\n * @returns The first supported one, falling back to `image/jpeg`, which\n *   every canvas implementation encodes.\n */\nexport async function bestSupportedType(\n    preferences: readonly ImageType[] = [\"image/webp\", \"image/jpeg\"],\n): Promise<ImageType> {\n    for (const type of preferences) {\n        if (await supportsImageType(type)) return type;\n    }\n    return \"image/jpeg\";\n}\n\n/**\n * Clear the format-support cache.\n *\n * Only useful in tests: browser support does not change at runtime.\n */\nexport function resetImageTypeSupportCache(): void {\n    supportCache.clear();\n}\n"],"mappings":";;;AAgBA,IAAaA,IAAkB,KAGlBC,IAA0B,cAEjCC,oBAAe,IAAI,IAAqB;AAU9C,eAAsBC,EAClB,GACA,IAAyB,CAAC,GACH;CACvB,IAAMC,IAAOC,EAAQ,QAAA,cAGfC,IAAO,MAAMC,EAAcC,GAASJ,GAF1BC,EAAQ,WAAA,GAE+B;CACvD,IAAIC,MAAS,MACT,MAAM,IAAIG,EACN,oCAAoCL,EAAK,+DAE7C;CAGJ,OAAO;EACH;EACA,OAAOI,EAAQ;EACf,QAAQA,EAAQ;EAChB,MAAMF,EAAK,QAAQF;EACnB,OAAOE,EAAK;CAChB;AACJ;AAaA,eAAeC,EACX,GACA,GACA,GACoB;CAIpB,OAHI,mBAAmBC,IACZ,MAAMA,EAAQ,cAAc;EAAE;EAAM;CAAQ,CAAC,IAEjD,MAAM,IAAI,SAAsB,MAAY;EAC/C,EAAQ,QAAQ,MAASE,EAAQJ,CAAI,GAAGF,GAAMO,CAAO;CACzD,CAAC;AACL;AAkBA,eAAsBC,EAAkB,GAAmC;CACvE,IAAMC,IAASX,EAAa,IAAIE,CAAI;CACpC,IAAIS,MAAW,KAAA,GAAW,OAAOA;CAEjC,IAAIC;CACJ,IAAI;EACA,IAAM,EAAE,qBAAkB,MAAM,OAAO,gBACjCN,IAAUO,EAAc,GAAG,CAAC;EAClC,EAAWP,CAAO;EAClB,IAAMF,IAAO,MAAMC,EAAcC,GAASJ,GAAM,EAAG;EACnD,IAAYE,MAAS,QAAQA,EAAK,SAASF;CAC/C,QAAQ;EACJ,IAAY;CAChB;CAGA,OADAF,EAAa,IAAIE,GAAMU,CAAS,GACzBA;AACX;AAcA,eAAsBE,EAClB,IAAoC,CAAC,cAAc,YAAY,GAC7C;CAClB,KAAK,IAAMZ,KAAQa,GACf,IAAI,MAAML,EAAkBR,CAAI,GAAG,OAAOA;CAE9C,OAAO;AACX"}

package/dist/imaging/exceptions.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"exceptions.cjs","names":[],"sources":["../../src/imaging/exceptions.ts"],"sourcesContent":["/**\n * Errors thrown by the imaging module.\n *\n * `name` is a literal string on every subclass: minifiers rename classes,\n * and a derived `new.target.name` ships as `error.name === \"t\"`.\n */\n\n/** Base class for every error this module throws. */\nexport class ImagingError extends Error {\n    constructor(message: string, options?: ErrorOptions) {\n        super(message, options);\n        this.name = \"ImagingError\";\n    }\n}\n\n/** The source could not be decoded into pixels. */\nexport class ImageDecodeError extends ImagingError {\n    constructor(message: string, options?: ErrorOptions) {\n        super(message, options);\n        this.name = \"ImageDecodeError\";\n    }\n}\n\n/** The canvas could not produce encoded bytes. */\nexport class ImageEncodeError extends ImagingError {\n    constructor(message: string, options?: ErrorOptions) {\n        super(message, options);\n        this.name = \"ImageEncodeError\";\n    }\n}\n\n/**\n * The browser cannot encode the requested format.\n *\n * Worth its own class because the failure is otherwise silent: asking a\n * canvas for an unsupported type does not throw — it hands back a PNG,\n * and an app that trusted the request ships 4 MB where it expected 300 KB.\n */\nexport class UnsupportedImageTypeError extends ImagingError {\n    constructor(message: string, options?: ErrorOptions) {\n        super(message, options);\n        this.name = \"UnsupportedImageTypeError\";\n    }\n}\n\n/**\n * The frame asked for never arrived.\n *\n * Its own class because the alternative is the failure this module refuses to\n * produce: a frame from the wrong instant. `seeked` firing does not mean the\n * frame for the new position is composited and readable, so a capture that\n * gave up waiting has to say so — a thumbnail of the neighbouring frame looks\n * exactly like a correct one, and nothing downstream can tell.\n */\nexport class FrameSeekError extends ImagingError {\n    constructor(message: string, options?: ErrorOptions) {\n        super(message, options);\n        this.name = \"FrameSeekError\";\n    }\n}\n\n/** The environment has no canvas to draw on. */\nexport class ImagingUnavailableError extends ImagingError {\n    constructor(message: string, options?: ErrorOptions) {\n        super(message, options);\n        this.name = \"ImagingUnavailableError\";\n    }\n}\n"],"mappings":"AAQA,IAAa,EAAb,cAAkC,KAAM,CACpC,YAAY,EAAiB,EAAwB,CACjD,MAAM,EAAS,CAAO,EACtB,KAAK,KAAO,cAChB,CACJ,EAGa,EAAb,cAAsC,CAAa,CAC/C,YAAY,EAAiB,EAAwB,CACjD,MAAM,EAAS,CAAO,EACtB,KAAK,KAAO,kBAChB,CACJ,EAGa,EAAb,cAAsC,CAAa,CAC/C,YAAY,EAAiB,EAAwB,CACjD,MAAM,EAAS,CAAO,EACtB,KAAK,KAAO,kBAChB,CACJ,EASa,EAAb,cAA+C,CAAa,CACxD,YAAY,EAAiB,EAAwB,CACjD,MAAM,EAAS,CAAO,EACtB,KAAK,KAAO,2BAChB,CACJ,EAWa,EAAb,cAAoC,CAAa,CAC7C,YAAY,EAAiB,EAAwB,CACjD,MAAM,EAAS,CAAO,EACtB,KAAK,KAAO,gBAChB,CACJ,EAGa,EAAb,cAA6C,CAAa,CACtD,YAAY,EAAiB,EAAwB,CACjD,MAAM,EAAS,CAAO,EACtB,KAAK,KAAO,yBAChB,CACJ"}
+{"version":3,"file":"exceptions.cjs","names":["ImagingError","message","options","ImageDecodeError","ImageEncodeError","UnsupportedImageTypeError","FrameSeekError","ImagingUnavailableError"],"sources":["../../src/imaging/exceptions.ts"],"sourcesContent":["/**\n * Errors thrown by the imaging module.\n *\n * `name` is a literal string on every subclass: minifiers rename classes,\n * and a derived `new.target.name` ships as `error.name === \"t\"`.\n */\n\n/** Base class for every error this module throws. */\nexport class ImagingError extends Error {\n    constructor(message: string, options?: ErrorOptions) {\n        super(message, options);\n        this.name = \"ImagingError\";\n    }\n}\n\n/** The source could not be decoded into pixels. */\nexport class ImageDecodeError extends ImagingError {\n    constructor(message: string, options?: ErrorOptions) {\n        super(message, options);\n        this.name = \"ImageDecodeError\";\n    }\n}\n\n/** The canvas could not produce encoded bytes. */\nexport class ImageEncodeError extends ImagingError {\n    constructor(message: string, options?: ErrorOptions) {\n        super(message, options);\n        this.name = \"ImageEncodeError\";\n    }\n}\n\n/**\n * The browser cannot encode the requested format.\n *\n * Worth its own class because the failure is otherwise silent: asking a\n * canvas for an unsupported type does not throw — it hands back a PNG,\n * and an app that trusted the request ships 4 MB where it expected 300 KB.\n */\nexport class UnsupportedImageTypeError extends ImagingError {\n    constructor(message: string, options?: ErrorOptions) {\n        super(message, options);\n        this.name = \"UnsupportedImageTypeError\";\n    }\n}\n\n/**\n * The frame asked for never arrived.\n *\n * Its own class because the alternative is the failure this module refuses to\n * produce: a frame from the wrong instant. `seeked` firing does not mean the\n * frame for the new position is composited and readable, so a capture that\n * gave up waiting has to say so — a thumbnail of the neighbouring frame looks\n * exactly like a correct one, and nothing downstream can tell.\n */\nexport class FrameSeekError extends ImagingError {\n    constructor(message: string, options?: ErrorOptions) {\n        super(message, options);\n        this.name = \"FrameSeekError\";\n    }\n}\n\n/** The environment has no canvas to draw on. */\nexport class ImagingUnavailableError extends ImagingError {\n    constructor(message: string, options?: ErrorOptions) {\n        super(message, options);\n        this.name = \"ImagingUnavailableError\";\n    }\n}\n"],"mappings":"AAQA,IAAaA,EAAb,cAAkC,KAAM,CACpC,YAAY,EAAiB,EAAwB,CACjD,MAAMC,EAASC,CAAO,EACtB,KAAK,KAAO,cAChB,CACJ,EAGaC,EAAb,cAAsCH,CAAa,CAC/C,YAAY,EAAiB,EAAwB,CACjD,MAAMC,EAASC,CAAO,EACtB,KAAK,KAAO,kBAChB,CACJ,EAGaE,EAAb,cAAsCJ,CAAa,CAC/C,YAAY,EAAiB,EAAwB,CACjD,MAAMC,EAASC,CAAO,EACtB,KAAK,KAAO,kBAChB,CACJ,EASaG,EAAb,cAA+CL,CAAa,CACxD,YAAY,EAAiB,EAAwB,CACjD,MAAMC,EAASC,CAAO,EACtB,KAAK,KAAO,2BAChB,CACJ,EAWaI,EAAb,cAAoCN,CAAa,CAC7C,YAAY,EAAiB,EAAwB,CACjD,MAAMC,EAASC,CAAO,EACtB,KAAK,KAAO,gBAChB,CACJ,EAGaK,EAAb,cAA6CP,CAAa,CACtD,YAAY,EAAiB,EAAwB,CACjD,MAAMC,EAASC,CAAO,EACtB,KAAK,KAAO,yBAChB,CACJ,E"}

package/dist/imaging/exceptions.js.map

@@ -1 +1 @@
-{"version":3,"file":"exceptions.js","names":[],"sources":["../../src/imaging/exceptions.ts"],"sourcesContent":["/**\n * Errors thrown by the imaging module.\n *\n * `name` is a literal string on every subclass: minifiers rename classes,\n * and a derived `new.target.name` ships as `error.name === \"t\"`.\n */\n\n/** Base class for every error this module throws. */\nexport class ImagingError extends Error {\n    constructor(message: string, options?: ErrorOptions) {\n        super(message, options);\n        this.name = \"ImagingError\";\n    }\n}\n\n/** The source could not be decoded into pixels. */\nexport class ImageDecodeError extends ImagingError {\n    constructor(message: string, options?: ErrorOptions) {\n        super(message, options);\n        this.name = \"ImageDecodeError\";\n    }\n}\n\n/** The canvas could not produce encoded bytes. */\nexport class ImageEncodeError extends ImagingError {\n    constructor(message: string, options?: ErrorOptions) {\n        super(message, options);\n        this.name = \"ImageEncodeError\";\n    }\n}\n\n/**\n * The browser cannot encode the requested format.\n *\n * Worth its own class because the failure is otherwise silent: asking a\n * canvas for an unsupported type does not throw — it hands back a PNG,\n * and an app that trusted the request ships 4 MB where it expected 300 KB.\n */\nexport class UnsupportedImageTypeError extends ImagingError {\n    constructor(message: string, options?: ErrorOptions) {\n        super(message, options);\n        this.name = \"UnsupportedImageTypeError\";\n    }\n}\n\n/**\n * The frame asked for never arrived.\n *\n * Its own class because the alternative is the failure this module refuses to\n * produce: a frame from the wrong instant. `seeked` firing does not mean the\n * frame for the new position is composited and readable, so a capture that\n * gave up waiting has to say so — a thumbnail of the neighbouring frame looks\n * exactly like a correct one, and nothing downstream can tell.\n */\nexport class FrameSeekError extends ImagingError {\n    constructor(message: string, options?: ErrorOptions) {\n        super(message, options);\n        this.name = \"FrameSeekError\";\n    }\n}\n\n/** The environment has no canvas to draw on. */\nexport class ImagingUnavailableError extends ImagingError {\n    constructor(message: string, options?: ErrorOptions) {\n        super(message, options);\n        this.name = \"ImagingUnavailableError\";\n    }\n}\n"],"mappings":";AAQA,IAAa,IAAb,cAAkC,MAAM;CACpC,YAAY,GAAiB,GAAwB;EAEjD,AADA,MAAM,GAAS,CAAO,GACtB,KAAK,OAAO;CAChB;AACJ,GAGa,IAAb,cAAsC,EAAa;CAC/C,YAAY,GAAiB,GAAwB;EAEjD,AADA,MAAM,GAAS,CAAO,GACtB,KAAK,OAAO;CAChB;AACJ,GAGa,IAAb,cAAsC,EAAa;CAC/C,YAAY,GAAiB,GAAwB;EAEjD,AADA,MAAM,GAAS,CAAO,GACtB,KAAK,OAAO;CAChB;AACJ,GASa,IAAb,cAA+C,EAAa;CACxD,YAAY,GAAiB,GAAwB;EAEjD,AADA,MAAM,GAAS,CAAO,GACtB,KAAK,OAAO;CAChB;AACJ,GAWa,IAAb,cAAoC,EAAa;CAC7C,YAAY,GAAiB,GAAwB;EAEjD,AADA,MAAM,GAAS,CAAO,GACtB,KAAK,OAAO;CAChB;AACJ,GAGa,IAAb,cAA6C,EAAa;CACtD,YAAY,GAAiB,GAAwB;EAEjD,AADA,MAAM,GAAS,CAAO,GACtB,KAAK,OAAO;CAChB;AACJ"}
+{"version":3,"file":"exceptions.js","names":["ImagingError","message","options","ImageDecodeError","ImageEncodeError","UnsupportedImageTypeError","FrameSeekError","ImagingUnavailableError"],"sources":["../../src/imaging/exceptions.ts"],"sourcesContent":["/**\n * Errors thrown by the imaging module.\n *\n * `name` is a literal string on every subclass: minifiers rename classes,\n * and a derived `new.target.name` ships as `error.name === \"t\"`.\n */\n\n/** Base class for every error this module throws. */\nexport class ImagingError extends Error {\n    constructor(message: string, options?: ErrorOptions) {\n        super(message, options);\n        this.name = \"ImagingError\";\n    }\n}\n\n/** The source could not be decoded into pixels. */\nexport class ImageDecodeError extends ImagingError {\n    constructor(message: string, options?: ErrorOptions) {\n        super(message, options);\n        this.name = \"ImageDecodeError\";\n    }\n}\n\n/** The canvas could not produce encoded bytes. */\nexport class ImageEncodeError extends ImagingError {\n    constructor(message: string, options?: ErrorOptions) {\n        super(message, options);\n        this.name = \"ImageEncodeError\";\n    }\n}\n\n/**\n * The browser cannot encode the requested format.\n *\n * Worth its own class because the failure is otherwise silent: asking a\n * canvas for an unsupported type does not throw — it hands back a PNG,\n * and an app that trusted the request ships 4 MB where it expected 300 KB.\n */\nexport class UnsupportedImageTypeError extends ImagingError {\n    constructor(message: string, options?: ErrorOptions) {\n        super(message, options);\n        this.name = \"UnsupportedImageTypeError\";\n    }\n}\n\n/**\n * The frame asked for never arrived.\n *\n * Its own class because the alternative is the failure this module refuses to\n * produce: a frame from the wrong instant. `seeked` firing does not mean the\n * frame for the new position is composited and readable, so a capture that\n * gave up waiting has to say so — a thumbnail of the neighbouring frame looks\n * exactly like a correct one, and nothing downstream can tell.\n */\nexport class FrameSeekError extends ImagingError {\n    constructor(message: string, options?: ErrorOptions) {\n        super(message, options);\n        this.name = \"FrameSeekError\";\n    }\n}\n\n/** The environment has no canvas to draw on. */\nexport class ImagingUnavailableError extends ImagingError {\n    constructor(message: string, options?: ErrorOptions) {\n        super(message, options);\n        this.name = \"ImagingUnavailableError\";\n    }\n}\n"],"mappings":";AAQA,IAAaA,IAAb,cAAkC,MAAM;CACpC,YAAY,GAAiB,GAAwB;EAEjD,AADA,MAAMC,GAASC,CAAO,GACtB,KAAK,OAAO;CAChB;AACJ,GAGaC,IAAb,cAAsCH,EAAa;CAC/C,YAAY,GAAiB,GAAwB;EAEjD,AADA,MAAMC,GAASC,CAAO,GACtB,KAAK,OAAO;CAChB;AACJ,GAGaE,IAAb,cAAsCJ,EAAa;CAC/C,YAAY,GAAiB,GAAwB;EAEjD,AADA,MAAMC,GAASC,CAAO,GACtB,KAAK,OAAO;CAChB;AACJ,GASaG,IAAb,cAA+CL,EAAa;CACxD,YAAY,GAAiB,GAAwB;EAEjD,AADA,MAAMC,GAASC,CAAO,GACtB,KAAK,OAAO;CAChB;AACJ,GAWaI,IAAb,cAAoCN,EAAa;CAC7C,YAAY,GAAiB,GAAwB;EAEjD,AADA,MAAMC,GAASC,CAAO,GACtB,KAAK,OAAO;CAChB;AACJ,GAGaK,IAAb,cAA6CP,EAAa;CACtD,YAAY,GAAiB,GAAwB;EAEjD,AADA,MAAMC,GAASC,CAAO,GACtB,KAAK,OAAO;CAChB;AACJ"}

package/dist/imaging/frame.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"frame.cjs","names":[],"sources":["../../src/imaging/frame.ts"],"sourcesContent":["/**\n * Reading one frame out of a `<video>`, at the instant you asked for.\n *\n * The current frame needs nothing from this file: `createImageBitmap` takes a\n * video element, so `resizeImage(video)` already works. A **chosen** instant is\n * the part every app writes by hand and writes wrong:\n *\n * ```ts\n * video.currentTime = 12.5;\n * await new Promise((r) => video.addEventListener(\"seeked\", r, { once: true }));\n * ctx.drawImage(video, 0, 0);   // may draw the PREVIOUS frame\n * ```\n *\n * `seeked` says the seek finished, not that the frame for the new position is\n * composited and readable by `drawImage`. The symptom is the worst kind: it\n * works on the machine it was written on and produces the neighbouring frame\n * elsewhere, with no error and no log.\n *\n * `requestVideoFrameCallback` is the only signal that reports a frame having\n * been **presented** — and measuring it, 2026-09-04 in Chromium, settled how it\n * can be used here: it fires while the video **plays** and does **not** fire\n * for a seek on a paused element. So blocking a seek on it would stall every\n * capture for the whole timeout and then proceed anyway. Instead:\n *\n * - Capturing from a **playing** video waits for the next presented frame, so\n *   the pixels are demonstrably fresh. That is the screen-recording print.\n * - Capturing at an **instant** waits for `seeked` and then two animation\n *   frames, which is what a browser offers for a paused element.\n * - Capturing the current frame of a **paused** video waits for nothing: the\n *   frame on screen already is the frame.\n *\n * `confirmed` in the result says which of those happened, so a caller can tell\n * a demonstrably fresh frame from a best-effort one instead of guessing. A\n * seek-based capture reporting `confirmed: false` is the normal case, not a\n * warning sign.\n *\n * Three more traps come along for the ride:\n *\n * - **A recording may arrive with no duration.** `MediaRecorder` does not\n *   guarantee a duration in the WebM header, so the blob `useVideoRecorder`\n *   just handed you may report `Infinity` — and the video an app most wants to\n *   grab a frame from is exactly that one. Seeking past the end forces the\n *   browser to demux to the last frame, after which it knows the length; that\n *   probe runs here rather than in every caller. Chromium was measured writing\n *   the duration for a one-shot recording, so this is for the paths that omit\n *   it — chunked `timeslice` recording, and other engines.\n * - **A cross-origin video taints the canvas**, and the failure surfaces far\n *   from its cause, so it is re-thrown saying what to set.\n * - **Moving `currentTime` moves the player** somebody is watching; `restore`\n *   puts it back, and touches only what actually moved.\n */\n\nimport { FrameSeekError, ImageDecodeError } from \"./exceptions\";\nimport { resizeImage } from \"./transform\";\nimport type { CaptureFrameOptions, CapturedFrame } from \"./types\";\n\n/** How long a seek and the frame after it may take, in milliseconds. */\nexport const DEFAULT_FRAME_TIMEOUT_MS = 3000;\n\n/** `HTMLMediaElement.HAVE_CURRENT_DATA` — there are pixels for the current position. */\nconst HAVE_CURRENT_DATA = 2;\n\n/** Below this, in seconds, a seek to `currentTime` is a seek to where we already are. */\nconst SAME_FRAME_EPSILON = 0.001;\n\n/**\n * How long to wait for a presented frame, in milliseconds.\n *\n * Its own budget, not the caller's `timeoutMs`: this wait is an optimisation on\n * freshness, and a video playing at 24 fps presents one every 42 ms. Spending\n * seconds here would stall the capture for a guarantee the platform may simply\n * not be able to give.\n */\nconst FRAME_SETTLE_MS = 200;\n\n/**\n * A video element that reports presented frames.\n *\n * Declared structurally rather than by augmenting `HTMLVideoElement`: this is a\n * published package, and widening a lib interface would widen it for every\n * consumer, in every file, whether they load a polyfill or not.\n *\n * The two members are one capability. The spec defines them together, so a\n * runtime with `requestVideoFrameCallback` and no `cancelVideoFrameCallback`\n * does not exist — guarding the second separately would add a branch no test\n * can honestly reach.\n */\ntype FrameCallbackVideo = HTMLVideoElement & {\n    requestVideoFrameCallback: (callback: (now: number) => void) => number;\n    cancelVideoFrameCallback: (handle: number) => void;\n};\n\n/**\n * Whether this element reports presented frames.\n *\n * @param video The element to test.\n * @returns `true` when the frame callback pair is available.\n */\nfunction reportsFrames(video: HTMLVideoElement): video is FrameCallbackVideo {\n    return typeof (video as Partial<FrameCallbackVideo>).requestVideoFrameCallback === \"function\";\n}\n\n/** Seek target that forces a demux to the end, to learn an unknown duration. */\nconst PAST_THE_END_SECONDS = 1e101;\n\n/** The `AbortError` a caller's `signal` produces. */\nfunction abortError(): DOMException {\n    return new DOMException(\"The frame capture was aborted.\", \"AbortError\");\n}\n\n/**\n * Wait for one media event, and clean up on every exit.\n *\n * @param video The element to listen on.\n * @param type The event to wait for.\n * @param timeoutMs How long to wait.\n * @param signal Optional abort signal.\n * @param whenLate Message for the {@link FrameSeekError} on timeout.\n * @returns Resolves when the event fires.\n * @throws {@link FrameSeekError} when the timeout is reached.\n */\nfunction onceEvent(\n    video: HTMLVideoElement,\n    type: string,\n    timeoutMs: number,\n    signal: AbortSignal | undefined,\n    whenLate: string,\n): Promise<void> {\n    return new Promise<void>((resolve, reject) => {\n        const finish = (settle: () => void): void => {\n            clearTimeout(timer);\n            video.removeEventListener(type, onEvent);\n            signal?.removeEventListener(\"abort\", onAbort);\n            settle();\n        };\n        const onEvent = (): void => finish(resolve);\n        const onAbort = (): void => finish(() => reject(abortError()));\n\n        const timer = setTimeout(\n            () => finish(() => reject(new FrameSeekError(whenLate))),\n            timeoutMs,\n        );\n        video.addEventListener(type, onEvent);\n        signal?.addEventListener(\"abort\", onAbort);\n    });\n}\n\n/**\n * Wait for the next frame the compositor presents.\n *\n * Only ever called for a **playing** element, because that is the only state in\n * which the callback fires — measured, not assumed. The timeout is the escape\n * for a hidden tab, which presents nothing at all.\n *\n * @param video A playing element that reports presented frames.\n * @returns `true` when a frame was presented, `false` when the wait expired.\n */\nfunction nextPresentedFrame(video: FrameCallbackVideo): Promise<boolean> {\n    return new Promise<boolean>((resolve) => {\n        const timer = setTimeout(() => {\n            video.cancelVideoFrameCallback(handle);\n            resolve(false);\n        }, FRAME_SETTLE_MS);\n        const handle = video.requestVideoFrameCallback(() => {\n            clearTimeout(timer);\n            resolve(true);\n        });\n    });\n}\n\n/**\n * Let the compositor catch up after a seek on a paused element.\n *\n * Two animation frames is what a browser offers here: the frame callback does\n * not fire for a paused seek, so there is nothing to confirm against. A runtime\n * with no animation frames at all gets a macrotask — enough for a test\n * environment, not a promise about pixels.\n *\n * @returns Resolves once the wait is over. Never a confirmation.\n */\nfunction settleAfterSeek(): Promise<void> {\n    if (typeof requestAnimationFrame === \"function\") {\n        return new Promise<void>((resolve) => {\n            requestAnimationFrame(() => requestAnimationFrame(() => resolve()));\n        });\n    }\n    return new Promise<void>((resolve) => setTimeout(resolve, 0));\n}\n\n/**\n * Wait for the freshest frame this element's state allows, and say which.\n *\n * @param video The element about to be read.\n * @param seeked Whether a seek just moved it.\n * @returns `true` when a presented frame was observed.\n */\nasync function awaitReadableFrame(video: HTMLVideoElement, seeked: boolean): Promise<boolean> {\n    if (!video.paused && reportsFrames(video)) return await nextPresentedFrame(video);\n    if (seeked) await settleAfterSeek();\n    return false;\n}\n\n/**\n * Whether the element is fed by a live stream rather than by a file.\n *\n * A truthiness check rather than `!== null`: the property is absent in\n * environments that model only part of `HTMLMediaElement`, where comparing\n * against `null` would read every element as live.\n *\n * @param video The element to test.\n * @returns `true` when a `MediaStream` is playing into it.\n */\nfunction isLiveStream(video: HTMLVideoElement): boolean {\n    return Boolean(video.srcObject);\n}\n\n/**\n * The video's length in seconds, probing for it when the header lacks one.\n *\n * `MediaRecorder` does not guarantee a duration in the WebM it produces, so a\n * recording can report `Infinity` until something forces the browser to demux\n * to the end. That is what the seek past the end does — the same hack the\n * `AudioPlayer` uses, for the same reason: the value is not in the file.\n *\n * @param video The element to measure.\n * @param timeoutMs How long the probe may take.\n * @param signal Optional abort signal.\n * @returns The duration in seconds.\n * @throws {@link FrameSeekError} when the element is a live stream, or the\n *   probe produced no duration.\n */\nasync function resolveDuration(\n    video: HTMLVideoElement,\n    timeoutMs: number,\n    signal: AbortSignal | undefined,\n): Promise<number> {\n    if (Number.isFinite(video.duration)) return video.duration;\n\n    if (isLiveStream(video)) {\n        throw new FrameSeekError(\n            \"This element is playing a live MediaStream, which has no timeline to seek: \" +\n                \"there is no instant but now. Leave `atMs` out to capture the frame on screen.\",\n        );\n    }\n\n    const probed = onceEvent(\n        video,\n        \"timeupdate\",\n        timeoutMs,\n        signal,\n        `The video reported no duration and the probe for it did not answer within ` +\n            `${timeoutMs}ms, so there is no timeline to seek on.`,\n    );\n    video.currentTime = PAST_THE_END_SECONDS;\n    await probed;\n\n    if (!Number.isFinite(video.duration)) {\n        throw new FrameSeekError(\n            \"This video still reports no duration after seeking past its end, so it has \" +\n                \"no seekable timeline — a live HLS or DASH source behaves this way. Leave \" +\n                \"`atMs` out to capture the frame on screen.\",\n        );\n    }\n    return video.duration;\n}\n\n/**\n * Move the video to an instant, and wait for that instant's frame.\n *\n * @param video The element to move.\n * @param atMs The instant, in milliseconds. Clamped to the duration.\n * @param timeoutMs How long the seek and the frame may take.\n * @param signal Optional abort signal.\n * @returns Whether a presented frame confirmed the new position.\n * @throws {@link FrameSeekError} when the video has no seekable timeline, or\n *   the seek did not land in time.\n */\nasync function seekTo(\n    video: HTMLVideoElement,\n    atMs: number,\n    timeoutMs: number,\n    signal: AbortSignal | undefined,\n): Promise<boolean> {\n    const duration = await resolveDuration(video, timeoutMs, signal);\n\n    const target = Math.min(Math.max(atMs / 1000, 0), duration);\n    if (Math.abs(video.currentTime - target) < SAME_FRAME_EPSILON) {\n        return await awaitReadableFrame(video, false);\n    }\n\n    const seeked = onceEvent(\n        video,\n        \"seeked\",\n        timeoutMs,\n        signal,\n        `The video did not finish seeking to ${target.toFixed(3)}s within ${timeoutMs}ms. ` +\n            \"Nothing was captured: a frame from the wrong instant is indistinguishable \" +\n            \"from a correct one downstream.\",\n    );\n    video.currentTime = target;\n    await seeked;\n    return await awaitReadableFrame(video, true);\n}\n\n/**\n * Re-throw a tainted-canvas failure saying what to fix.\n *\n * A cross-origin video without `crossOrigin` taints everything it is drawn\n * into, and the `SecurityError` then arrives from the encoder — one call away\n * from the element that caused it, wrapped in whatever the decode said.\n *\n * @param error What the imaging pipeline threw.\n * @returns The error to throw instead.\n */\nfunction explained(error: unknown): unknown {\n    const names = [error, (error as { cause?: unknown } | null)?.cause].map((candidate) =>\n        typeof candidate === \"object\" && candidate !== null && \"name\" in candidate\n            ? String((candidate as { name: unknown }).name)\n            : \"\",\n    );\n    if (!names.includes(\"SecurityError\")) return error;\n    return new ImageDecodeError(\n        \"The video is cross-origin, so reading its pixels is not allowed. Set \" +\n            'crossOrigin=\"anonymous\" on the element before the source loads, and serve the ' +\n            \"video with a permissive Access-Control-Allow-Origin.\",\n        { cause: error },\n    );\n}\n\n/**\n * Put playback back where the capture found it, touching only what moved.\n *\n * Each half is guarded because writing `currentTime` **is** a seek, even when\n * the value is unchanged: a capture that was refused before it moved anything\n * — a live stream, an abort — would otherwise perturb the player it never\n * touched. And a capture that paused without needing to move still has to let\n * go of the pause.\n *\n * @param video The element to restore.\n * @param time Where `currentTime` was.\n * @param wasPlaying Whether it was playing before the capture paused it.\n */\nfunction restorePlayback(video: HTMLVideoElement, time: number, wasPlaying: boolean): void {\n    if (video.currentTime !== time) video.currentTime = time;\n    if (wasPlaying && video.paused) void Promise.resolve(video.play()).catch(() => undefined);\n}\n\n/**\n * Capture a frame from a video as encoded image bytes.\n *\n * Without `atMs` it reads the frame on screen, which is what a screen or camera\n * recording wants — a print of what is being recorded. With `atMs` it seeks,\n * waits for that instant's frame to be presented, captures, and puts the player\n * back.\n *\n * @example Print of a screen recording in progress\n * ```ts\n * const shot = await captureFrame(videoRef.current!, {\n *     type: \"image/webp\",\n *     quality: 0.9,\n * });\n * await shareOrDownloadBlob(shot.blob, \"print.webp\");\n * ```\n *\n * @example A poster from ten seconds in, scaled down\n * ```ts\n * const poster = await captureFrame(video, { atMs: 10_000, width: 640 });\n * setPosterUrl(URL.createObjectURL(poster.blob));\n * console.log(`landed on ${poster.atMs}ms`);\n * ```\n *\n * @param video The element to read. It needs data — the capture waits for\n *   `loadeddata` when the element has none yet.\n * @param options Instant, output box, format, and how long to wait.\n * @returns The encoded frame, the instant it actually came from, and whether a\n *   presented frame confirmed that instant.\n * @throws {@link FrameSeekError} when the video has no data or no timeline in\n *   time, or the seek did not land.\n * @throws {@link ImageDecodeError} when the pixels cannot be read — a\n *   cross-origin video without `crossOrigin` is the common one.\n * @throws {@link ImageEncodeError} when the canvas produces no bytes.\n */\nexport async function captureFrame(\n    video: HTMLVideoElement,\n    options: CaptureFrameOptions = {},\n): Promise<CapturedFrame> {\n    const timeoutMs = options.timeoutMs ?? DEFAULT_FRAME_TIMEOUT_MS;\n    if (options.signal?.aborted === true) throw abortError();\n\n    if (video.readyState < HAVE_CURRENT_DATA) {\n        await onceEvent(\n            video,\n            \"loadeddata\",\n            timeoutMs,\n            options.signal,\n            `The video had no frame to read within ${timeoutMs}ms (readyState ` +\n                `${video.readyState}). Give it a source, or wait for it yourself.`,\n        );\n    }\n\n    const { atMs: requestedMs } = options;\n    const previousTime = video.currentTime;\n    const wasPlaying = !video.paused;\n\n    try {\n        let confirmed: boolean;\n        if (requestedMs === undefined) {\n            confirmed = await awaitReadableFrame(video, false);\n        } else {\n            if (wasPlaying) video.pause();\n            confirmed = await seekTo(video, requestedMs, timeoutMs, options.signal);\n        }\n\n        const atMs = video.currentTime * 1000;\n        const encoded = await resizeImage(video, options);\n        return { ...encoded, atMs, confirmed };\n    } catch (error) {\n        throw explained(error);\n    } finally {\n        if (options.restore !== false) restorePlayback(video, previousTime, wasPlaying);\n    }\n}\n"],"mappings":"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"}
+{"version":3,"file":"frame.cjs","names":["FrameSeekError","ImageDecodeError","resizeImage","require_exceptions","require_transform","DEFAULT_FRAME_TIMEOUT_MS","HAVE_CURRENT_DATA","SAME_FRAME_EPSILON","FRAME_SETTLE_MS","reportsFrames","video","PAST_THE_END_SECONDS","abortError","onceEvent","finish","timer","type","onEvent","signal","onAbort","settle","resolve","reject","whenLate","timeoutMs","nextPresentedFrame","handle","settleAfterSeek","awaitReadableFrame","seeked","isLiveStream","resolveDuration","probed","seekTo","duration","target","atMs","explained","error","candidate","restorePlayback","time","wasPlaying","captureFrame","options","requestedMs","previousTime","confirmed"],"sources":["../../src/imaging/frame.ts"],"sourcesContent":["/**\n * Reading one frame out of a `<video>`, at the instant you asked for.\n *\n * The current frame needs nothing from this file: `createImageBitmap` takes a\n * video element, so `resizeImage(video)` already works. A **chosen** instant is\n * the part every app writes by hand and writes wrong:\n *\n * ```ts\n * video.currentTime = 12.5;\n * await new Promise((r) => video.addEventListener(\"seeked\", r, { once: true }));\n * ctx.drawImage(video, 0, 0);   // may draw the PREVIOUS frame\n * ```\n *\n * `seeked` says the seek finished, not that the frame for the new position is\n * composited and readable by `drawImage`. The symptom is the worst kind: it\n * works on the machine it was written on and produces the neighbouring frame\n * elsewhere, with no error and no log.\n *\n * `requestVideoFrameCallback` is the only signal that reports a frame having\n * been **presented** — and measuring it, 2026-09-04 in Chromium, settled how it\n * can be used here: it fires while the video **plays** and does **not** fire\n * for a seek on a paused element. So blocking a seek on it would stall every\n * capture for the whole timeout and then proceed anyway. Instead:\n *\n * - Capturing from a **playing** video waits for the next presented frame, so\n *   the pixels are demonstrably fresh. That is the screen-recording print.\n * - Capturing at an **instant** waits for `seeked` and then two animation\n *   frames, which is what a browser offers for a paused element.\n * - Capturing the current frame of a **paused** video waits for nothing: the\n *   frame on screen already is the frame.\n *\n * `confirmed` in the result says which of those happened, so a caller can tell\n * a demonstrably fresh frame from a best-effort one instead of guessing. A\n * seek-based capture reporting `confirmed: false` is the normal case, not a\n * warning sign.\n *\n * Three more traps come along for the ride:\n *\n * - **A recording may arrive with no duration.** `MediaRecorder` does not\n *   guarantee a duration in the WebM header, so the blob `useVideoRecorder`\n *   just handed you may report `Infinity` — and the video an app most wants to\n *   grab a frame from is exactly that one. Seeking past the end forces the\n *   browser to demux to the last frame, after which it knows the length; that\n *   probe runs here rather than in every caller. Chromium was measured writing\n *   the duration for a one-shot recording, so this is for the paths that omit\n *   it — chunked `timeslice` recording, and other engines.\n * - **A cross-origin video taints the canvas**, and the failure surfaces far\n *   from its cause, so it is re-thrown saying what to set.\n * - **Moving `currentTime` moves the player** somebody is watching; `restore`\n *   puts it back, and touches only what actually moved.\n */\n\nimport { FrameSeekError, ImageDecodeError } from \"./exceptions\";\nimport { resizeImage } from \"./transform\";\nimport type { CaptureFrameOptions, CapturedFrame } from \"./types\";\n\n/** How long a seek and the frame after it may take, in milliseconds. */\nexport const DEFAULT_FRAME_TIMEOUT_MS = 3000;\n\n/** `HTMLMediaElement.HAVE_CURRENT_DATA` — there are pixels for the current position. */\nconst HAVE_CURRENT_DATA = 2;\n\n/** Below this, in seconds, a seek to `currentTime` is a seek to where we already are. */\nconst SAME_FRAME_EPSILON = 0.001;\n\n/**\n * How long to wait for a presented frame, in milliseconds.\n *\n * Its own budget, not the caller's `timeoutMs`: this wait is an optimisation on\n * freshness, and a video playing at 24 fps presents one every 42 ms. Spending\n * seconds here would stall the capture for a guarantee the platform may simply\n * not be able to give.\n */\nconst FRAME_SETTLE_MS = 200;\n\n/**\n * A video element that reports presented frames.\n *\n * Declared structurally rather than by augmenting `HTMLVideoElement`: this is a\n * published package, and widening a lib interface would widen it for every\n * consumer, in every file, whether they load a polyfill or not.\n *\n * The two members are one capability. The spec defines them together, so a\n * runtime with `requestVideoFrameCallback` and no `cancelVideoFrameCallback`\n * does not exist — guarding the second separately would add a branch no test\n * can honestly reach.\n */\ntype FrameCallbackVideo = HTMLVideoElement & {\n    requestVideoFrameCallback: (callback: (now: number) => void) => number;\n    cancelVideoFrameCallback: (handle: number) => void;\n};\n\n/**\n * Whether this element reports presented frames.\n *\n * @param video The element to test.\n * @returns `true` when the frame callback pair is available.\n */\nfunction reportsFrames(video: HTMLVideoElement): video is FrameCallbackVideo {\n    return typeof (video as Partial<FrameCallbackVideo>).requestVideoFrameCallback === \"function\";\n}\n\n/** Seek target that forces a demux to the end, to learn an unknown duration. */\nconst PAST_THE_END_SECONDS = 1e101;\n\n/** The `AbortError` a caller's `signal` produces. */\nfunction abortError(): DOMException {\n    return new DOMException(\"The frame capture was aborted.\", \"AbortError\");\n}\n\n/**\n * Wait for one media event, and clean up on every exit.\n *\n * @param video The element to listen on.\n * @param type The event to wait for.\n * @param timeoutMs How long to wait.\n * @param signal Optional abort signal.\n * @param whenLate Message for the {@link FrameSeekError} on timeout.\n * @returns Resolves when the event fires.\n * @throws {@link FrameSeekError} when the timeout is reached.\n */\nfunction onceEvent(\n    video: HTMLVideoElement,\n    type: string,\n    timeoutMs: number,\n    signal: AbortSignal | undefined,\n    whenLate: string,\n): Promise<void> {\n    return new Promise<void>((resolve, reject) => {\n        const finish = (settle: () => void): void => {\n            clearTimeout(timer);\n            video.removeEventListener(type, onEvent);\n            signal?.removeEventListener(\"abort\", onAbort);\n            settle();\n        };\n        const onEvent = (): void => finish(resolve);\n        const onAbort = (): void => finish(() => reject(abortError()));\n\n        const timer = setTimeout(\n            () => finish(() => reject(new FrameSeekError(whenLate))),\n            timeoutMs,\n        );\n        video.addEventListener(type, onEvent);\n        signal?.addEventListener(\"abort\", onAbort);\n    });\n}\n\n/**\n * Wait for the next frame the compositor presents.\n *\n * Only ever called for a **playing** element, because that is the only state in\n * which the callback fires — measured, not assumed. The timeout is the escape\n * for a hidden tab, which presents nothing at all.\n *\n * @param video A playing element that reports presented frames.\n * @returns `true` when a frame was presented, `false` when the wait expired.\n */\nfunction nextPresentedFrame(video: FrameCallbackVideo): Promise<boolean> {\n    return new Promise<boolean>((resolve) => {\n        const timer = setTimeout(() => {\n            video.cancelVideoFrameCallback(handle);\n            resolve(false);\n        }, FRAME_SETTLE_MS);\n        const handle = video.requestVideoFrameCallback(() => {\n            clearTimeout(timer);\n            resolve(true);\n        });\n    });\n}\n\n/**\n * Let the compositor catch up after a seek on a paused element.\n *\n * Two animation frames is what a browser offers here: the frame callback does\n * not fire for a paused seek, so there is nothing to confirm against. A runtime\n * with no animation frames at all gets a macrotask — enough for a test\n * environment, not a promise about pixels.\n *\n * @returns Resolves once the wait is over. Never a confirmation.\n */\nfunction settleAfterSeek(): Promise<void> {\n    if (typeof requestAnimationFrame === \"function\") {\n        return new Promise<void>((resolve) => {\n            requestAnimationFrame(() => requestAnimationFrame(() => resolve()));\n        });\n    }\n    return new Promise<void>((resolve) => setTimeout(resolve, 0));\n}\n\n/**\n * Wait for the freshest frame this element's state allows, and say which.\n *\n * @param video The element about to be read.\n * @param seeked Whether a seek just moved it.\n * @returns `true` when a presented frame was observed.\n */\nasync function awaitReadableFrame(video: HTMLVideoElement, seeked: boolean): Promise<boolean> {\n    if (!video.paused && reportsFrames(video)) return await nextPresentedFrame(video);\n    if (seeked) await settleAfterSeek();\n    return false;\n}\n\n/**\n * Whether the element is fed by a live stream rather than by a file.\n *\n * A truthiness check rather than `!== null`: the property is absent in\n * environments that model only part of `HTMLMediaElement`, where comparing\n * against `null` would read every element as live.\n *\n * @param video The element to test.\n * @returns `true` when a `MediaStream` is playing into it.\n */\nfunction isLiveStream(video: HTMLVideoElement): boolean {\n    return Boolean(video.srcObject);\n}\n\n/**\n * The video's length in seconds, probing for it when the header lacks one.\n *\n * `MediaRecorder` does not guarantee a duration in the WebM it produces, so a\n * recording can report `Infinity` until something forces the browser to demux\n * to the end. That is what the seek past the end does — the same hack the\n * `AudioPlayer` uses, for the same reason: the value is not in the file.\n *\n * @param video The element to measure.\n * @param timeoutMs How long the probe may take.\n * @param signal Optional abort signal.\n * @returns The duration in seconds.\n * @throws {@link FrameSeekError} when the element is a live stream, or the\n *   probe produced no duration.\n */\nasync function resolveDuration(\n    video: HTMLVideoElement,\n    timeoutMs: number,\n    signal: AbortSignal | undefined,\n): Promise<number> {\n    if (Number.isFinite(video.duration)) return video.duration;\n\n    if (isLiveStream(video)) {\n        throw new FrameSeekError(\n            \"This element is playing a live MediaStream, which has no timeline to seek: \" +\n                \"there is no instant but now. Leave `atMs` out to capture the frame on screen.\",\n        );\n    }\n\n    const probed = onceEvent(\n        video,\n        \"timeupdate\",\n        timeoutMs,\n        signal,\n        `The video reported no duration and the probe for it did not answer within ` +\n            `${timeoutMs}ms, so there is no timeline to seek on.`,\n    );\n    video.currentTime = PAST_THE_END_SECONDS;\n    await probed;\n\n    if (!Number.isFinite(video.duration)) {\n        throw new FrameSeekError(\n            \"This video still reports no duration after seeking past its end, so it has \" +\n                \"no seekable timeline — a live HLS or DASH source behaves this way. Leave \" +\n                \"`atMs` out to capture the frame on screen.\",\n        );\n    }\n    return video.duration;\n}\n\n/**\n * Move the video to an instant, and wait for that instant's frame.\n *\n * @param video The element to move.\n * @param atMs The instant, in milliseconds. Clamped to the duration.\n * @param timeoutMs How long the seek and the frame may take.\n * @param signal Optional abort signal.\n * @returns Whether a presented frame confirmed the new position.\n * @throws {@link FrameSeekError} when the video has no seekable timeline, or\n *   the seek did not land in time.\n */\nasync function seekTo(\n    video: HTMLVideoElement,\n    atMs: number,\n    timeoutMs: number,\n    signal: AbortSignal | undefined,\n): Promise<boolean> {\n    const duration = await resolveDuration(video, timeoutMs, signal);\n\n    const target = Math.min(Math.max(atMs / 1000, 0), duration);\n    if (Math.abs(video.currentTime - target) < SAME_FRAME_EPSILON) {\n        return await awaitReadableFrame(video, false);\n    }\n\n    const seeked = onceEvent(\n        video,\n        \"seeked\",\n        timeoutMs,\n        signal,\n        `The video did not finish seeking to ${target.toFixed(3)}s within ${timeoutMs}ms. ` +\n            \"Nothing was captured: a frame from the wrong instant is indistinguishable \" +\n            \"from a correct one downstream.\",\n    );\n    video.currentTime = target;\n    await seeked;\n    return await awaitReadableFrame(video, true);\n}\n\n/**\n * Re-throw a tainted-canvas failure saying what to fix.\n *\n * A cross-origin video without `crossOrigin` taints everything it is drawn\n * into, and the `SecurityError` then arrives from the encoder — one call away\n * from the element that caused it, wrapped in whatever the decode said.\n *\n * @param error What the imaging pipeline threw.\n * @returns The error to throw instead.\n */\nfunction explained(error: unknown): unknown {\n    const names = [error, (error as { cause?: unknown } | null)?.cause].map((candidate) =>\n        typeof candidate === \"object\" && candidate !== null && \"name\" in candidate\n            ? String((candidate as { name: unknown }).name)\n            : \"\",\n    );\n    if (!names.includes(\"SecurityError\")) return error;\n    return new ImageDecodeError(\n        \"The video is cross-origin, so reading its pixels is not allowed. Set \" +\n            'crossOrigin=\"anonymous\" on the element before the source loads, and serve the ' +\n            \"video with a permissive Access-Control-Allow-Origin.\",\n        { cause: error },\n    );\n}\n\n/**\n * Put playback back where the capture found it, touching only what moved.\n *\n * Each half is guarded because writing `currentTime` **is** a seek, even when\n * the value is unchanged: a capture that was refused before it moved anything\n * — a live stream, an abort — would otherwise perturb the player it never\n * touched. And a capture that paused without needing to move still has to let\n * go of the pause.\n *\n * @param video The element to restore.\n * @param time Where `currentTime` was.\n * @param wasPlaying Whether it was playing before the capture paused it.\n */\nfunction restorePlayback(video: HTMLVideoElement, time: number, wasPlaying: boolean): void {\n    if (video.currentTime !== time) video.currentTime = time;\n    if (wasPlaying && video.paused) void Promise.resolve(video.play()).catch(() => undefined);\n}\n\n/**\n * Capture a frame from a video as encoded image bytes.\n *\n * Without `atMs` it reads the frame on screen, which is what a screen or camera\n * recording wants — a print of what is being recorded. With `atMs` it seeks,\n * waits for that instant's frame to be presented, captures, and puts the player\n * back.\n *\n * @example Print of a screen recording in progress\n * ```ts\n * const shot = await captureFrame(videoRef.current!, {\n *     type: \"image/webp\",\n *     quality: 0.9,\n * });\n * await shareOrDownloadBlob(shot.blob, \"print.webp\");\n * ```\n *\n * @example A poster from ten seconds in, scaled down\n * ```ts\n * const poster = await captureFrame(video, { atMs: 10_000, width: 640 });\n * setPosterUrl(URL.createObjectURL(poster.blob));\n * console.log(`landed on ${poster.atMs}ms`);\n * ```\n *\n * @param video The element to read. It needs data — the capture waits for\n *   `loadeddata` when the element has none yet.\n * @param options Instant, output box, format, and how long to wait.\n * @returns The encoded frame, the instant it actually came from, and whether a\n *   presented frame confirmed that instant.\n * @throws {@link FrameSeekError} when the video has no data or no timeline in\n *   time, or the seek did not land.\n * @throws {@link ImageDecodeError} when the pixels cannot be read — a\n *   cross-origin video without `crossOrigin` is the common one.\n * @throws {@link ImageEncodeError} when the canvas produces no bytes.\n */\nexport async function captureFrame(\n    video: HTMLVideoElement,\n    options: CaptureFrameOptions = {},\n): Promise<CapturedFrame> {\n    const timeoutMs = options.timeoutMs ?? DEFAULT_FRAME_TIMEOUT_MS;\n    if (options.signal?.aborted === true) throw abortError();\n\n    if (video.readyState < HAVE_CURRENT_DATA) {\n        await onceEvent(\n            video,\n            \"loadeddata\",\n            timeoutMs,\n            options.signal,\n            `The video had no frame to read within ${timeoutMs}ms (readyState ` +\n                `${video.readyState}). Give it a source, or wait for it yourself.`,\n        );\n    }\n\n    const { atMs: requestedMs } = options;\n    const previousTime = video.currentTime;\n    const wasPlaying = !video.paused;\n\n    try {\n        let confirmed: boolean;\n        if (requestedMs === undefined) {\n            confirmed = await awaitReadableFrame(video, false);\n        } else {\n            if (wasPlaying) video.pause();\n            confirmed = await seekTo(video, requestedMs, timeoutMs, options.signal);\n        }\n\n        const atMs = video.currentTime * 1000;\n        const encoded = await resizeImage(video, options);\n        return { ...encoded, atMs, confirmed };\n    } catch (error) {\n        throw explained(error);\n    } finally {\n        if (options.restore !== false) restorePlayback(video, previousTime, wasPlaying);\n    }\n}\n"],"mappings":"A,iEAyDA,IAAaK,EAA2B,IAGlCC,EAAoB,EAGpBC,EAAqB,KAUrBC,EAAkB,IAyBxB,SAASC,EAAc,EAAsD,CACzE,OAAO,OAAQC,EAAsC,2BAA8B,UACvF,CAGA,IAAMC,EAAuB,MAG7B,SAASC,GAA2B,CAChC,OAAO,IAAI,aAAa,iCAAkC,YAAY,CAC1E,CAaA,SAASC,EACL,EACA,EACA,EACA,EACA,EACa,CACb,OAAO,IAAI,SAAe,EAAS,IAAW,CAC1C,IAAMC,EAAU,GAA6B,CACzC,aAAaC,CAAK,EAClBL,EAAM,oBAAoBM,EAAMC,CAAO,EACvCC,GAAQ,oBAAoB,QAASC,CAAO,EAC5CC,EAAO,CACX,EACMH,MAAsBH,EAAOO,CAAO,EACpCF,MAAsBL,MAAaQ,EAAOV,EAAW,CAAC,CAAC,EAEvDG,EAAQ,eACJD,MAAaQ,EAAO,IAAItB,EAAAA,eAAeuB,CAAQ,CAAC,CAAC,EACvDC,CACJ,EACAd,EAAM,iBAAiBM,EAAMC,CAAO,EACpCC,GAAQ,iBAAiB,QAASC,CAAO,CAC7C,CAAC,CACL,CAYA,SAASM,EAAmB,EAA6C,CACrE,OAAO,IAAI,QAAkB,GAAY,CACrC,IAAMV,EAAQ,eAAiB,CAC3BL,EAAM,yBAAyBgB,CAAM,EACrCL,EAAQ,EAAK,CACjB,EAAGb,CAAe,EACZkB,EAAShB,EAAM,8BAAgC,CACjD,aAAaK,CAAK,EAClBM,EAAQ,EAAI,CAChB,CAAC,CACL,CAAC,CACL,CAYA,SAASM,GAAiC,CAMtC,OALI,OAAO,uBAA0B,WAC1B,IAAI,QAAe,GAAY,CAClC,0BAA4B,0BAA4BN,EAAQ,CAAC,CAAC,CACtE,CAAC,EAEE,IAAI,QAAe,GAAY,WAAWA,EAAS,CAAC,CAAC,CAChE,CASA,eAAeO,EAAmB,EAAyB,EAAmC,CAG1F,MAFI,CAAClB,EAAM,QAAUD,EAAcC,CAAK,EAAU,MAAMe,EAAmBf,CAAK,GAC5EmB,GAAQ,MAAMF,EAAgB,EAC3B,GACX,CAYA,SAASG,EAAa,EAAkC,CACpD,MAAO,EAAQpB,EAAM,SACzB,CAiBA,eAAeqB,EACX,EACA,EACA,EACe,CACf,GAAI,OAAO,SAASrB,EAAM,QAAQ,EAAG,OAAOA,EAAM,SAElD,GAAIoB,EAAapB,CAAK,EAClB,MAAM,IAAIV,EAAAA,eACN,0JAEJ,EAGJ,IAAMgC,EAASnB,EACXH,EACA,aACAc,EACAN,EACA,6EACOM,EAAU,wCACrB,EAIA,GAHA,EAAM,YAAcb,EACpB,MAAMqB,EAEF,CAAC,OAAO,SAAStB,EAAM,QAAQ,EAC/B,MAAM,IAAIV,EAAAA,eACN,gMAGJ,EAEJ,OAAOU,EAAM,QACjB,CAaA,eAAeuB,EACX,EACA,EACA,EACA,EACgB,CAChB,IAAMC,EAAW,MAAMH,EAAgBrB,EAAOc,EAAWN,CAAM,EAEzDiB,EAAS,KAAK,IAAI,KAAK,IAAIC,EAAO,IAAM,CAAC,EAAGF,CAAQ,EAC1D,GAAI,KAAK,IAAIxB,EAAM,YAAcyB,CAAM,EAAI5B,EACvC,OAAO,MAAMqB,EAAmBlB,EAAO,EAAK,EAGhD,IAAMmB,EAAShB,EACXH,EACA,SACAc,EACAN,EACA,uCAAuCiB,EAAO,QAAQ,CAAC,EAAE,WAAWX,EAAU,6GAGlF,EAGA,MAFA,GAAM,YAAcW,EACpB,MAAMN,EACC,MAAMD,EAAmBlB,EAAO,EAAI,CAC/C,CAYA,SAAS2B,EAAU,EAAyB,CAOxC,MANc,CAACC,EAAQA,GAAsC,KAAK,CAAC,CAAC,IAAK,GACrE,OAAOC,GAAc,UAAYA,GAAsB,SAAUA,EAC3D,OAAQA,EAAgC,IAAI,EAC5C,EAEL,CAAA,CAAM,SAAS,eAAe,EAC5B,IAAItC,EAAAA,iBACP,0MAGA,CAAE,MAAOqC,CAAM,CACnB,EAN6CA,CAOjD,CAeA,SAASE,EAAgB,EAAyB,EAAc,EAA2B,CACnF9B,EAAM,cAAgB+B,IAAM,EAAM,YAAcA,GAChDC,GAAchC,EAAM,QAAQ,QAAa,QAAQA,EAAM,KAAK,CAAC,CAAC,CAAC,UAAY,IAAA,EAAS,CAC5F,CAqCA,eAAsBiC,EAClB,EACA,EAA+B,CAAC,EACV,CACtB,IAAMnB,EAAYoB,EAAQ,WAAA,IAC1B,GAAIA,EAAQ,QAAQ,UAAY,GAAM,MAAMhC,EAAW,EAEnDF,EAAM,WAAaJ,GACnB,MAAMO,EACFH,EACA,aACAc,EACAoB,EAAQ,OACR,yCAAyCpB,EAAU,iBAC5Cd,EAAM,WAAW,8CAC5B,EAGJ,GAAM,CAAE,KAAMmC,GAAgBD,EACxBE,EAAepC,EAAM,YACrBgC,EAAa,CAAChC,EAAM,OAE1B,GAAI,CACA,IAAIqC,EACAF,IAAgB,IAAA,GAChB,EAAY,MAAMjB,EAAmBlB,EAAO,EAAK,GAE7CgC,GAAYhC,EAAM,MAAM,EAC5B,EAAY,MAAMuB,EAAOvB,EAAOmC,EAAarB,EAAWoB,EAAQ,MAAM,GAG1E,IAAMR,EAAO1B,EAAM,YAAc,IAEjC,MAAO,CAAE,GAAG,MADUR,EAAAA,YAAYQ,EAAOkC,CAAO,EAC3B,OAAM,WAAU,CACzC,OAASN,EAAO,CACZ,MAAMD,EAAUC,CAAK,CACzB,QAAU,CACFM,EAAQ,UAAY,IAAOJ,EAAgB9B,EAAOoC,EAAcJ,CAAU,CAClF,CACJ,C"}

package/dist/imaging/frame.js.map

@@ -1 +1 @@
-{"version":3,"file":"frame.js","names":[],"sources":["../../src/imaging/frame.ts"],"sourcesContent":["/**\n * Reading one frame out of a `<video>`, at the instant you asked for.\n *\n * The current frame needs nothing from this file: `createImageBitmap` takes a\n * video element, so `resizeImage(video)` already works. A **chosen** instant is\n * the part every app writes by hand and writes wrong:\n *\n * ```ts\n * video.currentTime = 12.5;\n * await new Promise((r) => video.addEventListener(\"seeked\", r, { once: true }));\n * ctx.drawImage(video, 0, 0);   // may draw the PREVIOUS frame\n * ```\n *\n * `seeked` says the seek finished, not that the frame for the new position is\n * composited and readable by `drawImage`. The symptom is the worst kind: it\n * works on the machine it was written on and produces the neighbouring frame\n * elsewhere, with no error and no log.\n *\n * `requestVideoFrameCallback` is the only signal that reports a frame having\n * been **presented** — and measuring it, 2026-09-04 in Chromium, settled how it\n * can be used here: it fires while the video **plays** and does **not** fire\n * for a seek on a paused element. So blocking a seek on it would stall every\n * capture for the whole timeout and then proceed anyway. Instead:\n *\n * - Capturing from a **playing** video waits for the next presented frame, so\n *   the pixels are demonstrably fresh. That is the screen-recording print.\n * - Capturing at an **instant** waits for `seeked` and then two animation\n *   frames, which is what a browser offers for a paused element.\n * - Capturing the current frame of a **paused** video waits for nothing: the\n *   frame on screen already is the frame.\n *\n * `confirmed` in the result says which of those happened, so a caller can tell\n * a demonstrably fresh frame from a best-effort one instead of guessing. A\n * seek-based capture reporting `confirmed: false` is the normal case, not a\n * warning sign.\n *\n * Three more traps come along for the ride:\n *\n * - **A recording may arrive with no duration.** `MediaRecorder` does not\n *   guarantee a duration in the WebM header, so the blob `useVideoRecorder`\n *   just handed you may report `Infinity` — and the video an app most wants to\n *   grab a frame from is exactly that one. Seeking past the end forces the\n *   browser to demux to the last frame, after which it knows the length; that\n *   probe runs here rather than in every caller. Chromium was measured writing\n *   the duration for a one-shot recording, so this is for the paths that omit\n *   it — chunked `timeslice` recording, and other engines.\n * - **A cross-origin video taints the canvas**, and the failure surfaces far\n *   from its cause, so it is re-thrown saying what to set.\n * - **Moving `currentTime` moves the player** somebody is watching; `restore`\n *   puts it back, and touches only what actually moved.\n */\n\nimport { FrameSeekError, ImageDecodeError } from \"./exceptions\";\nimport { resizeImage } from \"./transform\";\nimport type { CaptureFrameOptions, CapturedFrame } from \"./types\";\n\n/** How long a seek and the frame after it may take, in milliseconds. */\nexport const DEFAULT_FRAME_TIMEOUT_MS = 3000;\n\n/** `HTMLMediaElement.HAVE_CURRENT_DATA` — there are pixels for the current position. */\nconst HAVE_CURRENT_DATA = 2;\n\n/** Below this, in seconds, a seek to `currentTime` is a seek to where we already are. */\nconst SAME_FRAME_EPSILON = 0.001;\n\n/**\n * How long to wait for a presented frame, in milliseconds.\n *\n * Its own budget, not the caller's `timeoutMs`: this wait is an optimisation on\n * freshness, and a video playing at 24 fps presents one every 42 ms. Spending\n * seconds here would stall the capture for a guarantee the platform may simply\n * not be able to give.\n */\nconst FRAME_SETTLE_MS = 200;\n\n/**\n * A video element that reports presented frames.\n *\n * Declared structurally rather than by augmenting `HTMLVideoElement`: this is a\n * published package, and widening a lib interface would widen it for every\n * consumer, in every file, whether they load a polyfill or not.\n *\n * The two members are one capability. The spec defines them together, so a\n * runtime with `requestVideoFrameCallback` and no `cancelVideoFrameCallback`\n * does not exist — guarding the second separately would add a branch no test\n * can honestly reach.\n */\ntype FrameCallbackVideo = HTMLVideoElement & {\n    requestVideoFrameCallback: (callback: (now: number) => void) => number;\n    cancelVideoFrameCallback: (handle: number) => void;\n};\n\n/**\n * Whether this element reports presented frames.\n *\n * @param video The element to test.\n * @returns `true` when the frame callback pair is available.\n */\nfunction reportsFrames(video: HTMLVideoElement): video is FrameCallbackVideo {\n    return typeof (video as Partial<FrameCallbackVideo>).requestVideoFrameCallback === \"function\";\n}\n\n/** Seek target that forces a demux to the end, to learn an unknown duration. */\nconst PAST_THE_END_SECONDS = 1e101;\n\n/** The `AbortError` a caller's `signal` produces. */\nfunction abortError(): DOMException {\n    return new DOMException(\"The frame capture was aborted.\", \"AbortError\");\n}\n\n/**\n * Wait for one media event, and clean up on every exit.\n *\n * @param video The element to listen on.\n * @param type The event to wait for.\n * @param timeoutMs How long to wait.\n * @param signal Optional abort signal.\n * @param whenLate Message for the {@link FrameSeekError} on timeout.\n * @returns Resolves when the event fires.\n * @throws {@link FrameSeekError} when the timeout is reached.\n */\nfunction onceEvent(\n    video: HTMLVideoElement,\n    type: string,\n    timeoutMs: number,\n    signal: AbortSignal | undefined,\n    whenLate: string,\n): Promise<void> {\n    return new Promise<void>((resolve, reject) => {\n        const finish = (settle: () => void): void => {\n            clearTimeout(timer);\n            video.removeEventListener(type, onEvent);\n            signal?.removeEventListener(\"abort\", onAbort);\n            settle();\n        };\n        const onEvent = (): void => finish(resolve);\n        const onAbort = (): void => finish(() => reject(abortError()));\n\n        const timer = setTimeout(\n            () => finish(() => reject(new FrameSeekError(whenLate))),\n            timeoutMs,\n        );\n        video.addEventListener(type, onEvent);\n        signal?.addEventListener(\"abort\", onAbort);\n    });\n}\n\n/**\n * Wait for the next frame the compositor presents.\n *\n * Only ever called for a **playing** element, because that is the only state in\n * which the callback fires — measured, not assumed. The timeout is the escape\n * for a hidden tab, which presents nothing at all.\n *\n * @param video A playing element that reports presented frames.\n * @returns `true` when a frame was presented, `false` when the wait expired.\n */\nfunction nextPresentedFrame(video: FrameCallbackVideo): Promise<boolean> {\n    return new Promise<boolean>((resolve) => {\n        const timer = setTimeout(() => {\n            video.cancelVideoFrameCallback(handle);\n            resolve(false);\n        }, FRAME_SETTLE_MS);\n        const handle = video.requestVideoFrameCallback(() => {\n            clearTimeout(timer);\n            resolve(true);\n        });\n    });\n}\n\n/**\n * Let the compositor catch up after a seek on a paused element.\n *\n * Two animation frames is what a browser offers here: the frame callback does\n * not fire for a paused seek, so there is nothing to confirm against. A runtime\n * with no animation frames at all gets a macrotask — enough for a test\n * environment, not a promise about pixels.\n *\n * @returns Resolves once the wait is over. Never a confirmation.\n */\nfunction settleAfterSeek(): Promise<void> {\n    if (typeof requestAnimationFrame === \"function\") {\n        return new Promise<void>((resolve) => {\n            requestAnimationFrame(() => requestAnimationFrame(() => resolve()));\n        });\n    }\n    return new Promise<void>((resolve) => setTimeout(resolve, 0));\n}\n\n/**\n * Wait for the freshest frame this element's state allows, and say which.\n *\n * @param video The element about to be read.\n * @param seeked Whether a seek just moved it.\n * @returns `true` when a presented frame was observed.\n */\nasync function awaitReadableFrame(video: HTMLVideoElement, seeked: boolean): Promise<boolean> {\n    if (!video.paused && reportsFrames(video)) return await nextPresentedFrame(video);\n    if (seeked) await settleAfterSeek();\n    return false;\n}\n\n/**\n * Whether the element is fed by a live stream rather than by a file.\n *\n * A truthiness check rather than `!== null`: the property is absent in\n * environments that model only part of `HTMLMediaElement`, where comparing\n * against `null` would read every element as live.\n *\n * @param video The element to test.\n * @returns `true` when a `MediaStream` is playing into it.\n */\nfunction isLiveStream(video: HTMLVideoElement): boolean {\n    return Boolean(video.srcObject);\n}\n\n/**\n * The video's length in seconds, probing for it when the header lacks one.\n *\n * `MediaRecorder` does not guarantee a duration in the WebM it produces, so a\n * recording can report `Infinity` until something forces the browser to demux\n * to the end. That is what the seek past the end does — the same hack the\n * `AudioPlayer` uses, for the same reason: the value is not in the file.\n *\n * @param video The element to measure.\n * @param timeoutMs How long the probe may take.\n * @param signal Optional abort signal.\n * @returns The duration in seconds.\n * @throws {@link FrameSeekError} when the element is a live stream, or the\n *   probe produced no duration.\n */\nasync function resolveDuration(\n    video: HTMLVideoElement,\n    timeoutMs: number,\n    signal: AbortSignal | undefined,\n): Promise<number> {\n    if (Number.isFinite(video.duration)) return video.duration;\n\n    if (isLiveStream(video)) {\n        throw new FrameSeekError(\n            \"This element is playing a live MediaStream, which has no timeline to seek: \" +\n                \"there is no instant but now. Leave `atMs` out to capture the frame on screen.\",\n        );\n    }\n\n    const probed = onceEvent(\n        video,\n        \"timeupdate\",\n        timeoutMs,\n        signal,\n        `The video reported no duration and the probe for it did not answer within ` +\n            `${timeoutMs}ms, so there is no timeline to seek on.`,\n    );\n    video.currentTime = PAST_THE_END_SECONDS;\n    await probed;\n\n    if (!Number.isFinite(video.duration)) {\n        throw new FrameSeekError(\n            \"This video still reports no duration after seeking past its end, so it has \" +\n                \"no seekable timeline — a live HLS or DASH source behaves this way. Leave \" +\n                \"`atMs` out to capture the frame on screen.\",\n        );\n    }\n    return video.duration;\n}\n\n/**\n * Move the video to an instant, and wait for that instant's frame.\n *\n * @param video The element to move.\n * @param atMs The instant, in milliseconds. Clamped to the duration.\n * @param timeoutMs How long the seek and the frame may take.\n * @param signal Optional abort signal.\n * @returns Whether a presented frame confirmed the new position.\n * @throws {@link FrameSeekError} when the video has no seekable timeline, or\n *   the seek did not land in time.\n */\nasync function seekTo(\n    video: HTMLVideoElement,\n    atMs: number,\n    timeoutMs: number,\n    signal: AbortSignal | undefined,\n): Promise<boolean> {\n    const duration = await resolveDuration(video, timeoutMs, signal);\n\n    const target = Math.min(Math.max(atMs / 1000, 0), duration);\n    if (Math.abs(video.currentTime - target) < SAME_FRAME_EPSILON) {\n        return await awaitReadableFrame(video, false);\n    }\n\n    const seeked = onceEvent(\n        video,\n        \"seeked\",\n        timeoutMs,\n        signal,\n        `The video did not finish seeking to ${target.toFixed(3)}s within ${timeoutMs}ms. ` +\n            \"Nothing was captured: a frame from the wrong instant is indistinguishable \" +\n            \"from a correct one downstream.\",\n    );\n    video.currentTime = target;\n    await seeked;\n    return await awaitReadableFrame(video, true);\n}\n\n/**\n * Re-throw a tainted-canvas failure saying what to fix.\n *\n * A cross-origin video without `crossOrigin` taints everything it is drawn\n * into, and the `SecurityError` then arrives from the encoder — one call away\n * from the element that caused it, wrapped in whatever the decode said.\n *\n * @param error What the imaging pipeline threw.\n * @returns The error to throw instead.\n */\nfunction explained(error: unknown): unknown {\n    const names = [error, (error as { cause?: unknown } | null)?.cause].map((candidate) =>\n        typeof candidate === \"object\" && candidate !== null && \"name\" in candidate\n            ? String((candidate as { name: unknown }).name)\n            : \"\",\n    );\n    if (!names.includes(\"SecurityError\")) return error;\n    return new ImageDecodeError(\n        \"The video is cross-origin, so reading its pixels is not allowed. Set \" +\n            'crossOrigin=\"anonymous\" on the element before the source loads, and serve the ' +\n            \"video with a permissive Access-Control-Allow-Origin.\",\n        { cause: error },\n    );\n}\n\n/**\n * Put playback back where the capture found it, touching only what moved.\n *\n * Each half is guarded because writing `currentTime` **is** a seek, even when\n * the value is unchanged: a capture that was refused before it moved anything\n * — a live stream, an abort — would otherwise perturb the player it never\n * touched. And a capture that paused without needing to move still has to let\n * go of the pause.\n *\n * @param video The element to restore.\n * @param time Where `currentTime` was.\n * @param wasPlaying Whether it was playing before the capture paused it.\n */\nfunction restorePlayback(video: HTMLVideoElement, time: number, wasPlaying: boolean): void {\n    if (video.currentTime !== time) video.currentTime = time;\n    if (wasPlaying && video.paused) void Promise.resolve(video.play()).catch(() => undefined);\n}\n\n/**\n * Capture a frame from a video as encoded image bytes.\n *\n * Without `atMs` it reads the frame on screen, which is what a screen or camera\n * recording wants — a print of what is being recorded. With `atMs` it seeks,\n * waits for that instant's frame to be presented, captures, and puts the player\n * back.\n *\n * @example Print of a screen recording in progress\n * ```ts\n * const shot = await captureFrame(videoRef.current!, {\n *     type: \"image/webp\",\n *     quality: 0.9,\n * });\n * await shareOrDownloadBlob(shot.blob, \"print.webp\");\n * ```\n *\n * @example A poster from ten seconds in, scaled down\n * ```ts\n * const poster = await captureFrame(video, { atMs: 10_000, width: 640 });\n * setPosterUrl(URL.createObjectURL(poster.blob));\n * console.log(`landed on ${poster.atMs}ms`);\n * ```\n *\n * @param video The element to read. It needs data — the capture waits for\n *   `loadeddata` when the element has none yet.\n * @param options Instant, output box, format, and how long to wait.\n * @returns The encoded frame, the instant it actually came from, and whether a\n *   presented frame confirmed that instant.\n * @throws {@link FrameSeekError} when the video has no data or no timeline in\n *   time, or the seek did not land.\n * @throws {@link ImageDecodeError} when the pixels cannot be read — a\n *   cross-origin video without `crossOrigin` is the common one.\n * @throws {@link ImageEncodeError} when the canvas produces no bytes.\n */\nexport async function captureFrame(\n    video: HTMLVideoElement,\n    options: CaptureFrameOptions = {},\n): Promise<CapturedFrame> {\n    const timeoutMs = options.timeoutMs ?? DEFAULT_FRAME_TIMEOUT_MS;\n    if (options.signal?.aborted === true) throw abortError();\n\n    if (video.readyState < HAVE_CURRENT_DATA) {\n        await onceEvent(\n            video,\n            \"loadeddata\",\n            timeoutMs,\n            options.signal,\n            `The video had no frame to read within ${timeoutMs}ms (readyState ` +\n                `${video.readyState}). Give it a source, or wait for it yourself.`,\n        );\n    }\n\n    const { atMs: requestedMs } = options;\n    const previousTime = video.currentTime;\n    const wasPlaying = !video.paused;\n\n    try {\n        let confirmed: boolean;\n        if (requestedMs === undefined) {\n            confirmed = await awaitReadableFrame(video, false);\n        } else {\n            if (wasPlaying) video.pause();\n            confirmed = await seekTo(video, requestedMs, timeoutMs, options.signal);\n        }\n\n        const atMs = video.currentTime * 1000;\n        const encoded = await resizeImage(video, options);\n        return { ...encoded, atMs, confirmed };\n    } catch (error) {\n        throw explained(error);\n    } finally {\n        if (options.restore !== false) restorePlayback(video, previousTime, wasPlaying);\n    }\n}\n"],"mappings":"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"}
+{"version":3,"file":"frame.js","names":["DEFAULT_FRAME_TIMEOUT_MS","HAVE_CURRENT_DATA","SAME_FRAME_EPSILON","FRAME_SETTLE_MS","reportsFrames","video","PAST_THE_END_SECONDS","abortError","onceEvent","finish","timer","type","onEvent","signal","onAbort","settle","resolve","reject","FrameSeekError","whenLate","timeoutMs","nextPresentedFrame","handle","settleAfterSeek","awaitReadableFrame","seeked","isLiveStream","resolveDuration","probed","seekTo","duration","target","atMs","explained","error","candidate","ImageDecodeError","restorePlayback","time","wasPlaying","captureFrame","options","requestedMs","previousTime","confirmed","resizeImage"],"sources":["../../src/imaging/frame.ts"],"sourcesContent":["/**\n * Reading one frame out of a `<video>`, at the instant you asked for.\n *\n * The current frame needs nothing from this file: `createImageBitmap` takes a\n * video element, so `resizeImage(video)` already works. A **chosen** instant is\n * the part every app writes by hand and writes wrong:\n *\n * ```ts\n * video.currentTime = 12.5;\n * await new Promise((r) => video.addEventListener(\"seeked\", r, { once: true }));\n * ctx.drawImage(video, 0, 0);   // may draw the PREVIOUS frame\n * ```\n *\n * `seeked` says the seek finished, not that the frame for the new position is\n * composited and readable by `drawImage`. The symptom is the worst kind: it\n * works on the machine it was written on and produces the neighbouring frame\n * elsewhere, with no error and no log.\n *\n * `requestVideoFrameCallback` is the only signal that reports a frame having\n * been **presented** — and measuring it, 2026-09-04 in Chromium, settled how it\n * can be used here: it fires while the video **plays** and does **not** fire\n * for a seek on a paused element. So blocking a seek on it would stall every\n * capture for the whole timeout and then proceed anyway. Instead:\n *\n * - Capturing from a **playing** video waits for the next presented frame, so\n *   the pixels are demonstrably fresh. That is the screen-recording print.\n * - Capturing at an **instant** waits for `seeked` and then two animation\n *   frames, which is what a browser offers for a paused element.\n * - Capturing the current frame of a **paused** video waits for nothing: the\n *   frame on screen already is the frame.\n *\n * `confirmed` in the result says which of those happened, so a caller can tell\n * a demonstrably fresh frame from a best-effort one instead of guessing. A\n * seek-based capture reporting `confirmed: false` is the normal case, not a\n * warning sign.\n *\n * Three more traps come along for the ride:\n *\n * - **A recording may arrive with no duration.** `MediaRecorder` does not\n *   guarantee a duration in the WebM header, so the blob `useVideoRecorder`\n *   just handed you may report `Infinity` — and the video an app most wants to\n *   grab a frame from is exactly that one. Seeking past the end forces the\n *   browser to demux to the last frame, after which it knows the length; that\n *   probe runs here rather than in every caller. Chromium was measured writing\n *   the duration for a one-shot recording, so this is for the paths that omit\n *   it — chunked `timeslice` recording, and other engines.\n * - **A cross-origin video taints the canvas**, and the failure surfaces far\n *   from its cause, so it is re-thrown saying what to set.\n * - **Moving `currentTime` moves the player** somebody is watching; `restore`\n *   puts it back, and touches only what actually moved.\n */\n\nimport { FrameSeekError, ImageDecodeError } from \"./exceptions\";\nimport { resizeImage } from \"./transform\";\nimport type { CaptureFrameOptions, CapturedFrame } from \"./types\";\n\n/** How long a seek and the frame after it may take, in milliseconds. */\nexport const DEFAULT_FRAME_TIMEOUT_MS = 3000;\n\n/** `HTMLMediaElement.HAVE_CURRENT_DATA` — there are pixels for the current position. */\nconst HAVE_CURRENT_DATA = 2;\n\n/** Below this, in seconds, a seek to `currentTime` is a seek to where we already are. */\nconst SAME_FRAME_EPSILON = 0.001;\n\n/**\n * How long to wait for a presented frame, in milliseconds.\n *\n * Its own budget, not the caller's `timeoutMs`: this wait is an optimisation on\n * freshness, and a video playing at 24 fps presents one every 42 ms. Spending\n * seconds here would stall the capture for a guarantee the platform may simply\n * not be able to give.\n */\nconst FRAME_SETTLE_MS = 200;\n\n/**\n * A video element that reports presented frames.\n *\n * Declared structurally rather than by augmenting `HTMLVideoElement`: this is a\n * published package, and widening a lib interface would widen it for every\n * consumer, in every file, whether they load a polyfill or not.\n *\n * The two members are one capability. The spec defines them together, so a\n * runtime with `requestVideoFrameCallback` and no `cancelVideoFrameCallback`\n * does not exist — guarding the second separately would add a branch no test\n * can honestly reach.\n */\ntype FrameCallbackVideo = HTMLVideoElement & {\n    requestVideoFrameCallback: (callback: (now: number) => void) => number;\n    cancelVideoFrameCallback: (handle: number) => void;\n};\n\n/**\n * Whether this element reports presented frames.\n *\n * @param video The element to test.\n * @returns `true` when the frame callback pair is available.\n */\nfunction reportsFrames(video: HTMLVideoElement): video is FrameCallbackVideo {\n    return typeof (video as Partial<FrameCallbackVideo>).requestVideoFrameCallback === \"function\";\n}\n\n/** Seek target that forces a demux to the end, to learn an unknown duration. */\nconst PAST_THE_END_SECONDS = 1e101;\n\n/** The `AbortError` a caller's `signal` produces. */\nfunction abortError(): DOMException {\n    return new DOMException(\"The frame capture was aborted.\", \"AbortError\");\n}\n\n/**\n * Wait for one media event, and clean up on every exit.\n *\n * @param video The element to listen on.\n * @param type The event to wait for.\n * @param timeoutMs How long to wait.\n * @param signal Optional abort signal.\n * @param whenLate Message for the {@link FrameSeekError} on timeout.\n * @returns Resolves when the event fires.\n * @throws {@link FrameSeekError} when the timeout is reached.\n */\nfunction onceEvent(\n    video: HTMLVideoElement,\n    type: string,\n    timeoutMs: number,\n    signal: AbortSignal | undefined,\n    whenLate: string,\n): Promise<void> {\n    return new Promise<void>((resolve, reject) => {\n        const finish = (settle: () => void): void => {\n            clearTimeout(timer);\n            video.removeEventListener(type, onEvent);\n            signal?.removeEventListener(\"abort\", onAbort);\n            settle();\n        };\n        const onEvent = (): void => finish(resolve);\n        const onAbort = (): void => finish(() => reject(abortError()));\n\n        const timer = setTimeout(\n            () => finish(() => reject(new FrameSeekError(whenLate))),\n            timeoutMs,\n        );\n        video.addEventListener(type, onEvent);\n        signal?.addEventListener(\"abort\", onAbort);\n    });\n}\n\n/**\n * Wait for the next frame the compositor presents.\n *\n * Only ever called for a **playing** element, because that is the only state in\n * which the callback fires — measured, not assumed. The timeout is the escape\n * for a hidden tab, which presents nothing at all.\n *\n * @param video A playing element that reports presented frames.\n * @returns `true` when a frame was presented, `false` when the wait expired.\n */\nfunction nextPresentedFrame(video: FrameCallbackVideo): Promise<boolean> {\n    return new Promise<boolean>((resolve) => {\n        const timer = setTimeout(() => {\n            video.cancelVideoFrameCallback(handle);\n            resolve(false);\n        }, FRAME_SETTLE_MS);\n        const handle = video.requestVideoFrameCallback(() => {\n            clearTimeout(timer);\n            resolve(true);\n        });\n    });\n}\n\n/**\n * Let the compositor catch up after a seek on a paused element.\n *\n * Two animation frames is what a browser offers here: the frame callback does\n * not fire for a paused seek, so there is nothing to confirm against. A runtime\n * with no animation frames at all gets a macrotask — enough for a test\n * environment, not a promise about pixels.\n *\n * @returns Resolves once the wait is over. Never a confirmation.\n */\nfunction settleAfterSeek(): Promise<void> {\n    if (typeof requestAnimationFrame === \"function\") {\n        return new Promise<void>((resolve) => {\n            requestAnimationFrame(() => requestAnimationFrame(() => resolve()));\n        });\n    }\n    return new Promise<void>((resolve) => setTimeout(resolve, 0));\n}\n\n/**\n * Wait for the freshest frame this element's state allows, and say which.\n *\n * @param video The element about to be read.\n * @param seeked Whether a seek just moved it.\n * @returns `true` when a presented frame was observed.\n */\nasync function awaitReadableFrame(video: HTMLVideoElement, seeked: boolean): Promise<boolean> {\n    if (!video.paused && reportsFrames(video)) return await nextPresentedFrame(video);\n    if (seeked) await settleAfterSeek();\n    return false;\n}\n\n/**\n * Whether the element is fed by a live stream rather than by a file.\n *\n * A truthiness check rather than `!== null`: the property is absent in\n * environments that model only part of `HTMLMediaElement`, where comparing\n * against `null` would read every element as live.\n *\n * @param video The element to test.\n * @returns `true` when a `MediaStream` is playing into it.\n */\nfunction isLiveStream(video: HTMLVideoElement): boolean {\n    return Boolean(video.srcObject);\n}\n\n/**\n * The video's length in seconds, probing for it when the header lacks one.\n *\n * `MediaRecorder` does not guarantee a duration in the WebM it produces, so a\n * recording can report `Infinity` until something forces the browser to demux\n * to the end. That is what the seek past the end does — the same hack the\n * `AudioPlayer` uses, for the same reason: the value is not in the file.\n *\n * @param video The element to measure.\n * @param timeoutMs How long the probe may take.\n * @param signal Optional abort signal.\n * @returns The duration in seconds.\n * @throws {@link FrameSeekError} when the element is a live stream, or the\n *   probe produced no duration.\n */\nasync function resolveDuration(\n    video: HTMLVideoElement,\n    timeoutMs: number,\n    signal: AbortSignal | undefined,\n): Promise<number> {\n    if (Number.isFinite(video.duration)) return video.duration;\n\n    if (isLiveStream(video)) {\n        throw new FrameSeekError(\n            \"This element is playing a live MediaStream, which has no timeline to seek: \" +\n                \"there is no instant but now. Leave `atMs` out to capture the frame on screen.\",\n        );\n    }\n\n    const probed = onceEvent(\n        video,\n        \"timeupdate\",\n        timeoutMs,\n        signal,\n        `The video reported no duration and the probe for it did not answer within ` +\n            `${timeoutMs}ms, so there is no timeline to seek on.`,\n    );\n    video.currentTime = PAST_THE_END_SECONDS;\n    await probed;\n\n    if (!Number.isFinite(video.duration)) {\n        throw new FrameSeekError(\n            \"This video still reports no duration after seeking past its end, so it has \" +\n                \"no seekable timeline — a live HLS or DASH source behaves this way. Leave \" +\n                \"`atMs` out to capture the frame on screen.\",\n        );\n    }\n    return video.duration;\n}\n\n/**\n * Move the video to an instant, and wait for that instant's frame.\n *\n * @param video The element to move.\n * @param atMs The instant, in milliseconds. Clamped to the duration.\n * @param timeoutMs How long the seek and the frame may take.\n * @param signal Optional abort signal.\n * @returns Whether a presented frame confirmed the new position.\n * @throws {@link FrameSeekError} when the video has no seekable timeline, or\n *   the seek did not land in time.\n */\nasync function seekTo(\n    video: HTMLVideoElement,\n    atMs: number,\n    timeoutMs: number,\n    signal: AbortSignal | undefined,\n): Promise<boolean> {\n    const duration = await resolveDuration(video, timeoutMs, signal);\n\n    const target = Math.min(Math.max(atMs / 1000, 0), duration);\n    if (Math.abs(video.currentTime - target) < SAME_FRAME_EPSILON) {\n        return await awaitReadableFrame(video, false);\n    }\n\n    const seeked = onceEvent(\n        video,\n        \"seeked\",\n        timeoutMs,\n        signal,\n        `The video did not finish seeking to ${target.toFixed(3)}s within ${timeoutMs}ms. ` +\n            \"Nothing was captured: a frame from the wrong instant is indistinguishable \" +\n            \"from a correct one downstream.\",\n    );\n    video.currentTime = target;\n    await seeked;\n    return await awaitReadableFrame(video, true);\n}\n\n/**\n * Re-throw a tainted-canvas failure saying what to fix.\n *\n * A cross-origin video without `crossOrigin` taints everything it is drawn\n * into, and the `SecurityError` then arrives from the encoder — one call away\n * from the element that caused it, wrapped in whatever the decode said.\n *\n * @param error What the imaging pipeline threw.\n * @returns The error to throw instead.\n */\nfunction explained(error: unknown): unknown {\n    const names = [error, (error as { cause?: unknown } | null)?.cause].map((candidate) =>\n        typeof candidate === \"object\" && candidate !== null && \"name\" in candidate\n            ? String((candidate as { name: unknown }).name)\n            : \"\",\n    );\n    if (!names.includes(\"SecurityError\")) return error;\n    return new ImageDecodeError(\n        \"The video is cross-origin, so reading its pixels is not allowed. Set \" +\n            'crossOrigin=\"anonymous\" on the element before the source loads, and serve the ' +\n            \"video with a permissive Access-Control-Allow-Origin.\",\n        { cause: error },\n    );\n}\n\n/**\n * Put playback back where the capture found it, touching only what moved.\n *\n * Each half is guarded because writing `currentTime` **is** a seek, even when\n * the value is unchanged: a capture that was refused before it moved anything\n * — a live stream, an abort — would otherwise perturb the player it never\n * touched. And a capture that paused without needing to move still has to let\n * go of the pause.\n *\n * @param video The element to restore.\n * @param time Where `currentTime` was.\n * @param wasPlaying Whether it was playing before the capture paused it.\n */\nfunction restorePlayback(video: HTMLVideoElement, time: number, wasPlaying: boolean): void {\n    if (video.currentTime !== time) video.currentTime = time;\n    if (wasPlaying && video.paused) void Promise.resolve(video.play()).catch(() => undefined);\n}\n\n/**\n * Capture a frame from a video as encoded image bytes.\n *\n * Without `atMs` it reads the frame on screen, which is what a screen or camera\n * recording wants — a print of what is being recorded. With `atMs` it seeks,\n * waits for that instant's frame to be presented, captures, and puts the player\n * back.\n *\n * @example Print of a screen recording in progress\n * ```ts\n * const shot = await captureFrame(videoRef.current!, {\n *     type: \"image/webp\",\n *     quality: 0.9,\n * });\n * await shareOrDownloadBlob(shot.blob, \"print.webp\");\n * ```\n *\n * @example A poster from ten seconds in, scaled down\n * ```ts\n * const poster = await captureFrame(video, { atMs: 10_000, width: 640 });\n * setPosterUrl(URL.createObjectURL(poster.blob));\n * console.log(`landed on ${poster.atMs}ms`);\n * ```\n *\n * @param video The element to read. It needs data — the capture waits for\n *   `loadeddata` when the element has none yet.\n * @param options Instant, output box, format, and how long to wait.\n * @returns The encoded frame, the instant it actually came from, and whether a\n *   presented frame confirmed that instant.\n * @throws {@link FrameSeekError} when the video has no data or no timeline in\n *   time, or the seek did not land.\n * @throws {@link ImageDecodeError} when the pixels cannot be read — a\n *   cross-origin video without `crossOrigin` is the common one.\n * @throws {@link ImageEncodeError} when the canvas produces no bytes.\n */\nexport async function captureFrame(\n    video: HTMLVideoElement,\n    options: CaptureFrameOptions = {},\n): Promise<CapturedFrame> {\n    const timeoutMs = options.timeoutMs ?? DEFAULT_FRAME_TIMEOUT_MS;\n    if (options.signal?.aborted === true) throw abortError();\n\n    if (video.readyState < HAVE_CURRENT_DATA) {\n        await onceEvent(\n            video,\n            \"loadeddata\",\n            timeoutMs,\n            options.signal,\n            `The video had no frame to read within ${timeoutMs}ms (readyState ` +\n                `${video.readyState}). Give it a source, or wait for it yourself.`,\n        );\n    }\n\n    const { atMs: requestedMs } = options;\n    const previousTime = video.currentTime;\n    const wasPlaying = !video.paused;\n\n    try {\n        let confirmed: boolean;\n        if (requestedMs === undefined) {\n            confirmed = await awaitReadableFrame(video, false);\n        } else {\n            if (wasPlaying) video.pause();\n            confirmed = await seekTo(video, requestedMs, timeoutMs, options.signal);\n        }\n\n        const atMs = video.currentTime * 1000;\n        const encoded = await resizeImage(video, options);\n        return { ...encoded, atMs, confirmed };\n    } catch (error) {\n        throw explained(error);\n    } finally {\n        if (options.restore !== false) restorePlayback(video, previousTime, wasPlaying);\n    }\n}\n"],"mappings":"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"}

package/dist/imaging/thumbnails.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"thumbnails.cjs","names":[],"sources":["../../src/imaging/thumbnails.ts"],"sourcesContent":["/**\n * Producing several sizes from one decode.\n *\n * A gallery needs a grid thumbnail, a list avatar and a detail view. Doing\n * that with three `resizeImage` calls decodes the same photo three times,\n * which on a 12-megapixel picture is most of the cost — the decode dominates,\n * not the scaling.\n */\n\nimport { createSurface, drawScaled } from \"./canvas\";\nimport { decodeImage } from \"./decode\";\nimport { encodeImage } from \"./encode\";\nimport type { EncodeOptions, ImageSource, ProcessedImage } from \"./types\";\n\n/** One requested size. */\nexport interface ThumbnailSpec {\n    /** Name to find it by in the result. */\n    readonly name: string;\n    /** Longest edge in pixels. */\n    readonly size: number;\n    /** Format and quality, overriding the shared options. */\n    readonly encode?: EncodeOptions;\n}\n\n/** A produced thumbnail. */\nexport interface Thumbnail extends ProcessedImage {\n    readonly name: string;\n}\n\n/**\n * Produce several sizes from a single decode.\n *\n * @example\n * ```ts\n * const [thumb, card] = await createThumbnails(file, [\n *     { name: \"thumb\", size: 96 },\n *     { name: \"card\", size: 480 },\n * ]);\n * ```\n *\n * Sizes are the **longest edge**, and the aspect ratio is kept, so a\n * portrait and a landscape photo both fit the same grid cell without a\n * separate calculation per orientation.\n *\n * @param source Anything decodable.\n * @param specs The sizes to produce.\n * @param options Shared format and quality.\n * @returns One result per spec, in the order requested.\n * @throws {@link ImageDecodeError} when the source cannot be decoded.\n */\nexport async function createThumbnails(\n    source: ImageSource,\n    specs: readonly ThumbnailSpec[],\n    options: EncodeOptions = {},\n): Promise<Thumbnail[]> {\n    const { bitmap } = await decodeImage(source);\n    try {\n        const results: Thumbnail[] = [];\n        for (const spec of specs) {\n            const scale = Math.min(1, spec.size / Math.max(bitmap.width, bitmap.height));\n            const width = Math.max(1, Math.round(bitmap.width * scale));\n            const height = Math.max(1, Math.round(bitmap.height * scale));\n\n            const surface = createSurface(width, height);\n            drawScaled(bitmap, surface, { x: 0, y: 0, width, height });\n            const encoded = await encodeImage(surface, { ...options, ...spec.encode });\n            results.push({ ...encoded, name: spec.name });\n        }\n        return results;\n    } finally {\n        bitmap.close?.();\n    }\n}\n"],"mappings":"oFAkDA,eAAsB,EAClB,EACA,EACA,EAAyB,CAAC,EACN,CACpB,GAAM,CAAE,UAAW,MAAM,EAAA,YAAY,CAAM,EAC3C,GAAI,CACA,IAAM,EAAuB,CAAC,EAC9B,IAAK,IAAM,KAAQ,EAAO,CACtB,IAAM,EAAQ,KAAK,IAAI,EAAG,EAAK,KAAO,KAAK,IAAI,EAAO,MAAO,EAAO,MAAM,CAAC,EACrE,EAAQ,KAAK,IAAI,EAAG,KAAK,MAAM,EAAO,MAAQ,CAAK,CAAC,EACpD,EAAS,KAAK,IAAI,EAAG,KAAK,MAAM,EAAO,OAAS,CAAK,CAAC,EAEtD,EAAU,EAAA,cAAc,EAAO,CAAM,EAC3C,EAAA,WAAW,EAAQ,EAAS,CAAE,EAAG,EAAG,EAAG,EAAG,QAAO,QAAO,CAAC,EACzD,IAAM,EAAU,MAAM,EAAA,YAAY,EAAS,CAAE,GAAG,EAAS,GAAG,EAAK,MAAO,CAAC,EACzE,EAAQ,KAAK,CAAE,GAAG,EAAS,KAAM,EAAK,IAAK,CAAC,CAChD,CACA,OAAO,CACX,QAAU,CACN,EAAO,QAAQ,CACnB,CACJ"}
+{"version":3,"file":"thumbnails.cjs","names":["decodeImage","createSurface","encodeImage","require_canvas","require_decode","require_encode","createThumbnails","source","results","spec","specs","scale","bitmap","width","height","surface","encoded","options"],"sources":["../../src/imaging/thumbnails.ts"],"sourcesContent":["/**\n * Producing several sizes from one decode.\n *\n * A gallery needs a grid thumbnail, a list avatar and a detail view. Doing\n * that with three `resizeImage` calls decodes the same photo three times,\n * which on a 12-megapixel picture is most of the cost — the decode dominates,\n * not the scaling.\n */\n\nimport { createSurface, drawScaled } from \"./canvas\";\nimport { decodeImage } from \"./decode\";\nimport { encodeImage } from \"./encode\";\nimport type { EncodeOptions, ImageSource, ProcessedImage } from \"./types\";\n\n/** One requested size. */\nexport interface ThumbnailSpec {\n    /** Name to find it by in the result. */\n    readonly name: string;\n    /** Longest edge in pixels. */\n    readonly size: number;\n    /** Format and quality, overriding the shared options. */\n    readonly encode?: EncodeOptions;\n}\n\n/** A produced thumbnail. */\nexport interface Thumbnail extends ProcessedImage {\n    readonly name: string;\n}\n\n/**\n * Produce several sizes from a single decode.\n *\n * @example\n * ```ts\n * const [thumb, card] = await createThumbnails(file, [\n *     { name: \"thumb\", size: 96 },\n *     { name: \"card\", size: 480 },\n * ]);\n * ```\n *\n * Sizes are the **longest edge**, and the aspect ratio is kept, so a\n * portrait and a landscape photo both fit the same grid cell without a\n * separate calculation per orientation.\n *\n * @param source Anything decodable.\n * @param specs The sizes to produce.\n * @param options Shared format and quality.\n * @returns One result per spec, in the order requested.\n * @throws {@link ImageDecodeError} when the source cannot be decoded.\n */\nexport async function createThumbnails(\n    source: ImageSource,\n    specs: readonly ThumbnailSpec[],\n    options: EncodeOptions = {},\n): Promise<Thumbnail[]> {\n    const { bitmap } = await decodeImage(source);\n    try {\n        const results: Thumbnail[] = [];\n        for (const spec of specs) {\n            const scale = Math.min(1, spec.size / Math.max(bitmap.width, bitmap.height));\n            const width = Math.max(1, Math.round(bitmap.width * scale));\n            const height = Math.max(1, Math.round(bitmap.height * scale));\n\n            const surface = createSurface(width, height);\n            drawScaled(bitmap, surface, { x: 0, y: 0, width, height });\n            const encoded = await encodeImage(surface, { ...options, ...spec.encode });\n            results.push({ ...encoded, name: spec.name });\n        }\n        return results;\n    } finally {\n        bitmap.close?.();\n    }\n}\n"],"mappings":"A,oFAkDA,eAAsBM,EAClB,EACA,EACA,EAAyB,CAAC,EACN,CACpB,GAAM,CAAE,UAAW,MAAMN,EAAAA,YAAYO,CAAM,EAC3C,GAAI,CACA,IAAMC,EAAuB,CAAC,EAC9B,IAAK,IAAMC,KAAQC,EAAO,CACtB,IAAMC,EAAQ,KAAK,IAAI,EAAGF,EAAK,KAAO,KAAK,IAAIG,EAAO,MAAOA,EAAO,MAAM,CAAC,EACrEC,EAAQ,KAAK,IAAI,EAAG,KAAK,MAAMD,EAAO,MAAQD,CAAK,CAAC,EACpDG,EAAS,KAAK,IAAI,EAAG,KAAK,MAAMF,EAAO,OAASD,CAAK,CAAC,EAEtDI,EAAUd,EAAAA,cAAcY,EAAOC,CAAM,EAC3CX,EAAA,WAAWS,EAAQG,EAAS,CAAE,EAAG,EAAG,EAAG,EAAG,QAAO,QAAO,CAAC,EACzD,IAAMC,EAAU,MAAMd,EAAAA,YAAYa,EAAS,CAAE,GAAGE,EAAS,GAAGR,EAAK,MAAO,CAAC,EACzED,EAAQ,KAAK,CAAE,GAAGQ,EAAS,KAAMP,EAAK,IAAK,CAAC,CAChD,CACA,OAAOD,CACX,QAAU,CACNI,EAAO,QAAQ,CACnB,CACJ,C"}

package/dist/imaging/thumbnails.js.map

@@ -1 +1 @@
-{"version":3,"file":"thumbnails.js","names":[],"sources":["../../src/imaging/thumbnails.ts"],"sourcesContent":["/**\n * Producing several sizes from one decode.\n *\n * A gallery needs a grid thumbnail, a list avatar and a detail view. Doing\n * that with three `resizeImage` calls decodes the same photo three times,\n * which on a 12-megapixel picture is most of the cost — the decode dominates,\n * not the scaling.\n */\n\nimport { createSurface, drawScaled } from \"./canvas\";\nimport { decodeImage } from \"./decode\";\nimport { encodeImage } from \"./encode\";\nimport type { EncodeOptions, ImageSource, ProcessedImage } from \"./types\";\n\n/** One requested size. */\nexport interface ThumbnailSpec {\n    /** Name to find it by in the result. */\n    readonly name: string;\n    /** Longest edge in pixels. */\n    readonly size: number;\n    /** Format and quality, overriding the shared options. */\n    readonly encode?: EncodeOptions;\n}\n\n/** A produced thumbnail. */\nexport interface Thumbnail extends ProcessedImage {\n    readonly name: string;\n}\n\n/**\n * Produce several sizes from a single decode.\n *\n * @example\n * ```ts\n * const [thumb, card] = await createThumbnails(file, [\n *     { name: \"thumb\", size: 96 },\n *     { name: \"card\", size: 480 },\n * ]);\n * ```\n *\n * Sizes are the **longest edge**, and the aspect ratio is kept, so a\n * portrait and a landscape photo both fit the same grid cell without a\n * separate calculation per orientation.\n *\n * @param source Anything decodable.\n * @param specs The sizes to produce.\n * @param options Shared format and quality.\n * @returns One result per spec, in the order requested.\n * @throws {@link ImageDecodeError} when the source cannot be decoded.\n */\nexport async function createThumbnails(\n    source: ImageSource,\n    specs: readonly ThumbnailSpec[],\n    options: EncodeOptions = {},\n): Promise<Thumbnail[]> {\n    const { bitmap } = await decodeImage(source);\n    try {\n        const results: Thumbnail[] = [];\n        for (const spec of specs) {\n            const scale = Math.min(1, spec.size / Math.max(bitmap.width, bitmap.height));\n            const width = Math.max(1, Math.round(bitmap.width * scale));\n            const height = Math.max(1, Math.round(bitmap.height * scale));\n\n            const surface = createSurface(width, height);\n            drawScaled(bitmap, surface, { x: 0, y: 0, width, height });\n            const encoded = await encodeImage(surface, { ...options, ...spec.encode });\n            results.push({ ...encoded, name: spec.name });\n        }\n        return results;\n    } finally {\n        bitmap.close?.();\n    }\n}\n"],"mappings":";;;;AAkDA,eAAsB,EAClB,GACA,GACA,IAAyB,CAAC,GACN;CACpB,IAAM,EAAE,cAAW,MAAM,EAAY,CAAM;CAC3C,IAAI;EACA,IAAM,IAAuB,CAAC;EAC9B,KAAK,IAAM,KAAQ,GAAO;GACtB,IAAM,IAAQ,KAAK,IAAI,GAAG,EAAK,OAAO,KAAK,IAAI,EAAO,OAAO,EAAO,MAAM,CAAC,GACrE,IAAQ,KAAK,IAAI,GAAG,KAAK,MAAM,EAAO,QAAQ,CAAK,CAAC,GACpD,IAAS,KAAK,IAAI,GAAG,KAAK,MAAM,EAAO,SAAS,CAAK,CAAC,GAEtD,IAAU,EAAc,GAAO,CAAM;GAC3C,EAAW,GAAQ,GAAS;IAAE,GAAG;IAAG,GAAG;IAAG;IAAO;GAAO,CAAC;GACzD,IAAM,IAAU,MAAM,EAAY,GAAS;IAAE,GAAG;IAAS,GAAG,EAAK;GAAO,CAAC;GACzE,EAAQ,KAAK;IAAE,GAAG;IAAS,MAAM,EAAK;GAAK,CAAC;EAChD;EACA,OAAO;CACX,UAAU;EACN,EAAO,QAAQ;CACnB;AACJ"}
+{"version":3,"file":"thumbnails.js","names":["createThumbnails","decodeImage","source","results","spec","specs","scale","bitmap","width","height","surface","createSurface","encoded","encodeImage","options"],"sources":["../../src/imaging/thumbnails.ts"],"sourcesContent":["/**\n * Producing several sizes from one decode.\n *\n * A gallery needs a grid thumbnail, a list avatar and a detail view. Doing\n * that with three `resizeImage` calls decodes the same photo three times,\n * which on a 12-megapixel picture is most of the cost — the decode dominates,\n * not the scaling.\n */\n\nimport { createSurface, drawScaled } from \"./canvas\";\nimport { decodeImage } from \"./decode\";\nimport { encodeImage } from \"./encode\";\nimport type { EncodeOptions, ImageSource, ProcessedImage } from \"./types\";\n\n/** One requested size. */\nexport interface ThumbnailSpec {\n    /** Name to find it by in the result. */\n    readonly name: string;\n    /** Longest edge in pixels. */\n    readonly size: number;\n    /** Format and quality, overriding the shared options. */\n    readonly encode?: EncodeOptions;\n}\n\n/** A produced thumbnail. */\nexport interface Thumbnail extends ProcessedImage {\n    readonly name: string;\n}\n\n/**\n * Produce several sizes from a single decode.\n *\n * @example\n * ```ts\n * const [thumb, card] = await createThumbnails(file, [\n *     { name: \"thumb\", size: 96 },\n *     { name: \"card\", size: 480 },\n * ]);\n * ```\n *\n * Sizes are the **longest edge**, and the aspect ratio is kept, so a\n * portrait and a landscape photo both fit the same grid cell without a\n * separate calculation per orientation.\n *\n * @param source Anything decodable.\n * @param specs The sizes to produce.\n * @param options Shared format and quality.\n * @returns One result per spec, in the order requested.\n * @throws {@link ImageDecodeError} when the source cannot be decoded.\n */\nexport async function createThumbnails(\n    source: ImageSource,\n    specs: readonly ThumbnailSpec[],\n    options: EncodeOptions = {},\n): Promise<Thumbnail[]> {\n    const { bitmap } = await decodeImage(source);\n    try {\n        const results: Thumbnail[] = [];\n        for (const spec of specs) {\n            const scale = Math.min(1, spec.size / Math.max(bitmap.width, bitmap.height));\n            const width = Math.max(1, Math.round(bitmap.width * scale));\n            const height = Math.max(1, Math.round(bitmap.height * scale));\n\n            const surface = createSurface(width, height);\n            drawScaled(bitmap, surface, { x: 0, y: 0, width, height });\n            const encoded = await encodeImage(surface, { ...options, ...spec.encode });\n            results.push({ ...encoded, name: spec.name });\n        }\n        return results;\n    } finally {\n        bitmap.close?.();\n    }\n}\n"],"mappings":";;;;AAkDA,eAAsBA,EAClB,GACA,GACA,IAAyB,CAAC,GACN;CACpB,IAAM,EAAE,cAAW,MAAMC,EAAYC,CAAM;CAC3C,IAAI;EACA,IAAMC,IAAuB,CAAC;EAC9B,KAAK,IAAMC,KAAQC,GAAO;GACtB,IAAMC,IAAQ,KAAK,IAAI,GAAGF,EAAK,OAAO,KAAK,IAAIG,EAAO,OAAOA,EAAO,MAAM,CAAC,GACrEC,IAAQ,KAAK,IAAI,GAAG,KAAK,MAAMD,EAAO,QAAQD,CAAK,CAAC,GACpDG,IAAS,KAAK,IAAI,GAAG,KAAK,MAAMF,EAAO,SAASD,CAAK,CAAC,GAEtDI,IAAUC,EAAcH,GAAOC,CAAM;GAC3C,EAAWF,GAAQG,GAAS;IAAE,GAAG;IAAG,GAAG;IAAG;IAAO;GAAO,CAAC;GACzD,IAAME,IAAU,MAAMC,EAAYH,GAAS;IAAE,GAAGI;IAAS,GAAGV,EAAK;GAAO,CAAC;GACzE,EAAQ,KAAK;IAAE,GAAGQ;IAAS,MAAMR,EAAK;GAAK,CAAC;EAChD;EACA,OAAOD;CACX,UAAU;EACN,EAAO,QAAQ;CACnB;AACJ"}

package/dist/imaging/transform.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"transform.cjs","names":[],"sources":["../../src/imaging/transform.ts"],"sourcesContent":["/**\n * Resize, crop, rotate — the operations a PWA runs before an upload.\n *\n * Every one of them ends in a re-encode, which has a consequence worth\n * knowing: **the output carries no EXIF.** Location, camera serial and\n * timestamp do not survive a canvas round trip. For an app handling user\n * photos that is usually the point, and it is the reason `resizeImage` is\n * also the privacy step, not only the bandwidth step.\n */\n\nimport { createSurface, drawScaled, getContext } from \"./canvas\";\nimport { decodeImage } from \"./decode\";\nimport type {\n    CropRect,\n    EncodeOptions,\n    ImageSource,\n    ProcessedImage,\n    ResizeFit,\n    ResizeOptions,\n} from \"./types\";\nimport { encodeImage } from \"./encode\";\n\n/** Background used when a format cannot carry transparency. */\nexport const DEFAULT_BACKGROUND = \"#ffffff\";\n\n/** Formats that have no alpha channel. */\nconst OPAQUE_TYPES = new Set([\"image/jpeg\", \"image/jpg\"]);\n\n/**\n * Compute the drawing geometry for a fit mode.\n *\n * @param source Source dimensions.\n * @param box Requested box; a missing side is derived from the aspect ratio.\n * @param fit How to fit the box.\n * @param withoutEnlargement Never scale up.\n * @returns Surface size and where the image lands inside it.\n */\nfunction layout(\n    source: { width: number; height: number },\n    box: { width?: number; height?: number },\n    fit: ResizeFit,\n    withoutEnlargement: boolean,\n): {\n    surface: { width: number; height: number };\n    draw: { x: number; y: number; width: number; height: number };\n} {\n    const ratio = source.width / source.height;\n    let targetWidth = box.width ?? (box.height !== undefined ? box.height * ratio : source.width);\n    let targetHeight = box.height ?? (box.width !== undefined ? box.width / ratio : source.height);\n\n    if (withoutEnlargement) {\n        const scale = Math.min(1, source.width / targetWidth, source.height / targetHeight);\n        targetWidth *= scale;\n        targetHeight *= scale;\n    }\n\n    targetWidth = Math.max(1, Math.round(targetWidth));\n    targetHeight = Math.max(1, Math.round(targetHeight));\n\n    if (fit === \"fill\") {\n        return {\n            surface: { width: targetWidth, height: targetHeight },\n            draw: { x: 0, y: 0, width: targetWidth, height: targetHeight },\n        };\n    }\n\n    const scale =\n        fit === \"cover\"\n            ? Math.max(targetWidth / source.width, targetHeight / source.height)\n            : Math.min(targetWidth / source.width, targetHeight / source.height);\n\n    const drawWidth = Math.max(1, Math.round(source.width * scale));\n    const drawHeight = Math.max(1, Math.round(source.height * scale));\n\n    if (fit === \"contain\") {\n        return {\n            surface: { width: drawWidth, height: drawHeight },\n            draw: { x: 0, y: 0, width: drawWidth, height: drawHeight },\n        };\n    }\n\n    return {\n        surface: { width: targetWidth, height: targetHeight },\n        draw: {\n            x: Math.round((targetWidth - drawWidth) / 2),\n            y: Math.round((targetHeight - drawHeight) / 2),\n            width: drawWidth,\n            height: drawHeight,\n        },\n    };\n}\n\n/**\n * Resolve the background to paint before drawing.\n *\n * @param options The caller's options.\n * @returns A colour, or `undefined` to keep transparency.\n */\nfunction backgroundFor(options: ResizeOptions): string | undefined {\n    if (options.background !== undefined) return options.background;\n    const type = options.type ?? \"image/jpeg\";\n    if (OPAQUE_TYPES.has(type)) return DEFAULT_BACKGROUND;\n    return options.fit === \"pad\" ? DEFAULT_BACKGROUND : undefined;\n}\n\n/**\n * Resize an image, re-encoding it.\n *\n * @example\n * ```ts\n * const resized = await resizeImage(file, { width: 1600, type: \"image/webp\" });\n * console.log(resized.width, resized.bytes, resized.type);\n * ```\n *\n * @param source Anything decodable.\n * @param options Target box, fit, format and quality.\n * @returns The encoded result.\n * @throws {@link ImageDecodeError} when the source cannot be decoded.\n * @throws {@link ImageEncodeError} when the canvas produces no bytes.\n */\nexport async function resizeImage(\n    source: ImageSource,\n    options: ResizeOptions = {},\n): Promise<ProcessedImage> {\n    const { bitmap } = await decodeImage(source);\n    try {\n        const geometry = layout(\n            bitmap,\n            { width: options.width, height: options.height },\n            options.fit ?? \"contain\",\n            options.withoutEnlargement !== false,\n        );\n        const surface = createSurface(geometry.surface.width, geometry.surface.height);\n        drawScaled(bitmap, surface, geometry.draw, backgroundFor(options));\n        return await encodeImage(surface, options);\n    } finally {\n        bitmap.close?.();\n    }\n}\n\n/**\n * Crop a rectangle out of an image, in source pixels.\n *\n * The rectangle is clamped to the image, so a crop dragged past the edge\n * produces a smaller result instead of transparent padding.\n *\n * @example\n * ```ts\n * const badge = await cropImage(file, { x: 120, y: 80, width: 400, height: 400 });\n * ```\n *\n * @param source Anything decodable.\n * @param rect The region to keep.\n * @param options Format and quality.\n * @returns The encoded crop.\n * @throws {@link ImageDecodeError} when the source cannot be decoded.\n */\nexport async function cropImage(\n    source: ImageSource,\n    rect: CropRect,\n    options: EncodeOptions = {},\n): Promise<ProcessedImage> {\n    const { bitmap } = await decodeImage(source);\n    try {\n        const x = Math.max(0, Math.min(Math.round(rect.x), bitmap.width - 1));\n        const y = Math.max(0, Math.min(Math.round(rect.y), bitmap.height - 1));\n        const width = Math.max(1, Math.min(Math.round(rect.width), bitmap.width - x));\n        const height = Math.max(1, Math.min(Math.round(rect.height), bitmap.height - y));\n\n        const surface = createSurface(width, height);\n        const context = getContext(\n            surface,\n            OPAQUE_TYPES.has(options.type ?? \"image/jpeg\") ? DEFAULT_BACKGROUND : undefined,\n        );\n        context.drawImage(bitmap, x, y, width, height, 0, 0, width, height);\n        return await encodeImage(surface, options);\n    } finally {\n        bitmap.close?.();\n    }\n}\n\n/**\n * Rotate an image by a multiple of 90 degrees.\n *\n * Restricted to right angles on purpose: an arbitrary angle needs a\n * decision about the corners (crop, pad, or grow the canvas) that belongs\n * to the caller's design, not to a utility default.\n *\n * @example\n * ```ts\n * const upright = await rotateImage(file, 90);\n * ```\n *\n * @param source Anything decodable.\n * @param degrees `90`, `180`, `270` — or any multiple, normalised.\n * @param options Format and quality.\n * @returns The rotated image.\n * @throws {@link ImageDecodeError} when the source cannot be decoded.\n * @throws {@link RangeError} when the angle is not a multiple of 90.\n */\nexport async function rotateImage(\n    source: ImageSource,\n    degrees: number,\n    options: EncodeOptions = {},\n): Promise<ProcessedImage> {\n    if (degrees % 90 !== 0) {\n        throw new RangeError(\n            `rotateImage takes multiples of 90 degrees; got ${degrees}. For an ` +\n                \"arbitrary angle, draw it yourself: the corner handling is a design \" +\n                \"decision, not a default.\",\n        );\n    }\n    const turns = (((degrees / 90) % 4) + 4) % 4;\n    const { bitmap } = await decodeImage(source);\n    try {\n        const swapped = turns % 2 === 1;\n        const width = swapped ? bitmap.height : bitmap.width;\n        const height = swapped ? bitmap.width : bitmap.height;\n\n        const surface = createSurface(width, height);\n        const context = getContext(\n            surface,\n            OPAQUE_TYPES.has(options.type ?? \"image/jpeg\") ? DEFAULT_BACKGROUND : undefined,\n        );\n        context.translate(width / 2, height / 2);\n        context.rotate((turns * Math.PI) / 2);\n        context.drawImage(bitmap, -bitmap.width / 2, -bitmap.height / 2);\n        return await encodeImage(surface, options);\n    } finally {\n        bitmap.close?.();\n    }\n}\n\n/**\n * Mirror an image horizontally, vertically, or both.\n *\n * @example\n * ```ts\n * const selfie = await flipImage(capture, { horizontal: true });\n * ```\n *\n * @param source Anything decodable.\n * @param axes Which axes to mirror.\n * @param options Format and quality.\n * @returns The flipped image.\n * @throws {@link ImageDecodeError} when the source cannot be decoded.\n */\nexport async function flipImage(\n    source: ImageSource,\n    axes: { horizontal?: boolean; vertical?: boolean },\n    options: EncodeOptions = {},\n): Promise<ProcessedImage> {\n    const { bitmap } = await decodeImage(source);\n    try {\n        const surface = createSurface(bitmap.width, bitmap.height);\n        const context = getContext(\n            surface,\n            OPAQUE_TYPES.has(options.type ?? \"image/jpeg\") ? DEFAULT_BACKGROUND : undefined,\n        );\n        context.translate(\n            axes.horizontal === true ? bitmap.width : 0,\n            axes.vertical === true ? bitmap.height : 0,\n        );\n        context.scale(axes.horizontal === true ? -1 : 1, axes.vertical === true ? -1 : 1);\n        context.drawImage(bitmap, 0, 0);\n        return await encodeImage(surface, options);\n    } finally {\n        bitmap.close?.();\n    }\n}\n"],"mappings":"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"}
+{"version":3,"file":"transform.cjs","names":["decodeImage","createSurface","encodeImage","getContext","require_canvas","require_decode","require_encode","DEFAULT_BACKGROUND","OPAQUE_TYPES","layout","ratio","source","targetWidth","box","targetHeight","withoutEnlargement","scale","fit","drawWidth","drawHeight","backgroundFor","options","type","resizeImage","geometry","bitmap","surface","cropImage","x","rect","y","width","height","rotateImage","degrees","turns","swapped","context","flipImage","axes"],"sources":["../../src/imaging/transform.ts"],"sourcesContent":["/**\n * Resize, crop, rotate — the operations a PWA runs before an upload.\n *\n * Every one of them ends in a re-encode, which has a consequence worth\n * knowing: **the output carries no EXIF.** Location, camera serial and\n * timestamp do not survive a canvas round trip. For an app handling user\n * photos that is usually the point, and it is the reason `resizeImage` is\n * also the privacy step, not only the bandwidth step.\n */\n\nimport { createSurface, drawScaled, getContext } from \"./canvas\";\nimport { decodeImage } from \"./decode\";\nimport type {\n    CropRect,\n    EncodeOptions,\n    ImageSource,\n    ProcessedImage,\n    ResizeFit,\n    ResizeOptions,\n} from \"./types\";\nimport { encodeImage } from \"./encode\";\n\n/** Background used when a format cannot carry transparency. */\nexport const DEFAULT_BACKGROUND = \"#ffffff\";\n\n/** Formats that have no alpha channel. */\nconst OPAQUE_TYPES = new Set([\"image/jpeg\", \"image/jpg\"]);\n\n/**\n * Compute the drawing geometry for a fit mode.\n *\n * @param source Source dimensions.\n * @param box Requested box; a missing side is derived from the aspect ratio.\n * @param fit How to fit the box.\n * @param withoutEnlargement Never scale up.\n * @returns Surface size and where the image lands inside it.\n */\nfunction layout(\n    source: { width: number; height: number },\n    box: { width?: number; height?: number },\n    fit: ResizeFit,\n    withoutEnlargement: boolean,\n): {\n    surface: { width: number; height: number };\n    draw: { x: number; y: number; width: number; height: number };\n} {\n    const ratio = source.width / source.height;\n    let targetWidth = box.width ?? (box.height !== undefined ? box.height * ratio : source.width);\n    let targetHeight = box.height ?? (box.width !== undefined ? box.width / ratio : source.height);\n\n    if (withoutEnlargement) {\n        const scale = Math.min(1, source.width / targetWidth, source.height / targetHeight);\n        targetWidth *= scale;\n        targetHeight *= scale;\n    }\n\n    targetWidth = Math.max(1, Math.round(targetWidth));\n    targetHeight = Math.max(1, Math.round(targetHeight));\n\n    if (fit === \"fill\") {\n        return {\n            surface: { width: targetWidth, height: targetHeight },\n            draw: { x: 0, y: 0, width: targetWidth, height: targetHeight },\n        };\n    }\n\n    const scale =\n        fit === \"cover\"\n            ? Math.max(targetWidth / source.width, targetHeight / source.height)\n            : Math.min(targetWidth / source.width, targetHeight / source.height);\n\n    const drawWidth = Math.max(1, Math.round(source.width * scale));\n    const drawHeight = Math.max(1, Math.round(source.height * scale));\n\n    if (fit === \"contain\") {\n        return {\n            surface: { width: drawWidth, height: drawHeight },\n            draw: { x: 0, y: 0, width: drawWidth, height: drawHeight },\n        };\n    }\n\n    return {\n        surface: { width: targetWidth, height: targetHeight },\n        draw: {\n            x: Math.round((targetWidth - drawWidth) / 2),\n            y: Math.round((targetHeight - drawHeight) / 2),\n            width: drawWidth,\n            height: drawHeight,\n        },\n    };\n}\n\n/**\n * Resolve the background to paint before drawing.\n *\n * @param options The caller's options.\n * @returns A colour, or `undefined` to keep transparency.\n */\nfunction backgroundFor(options: ResizeOptions): string | undefined {\n    if (options.background !== undefined) return options.background;\n    const type = options.type ?? \"image/jpeg\";\n    if (OPAQUE_TYPES.has(type)) return DEFAULT_BACKGROUND;\n    return options.fit === \"pad\" ? DEFAULT_BACKGROUND : undefined;\n}\n\n/**\n * Resize an image, re-encoding it.\n *\n * @example\n * ```ts\n * const resized = await resizeImage(file, { width: 1600, type: \"image/webp\" });\n * console.log(resized.width, resized.bytes, resized.type);\n * ```\n *\n * @param source Anything decodable.\n * @param options Target box, fit, format and quality.\n * @returns The encoded result.\n * @throws {@link ImageDecodeError} when the source cannot be decoded.\n * @throws {@link ImageEncodeError} when the canvas produces no bytes.\n */\nexport async function resizeImage(\n    source: ImageSource,\n    options: ResizeOptions = {},\n): Promise<ProcessedImage> {\n    const { bitmap } = await decodeImage(source);\n    try {\n        const geometry = layout(\n            bitmap,\n            { width: options.width, height: options.height },\n            options.fit ?? \"contain\",\n            options.withoutEnlargement !== false,\n        );\n        const surface = createSurface(geometry.surface.width, geometry.surface.height);\n        drawScaled(bitmap, surface, geometry.draw, backgroundFor(options));\n        return await encodeImage(surface, options);\n    } finally {\n        bitmap.close?.();\n    }\n}\n\n/**\n * Crop a rectangle out of an image, in source pixels.\n *\n * The rectangle is clamped to the image, so a crop dragged past the edge\n * produces a smaller result instead of transparent padding.\n *\n * @example\n * ```ts\n * const badge = await cropImage(file, { x: 120, y: 80, width: 400, height: 400 });\n * ```\n *\n * @param source Anything decodable.\n * @param rect The region to keep.\n * @param options Format and quality.\n * @returns The encoded crop.\n * @throws {@link ImageDecodeError} when the source cannot be decoded.\n */\nexport async function cropImage(\n    source: ImageSource,\n    rect: CropRect,\n    options: EncodeOptions = {},\n): Promise<ProcessedImage> {\n    const { bitmap } = await decodeImage(source);\n    try {\n        const x = Math.max(0, Math.min(Math.round(rect.x), bitmap.width - 1));\n        const y = Math.max(0, Math.min(Math.round(rect.y), bitmap.height - 1));\n        const width = Math.max(1, Math.min(Math.round(rect.width), bitmap.width - x));\n        const height = Math.max(1, Math.min(Math.round(rect.height), bitmap.height - y));\n\n        const surface = createSurface(width, height);\n        const context = getContext(\n            surface,\n            OPAQUE_TYPES.has(options.type ?? \"image/jpeg\") ? DEFAULT_BACKGROUND : undefined,\n        );\n        context.drawImage(bitmap, x, y, width, height, 0, 0, width, height);\n        return await encodeImage(surface, options);\n    } finally {\n        bitmap.close?.();\n    }\n}\n\n/**\n * Rotate an image by a multiple of 90 degrees.\n *\n * Restricted to right angles on purpose: an arbitrary angle needs a\n * decision about the corners (crop, pad, or grow the canvas) that belongs\n * to the caller's design, not to a utility default.\n *\n * @example\n * ```ts\n * const upright = await rotateImage(file, 90);\n * ```\n *\n * @param source Anything decodable.\n * @param degrees `90`, `180`, `270` — or any multiple, normalised.\n * @param options Format and quality.\n * @returns The rotated image.\n * @throws {@link ImageDecodeError} when the source cannot be decoded.\n * @throws {@link RangeError} when the angle is not a multiple of 90.\n */\nexport async function rotateImage(\n    source: ImageSource,\n    degrees: number,\n    options: EncodeOptions = {},\n): Promise<ProcessedImage> {\n    if (degrees % 90 !== 0) {\n        throw new RangeError(\n            `rotateImage takes multiples of 90 degrees; got ${degrees}. For an ` +\n                \"arbitrary angle, draw it yourself: the corner handling is a design \" +\n                \"decision, not a default.\",\n        );\n    }\n    const turns = (((degrees / 90) % 4) + 4) % 4;\n    const { bitmap } = await decodeImage(source);\n    try {\n        const swapped = turns % 2 === 1;\n        const width = swapped ? bitmap.height : bitmap.width;\n        const height = swapped ? bitmap.width : bitmap.height;\n\n        const surface = createSurface(width, height);\n        const context = getContext(\n            surface,\n            OPAQUE_TYPES.has(options.type ?? \"image/jpeg\") ? DEFAULT_BACKGROUND : undefined,\n        );\n        context.translate(width / 2, height / 2);\n        context.rotate((turns * Math.PI) / 2);\n        context.drawImage(bitmap, -bitmap.width / 2, -bitmap.height / 2);\n        return await encodeImage(surface, options);\n    } finally {\n        bitmap.close?.();\n    }\n}\n\n/**\n * Mirror an image horizontally, vertically, or both.\n *\n * @example\n * ```ts\n * const selfie = await flipImage(capture, { horizontal: true });\n * ```\n *\n * @param source Anything decodable.\n * @param axes Which axes to mirror.\n * @param options Format and quality.\n * @returns The flipped image.\n * @throws {@link ImageDecodeError} when the source cannot be decoded.\n */\nexport async function flipImage(\n    source: ImageSource,\n    axes: { horizontal?: boolean; vertical?: boolean },\n    options: EncodeOptions = {},\n): Promise<ProcessedImage> {\n    const { bitmap } = await decodeImage(source);\n    try {\n        const surface = createSurface(bitmap.width, bitmap.height);\n        const context = getContext(\n            surface,\n            OPAQUE_TYPES.has(options.type ?? \"image/jpeg\") ? DEFAULT_BACKGROUND : undefined,\n        );\n        context.translate(\n            axes.horizontal === true ? bitmap.width : 0,\n            axes.vertical === true ? bitmap.height : 0,\n        );\n        context.scale(axes.horizontal === true ? -1 : 1, axes.vertical === true ? -1 : 1);\n        context.drawImage(bitmap, 0, 0);\n        return await encodeImage(surface, options);\n    } finally {\n        bitmap.close?.();\n    }\n}\n"],"mappings":"A,oFAuBA,IAAaO,EAAqB,UAG5BC,EAAe,IAAI,IAAI,CAAC,aAAc,WAAW,CAAC,EAWxD,SAASC,EACL,EACA,EACA,EACA,EAIF,CACE,IAAMC,EAAQC,EAAO,MAAQA,EAAO,OAChCC,EAAcC,EAAI,QAAUA,EAAI,SAAW,IAAA,GAAiCF,EAAO,MAA5BE,EAAI,OAASH,GACpEI,EAAeD,EAAI,SAAWA,EAAI,QAAU,IAAA,GAAgCF,EAAO,OAA3BE,EAAI,MAAQH,GAExE,GAAIK,EAAoB,CACpB,IAAMC,EAAQ,KAAK,IAAI,EAAGL,EAAO,MAAQC,EAAaD,EAAO,OAASG,CAAY,EAClF,GAAeE,EACf,GAAgBA,CACpB,CAKA,GAHA,EAAc,KAAK,IAAI,EAAG,KAAK,MAAMJ,CAAW,CAAC,EACjD,EAAe,KAAK,IAAI,EAAG,KAAK,MAAME,CAAY,CAAC,EAE/CG,IAAQ,OACR,MAAO,CACH,QAAS,CAAE,MAAOL,EAAa,OAAQE,CAAa,EACpD,KAAM,CAAE,EAAG,EAAG,EAAG,EAAG,MAAOF,EAAa,OAAQE,CAAa,CACjE,EAGJ,IAAME,EACFC,IAAQ,QACF,KAAK,IAAIL,EAAcD,EAAO,MAAOG,EAAeH,EAAO,MAAM,EACjE,KAAK,IAAIC,EAAcD,EAAO,MAAOG,EAAeH,EAAO,MAAM,EAErEO,EAAY,KAAK,IAAI,EAAG,KAAK,MAAMP,EAAO,MAAQK,CAAK,CAAC,EACxDG,EAAa,KAAK,IAAI,EAAG,KAAK,MAAMR,EAAO,OAASK,CAAK,CAAC,EAShE,OAPIC,IAAQ,UACD,CACH,QAAS,CAAE,MAAOC,EAAW,OAAQC,CAAW,EAChD,KAAM,CAAE,EAAG,EAAG,EAAG,EAAG,MAAOD,EAAW,OAAQC,CAAW,CAC7D,EAGG,CACH,QAAS,CAAE,MAAOP,EAAa,OAAQE,CAAa,EACpD,KAAM,CACF,EAAG,KAAK,OAAOF,EAAcM,GAAa,CAAC,EAC3C,EAAG,KAAK,OAAOJ,EAAeK,GAAc,CAAC,EAC7C,MAAOD,EACP,OAAQC,CACZ,CACJ,CACJ,CAQA,SAASC,EAAc,EAA4C,CAC/D,GAAIC,EAAQ,aAAe,IAAA,GAAW,OAAOA,EAAQ,WACrD,IAAMC,EAAOD,EAAQ,MAAQ,aAE7B,OADIb,EAAa,IAAIc,CAAI,GAClBD,EAAQ,MAAQ,MADYd,EACiB,IAAA,EACxD,CAiBA,eAAsBgB,EAClB,EACA,EAAyB,CAAC,EACH,CACvB,GAAM,CAAE,UAAW,MAAMvB,EAAAA,YAAYW,CAAM,EAC3C,GAAI,CACA,IAAMa,EAAWf,EACbgB,EACA,CAAE,MAAOJ,EAAQ,MAAO,OAAQA,EAAQ,MAAO,EAC/CA,EAAQ,KAAO,UACfA,EAAQ,qBAAuB,EACnC,EACMK,EAAUzB,EAAAA,cAAcuB,EAAS,QAAQ,MAAOA,EAAS,QAAQ,MAAM,EAE7E,OADApB,EAAA,WAAWqB,EAAQC,EAASF,EAAS,KAAMJ,EAAcC,CAAO,CAAC,EAC1D,MAAMnB,EAAAA,YAAYwB,EAASL,CAAO,CAC7C,QAAU,CACNI,EAAO,QAAQ,CACnB,CACJ,CAmBA,eAAsBE,EAClB,EACA,EACA,EAAyB,CAAC,EACH,CACvB,GAAM,CAAE,UAAW,MAAM3B,EAAAA,YAAYW,CAAM,EAC3C,GAAI,CACA,IAAMiB,EAAI,KAAK,IAAI,EAAG,KAAK,IAAI,KAAK,MAAMC,EAAK,CAAC,EAAGJ,EAAO,MAAQ,CAAC,CAAC,EAC9DK,EAAI,KAAK,IAAI,EAAG,KAAK,IAAI,KAAK,MAAMD,EAAK,CAAC,EAAGJ,EAAO,OAAS,CAAC,CAAC,EAC/DM,EAAQ,KAAK,IAAI,EAAG,KAAK,IAAI,KAAK,MAAMF,EAAK,KAAK,EAAGJ,EAAO,MAAQG,CAAC,CAAC,EACtEI,EAAS,KAAK,IAAI,EAAG,KAAK,IAAI,KAAK,MAAMH,EAAK,MAAM,EAAGJ,EAAO,OAASK,CAAC,CAAC,EAEzEJ,EAAUzB,EAAAA,cAAc8B,EAAOC,CAAM,EAM3C,OADA5B,EAJgBD,WACZuB,EACAlB,EAAa,IAAIa,EAAQ,MAAQ,YAAY,EAAId,EAAqB,IAAA,EAE1E,CAAA,CAAQ,UAAUkB,EAAQG,EAAGE,EAAGC,EAAOC,EAAQ,EAAG,EAAGD,EAAOC,CAAM,EAC3D,MAAM9B,EAAAA,YAAYwB,EAASL,CAAO,CAC7C,QAAU,CACNI,EAAO,QAAQ,CACnB,CACJ,CAqBA,eAAsBQ,EAClB,EACA,EACA,EAAyB,CAAC,EACH,CACvB,GAAIC,EAAU,IAAO,EACjB,MAAU,WACN,kDAAkDA,EAAQ,qGAG9D,EAEJ,IAAMC,GAAWD,EAAU,GAAM,EAAK,GAAK,EACrC,CAAE,UAAW,MAAMlC,EAAAA,YAAYW,CAAM,EAC3C,GAAI,CACA,IAAMyB,EAAUD,EAAQ,GAAM,EACxBJ,EAAQK,EAAUX,EAAO,OAASA,EAAO,MACzCO,EAASI,EAAUX,EAAO,MAAQA,EAAO,OAEzCC,EAAUzB,EAAAA,cAAc8B,EAAOC,CAAM,EACrCK,EAAUlC,EAAAA,WACZuB,EACAlB,EAAa,IAAIa,EAAQ,MAAQ,YAAY,EAAId,EAAqB,IAAA,EAC1E,EAIA,OAHA8B,EAAQ,UAAUN,EAAQ,EAAGC,EAAS,CAAC,EACvCK,EAAQ,OAAQF,EAAQ,KAAK,GAAM,CAAC,EACpCE,EAAQ,UAAUZ,EAAQ,CAACA,EAAO,MAAQ,EAAG,CAACA,EAAO,OAAS,CAAC,EACxD,MAAMvB,EAAAA,YAAYwB,EAASL,CAAO,CAC7C,QAAU,CACNI,EAAO,QAAQ,CACnB,CACJ,CAgBA,eAAsBa,EAClB,EACA,EACA,EAAyB,CAAC,EACH,CACvB,GAAM,CAAE,UAAW,MAAMtC,EAAAA,YAAYW,CAAM,EAC3C,GAAI,CACA,IAAMe,EAAUzB,EAAAA,cAAcwB,EAAO,MAAOA,EAAO,MAAM,EACnDY,EAAUlC,EAAAA,WACZuB,EACAlB,EAAa,IAAIa,EAAQ,MAAQ,YAAY,EAAId,EAAqB,IAAA,EAC1E,EAOA,OANA8B,EAAQ,UACJE,EAAK,aAAe,GAAOd,EAAO,MAAQ,EAC1Cc,EAAK,WAAa,GAAOd,EAAO,OAAS,CAC7C,EACAY,EAAQ,MAAME,EAAK,aAAe,GAAO,GAAK,EAAGA,EAAK,WAAa,GAAO,GAAK,CAAC,EAChFF,EAAQ,UAAUZ,EAAQ,EAAG,CAAC,EACvB,MAAMvB,EAAAA,YAAYwB,EAASL,CAAO,CAC7C,QAAU,CACNI,EAAO,QAAQ,CACnB,CACJ,C"}

package/dist/imaging/transform.js.map

@@ -1 +1 @@
-{"version":3,"file":"transform.js","names":[],"sources":["../../src/imaging/transform.ts"],"sourcesContent":["/**\n * Resize, crop, rotate — the operations a PWA runs before an upload.\n *\n * Every one of them ends in a re-encode, which has a consequence worth\n * knowing: **the output carries no EXIF.** Location, camera serial and\n * timestamp do not survive a canvas round trip. For an app handling user\n * photos that is usually the point, and it is the reason `resizeImage` is\n * also the privacy step, not only the bandwidth step.\n */\n\nimport { createSurface, drawScaled, getContext } from \"./canvas\";\nimport { decodeImage } from \"./decode\";\nimport type {\n    CropRect,\n    EncodeOptions,\n    ImageSource,\n    ProcessedImage,\n    ResizeFit,\n    ResizeOptions,\n} from \"./types\";\nimport { encodeImage } from \"./encode\";\n\n/** Background used when a format cannot carry transparency. */\nexport const DEFAULT_BACKGROUND = \"#ffffff\";\n\n/** Formats that have no alpha channel. */\nconst OPAQUE_TYPES = new Set([\"image/jpeg\", \"image/jpg\"]);\n\n/**\n * Compute the drawing geometry for a fit mode.\n *\n * @param source Source dimensions.\n * @param box Requested box; a missing side is derived from the aspect ratio.\n * @param fit How to fit the box.\n * @param withoutEnlargement Never scale up.\n * @returns Surface size and where the image lands inside it.\n */\nfunction layout(\n    source: { width: number; height: number },\n    box: { width?: number; height?: number },\n    fit: ResizeFit,\n    withoutEnlargement: boolean,\n): {\n    surface: { width: number; height: number };\n    draw: { x: number; y: number; width: number; height: number };\n} {\n    const ratio = source.width / source.height;\n    let targetWidth = box.width ?? (box.height !== undefined ? box.height * ratio : source.width);\n    let targetHeight = box.height ?? (box.width !== undefined ? box.width / ratio : source.height);\n\n    if (withoutEnlargement) {\n        const scale = Math.min(1, source.width / targetWidth, source.height / targetHeight);\n        targetWidth *= scale;\n        targetHeight *= scale;\n    }\n\n    targetWidth = Math.max(1, Math.round(targetWidth));\n    targetHeight = Math.max(1, Math.round(targetHeight));\n\n    if (fit === \"fill\") {\n        return {\n            surface: { width: targetWidth, height: targetHeight },\n            draw: { x: 0, y: 0, width: targetWidth, height: targetHeight },\n        };\n    }\n\n    const scale =\n        fit === \"cover\"\n            ? Math.max(targetWidth / source.width, targetHeight / source.height)\n            : Math.min(targetWidth / source.width, targetHeight / source.height);\n\n    const drawWidth = Math.max(1, Math.round(source.width * scale));\n    const drawHeight = Math.max(1, Math.round(source.height * scale));\n\n    if (fit === \"contain\") {\n        return {\n            surface: { width: drawWidth, height: drawHeight },\n            draw: { x: 0, y: 0, width: drawWidth, height: drawHeight },\n        };\n    }\n\n    return {\n        surface: { width: targetWidth, height: targetHeight },\n        draw: {\n            x: Math.round((targetWidth - drawWidth) / 2),\n            y: Math.round((targetHeight - drawHeight) / 2),\n            width: drawWidth,\n            height: drawHeight,\n        },\n    };\n}\n\n/**\n * Resolve the background to paint before drawing.\n *\n * @param options The caller's options.\n * @returns A colour, or `undefined` to keep transparency.\n */\nfunction backgroundFor(options: ResizeOptions): string | undefined {\n    if (options.background !== undefined) return options.background;\n    const type = options.type ?? \"image/jpeg\";\n    if (OPAQUE_TYPES.has(type)) return DEFAULT_BACKGROUND;\n    return options.fit === \"pad\" ? DEFAULT_BACKGROUND : undefined;\n}\n\n/**\n * Resize an image, re-encoding it.\n *\n * @example\n * ```ts\n * const resized = await resizeImage(file, { width: 1600, type: \"image/webp\" });\n * console.log(resized.width, resized.bytes, resized.type);\n * ```\n *\n * @param source Anything decodable.\n * @param options Target box, fit, format and quality.\n * @returns The encoded result.\n * @throws {@link ImageDecodeError} when the source cannot be decoded.\n * @throws {@link ImageEncodeError} when the canvas produces no bytes.\n */\nexport async function resizeImage(\n    source: ImageSource,\n    options: ResizeOptions = {},\n): Promise<ProcessedImage> {\n    const { bitmap } = await decodeImage(source);\n    try {\n        const geometry = layout(\n            bitmap,\n            { width: options.width, height: options.height },\n            options.fit ?? \"contain\",\n            options.withoutEnlargement !== false,\n        );\n        const surface = createSurface(geometry.surface.width, geometry.surface.height);\n        drawScaled(bitmap, surface, geometry.draw, backgroundFor(options));\n        return await encodeImage(surface, options);\n    } finally {\n        bitmap.close?.();\n    }\n}\n\n/**\n * Crop a rectangle out of an image, in source pixels.\n *\n * The rectangle is clamped to the image, so a crop dragged past the edge\n * produces a smaller result instead of transparent padding.\n *\n * @example\n * ```ts\n * const badge = await cropImage(file, { x: 120, y: 80, width: 400, height: 400 });\n * ```\n *\n * @param source Anything decodable.\n * @param rect The region to keep.\n * @param options Format and quality.\n * @returns The encoded crop.\n * @throws {@link ImageDecodeError} when the source cannot be decoded.\n */\nexport async function cropImage(\n    source: ImageSource,\n    rect: CropRect,\n    options: EncodeOptions = {},\n): Promise<ProcessedImage> {\n    const { bitmap } = await decodeImage(source);\n    try {\n        const x = Math.max(0, Math.min(Math.round(rect.x), bitmap.width - 1));\n        const y = Math.max(0, Math.min(Math.round(rect.y), bitmap.height - 1));\n        const width = Math.max(1, Math.min(Math.round(rect.width), bitmap.width - x));\n        const height = Math.max(1, Math.min(Math.round(rect.height), bitmap.height - y));\n\n        const surface = createSurface(width, height);\n        const context = getContext(\n            surface,\n            OPAQUE_TYPES.has(options.type ?? \"image/jpeg\") ? DEFAULT_BACKGROUND : undefined,\n        );\n        context.drawImage(bitmap, x, y, width, height, 0, 0, width, height);\n        return await encodeImage(surface, options);\n    } finally {\n        bitmap.close?.();\n    }\n}\n\n/**\n * Rotate an image by a multiple of 90 degrees.\n *\n * Restricted to right angles on purpose: an arbitrary angle needs a\n * decision about the corners (crop, pad, or grow the canvas) that belongs\n * to the caller's design, not to a utility default.\n *\n * @example\n * ```ts\n * const upright = await rotateImage(file, 90);\n * ```\n *\n * @param source Anything decodable.\n * @param degrees `90`, `180`, `270` — or any multiple, normalised.\n * @param options Format and quality.\n * @returns The rotated image.\n * @throws {@link ImageDecodeError} when the source cannot be decoded.\n * @throws {@link RangeError} when the angle is not a multiple of 90.\n */\nexport async function rotateImage(\n    source: ImageSource,\n    degrees: number,\n    options: EncodeOptions = {},\n): Promise<ProcessedImage> {\n    if (degrees % 90 !== 0) {\n        throw new RangeError(\n            `rotateImage takes multiples of 90 degrees; got ${degrees}. For an ` +\n                \"arbitrary angle, draw it yourself: the corner handling is a design \" +\n                \"decision, not a default.\",\n        );\n    }\n    const turns = (((degrees / 90) % 4) + 4) % 4;\n    const { bitmap } = await decodeImage(source);\n    try {\n        const swapped = turns % 2 === 1;\n        const width = swapped ? bitmap.height : bitmap.width;\n        const height = swapped ? bitmap.width : bitmap.height;\n\n        const surface = createSurface(width, height);\n        const context = getContext(\n            surface,\n            OPAQUE_TYPES.has(options.type ?? \"image/jpeg\") ? DEFAULT_BACKGROUND : undefined,\n        );\n        context.translate(width / 2, height / 2);\n        context.rotate((turns * Math.PI) / 2);\n        context.drawImage(bitmap, -bitmap.width / 2, -bitmap.height / 2);\n        return await encodeImage(surface, options);\n    } finally {\n        bitmap.close?.();\n    }\n}\n\n/**\n * Mirror an image horizontally, vertically, or both.\n *\n * @example\n * ```ts\n * const selfie = await flipImage(capture, { horizontal: true });\n * ```\n *\n * @param source Anything decodable.\n * @param axes Which axes to mirror.\n * @param options Format and quality.\n * @returns The flipped image.\n * @throws {@link ImageDecodeError} when the source cannot be decoded.\n */\nexport async function flipImage(\n    source: ImageSource,\n    axes: { horizontal?: boolean; vertical?: boolean },\n    options: EncodeOptions = {},\n): Promise<ProcessedImage> {\n    const { bitmap } = await decodeImage(source);\n    try {\n        const surface = createSurface(bitmap.width, bitmap.height);\n        const context = getContext(\n            surface,\n            OPAQUE_TYPES.has(options.type ?? \"image/jpeg\") ? DEFAULT_BACKGROUND : undefined,\n        );\n        context.translate(\n            axes.horizontal === true ? bitmap.width : 0,\n            axes.vertical === true ? bitmap.height : 0,\n        );\n        context.scale(axes.horizontal === true ? -1 : 1, axes.vertical === true ? -1 : 1);\n        context.drawImage(bitmap, 0, 0);\n        return await encodeImage(surface, options);\n    } finally {\n        bitmap.close?.();\n    }\n}\n"],"mappings":"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"}
+{"version":3,"file":"transform.js","names":["DEFAULT_BACKGROUND","OPAQUE_TYPES","layout","ratio","source","targetWidth","box","targetHeight","withoutEnlargement","scale","fit","drawWidth","drawHeight","backgroundFor","options","type","resizeImage","decodeImage","geometry","bitmap","surface","createSurface","drawScaled","encodeImage","cropImage","x","rect","y","width","height","getContext","rotateImage","degrees","turns","swapped","context","flipImage","axes"],"sources":["../../src/imaging/transform.ts"],"sourcesContent":["/**\n * Resize, crop, rotate — the operations a PWA runs before an upload.\n *\n * Every one of them ends in a re-encode, which has a consequence worth\n * knowing: **the output carries no EXIF.** Location, camera serial and\n * timestamp do not survive a canvas round trip. For an app handling user\n * photos that is usually the point, and it is the reason `resizeImage` is\n * also the privacy step, not only the bandwidth step.\n */\n\nimport { createSurface, drawScaled, getContext } from \"./canvas\";\nimport { decodeImage } from \"./decode\";\nimport type {\n    CropRect,\n    EncodeOptions,\n    ImageSource,\n    ProcessedImage,\n    ResizeFit,\n    ResizeOptions,\n} from \"./types\";\nimport { encodeImage } from \"./encode\";\n\n/** Background used when a format cannot carry transparency. */\nexport const DEFAULT_BACKGROUND = \"#ffffff\";\n\n/** Formats that have no alpha channel. */\nconst OPAQUE_TYPES = new Set([\"image/jpeg\", \"image/jpg\"]);\n\n/**\n * Compute the drawing geometry for a fit mode.\n *\n * @param source Source dimensions.\n * @param box Requested box; a missing side is derived from the aspect ratio.\n * @param fit How to fit the box.\n * @param withoutEnlargement Never scale up.\n * @returns Surface size and where the image lands inside it.\n */\nfunction layout(\n    source: { width: number; height: number },\n    box: { width?: number; height?: number },\n    fit: ResizeFit,\n    withoutEnlargement: boolean,\n): {\n    surface: { width: number; height: number };\n    draw: { x: number; y: number; width: number; height: number };\n} {\n    const ratio = source.width / source.height;\n    let targetWidth = box.width ?? (box.height !== undefined ? box.height * ratio : source.width);\n    let targetHeight = box.height ?? (box.width !== undefined ? box.width / ratio : source.height);\n\n    if (withoutEnlargement) {\n        const scale = Math.min(1, source.width / targetWidth, source.height / targetHeight);\n        targetWidth *= scale;\n        targetHeight *= scale;\n    }\n\n    targetWidth = Math.max(1, Math.round(targetWidth));\n    targetHeight = Math.max(1, Math.round(targetHeight));\n\n    if (fit === \"fill\") {\n        return {\n            surface: { width: targetWidth, height: targetHeight },\n            draw: { x: 0, y: 0, width: targetWidth, height: targetHeight },\n        };\n    }\n\n    const scale =\n        fit === \"cover\"\n            ? Math.max(targetWidth / source.width, targetHeight / source.height)\n            : Math.min(targetWidth / source.width, targetHeight / source.height);\n\n    const drawWidth = Math.max(1, Math.round(source.width * scale));\n    const drawHeight = Math.max(1, Math.round(source.height * scale));\n\n    if (fit === \"contain\") {\n        return {\n            surface: { width: drawWidth, height: drawHeight },\n            draw: { x: 0, y: 0, width: drawWidth, height: drawHeight },\n        };\n    }\n\n    return {\n        surface: { width: targetWidth, height: targetHeight },\n        draw: {\n            x: Math.round((targetWidth - drawWidth) / 2),\n            y: Math.round((targetHeight - drawHeight) / 2),\n            width: drawWidth,\n            height: drawHeight,\n        },\n    };\n}\n\n/**\n * Resolve the background to paint before drawing.\n *\n * @param options The caller's options.\n * @returns A colour, or `undefined` to keep transparency.\n */\nfunction backgroundFor(options: ResizeOptions): string | undefined {\n    if (options.background !== undefined) return options.background;\n    const type = options.type ?? \"image/jpeg\";\n    if (OPAQUE_TYPES.has(type)) return DEFAULT_BACKGROUND;\n    return options.fit === \"pad\" ? DEFAULT_BACKGROUND : undefined;\n}\n\n/**\n * Resize an image, re-encoding it.\n *\n * @example\n * ```ts\n * const resized = await resizeImage(file, { width: 1600, type: \"image/webp\" });\n * console.log(resized.width, resized.bytes, resized.type);\n * ```\n *\n * @param source Anything decodable.\n * @param options Target box, fit, format and quality.\n * @returns The encoded result.\n * @throws {@link ImageDecodeError} when the source cannot be decoded.\n * @throws {@link ImageEncodeError} when the canvas produces no bytes.\n */\nexport async function resizeImage(\n    source: ImageSource,\n    options: ResizeOptions = {},\n): Promise<ProcessedImage> {\n    const { bitmap } = await decodeImage(source);\n    try {\n        const geometry = layout(\n            bitmap,\n            { width: options.width, height: options.height },\n            options.fit ?? \"contain\",\n            options.withoutEnlargement !== false,\n        );\n        const surface = createSurface(geometry.surface.width, geometry.surface.height);\n        drawScaled(bitmap, surface, geometry.draw, backgroundFor(options));\n        return await encodeImage(surface, options);\n    } finally {\n        bitmap.close?.();\n    }\n}\n\n/**\n * Crop a rectangle out of an image, in source pixels.\n *\n * The rectangle is clamped to the image, so a crop dragged past the edge\n * produces a smaller result instead of transparent padding.\n *\n * @example\n * ```ts\n * const badge = await cropImage(file, { x: 120, y: 80, width: 400, height: 400 });\n * ```\n *\n * @param source Anything decodable.\n * @param rect The region to keep.\n * @param options Format and quality.\n * @returns The encoded crop.\n * @throws {@link ImageDecodeError} when the source cannot be decoded.\n */\nexport async function cropImage(\n    source: ImageSource,\n    rect: CropRect,\n    options: EncodeOptions = {},\n): Promise<ProcessedImage> {\n    const { bitmap } = await decodeImage(source);\n    try {\n        const x = Math.max(0, Math.min(Math.round(rect.x), bitmap.width - 1));\n        const y = Math.max(0, Math.min(Math.round(rect.y), bitmap.height - 1));\n        const width = Math.max(1, Math.min(Math.round(rect.width), bitmap.width - x));\n        const height = Math.max(1, Math.min(Math.round(rect.height), bitmap.height - y));\n\n        const surface = createSurface(width, height);\n        const context = getContext(\n            surface,\n            OPAQUE_TYPES.has(options.type ?? \"image/jpeg\") ? DEFAULT_BACKGROUND : undefined,\n        );\n        context.drawImage(bitmap, x, y, width, height, 0, 0, width, height);\n        return await encodeImage(surface, options);\n    } finally {\n        bitmap.close?.();\n    }\n}\n\n/**\n * Rotate an image by a multiple of 90 degrees.\n *\n * Restricted to right angles on purpose: an arbitrary angle needs a\n * decision about the corners (crop, pad, or grow the canvas) that belongs\n * to the caller's design, not to a utility default.\n *\n * @example\n * ```ts\n * const upright = await rotateImage(file, 90);\n * ```\n *\n * @param source Anything decodable.\n * @param degrees `90`, `180`, `270` — or any multiple, normalised.\n * @param options Format and quality.\n * @returns The rotated image.\n * @throws {@link ImageDecodeError} when the source cannot be decoded.\n * @throws {@link RangeError} when the angle is not a multiple of 90.\n */\nexport async function rotateImage(\n    source: ImageSource,\n    degrees: number,\n    options: EncodeOptions = {},\n): Promise<ProcessedImage> {\n    if (degrees % 90 !== 0) {\n        throw new RangeError(\n            `rotateImage takes multiples of 90 degrees; got ${degrees}. For an ` +\n                \"arbitrary angle, draw it yourself: the corner handling is a design \" +\n                \"decision, not a default.\",\n        );\n    }\n    const turns = (((degrees / 90) % 4) + 4) % 4;\n    const { bitmap } = await decodeImage(source);\n    try {\n        const swapped = turns % 2 === 1;\n        const width = swapped ? bitmap.height : bitmap.width;\n        const height = swapped ? bitmap.width : bitmap.height;\n\n        const surface = createSurface(width, height);\n        const context = getContext(\n            surface,\n            OPAQUE_TYPES.has(options.type ?? \"image/jpeg\") ? DEFAULT_BACKGROUND : undefined,\n        );\n        context.translate(width / 2, height / 2);\n        context.rotate((turns * Math.PI) / 2);\n        context.drawImage(bitmap, -bitmap.width / 2, -bitmap.height / 2);\n        return await encodeImage(surface, options);\n    } finally {\n        bitmap.close?.();\n    }\n}\n\n/**\n * Mirror an image horizontally, vertically, or both.\n *\n * @example\n * ```ts\n * const selfie = await flipImage(capture, { horizontal: true });\n * ```\n *\n * @param source Anything decodable.\n * @param axes Which axes to mirror.\n * @param options Format and quality.\n * @returns The flipped image.\n * @throws {@link ImageDecodeError} when the source cannot be decoded.\n */\nexport async function flipImage(\n    source: ImageSource,\n    axes: { horizontal?: boolean; vertical?: boolean },\n    options: EncodeOptions = {},\n): Promise<ProcessedImage> {\n    const { bitmap } = await decodeImage(source);\n    try {\n        const surface = createSurface(bitmap.width, bitmap.height);\n        const context = getContext(\n            surface,\n            OPAQUE_TYPES.has(options.type ?? \"image/jpeg\") ? DEFAULT_BACKGROUND : undefined,\n        );\n        context.translate(\n            axes.horizontal === true ? bitmap.width : 0,\n            axes.vertical === true ? bitmap.height : 0,\n        );\n        context.scale(axes.horizontal === true ? -1 : 1, axes.vertical === true ? -1 : 1);\n        context.drawImage(bitmap, 0, 0);\n        return await encodeImage(surface, options);\n    } finally {\n        bitmap.close?.();\n    }\n}\n"],"mappings":";;;;AAuBA,IAAaA,IAAqB,WAG5BC,oBAAe,IAAI,IAAI,CAAC,cAAc,WAAW,CAAC;AAWxD,SAASC,EACL,GACA,GACA,GACA,GAIF;CACE,IAAMC,IAAQC,EAAO,QAAQA,EAAO,QAChCC,IAAcC,EAAI,UAAUA,EAAI,WAAW,KAAA,IAAiCF,EAAO,QAA5BE,EAAI,SAASH,IACpEI,IAAeD,EAAI,WAAWA,EAAI,UAAU,KAAA,IAAgCF,EAAO,SAA3BE,EAAI,QAAQH;CAExE,IAAIK,GAAoB;EACpB,IAAMC,IAAQ,KAAK,IAAI,GAAGL,EAAO,QAAQC,GAAaD,EAAO,SAASG,CAAY;EAElF,AADA,KAAeE,GACf,KAAgBA;CACpB;CAKA,IAHA,IAAc,KAAK,IAAI,GAAG,KAAK,MAAMJ,CAAW,CAAC,GACjD,IAAe,KAAK,IAAI,GAAG,KAAK,MAAME,CAAY,CAAC,GAE/CG,MAAQ,QACR,OAAO;EACH,SAAS;GAAE,OAAOL;GAAa,QAAQE;EAAa;EACpD,MAAM;GAAE,GAAG;GAAG,GAAG;GAAG,OAAOF;GAAa,QAAQE;EAAa;CACjE;CAGJ,IAAME,IACFC,MAAQ,UACF,KAAK,IAAIL,IAAcD,EAAO,OAAOG,IAAeH,EAAO,MAAM,IACjE,KAAK,IAAIC,IAAcD,EAAO,OAAOG,IAAeH,EAAO,MAAM,GAErEO,IAAY,KAAK,IAAI,GAAG,KAAK,MAAMP,EAAO,QAAQK,CAAK,CAAC,GACxDG,IAAa,KAAK,IAAI,GAAG,KAAK,MAAMR,EAAO,SAASK,CAAK,CAAC;CAShE,OAPIC,MAAQ,YACD;EACH,SAAS;GAAE,OAAOC;GAAW,QAAQC;EAAW;EAChD,MAAM;GAAE,GAAG;GAAG,GAAG;GAAG,OAAOD;GAAW,QAAQC;EAAW;CAC7D,IAGG;EACH,SAAS;GAAE,OAAOP;GAAa,QAAQE;EAAa;EACpD,MAAM;GACF,GAAG,KAAK,OAAOF,IAAcM,KAAa,CAAC;GAC3C,GAAG,KAAK,OAAOJ,IAAeK,KAAc,CAAC;GAC7C,OAAOD;GACP,QAAQC;EACZ;CACJ;AACJ;AAQA,SAASC,EAAc,GAA4C;CAC/D,IAAIC,EAAQ,eAAe,KAAA,GAAW,OAAOA,EAAQ;CACrD,IAAMC,IAAOD,EAAQ,QAAQ;CAE7B,OADIb,EAAa,IAAIc,CAAI,KAClBD,EAAQ,QAAQ,QADYd,IACiB,KAAA;AACxD;AAiBA,eAAsBgB,EAClB,GACA,IAAyB,CAAC,GACH;CACvB,IAAM,EAAE,cAAW,MAAMC,EAAYb,CAAM;CAC3C,IAAI;EACA,IAAMc,IAAWhB,EACbiB,GACA;GAAE,OAAOL,EAAQ;GAAO,QAAQA,EAAQ;EAAO,GAC/CA,EAAQ,OAAO,WACfA,EAAQ,uBAAuB,EACnC,GACMM,IAAUC,EAAcH,EAAS,QAAQ,OAAOA,EAAS,QAAQ,MAAM;EAE7E,OADAI,EAAWH,GAAQC,GAASF,EAAS,MAAML,EAAcC,CAAO,CAAC,GAC1D,MAAMS,EAAYH,GAASN,CAAO;CAC7C,UAAU;EACN,EAAO,QAAQ;CACnB;AACJ;AAmBA,eAAsBU,EAClB,GACA,GACA,IAAyB,CAAC,GACH;CACvB,IAAM,EAAE,cAAW,MAAMP,EAAYb,CAAM;CAC3C,IAAI;EACA,IAAMqB,IAAI,KAAK,IAAI,GAAG,KAAK,IAAI,KAAK,MAAMC,EAAK,CAAC,GAAGP,EAAO,QAAQ,CAAC,CAAC,GAC9DQ,IAAI,KAAK,IAAI,GAAG,KAAK,IAAI,KAAK,MAAMD,EAAK,CAAC,GAAGP,EAAO,SAAS,CAAC,CAAC,GAC/DS,IAAQ,KAAK,IAAI,GAAG,KAAK,IAAI,KAAK,MAAMF,EAAK,KAAK,GAAGP,EAAO,QAAQM,CAAC,CAAC,GACtEI,IAAS,KAAK,IAAI,GAAG,KAAK,IAAI,KAAK,MAAMH,EAAK,MAAM,GAAGP,EAAO,SAASQ,CAAC,CAAC,GAEzEP,IAAUC,EAAcO,GAAOC,CAAM;EAM3C,OADAC,EAHIV,GACAnB,EAAa,IAAIa,EAAQ,QAAQ,YAAY,IAAId,IAAqB,KAAA,CAE1E,CAAA,CAAQ,UAAUmB,GAAQM,GAAGE,GAAGC,GAAOC,GAAQ,GAAG,GAAGD,GAAOC,CAAM,GAC3D,MAAMN,EAAYH,GAASN,CAAO;CAC7C,UAAU;EACN,EAAO,QAAQ;CACnB;AACJ;AAqBA,eAAsBiB,EAClB,GACA,GACA,IAAyB,CAAC,GACH;CACvB,IAAIC,IAAU,MAAO,GACjB,MAAU,WACN,kDAAkDA,EAAQ,qGAG9D;CAEJ,IAAMC,KAAWD,IAAU,KAAM,IAAK,KAAK,GACrC,EAAE,cAAW,MAAMf,EAAYb,CAAM;CAC3C,IAAI;EACA,IAAM8B,IAAUD,IAAQ,KAAM,GACxBL,IAAQM,IAAUf,EAAO,SAASA,EAAO,OACzCU,IAASK,IAAUf,EAAO,QAAQA,EAAO,QAEzCC,IAAUC,EAAcO,GAAOC,CAAM,GACrCM,IAAUL,EACZV,GACAnB,EAAa,IAAIa,EAAQ,QAAQ,YAAY,IAAId,IAAqB,KAAA,CAC1E;EAIA,OAHAmC,EAAQ,UAAUP,IAAQ,GAAGC,IAAS,CAAC,GACvCM,EAAQ,OAAQF,IAAQ,KAAK,KAAM,CAAC,GACpCE,EAAQ,UAAUhB,GAAQ,CAACA,EAAO,QAAQ,GAAG,CAACA,EAAO,SAAS,CAAC,GACxD,MAAMI,EAAYH,GAASN,CAAO;CAC7C,UAAU;EACN,EAAO,QAAQ;CACnB;AACJ;AAgBA,eAAsBsB,EAClB,GACA,GACA,IAAyB,CAAC,GACH;CACvB,IAAM,EAAE,cAAW,MAAMnB,EAAYb,CAAM;CAC3C,IAAI;EACA,IAAMgB,IAAUC,EAAcF,EAAO,OAAOA,EAAO,MAAM,GACnDgB,IAAUL,EACZV,GACAnB,EAAa,IAAIa,EAAQ,QAAQ,YAAY,IAAId,IAAqB,KAAA,CAC1E;EAOA,OANAmC,EAAQ,UACJE,EAAK,eAAe,KAAOlB,EAAO,QAAQ,GAC1CkB,EAAK,aAAa,KAAOlB,EAAO,SAAS,CAC7C,GACAgB,EAAQ,MAAME,EAAK,eAAe,KAAO,KAAK,GAAGA,EAAK,aAAa,KAAO,KAAK,CAAC,GAChFF,EAAQ,UAAUhB,GAAQ,GAAG,CAAC,GACvB,MAAMI,EAAYH,GAASN,CAAO;CAC7C,UAAU;EACN,EAAO,QAAQ;CACnB;AACJ"}

package/dist/imaging/use-image-processing.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"use-image-processing.cjs","names":[],"sources":["../../src/imaging/use-image-processing.ts"],"sourcesContent":["/**\n * React bindings for image work.\n *\n * Two things components get wrong every time: they leak object URLs (an\n * `URL.createObjectURL` without its `revokeObjectURL` holds the whole blob\n * in memory for the page's lifetime), and they set state after unmounting\n * when a slow resize finishes late. Both live here instead of in each\n * component.\n */\n\nimport { useCallback, useEffect, useRef, useState } from \"react\";\n\nimport { compressToTarget, type CompressedImage } from \"./compress\";\nimport type { CompressOptions, ImageSource, ProcessedImage, ResizeOptions } from \"./types\";\nimport { resizeImage } from \"./transform\";\n\n/** What {@link useImagePreview} returns. */\nexport interface UseImagePreviewResult {\n    /** Object URL for the current source, or `null`. */\n    readonly url: string | null;\n}\n\n/**\n * Hold an object URL for a blob, and revoke it when it is replaced.\n *\n * @example\n * ```tsx\n * function Preview({ file }: { file: File | null }) {\n *     const { url } = useImagePreview(file);\n *     return url === null ? null : <img src={url} alt=\"\" />;\n * }\n * ```\n *\n * @param source The blob to preview, or `null`.\n * @returns The object URL, valid until the source changes or the component\n *   unmounts.\n */\nexport function useImagePreview(source: Blob | null | undefined): UseImagePreviewResult {\n    const [url, setUrl] = useState<string | null>(null);\n\n    useEffect(() => {\n        if (source === null || source === undefined) {\n            setUrl(null);\n            return;\n        }\n        const created = URL.createObjectURL(source);\n        setUrl(created);\n        return () => {\n            URL.revokeObjectURL(created);\n        };\n    }, [source]);\n\n    return { url };\n}\n\n/** Lifecycle of a processing call. */\nexport type ImageProcessingStatus = \"idle\" | \"working\" | \"done\" | \"error\";\n\n/** What {@link useImageProcessing} returns. */\nexport interface UseImageProcessingResult {\n    /** Resize (and re-encode) an image. */\n    readonly resize: (source: ImageSource, options?: ResizeOptions) => Promise<ProcessedImage>;\n    /** Compress an image into a byte budget. */\n    readonly compress: (source: ImageSource, options: CompressOptions) => Promise<CompressedImage>;\n    /** The most recent result. */\n    readonly result: ProcessedImage | null;\n    /** Where the last call is. */\n    readonly status: ImageProcessingStatus;\n    /** Why the last call failed. */\n    readonly error: Error | null;\n    /** Whether a call is in flight. */\n    readonly isWorking: boolean;\n}\n\n/**\n * Run image operations with status tracking, safe against unmount.\n *\n * @example\n * ```tsx\n * function Upload() {\n *     const { compress, isWorking, result } = useImageProcessing();\n *\n *     async function onPick(file: File) {\n *         const ready = await compress(file, { maxBytes: 1_000_000, width: 1600 });\n *         await fetch(\"/api/photos\", { method: \"POST\", body: ready.blob });\n *     }\n *\n *     return <input type=\"file\" disabled={isWorking} onChange={(e) => onPick(e.target.files![0]!)} />;\n * }\n * ```\n *\n * The returned promises still reject on failure, so a caller can `try`\n * around them; `status` and `error` exist for rendering, not for swallowing\n * the failure.\n *\n * @returns The operations plus their state.\n */\nexport function useImageProcessing(): UseImageProcessingResult {\n    const [result, setResult] = useState<ProcessedImage | null>(null);\n    const [status, setStatus] = useState<ImageProcessingStatus>(\"idle\");\n    const [error, setError] = useState<Error | null>(null);\n    const mounted = useRef(true);\n\n    useEffect(() => {\n        mounted.current = true;\n        return () => {\n            mounted.current = false;\n        };\n    }, []);\n\n    const run = useCallback(\n        async <T extends ProcessedImage>(work: () => Promise<T>): Promise<T> => {\n            if (mounted.current) {\n                setStatus(\"working\");\n                setError(null);\n            }\n            try {\n                const produced = await work();\n                if (mounted.current) {\n                    setResult(produced);\n                    setStatus(\"done\");\n                }\n                return produced;\n            } catch (caught) {\n                const failure = caught instanceof Error ? caught : new Error(String(caught));\n                if (mounted.current) {\n                    setError(failure);\n                    setStatus(\"error\");\n                }\n                throw failure;\n            }\n        },\n        [],\n    );\n\n    const resize = useCallback(\n        (source: ImageSource, options: ResizeOptions = {}) =>\n            run(() => resizeImage(source, options)),\n        [run],\n    );\n\n    const compress = useCallback(\n        (source: ImageSource, options: CompressOptions) =>\n            run(() => compressToTarget(source, options)),\n        [run],\n    );\n\n    return {\n        resize,\n        compress,\n        result,\n        status,\n        error,\n        isWorking: status === \"working\",\n    };\n}\n"],"mappings":"sFAqCA,SAAgB,EAAgB,EAAwD,CACpF,GAAM,CAAC,EAAK,IAAA,EAAU,EAAA,SAAA,CAAwB,IAAI,EAclD,OAZA,EAAA,EAAA,UAAA,KAAgB,CACZ,GAAI,GAAW,KAA8B,CACzC,EAAO,IAAI,EACX,MACJ,CACA,IAAM,EAAU,IAAI,gBAAgB,CAAM,EAE1C,OADA,EAAO,CAAO,MACD,CACT,IAAI,gBAAgB,CAAO,CAC/B,CACJ,EAAG,CAAC,CAAM,CAAC,EAEJ,CAAE,KAAI,CACjB,CA4CA,SAAgB,GAA+C,CAC3D,GAAM,CAAC,EAAQ,IAAA,EAAa,EAAA,SAAA,CAAgC,IAAI,EAC1D,CAAC,EAAQ,IAAA,EAAa,EAAA,SAAA,CAAgC,MAAM,EAC5D,CAAC,EAAO,IAAA,EAAY,EAAA,SAAA,CAAuB,IAAI,EAC/C,GAAA,EAAU,EAAA,OAAA,CAAO,EAAI,GAE3B,EAAA,EAAA,UAAA,MACI,EAAQ,QAAU,OACL,CACT,EAAQ,QAAU,EACtB,GACD,CAAC,CAAC,EAEL,IAAM,GAAA,EAAM,EAAA,YAAA,CACR,KAAiC,IAAuC,CAChE,EAAQ,UACR,EAAU,SAAS,EACnB,EAAS,IAAI,GAEjB,GAAI,CACA,IAAM,EAAW,MAAM,EAAK,EAK5B,OAJI,EAAQ,UACR,EAAU,CAAQ,EAClB,EAAU,MAAM,GAEb,CACX,OAAS,EAAQ,CACb,IAAM,EAAU,aAAkB,MAAQ,EAAa,MAAM,OAAO,CAAM,CAAC,EAK3E,MAJI,EAAQ,UACR,EAAS,CAAO,EAChB,EAAU,OAAO,GAEf,CACV,CACJ,EACA,CAAC,CACL,EAcA,MAAO,CACH,QAAA,EAbW,EAAA,YAAA,EACV,EAAqB,EAAyB,CAAC,IAC5C,MAAU,EAAA,YAAY,EAAQ,CAAO,CAAC,EAC1C,CAAC,CAAG,CAUJ,EACA,UAAA,EARa,EAAA,YAAA,EACZ,EAAqB,IAClB,MAAU,EAAA,iBAAiB,EAAQ,CAAO,CAAC,EAC/C,CAAC,CAAG,CAKJ,EACA,SACA,SACA,QACA,UAAW,IAAW,SAC1B,CACJ"}
+{"version":3,"file":"use-image-processing.cjs","names":["useState","useRef","useCallback","resizeImage","compressToTarget","require_transform","require_compress","react","useImagePreview","url","setUrl","source","created","useImageProcessing","result","setResult","status","setStatus","error","setError","mounted","run","produced","work","caught","failure","options"],"sources":["../../src/imaging/use-image-processing.ts"],"sourcesContent":["/**\n * React bindings for image work.\n *\n * Two things components get wrong every time: they leak object URLs (an\n * `URL.createObjectURL` without its `revokeObjectURL` holds the whole blob\n * in memory for the page's lifetime), and they set state after unmounting\n * when a slow resize finishes late. Both live here instead of in each\n * component.\n */\n\nimport { useCallback, useEffect, useRef, useState } from \"react\";\n\nimport { compressToTarget, type CompressedImage } from \"./compress\";\nimport type { CompressOptions, ImageSource, ProcessedImage, ResizeOptions } from \"./types\";\nimport { resizeImage } from \"./transform\";\n\n/** What {@link useImagePreview} returns. */\nexport interface UseImagePreviewResult {\n    /** Object URL for the current source, or `null`. */\n    readonly url: string | null;\n}\n\n/**\n * Hold an object URL for a blob, and revoke it when it is replaced.\n *\n * @example\n * ```tsx\n * function Preview({ file }: { file: File | null }) {\n *     const { url } = useImagePreview(file);\n *     return url === null ? null : <img src={url} alt=\"\" />;\n * }\n * ```\n *\n * @param source The blob to preview, or `null`.\n * @returns The object URL, valid until the source changes or the component\n *   unmounts.\n */\nexport function useImagePreview(source: Blob | null | undefined): UseImagePreviewResult {\n    const [url, setUrl] = useState<string | null>(null);\n\n    useEffect(() => {\n        if (source === null || source === undefined) {\n            setUrl(null);\n            return;\n        }\n        const created = URL.createObjectURL(source);\n        setUrl(created);\n        return () => {\n            URL.revokeObjectURL(created);\n        };\n    }, [source]);\n\n    return { url };\n}\n\n/** Lifecycle of a processing call. */\nexport type ImageProcessingStatus = \"idle\" | \"working\" | \"done\" | \"error\";\n\n/** What {@link useImageProcessing} returns. */\nexport interface UseImageProcessingResult {\n    /** Resize (and re-encode) an image. */\n    readonly resize: (source: ImageSource, options?: ResizeOptions) => Promise<ProcessedImage>;\n    /** Compress an image into a byte budget. */\n    readonly compress: (source: ImageSource, options: CompressOptions) => Promise<CompressedImage>;\n    /** The most recent result. */\n    readonly result: ProcessedImage | null;\n    /** Where the last call is. */\n    readonly status: ImageProcessingStatus;\n    /** Why the last call failed. */\n    readonly error: Error | null;\n    /** Whether a call is in flight. */\n    readonly isWorking: boolean;\n}\n\n/**\n * Run image operations with status tracking, safe against unmount.\n *\n * @example\n * ```tsx\n * function Upload() {\n *     const { compress, isWorking, result } = useImageProcessing();\n *\n *     async function onPick(file: File) {\n *         const ready = await compress(file, { maxBytes: 1_000_000, width: 1600 });\n *         await fetch(\"/api/photos\", { method: \"POST\", body: ready.blob });\n *     }\n *\n *     return <input type=\"file\" disabled={isWorking} onChange={(e) => onPick(e.target.files![0]!)} />;\n * }\n * ```\n *\n * The returned promises still reject on failure, so a caller can `try`\n * around them; `status` and `error` exist for rendering, not for swallowing\n * the failure.\n *\n * @returns The operations plus their state.\n */\nexport function useImageProcessing(): UseImageProcessingResult {\n    const [result, setResult] = useState<ProcessedImage | null>(null);\n    const [status, setStatus] = useState<ImageProcessingStatus>(\"idle\");\n    const [error, setError] = useState<Error | null>(null);\n    const mounted = useRef(true);\n\n    useEffect(() => {\n        mounted.current = true;\n        return () => {\n            mounted.current = false;\n        };\n    }, []);\n\n    const run = useCallback(\n        async <T extends ProcessedImage>(work: () => Promise<T>): Promise<T> => {\n            if (mounted.current) {\n                setStatus(\"working\");\n                setError(null);\n            }\n            try {\n                const produced = await work();\n                if (mounted.current) {\n                    setResult(produced);\n                    setStatus(\"done\");\n                }\n                return produced;\n            } catch (caught) {\n                const failure = caught instanceof Error ? caught : new Error(String(caught));\n                if (mounted.current) {\n                    setError(failure);\n                    setStatus(\"error\");\n                }\n                throw failure;\n            }\n        },\n        [],\n    );\n\n    const resize = useCallback(\n        (source: ImageSource, options: ResizeOptions = {}) =>\n            run(() => resizeImage(source, options)),\n        [run],\n    );\n\n    const compress = useCallback(\n        (source: ImageSource, options: CompressOptions) =>\n            run(() => compressToTarget(source, options)),\n        [run],\n    );\n\n    return {\n        resize,\n        compress,\n        result,\n        status,\n        error,\n        isWorking: status === \"working\",\n    };\n}\n"],"mappings":"A,sFAqCA,SAAgBQ,EAAgB,EAAwD,CACpF,GAAM,CAACC,EAAKC,IAAA,EAAUV,EAAAA,SAAAA,CAAwB,IAAI,EAclD,OAZA,EAAAO,EAAA,UAAA,KAAgB,CACZ,GAAII,GAAW,KAA8B,CACzCD,EAAO,IAAI,EACX,MACJ,CACA,IAAME,EAAU,IAAI,gBAAgBD,CAAM,EAE1C,OADAD,EAAOE,CAAO,MACD,CACT,IAAI,gBAAgBA,CAAO,CAC/B,CACJ,EAAG,CAACD,CAAM,CAAC,EAEJ,CAAE,KAAI,CACjB,CA4CA,SAAgBE,GAA+C,CAC3D,GAAM,CAACC,EAAQC,IAAA,EAAaf,EAAAA,SAAAA,CAAgC,IAAI,EAC1D,CAACgB,EAAQC,IAAA,EAAajB,EAAAA,SAAAA,CAAgC,MAAM,EAC5D,CAACkB,EAAOC,IAAA,EAAYnB,EAAAA,SAAAA,CAAuB,IAAI,EAC/CoB,GAAA,EAAUnB,EAAAA,OAAAA,CAAO,EAAI,GAE3B,EAAAM,EAAA,UAAA,MACI,EAAQ,QAAU,OACL,CACT,EAAQ,QAAU,EACtB,GACD,CAAC,CAAC,EAEL,IAAMc,GAAA,EAAMnB,EAAAA,YAAAA,CACR,KAAiC,IAAuC,CAChEkB,EAAQ,UACRH,EAAU,SAAS,EACnBE,EAAS,IAAI,GAEjB,GAAI,CACA,IAAMG,EAAW,MAAMC,EAAK,EAK5B,OAJIH,EAAQ,UACRL,EAAUO,CAAQ,EAClBL,EAAU,MAAM,GAEbK,CACX,OAASE,EAAQ,CACb,IAAMC,EAAUD,aAAkB,MAAQA,EAAa,MAAM,OAAOA,CAAM,CAAC,EAK3E,MAJIJ,EAAQ,UACRD,EAASM,CAAO,EAChBR,EAAU,OAAO,GAEfQ,CACV,CACJ,EACA,CAAC,CACL,EAcA,MAAO,CACH,QAAA,EAbWvB,EAAAA,YAAAA,EACV,EAAqB,EAAyB,CAAC,IAC5CmB,MAAUlB,EAAAA,YAAYQ,EAAQe,CAAO,CAAC,EAC1C,CAACL,CAAG,CAUJ,EACA,UAAA,EARanB,EAAAA,YAAAA,EACZ,EAAqB,IAClBmB,MAAUjB,EAAAA,iBAAiBO,EAAQe,CAAO,CAAC,EAC/C,CAACL,CAAG,CAKJ,EACA,SACA,SACA,QACA,UAAWL,IAAW,SAC1B,CACJ,C"}

package/dist/imaging/use-image-processing.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-image-processing.js","names":[],"sources":["../../src/imaging/use-image-processing.ts"],"sourcesContent":["/**\n * React bindings for image work.\n *\n * Two things components get wrong every time: they leak object URLs (an\n * `URL.createObjectURL` without its `revokeObjectURL` holds the whole blob\n * in memory for the page's lifetime), and they set state after unmounting\n * when a slow resize finishes late. Both live here instead of in each\n * component.\n */\n\nimport { useCallback, useEffect, useRef, useState } from \"react\";\n\nimport { compressToTarget, type CompressedImage } from \"./compress\";\nimport type { CompressOptions, ImageSource, ProcessedImage, ResizeOptions } from \"./types\";\nimport { resizeImage } from \"./transform\";\n\n/** What {@link useImagePreview} returns. */\nexport interface UseImagePreviewResult {\n    /** Object URL for the current source, or `null`. */\n    readonly url: string | null;\n}\n\n/**\n * Hold an object URL for a blob, and revoke it when it is replaced.\n *\n * @example\n * ```tsx\n * function Preview({ file }: { file: File | null }) {\n *     const { url } = useImagePreview(file);\n *     return url === null ? null : <img src={url} alt=\"\" />;\n * }\n * ```\n *\n * @param source The blob to preview, or `null`.\n * @returns The object URL, valid until the source changes or the component\n *   unmounts.\n */\nexport function useImagePreview(source: Blob | null | undefined): UseImagePreviewResult {\n    const [url, setUrl] = useState<string | null>(null);\n\n    useEffect(() => {\n        if (source === null || source === undefined) {\n            setUrl(null);\n            return;\n        }\n        const created = URL.createObjectURL(source);\n        setUrl(created);\n        return () => {\n            URL.revokeObjectURL(created);\n        };\n    }, [source]);\n\n    return { url };\n}\n\n/** Lifecycle of a processing call. */\nexport type ImageProcessingStatus = \"idle\" | \"working\" | \"done\" | \"error\";\n\n/** What {@link useImageProcessing} returns. */\nexport interface UseImageProcessingResult {\n    /** Resize (and re-encode) an image. */\n    readonly resize: (source: ImageSource, options?: ResizeOptions) => Promise<ProcessedImage>;\n    /** Compress an image into a byte budget. */\n    readonly compress: (source: ImageSource, options: CompressOptions) => Promise<CompressedImage>;\n    /** The most recent result. */\n    readonly result: ProcessedImage | null;\n    /** Where the last call is. */\n    readonly status: ImageProcessingStatus;\n    /** Why the last call failed. */\n    readonly error: Error | null;\n    /** Whether a call is in flight. */\n    readonly isWorking: boolean;\n}\n\n/**\n * Run image operations with status tracking, safe against unmount.\n *\n * @example\n * ```tsx\n * function Upload() {\n *     const { compress, isWorking, result } = useImageProcessing();\n *\n *     async function onPick(file: File) {\n *         const ready = await compress(file, { maxBytes: 1_000_000, width: 1600 });\n *         await fetch(\"/api/photos\", { method: \"POST\", body: ready.blob });\n *     }\n *\n *     return <input type=\"file\" disabled={isWorking} onChange={(e) => onPick(e.target.files![0]!)} />;\n * }\n * ```\n *\n * The returned promises still reject on failure, so a caller can `try`\n * around them; `status` and `error` exist for rendering, not for swallowing\n * the failure.\n *\n * @returns The operations plus their state.\n */\nexport function useImageProcessing(): UseImageProcessingResult {\n    const [result, setResult] = useState<ProcessedImage | null>(null);\n    const [status, setStatus] = useState<ImageProcessingStatus>(\"idle\");\n    const [error, setError] = useState<Error | null>(null);\n    const mounted = useRef(true);\n\n    useEffect(() => {\n        mounted.current = true;\n        return () => {\n            mounted.current = false;\n        };\n    }, []);\n\n    const run = useCallback(\n        async <T extends ProcessedImage>(work: () => Promise<T>): Promise<T> => {\n            if (mounted.current) {\n                setStatus(\"working\");\n                setError(null);\n            }\n            try {\n                const produced = await work();\n                if (mounted.current) {\n                    setResult(produced);\n                    setStatus(\"done\");\n                }\n                return produced;\n            } catch (caught) {\n                const failure = caught instanceof Error ? caught : new Error(String(caught));\n                if (mounted.current) {\n                    setError(failure);\n                    setStatus(\"error\");\n                }\n                throw failure;\n            }\n        },\n        [],\n    );\n\n    const resize = useCallback(\n        (source: ImageSource, options: ResizeOptions = {}) =>\n            run(() => resizeImage(source, options)),\n        [run],\n    );\n\n    const compress = useCallback(\n        (source: ImageSource, options: CompressOptions) =>\n            run(() => compressToTarget(source, options)),\n        [run],\n    );\n\n    return {\n        resize,\n        compress,\n        result,\n        status,\n        error,\n        isWorking: status === \"working\",\n    };\n}\n"],"mappings":";;;;AAqCA,SAAgB,EAAgB,GAAwD;CACpF,IAAM,CAAC,GAAK,KAAU,EAAwB,IAAI;CAclD,OAZA,QAAgB;EACZ,IAAI,KAAW,MAA8B;GACzC,EAAO,IAAI;GACX;EACJ;EACA,IAAM,IAAU,IAAI,gBAAgB,CAAM;EAE1C,OADA,EAAO,CAAO,SACD;GACT,IAAI,gBAAgB,CAAO;EAC/B;CACJ,GAAG,CAAC,CAAM,CAAC,GAEJ,EAAE,OAAI;AACjB;AA4CA,SAAgB,IAA+C;CAC3D,IAAM,CAAC,GAAQ,KAAa,EAAgC,IAAI,GAC1D,CAAC,GAAQ,KAAa,EAAgC,MAAM,GAC5D,CAAC,GAAO,KAAY,EAAuB,IAAI,GAC/C,IAAU,EAAO,EAAI;CAE3B,SACI,EAAQ,UAAU,UACL;EACT,EAAQ,UAAU;CACtB,IACD,CAAC,CAAC;CAEL,IAAM,IAAM,EACR,OAAiC,MAAuC;EACpE,AAAI,EAAQ,YACR,EAAU,SAAS,GACnB,EAAS,IAAI;EAEjB,IAAI;GACA,IAAM,IAAW,MAAM,EAAK;GAK5B,OAJI,EAAQ,YACR,EAAU,CAAQ,GAClB,EAAU,MAAM,IAEb;EACX,SAAS,GAAQ;GACb,IAAM,IAAU,aAAkB,QAAQ,IAAa,MAAM,OAAO,CAAM,CAAC;GAK3E,MAJI,EAAQ,YACR,EAAS,CAAO,GAChB,EAAU,OAAO,IAEf;EACV;CACJ,GACA,CAAC,CACL;CAcA,OAAO;EACH,QAbW,GACV,GAAqB,IAAyB,CAAC,MAC5C,QAAU,EAAY,GAAQ,CAAO,CAAC,GAC1C,CAAC,CAAG,CAUJ;EACA,UARa,GACZ,GAAqB,MAClB,QAAU,EAAiB,GAAQ,CAAO,CAAC,GAC/C,CAAC,CAAG,CAKJ;EACA;EACA;EACA;EACA,WAAW,MAAW;CAC1B;AACJ"}
+{"version":3,"file":"use-image-processing.js","names":["useImagePreview","url","setUrl","useState","useEffect","source","created","useImageProcessing","result","setResult","status","setStatus","error","setError","mounted","useRef","run","useCallback","produced","work","caught","failure","resizeImage","options","compressToTarget"],"sources":["../../src/imaging/use-image-processing.ts"],"sourcesContent":["/**\n * React bindings for image work.\n *\n * Two things components get wrong every time: they leak object URLs (an\n * `URL.createObjectURL` without its `revokeObjectURL` holds the whole blob\n * in memory for the page's lifetime), and they set state after unmounting\n * when a slow resize finishes late. Both live here instead of in each\n * component.\n */\n\nimport { useCallback, useEffect, useRef, useState } from \"react\";\n\nimport { compressToTarget, type CompressedImage } from \"./compress\";\nimport type { CompressOptions, ImageSource, ProcessedImage, ResizeOptions } from \"./types\";\nimport { resizeImage } from \"./transform\";\n\n/** What {@link useImagePreview} returns. */\nexport interface UseImagePreviewResult {\n    /** Object URL for the current source, or `null`. */\n    readonly url: string | null;\n}\n\n/**\n * Hold an object URL for a blob, and revoke it when it is replaced.\n *\n * @example\n * ```tsx\n * function Preview({ file }: { file: File | null }) {\n *     const { url } = useImagePreview(file);\n *     return url === null ? null : <img src={url} alt=\"\" />;\n * }\n * ```\n *\n * @param source The blob to preview, or `null`.\n * @returns The object URL, valid until the source changes or the component\n *   unmounts.\n */\nexport function useImagePreview(source: Blob | null | undefined): UseImagePreviewResult {\n    const [url, setUrl] = useState<string | null>(null);\n\n    useEffect(() => {\n        if (source === null || source === undefined) {\n            setUrl(null);\n            return;\n        }\n        const created = URL.createObjectURL(source);\n        setUrl(created);\n        return () => {\n            URL.revokeObjectURL(created);\n        };\n    }, [source]);\n\n    return { url };\n}\n\n/** Lifecycle of a processing call. */\nexport type ImageProcessingStatus = \"idle\" | \"working\" | \"done\" | \"error\";\n\n/** What {@link useImageProcessing} returns. */\nexport interface UseImageProcessingResult {\n    /** Resize (and re-encode) an image. */\n    readonly resize: (source: ImageSource, options?: ResizeOptions) => Promise<ProcessedImage>;\n    /** Compress an image into a byte budget. */\n    readonly compress: (source: ImageSource, options: CompressOptions) => Promise<CompressedImage>;\n    /** The most recent result. */\n    readonly result: ProcessedImage | null;\n    /** Where the last call is. */\n    readonly status: ImageProcessingStatus;\n    /** Why the last call failed. */\n    readonly error: Error | null;\n    /** Whether a call is in flight. */\n    readonly isWorking: boolean;\n}\n\n/**\n * Run image operations with status tracking, safe against unmount.\n *\n * @example\n * ```tsx\n * function Upload() {\n *     const { compress, isWorking, result } = useImageProcessing();\n *\n *     async function onPick(file: File) {\n *         const ready = await compress(file, { maxBytes: 1_000_000, width: 1600 });\n *         await fetch(\"/api/photos\", { method: \"POST\", body: ready.blob });\n *     }\n *\n *     return <input type=\"file\" disabled={isWorking} onChange={(e) => onPick(e.target.files![0]!)} />;\n * }\n * ```\n *\n * The returned promises still reject on failure, so a caller can `try`\n * around them; `status` and `error` exist for rendering, not for swallowing\n * the failure.\n *\n * @returns The operations plus their state.\n */\nexport function useImageProcessing(): UseImageProcessingResult {\n    const [result, setResult] = useState<ProcessedImage | null>(null);\n    const [status, setStatus] = useState<ImageProcessingStatus>(\"idle\");\n    const [error, setError] = useState<Error | null>(null);\n    const mounted = useRef(true);\n\n    useEffect(() => {\n        mounted.current = true;\n        return () => {\n            mounted.current = false;\n        };\n    }, []);\n\n    const run = useCallback(\n        async <T extends ProcessedImage>(work: () => Promise<T>): Promise<T> => {\n            if (mounted.current) {\n                setStatus(\"working\");\n                setError(null);\n            }\n            try {\n                const produced = await work();\n                if (mounted.current) {\n                    setResult(produced);\n                    setStatus(\"done\");\n                }\n                return produced;\n            } catch (caught) {\n                const failure = caught instanceof Error ? caught : new Error(String(caught));\n                if (mounted.current) {\n                    setError(failure);\n                    setStatus(\"error\");\n                }\n                throw failure;\n            }\n        },\n        [],\n    );\n\n    const resize = useCallback(\n        (source: ImageSource, options: ResizeOptions = {}) =>\n            run(() => resizeImage(source, options)),\n        [run],\n    );\n\n    const compress = useCallback(\n        (source: ImageSource, options: CompressOptions) =>\n            run(() => compressToTarget(source, options)),\n        [run],\n    );\n\n    return {\n        resize,\n        compress,\n        result,\n        status,\n        error,\n        isWorking: status === \"working\",\n    };\n}\n"],"mappings":";;;;AAqCA,SAAgBA,EAAgB,GAAwD;CACpF,IAAM,CAACC,GAAKC,KAAUC,EAAwB,IAAI;CAclD,OAZAC,QAAgB;EACZ,IAAIC,KAAW,MAA8B;GACzC,EAAO,IAAI;GACX;EACJ;EACA,IAAMC,IAAU,IAAI,gBAAgBD,CAAM;EAE1C,OADAH,EAAOI,CAAO,SACD;GACT,IAAI,gBAAgBA,CAAO;EAC/B;CACJ,GAAG,CAACD,CAAM,CAAC,GAEJ,EAAE,OAAI;AACjB;AA4CA,SAAgBE,IAA+C;CAC3D,IAAM,CAACC,GAAQC,KAAaN,EAAgC,IAAI,GAC1D,CAACO,GAAQC,KAAaR,EAAgC,MAAM,GAC5D,CAACS,GAAOC,KAAYV,EAAuB,IAAI,GAC/CW,IAAUC,EAAO,EAAI;CAE3B,SACI,EAAQ,UAAU,UACL;EACT,EAAQ,UAAU;CACtB,IACD,CAAC,CAAC;CAEL,IAAMC,IAAMC,EACR,OAAiC,MAAuC;EACpE,AAAIH,EAAQ,YACRH,EAAU,SAAS,GACnBE,EAAS,IAAI;EAEjB,IAAI;GACA,IAAMK,IAAW,MAAMC,EAAK;GAK5B,OAJIL,EAAQ,YACRL,EAAUS,CAAQ,GAClBP,EAAU,MAAM,IAEbO;EACX,SAASE,GAAQ;GACb,IAAMC,IAAUD,aAAkB,QAAQA,IAAa,MAAM,OAAOA,CAAM,CAAC;GAK3E,MAJIN,EAAQ,YACRD,EAASQ,CAAO,GAChBV,EAAU,OAAO,IAEfU;EACV;CACJ,GACA,CAAC,CACL;CAcA,OAAO;EACH,QAbWJ,GACV,GAAqB,IAAyB,CAAC,MAC5CD,QAAUM,EAAYjB,GAAQkB,CAAO,CAAC,GAC1C,CAACP,CAAG,CAUJ;EACA,UARaC,GACZ,GAAqB,MAClBD,QAAUQ,EAAiBnB,GAAQkB,CAAO,CAAC,GAC/C,CAACP,CAAG,CAKJ;EACA;EACA;EACA;EACA,WAAWN,MAAW;CAC1B;AACJ"}