@su-engineering/heic 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,445 @@
+import { S as SourceColor, H as HeicWarning, a as SupportReport, D as DecodeOptions, b as DecodedImage, c as DecoderAdapter } from './types-Bv9KPnri.js';
+export { A as AdapterRequest, d as AdapterResult, O as OutputColorSpace, e as Strategy, T as TransformsApplied } from './types-Bv9KPnri.js';
+
+/**
+ * Typed error hierarchy. The parser consumes hostile input and the decode path
+ * fails in browser-specific ways, so every throw carries enough context to file
+ * a useful bug report without the reporter having to reproduce it.
+ */
+interface HeicErrorContext {
+    /** ftyp major brand, when we got far enough to read it. */
+    brand?: string | undefined;
+    /** item_type of the item being worked on ('grid', 'hvc1', ...). */
+    itemType?: string | undefined;
+    /** Item ID being worked on. */
+    itemId?: number | undefined;
+    /** Strategy that produced the failure. */
+    strategy?: string | undefined;
+    /** Codec string handed to VideoDecoder. */
+    codec?: string | undefined;
+    /** Byte offset in the source buffer, for parse failures. */
+    offset?: number | undefined;
+    /** Four-character box type being read, for parse failures. */
+    box?: string | undefined;
+}
+declare class HeicError extends Error {
+    readonly context: HeicErrorContext;
+    constructor(message: string, context?: HeicErrorContext, options?: ErrorOptions);
+}
+/** The file is malformed, truncated, or uses a container feature we refuse to guess at. */
+declare class HeicParseError extends HeicError {
+    constructor(message: string, context?: HeicErrorContext, options?: ErrorOptions);
+}
+/** The file is well-formed but this environment cannot decode it. */
+declare class HeicUnsupportedError extends HeicError {
+    /** Strategies that were tried, and why each one was unavailable or failed. */
+    readonly attempts: ReadonlyArray<{
+        strategy: string;
+        reason: string;
+    }>;
+    constructor(message: string, attempts?: ReadonlyArray<{
+        strategy: string;
+        reason: string;
+    }>, context?: HeicErrorContext, options?: ErrorOptions);
+}
+/** A decoder was available and accepted the config, but decoding failed. */
+declare class HeicDecodeError extends HeicError {
+    constructor(message: string, context?: HeicErrorContext, options?: ErrorOptions);
+}
+/** The caller's AbortSignal fired. */
+declare class HeicAbortError extends HeicError {
+    constructor(message?: string, context?: HeicErrorContext, options?: ErrorOptions);
+}
+
+/**
+ * Bounds-checked big-endian byte reader.
+ *
+ * Every single read validates against the window before touching the buffer.
+ * This is the only place in the package that indexes raw bytes, so the security
+ * guarantee is enforceable by review: if it isn't going through Reader, it isn't
+ * reading the file.
+ *
+ * A Reader is a *window* onto a shared ArrayBuffer, not a copy. Sub-readers for
+ * nested boxes are free.
+ */
+declare class Reader {
+    readonly bytes: Uint8Array;
+    private readonly view;
+    /** Absolute offset of this window's start within the underlying ArrayBuffer. */
+    readonly base: number;
+    /** Cursor, relative to the window start. */
+    private pos;
+    constructor(source: ArrayBuffer | Uint8Array, byteOffset?: number, byteLength?: number);
+    get length(): number;
+    get offset(): number;
+    /** Absolute offset of the cursor in the underlying buffer, for error reports. */
+    get absoluteOffset(): number;
+    get remaining(): number;
+    get eof(): boolean;
+    seek(to: number): void;
+    skip(count: number): void;
+    /**
+     * Throws unless `count` bytes are readable at `at` (default: the cursor).
+     * Callers that are about to allocate should call this first with the declared
+     * size, so a hostile length field fails here rather than in the allocator.
+     */
+    require(count: number, at?: number): void;
+    u8(): number;
+    u16(): number;
+    u24(): number;
+    u32(): number;
+    /**
+     * Returns a JS number, not a BigInt. Values above Number.MAX_SAFE_INTEGER are
+     * rejected rather than silently losing precision — a 9-petabyte box size is a
+     * malformed file, not something to accommodate.
+     */
+    u64(): number;
+    /** Reads a big-endian unsigned integer of 0, 1, 2, 4 or 8 bytes. `iloc` needs this. */
+    uint(byteCount: number): number;
+    /** Four-character box type. Non-printable bytes are escaped so error messages stay readable. */
+    fourCC(): string;
+    /** NUL-terminated UTF-8 string. Stops at the window end if the NUL is missing. */
+    cString(): string;
+    /** A view onto the next `count` bytes. No copy — do not retain past the buffer's life. */
+    view_(count: number): Uint8Array;
+    /** A copy of the next `count` bytes. Use when the result outlives the source buffer. */
+    copy(count: number): Uint8Array;
+    /** A sub-reader over `count` bytes, advancing this reader past them. */
+    sub(count: number): Reader;
+    /** A sub-reader over the rest of the window, without advancing this reader. */
+    peekRest(): Reader;
+}
+
+interface HvccNalArray {
+    arrayCompleteness: boolean;
+    nalUnitType: number;
+    /** Views into the source buffer, not copies. */
+    nalus: Uint8Array[];
+}
+/** Parsed HEVCDecoderConfigurationRecord (ISO/IEC 14496-15 §8.3.3.1). */
+interface HvcC {
+    configurationVersion: number;
+    generalProfileSpace: number;
+    generalTierFlag: number;
+    generalProfileIdc: number;
+    generalProfileCompatibilityFlags: number;
+    /** Six bytes, big-endian order as stored. */
+    generalConstraintIndicatorFlags: Uint8Array;
+    generalLevelIdc: number;
+    minSpatialSegmentationIdc: number;
+    parallelismType: number;
+    chromaFormat: number;
+    bitDepthLumaMinus8: number;
+    bitDepthChromaMinus8: number;
+    avgFrameRate: number;
+    constantFrameRate: number;
+    numTemporalLayers: number;
+    temporalIdNested: number;
+    /** Byte width of the length prefix on each NAL unit in the item payload. */
+    lengthSizeMinusOne: number;
+    arrays: HvccNalArray[];
+    /** The raw record, which is what VideoDecoderConfig.description wants. */
+    raw: Uint8Array;
+}
+declare function parseHvcC(reader: Reader): HvcC;
+/**
+ * Builds the RFC 6381 codec string for a VideoDecoderConfig.
+ *
+ * Format: `{fourcc}.{space}{profile_idc}.{compat}.{tier}{level}.{constraints}`
+ * A typical iPhone Main-profile record produces `hvc1.1.6.L93.B0`.
+ */
+declare function hvccToCodecString(hvcc: HvcC, fourCC?: 'hvc1' | 'hev1'): string;
+/**
+ * Builds an Annex B parameter-set prologue (VPS/SPS/PPS, each start-code
+ * prefixed) for the `hev1` fallback configuration mode.
+ */
+declare function hvccToAnnexBPrologue(hvcc: HvcC): Uint8Array;
+/**
+ * Rewrites a length-prefixed NAL unit stream to Annex B start codes.
+ * `lengthSize` is `lengthSizeMinusOne + 1` from the hvcC.
+ */
+declare function lengthPrefixedToAnnexB(data: Uint8Array, lengthSize: number): Uint8Array;
+
+interface ItemInfo {
+    itemId: number;
+    protectionIndex: number;
+    /** 'hvc1', 'grid', 'Exif', 'mime', ... Empty for version 0/1 infe boxes. */
+    itemType: string;
+    itemName: string;
+    contentType?: string;
+    /** Set when the infe declares the item hidden. */
+    hidden: boolean;
+}
+interface ItemExtent {
+    /** Offset, relative to whatever `constructionMethod` selects. */
+    offset: number;
+    length: number;
+}
+interface ItemLocation {
+    itemId: number;
+    /** 0 = offset into the file, 1 = offset into idat, 2 = offset into another item. */
+    constructionMethod: number;
+    baseOffset: number;
+    extents: ItemExtent[];
+}
+interface IspeProperty {
+    type: 'ispe';
+    width: number;
+    height: number;
+}
+interface HvccProperty {
+    type: 'hvcC';
+    hvcc: HvcC;
+}
+interface IrotProperty {
+    type: 'irot';
+    /** Counter-clockwise rotation in degrees. */
+    angle: 0 | 90 | 180 | 270;
+}
+interface ImirProperty {
+    type: 'imir';
+    /** Raw `axis` field. See render/transform.ts for the semantics, which are verified empirically. */
+    axis: 0 | 1;
+}
+interface ColrNclxProperty {
+    type: 'colr';
+    colorType: 'nclx';
+    primaries: number;
+    transfer: number;
+    matrix: number;
+    fullRange: boolean;
+}
+interface ColrIccProperty {
+    type: 'colr';
+    colorType: 'icc';
+    profile: Uint8Array;
+}
+interface PixiProperty {
+    type: 'pixi';
+    bitsPerChannel: number[];
+}
+interface ClapProperty {
+    type: 'clap';
+    widthN: number;
+    widthD: number;
+    heightN: number;
+    heightD: number;
+    horizOffN: number;
+    horizOffD: number;
+    vertOffN: number;
+    vertOffD: number;
+}
+interface AuxCProperty {
+    type: 'auxC';
+    auxType: string;
+}
+interface UnknownProperty {
+    type: 'unknown';
+    boxType: string;
+}
+type ItemProperty = IspeProperty | HvccProperty | IrotProperty | ImirProperty | ColrNclxProperty | ColrIccProperty | PixiProperty | ClapProperty | AuxCProperty | UnknownProperty;
+interface PropertyAssociation {
+    /** 1-based index into the ipco child list. */
+    index: number;
+    essential: boolean;
+}
+interface ItemProperties {
+    /** 1-indexed in the file; index 0 is "no property" and is never present here. */
+    properties: ItemProperty[];
+    associations: Map<number, PropertyAssociation[]>;
+}
+/** referenceType → fromItemId → toItemIds, in file order. */
+type ItemReferences = Map<string, Map<number, number[]>>;
+interface HeifFile {
+    majorBrand: string;
+    minorVersion: number;
+    compatibleBrands: string[];
+    /** Item ID named by `pitm`. */
+    primaryItemId: number;
+    handlerType: string;
+    items: Map<number, ItemInfo>;
+    locations: Map<number, ItemLocation>;
+    itemProperties: ItemProperties;
+    references: ItemReferences;
+    /** Payload of the `idat` box, for construction_method 1. */
+    itemData: Uint8Array | undefined;
+    /** The whole source buffer, for construction_method 0 offsets. */
+    source: Uint8Array;
+}
+interface ParseOptions {
+    /**
+     * Tolerate a top-level box that runs past the end of the buffer, stopping the
+     * walk there instead of throwing. Only for detection, which is deliberately
+     * handed a truncated prefix; a full-file parse stays strict so that genuine
+     * truncation is reported rather than silently half-decoded.
+     */
+    truncated?: boolean;
+}
+declare function parseHeif(input: ArrayBuffer | Uint8Array, options?: ParseOptions): HeifFile;
+/** Properties associated with an item, in `ipma` order. Order matters for transforms. */
+declare function propertiesForItem(file: HeifFile, itemId: number): ItemProperty[];
+/** First property of the given kind for an item, or undefined. */
+declare function findProperty<T extends ItemProperty['type']>(properties: readonly ItemProperty[], type: T): Extract<ItemProperty, {
+    type: T;
+}> | undefined;
+/**
+ * Assembles an item's payload from its extents.
+ *
+ * Extents are concatenated in order. Every offset and length is validated
+ * against the actual buffer before a single byte is allocated, so a malformed
+ * `extent_length` fails here rather than in the allocator.
+ */
+declare function readItemData(file: HeifFile, itemId: number): Uint8Array;
+
+interface GridDescriptor {
+    rows: number;
+    columns: number;
+    /** Output dimensions the grid declares in its payload. */
+    outputWidth: number;
+    outputHeight: number;
+    /** Tile item IDs in raster order (left to right, top to bottom). */
+    tileItemIds: number[];
+}
+/**
+ * Parses an ImageGrid payload (HEIF §6.6.2.3.1).
+ *
+ * ```
+ * u8 version (0)
+ * u8 flags            bit 0 = field_length_size: 0 -> u16 dims, 1 -> u32 dims
+ * u8 rows_minus_one
+ * u8 columns_minus_one
+ * output_width        u16 or u32
+ * output_height       u16 or u32
+ * ```
+ */
+declare function parseGridPayload(payload: Uint8Array): Omit<GridDescriptor, 'tileItemIds'>;
+interface GridWarning {
+    code: string;
+    message: string;
+}
+/**
+ * Reads the full grid description for an item, cross-checking the declared
+ * dimensions against `ispe` and the declared tile count against `dimg`.
+ */
+declare function readGrid(file: HeifFile, itemId: number, warnings?: GridWarning[]): GridDescriptor;
+
+/** A transform to apply, in the order the file associated it. */
+type TransformOp = {
+    kind: 'rotate';
+    angle: 90 | 180 | 270;
+} | {
+    kind: 'mirror';
+    axis: 0 | 1;
+} | {
+    kind: 'crop';
+    width: number;
+    height: number;
+    offsetX: number;
+    offsetY: number;
+};
+interface TileGroup {
+    /** ipco property index of the hvcC these tiles share. */
+    configIndex: number;
+    hvcc: HvcC;
+    codec: string;
+    /** Indices into `ImagePlan.tiles`, in submission order. */
+    tileIndices: number[];
+}
+interface PlannedTile {
+    itemId: number;
+    /** Position in the composited canvas, before any transform. */
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+interface ImagePlan {
+    file: HeifFile;
+    primaryItemId: number;
+    isGrid: boolean;
+    /** Coded dimensions, before transforms. */
+    codedWidth: number;
+    codedHeight: number;
+    /** Dimensions as displayed, after transforms. What the caller sees. */
+    displayWidth: number;
+    displayHeight: number;
+    tiles: PlannedTile[];
+    /** Tiles grouped by decoder configuration. Normally exactly one group. */
+    tileGroups: TileGroup[];
+    /** Transforms in `ipma` association order. */
+    transforms: TransformOp[];
+    bitDepth: number;
+    sourceColor: SourceColor;
+    warnings: HeicWarning[];
+}
+/**
+ * Parses the container and works out everything every strategy needs.
+ *
+ * Always runs, whichever strategy ends up decoding: the native path needs the
+ * dimensions to validate its output, the WebCodecs path needs the tiles, and the
+ * wasm path needs the metadata we report back.
+ */
+declare function planDecode(input: ArrayBuffer | Uint8Array): ImagePlan;
+
+/**
+ * Reports what this environment can decode, before anything is downloaded.
+ *
+ * The point is to let a caller decide whether to preload the wasm fallback:
+ * `recommended === 'wasm'` means the ~1.2 MB codec will be needed, and knowing
+ * that at page load is much better than discovering it when a user drops a file.
+ *
+ * Cheap: `isConfigSupported` is a capability query, not a decoder, and the native
+ * probe decodes a 471-byte inline image.
+ */
+declare function probeSupport(): Promise<SupportReport>;
+
+type BinaryInput = Blob | ArrayBuffer | Uint8Array;
+interface IsHeicResult {
+    isHeic: boolean;
+    /** ftyp major brand, when the file had one. */
+    brand?: string | undefined;
+    /** item_type of the primary item ('hvc1', 'grid', 'av01', ...). */
+    primaryItemType?: string | undefined;
+    /** What the primary item is coded with. 'av1' means this is an AVIF. */
+    coding?: 'hevc' | 'av1' | 'unknown' | undefined;
+}
+/**
+ * Identifies a HEIC file from its contents.
+ *
+ * Reads the `ftyp` brands and the primary item type — never the filename or the
+ * MIME type the browser guessed, both of which are routinely wrong for photos
+ * copied off a phone.
+ *
+ * Given a Blob, only the first 64 KB are read, because this gets called
+ * speculatively on every file a user drops. AVIF also uses the `mif1` brand, so
+ * the result is discriminated rather than boolean: `{ isHeic: false, coding:
+ * 'av1' }` tells a caller to route the file to an AVIF decoder instead of
+ * treating it as garbage.
+ */
+declare function isHeic(input: BinaryInput): Promise<IsHeicResult>;
+/**
+ * Decodes a HEIC image to an `ImageBitmap`.
+ *
+ * The container is parsed first regardless of which strategy ends up decoding —
+ * parsing costs microseconds and every strategy needs its output. The cascade
+ * then picks a *decode* path:
+ *
+ *   1. `createImageBitmap` — free, works on Safari and some Chrome builds
+ *   2. WebCodecs `VideoDecoder` — ~15 KB of JS, hardware decode, most Chromium
+ *   3. a wasm adapter — ~1.2 MB, only if the caller supplied one
+ *
+ * Step 3 never happens behind the caller's back: without `wasmLoader` or a
+ * registered adapter, a file that needs wasm throws `HeicUnsupportedError`
+ * naming what was missing, rather than silently fetching a megabyte.
+ */
+declare function decodeHeic(input: BinaryInput, options?: DecodeOptions): Promise<DecodedImage>;
+/**
+ * Registers a wasm (or other) fallback adapter for every subsequent decode.
+ *
+ * An alternative to passing `wasmLoader` on each call. Either way the caller
+ * chooses when the megabyte is paid for; nothing is fetched implicitly.
+ */
+declare function registerDecoderAdapter(adapter: DecoderAdapter | undefined): void;
+declare function getRegisteredAdapter(): DecoderAdapter | undefined;
+
+export { type BinaryInput, DecodeOptions, DecodedImage, DecoderAdapter, type GridDescriptor, HeicAbortError, HeicDecodeError, HeicError, type HeicErrorContext, HeicParseError, HeicUnsupportedError, HeicWarning, type HeifFile, type HvcC, type ImagePlan, type IsHeicResult, type ItemInfo, type ItemLocation, type ItemProperties, type ItemProperty, type ItemReferences, type PlannedTile, SourceColor, SupportReport, type TileGroup, type TransformOp, decodeHeic, findProperty, getRegisteredAdapter, hvccToAnnexBPrologue, hvccToCodecString, isHeic, lengthPrefixedToAnnexB, parseGridPayload, parseHeif, parseHvcC, planDecode, probeSupport, propertiesForItem, readGrid, readItemData, registerDecoderAdapter };