@aglyn/aglyn 1.0.0-beta.197 → 1.0.0-beta.199

package/src/lib/app-utils/media-embedded-metadata/webp.js

@@ -0,0 +1,272 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * WebP metadata blocks: the `EXIF`, `XMP ` and `ICCP` chunks, read and
+ * rewritten without touching the image (AGL-3331).
+ *
+ * A WebP is a RIFF file (RFC 9649, section 2): `RIFF`, a little-endian
+ * size, `WEBP`, then chunks of a FourCC, a little-endian size and the data,
+ * padded with one zero byte to an even length. A simple file holds a single
+ * `VP8 ` (lossy) or `VP8L` (lossless) chunk; metadata needs the extended
+ * format (2.7), which opens with a `VP8X` chunk whose flags announce the
+ * optional chunks, in this order:
+ *
+ *   VP8X, ICCP, ANIM, (ALPH + VP8 | VP8L | ANMF…), EXIF, XMP
+ *
+ * The writer rebuilds only the `EXIF` and `XMP ` chunks and the `VP8X`
+ * flags byte; every image, frame, alpha and unknown chunk is copied byte for
+ * byte. Adding metadata to a simple file converts it to the extended format
+ * by prepending a `VP8X` whose canvas is read from the bitstream header —
+ * the image chunk itself is unchanged.
+ */ import { EmbeddedWriteError } from "./types.js";
+import { FILE_DAMAGED, METADATA_TOO_LARGE, asciiBytes, bytesAt, concatBytes, readAscii, readU16LE, readU32LE, trimNul, utf8Decode, utf8Encode, writeU32LE } from "./image-blocks.js";
+const RIFF = asciiBytes('RIFF');
+const WEBP = asciiBytes('WEBP');
+const EXIF_HEADER = asciiBytes('Exif\0\0');
+/** VP8X flag bits (RFC 9649, 2.7): ICC, alpha, EXIF, XMP, animation. */ const FLAG_ICC = 0x20;
+const FLAG_ALPHA = 0x10;
+const FLAG_EXIF = 0x08;
+const FLAG_XMP = 0x04;
+/** A RIFF size field is 32 bits; the file tops out at 2^32 − 2 bytes. */ const MAX_RIFF_SIZE = 0xfffffffe - 8;
+/** Chunk count past which a file is not an image; the walk stops. */ const MAX_CHUNKS = 1 << 20;
+/** Chunks that make up the image, after which EXIF and XMP belong. */ const IMAGE_CHUNKS = new Set([
+    'VP8X',
+    'ICCP',
+    'ANIM',
+    'ANMF',
+    'ALPH',
+    'VP8 ',
+    'VP8L'
+]);
+/** Walks the RIFF chunks. `null` when the bytes are not `RIFF….WEBP`. */ function walkWebp(bytes) {
+    if (!bytesAt(bytes, 0, RIFF) || !bytesAt(bytes, 8, WEBP)) return null;
+    const declared = 8 + readU32LE(bytes, 4);
+    const riffEnd = Math.min(declared, bytes.length);
+    const chunks = [];
+    let offset = 12;
+    let complete = declared <= bytes.length;
+    while(offset + 8 <= riffEnd && chunks.length < MAX_CHUNKS){
+        const size = readU32LE(bytes, offset + 4);
+        const dataEnd = offset + 8 + size;
+        if (dataEnd > riffEnd) {
+            complete = false;
+            break;
+        }
+        const end = Math.min(dataEnd + (size & 1), riffEnd);
+        chunks.push({
+            fourcc: readAscii(bytes, offset, 4),
+            start: offset,
+            dataStart: offset + 8,
+            size,
+            end
+        });
+        offset = end;
+    }
+    // Bytes left inside the RIFF payload that are not a whole chunk.
+    if (offset < riffEnd) complete = false;
+    return {
+        chunks,
+        riffEnd,
+        complete
+    };
+}
+/** Strips the `Exif\0\0` prefix some writers put in front of the TIFF bytes. */ function bareTiff(exif) {
+    return bytesAt(exif, 0, EXIF_HEADER) ? exif.subarray(EXIF_HEADER.length) : exif;
+}
+/**
+ * Reads the metadata blocks of a WebP. Returns `null` when the bytes are not
+ * a WebP; a damaged file yields what came before the damage.
+ */ export function readWebpBlocks(bytes) {
+    const layout = walkWebp(bytes);
+    if (!layout) return null;
+    const blocks = {};
+    for (const chunk of layout.chunks){
+        const data = bytes.subarray(chunk.dataStart, chunk.dataStart + chunk.size);
+        if (chunk.fourcc === 'EXIF' && !blocks.exif) blocks.exif = bareTiff(data).slice();
+        if (chunk.fourcc === 'XMP ' && blocks.xmp === undefined) {
+            blocks.xmp = trimNul(utf8Decode(data));
+        }
+        if (chunk.fourcc === 'ICCP' && !blocks.icc) blocks.icc = data.slice();
+    }
+    return blocks;
+}
+/** Builds a chunk: FourCC, little-endian size, data, and the pad byte. */ function buildChunk(fourcc, data) {
+    if (data.length > MAX_RIFF_SIZE) throw new EmbeddedWriteError(METADATA_TOO_LARGE);
+    const out = new Uint8Array(8 + data.length + (data.length & 1));
+    out.set(asciiBytes(fourcc), 0);
+    writeU32LE(out, 4, data.length);
+    out.set(data, 8);
+    return out;
+}
+/**
+ * The canvas size and alpha of a simple file's image chunk, for the `VP8X`
+ * a conversion adds, or `null` when the bitstream header is unreadable.
+ *
+ * - `VP8 `: a 3-byte frame tag whose low bit is 0 on a key frame, the start
+ *   code `9D 01 2A`, then 14-bit width and height (RFC 6386, 9.1).
+ * - `VP8L`: the signature `0x2F`, then 14 bits of width − 1, 14 of
+ *   height − 1 and the alpha hint (RFC 9649, section 3, the lossless header).
+ */ function simpleCanvas(bytes, chunk) {
+    const data = bytes.subarray(chunk.dataStart, chunk.dataStart + chunk.size);
+    if (chunk.fourcc === 'VP8 ') {
+        var _data_;
+        if (data.length < 10 || ((_data_ = data[0]) != null ? _data_ : 1) & 1) return null;
+        if (data[3] !== 0x9d || data[4] !== 0x01 || data[5] !== 0x2a) return null;
+        const width = readU16LE(data, 6) & 0x3fff;
+        const height = readU16LE(data, 8) & 0x3fff;
+        return width && height ? {
+            width,
+            height,
+            alpha: false
+        } : null;
+    }
+    if (chunk.fourcc === 'VP8L') {
+        if (data.length < 5 || data[0] !== 0x2f) return null;
+        const bits = readU32LE(data, 1);
+        return {
+            width: (bits & 0x3fff) + 1,
+            height: (bits >>> 14 & 0x3fff) + 1,
+            alpha: (bits >>> 28 & 1) === 1
+        };
+    }
+    return null;
+}
+/** A `VP8X` chunk (RFC 9649, 2.7): flags, 3 reserved bytes, canvas − 1. */ function vp8xChunk(flags, width, height) {
+    const data = new Uint8Array(10);
+    data[0] = flags;
+    data[4] = width - 1 & 0xff;
+    data[5] = width - 1 >>> 8 & 0xff;
+    data[6] = width - 1 >>> 16 & 0xff;
+    data[7] = height - 1 & 0xff;
+    data[8] = height - 1 >>> 8 & 0xff;
+    data[9] = height - 1 >>> 16 & 0xff;
+    return buildChunk('VP8X', data);
+}
+/**
+ * Writes an update into a WebP and returns the new file.
+ *
+ * An existing `EXIF` or `XMP ` chunk is replaced in place (later duplicates
+ * removed); a new one goes after the image — EXIF before any existing XMP,
+ * XMP after EXIF — as the extended format orders them. `null` removes every
+ * copy. The `VP8X` EXIF and XMP flags are set to match what the file then
+ * holds; ICC, alpha and animation flags are left as they were.
+ *
+ * Throws `EmbeddedWriteError` for a file that is not a WebP or is truncated,
+ * for a layout that is neither simple nor extended, for a simple file whose
+ * bitstream header cannot give the canvas size a conversion needs, and for
+ * an IRB or PNG text update.
+ */ export function writeWebpBlocks(bytes, update) {
+    var _update_irb;
+    const layout = walkWebp(bytes);
+    if (!layout) throw new EmbeddedWriteError('This file is not a WebP image.');
+    if (!layout.complete) throw new EmbeddedWriteError(FILE_DAMAGED);
+    if ((_update_irb = update.irb) == null ? void 0 : _update_irb.length) {
+        throw new EmbeddedWriteError('A WebP has no place for Photoshop or IPTC metadata.');
+    }
+    if (update.pngText && Object.values(update.pngText).some((value)=>value !== null)) {
+        throw new EmbeddedWriteError('PNG text fields can only be written to a PNG.');
+    }
+    const first = layout.chunks[0];
+    const extended = (first == null ? void 0 : first.fourcc) === 'VP8X';
+    if (!first || !extended && first.fourcc !== 'VP8 ' && first.fourcc !== 'VP8L') {
+        throw new EmbeddedWriteError(FILE_DAMAGED);
+    }
+    const pieces = layout.chunks.map((chunk)=>{
+        const expected = 8 + chunk.size + (chunk.size & 1);
+        const original = bytes.subarray(chunk.start, chunk.end);
+        // A last chunk missing its pad byte gets one, or anything after it
+        // would start on an odd offset.
+        const padded = original.length < expected ? concatBytes([
+            original,
+            new Uint8Array(1)
+        ]) : original;
+        return {
+            fourcc: chunk.fourcc,
+            bytes: padded
+        };
+    });
+    const lastImage = ()=>{
+        for(let i = pieces.length - 1; i >= 0; i -= 1){
+            var _ref;
+            var _pieces_i;
+            if (IMAGE_CHUNKS.has((_ref = (_pieces_i = pieces[i]) == null ? void 0 : _pieces_i.fourcc) != null ? _ref : '')) return i + 1;
+        }
+        return pieces.length;
+    };
+    const indexOf = (fourcc)=>pieces.findIndex((p)=>p.fourcc === fourcc);
+    const place = (fourcc, data, anchor)=>{
+        const chunk = data && data.length ? buildChunk(fourcc, data) : null;
+        const at = indexOf(fourcc);
+        for(let i = pieces.length - 1; i > at; i -= 1){
+            var _pieces_i;
+            if (((_pieces_i = pieces[i]) == null ? void 0 : _pieces_i.fourcc) === fourcc) pieces.splice(i, 1);
+        }
+        const existing = pieces[at];
+        if (existing && chunk) existing.bytes = chunk;
+        else if (existing) pieces.splice(at, 1);
+        else if (chunk) pieces.splice(anchor(), 0, {
+            fourcc,
+            bytes: chunk
+        });
+    };
+    if (update.exif !== undefined) {
+        place('EXIF', update.exif && bareTiff(update.exif), ()=>{
+            const xmp = indexOf('XMP ');
+            return xmp >= lastImage() ? xmp : lastImage();
+        });
+    }
+    if (update.xmp !== undefined) {
+        place('XMP ', update.xmp ? utf8Encode(update.xmp) : null, ()=>{
+            const exif = indexOf('EXIF');
+            return exif >= 0 ? Math.max(exif + 1, lastImage()) : lastImage();
+        });
+    }
+    const hasExif = indexOf('EXIF') >= 0;
+    const hasXmp = indexOf('XMP ') >= 0;
+    const vp8x = pieces[0];
+    if (extended && vp8x) {
+        var _chunk_;
+        const chunk = vp8x.bytes.slice();
+        let flags = (_chunk_ = chunk[8]) != null ? _chunk_ : 0;
+        flags = hasExif ? flags | FLAG_EXIF : flags & ~FLAG_EXIF;
+        flags = hasXmp ? flags | FLAG_XMP : flags & ~FLAG_XMP;
+        chunk[8] = flags;
+        vp8x.bytes = chunk;
+    } else if (hasExif || hasXmp) {
+        const canvas = simpleCanvas(bytes, first);
+        if (!canvas) throw new EmbeddedWriteError(FILE_DAMAGED);
+        let flags = (hasExif ? FLAG_EXIF : 0) | (hasXmp ? FLAG_XMP : 0);
+        if (canvas.alpha) flags |= FLAG_ALPHA;
+        if (indexOf('ICCP') >= 0) flags |= FLAG_ICC;
+        pieces.unshift({
+            fourcc: 'VP8X',
+            bytes: vp8xChunk(flags, canvas.width, canvas.height)
+        });
+    }
+    const body = concatBytes(pieces.map((piece)=>piece.bytes));
+    if (body.length + 4 > MAX_RIFF_SIZE) throw new EmbeddedWriteError(METADATA_TOO_LARGE);
+    const header = new Uint8Array(12);
+    header.set(RIFF, 0);
+    writeU32LE(header, 4, body.length + 4);
+    header.set(WEBP, 8);
+    return concatBytes([
+        header,
+        body,
+        bytes.subarray(layout.riffEnd)
+    ]);
+}
+
+//# sourceMappingURL=webp.js.map

package/src/lib/app-utils/media-embedded-metadata/webp.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/aglyn/src/lib/app-utils/media-embedded-metadata/webp.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\n/**\n * WebP metadata blocks: the `EXIF`, `XMP ` and `ICCP` chunks, read and\n * rewritten without touching the image (AGL-3331).\n *\n * A WebP is a RIFF file (RFC 9649, section 2): `RIFF`, a little-endian\n * size, `WEBP`, then chunks of a FourCC, a little-endian size and the data,\n * padded with one zero byte to an even length. A simple file holds a single\n * `VP8 ` (lossy) or `VP8L` (lossless) chunk; metadata needs the extended\n * format (2.7), which opens with a `VP8X` chunk whose flags announce the\n * optional chunks, in this order:\n *\n *   VP8X, ICCP, ANIM, (ALPH + VP8 | VP8L | ANMF…), EXIF, XMP\n *\n * The writer rebuilds only the `EXIF` and `XMP ` chunks and the `VP8X`\n * flags byte; every image, frame, alpha and unknown chunk is copied byte for\n * byte. Adding metadata to a simple file converts it to the extended format\n * by prepending a `VP8X` whose canvas is read from the bitstream header —\n * the image chunk itself is unchanged.\n */\n\nimport { EmbeddedWriteError } from './types'\nimport {\n  FILE_DAMAGED,\n  METADATA_TOO_LARGE,\n  asciiBytes,\n  bytesAt,\n  concatBytes,\n  readAscii,\n  readU16LE,\n  readU32LE,\n  trimNul,\n  utf8Decode,\n  utf8Encode,\n  writeU32LE,\n  type ImageBlockUpdate,\n  type ImageBlocks,\n} from './image-blocks'\n\nconst RIFF = asciiBytes('RIFF')\nconst WEBP = asciiBytes('WEBP')\nconst EXIF_HEADER = asciiBytes('Exif\\0\\0')\n\n/** VP8X flag bits (RFC 9649, 2.7): ICC, alpha, EXIF, XMP, animation. */\nconst FLAG_ICC = 0x20\nconst FLAG_ALPHA = 0x10\nconst FLAG_EXIF = 0x08\nconst FLAG_XMP = 0x04\n\n/** A RIFF size field is 32 bits; the file tops out at 2^32 − 2 bytes. */\nconst MAX_RIFF_SIZE = 0xfffffffe - 8\n/** Chunk count past which a file is not an image; the walk stops. */\nconst MAX_CHUNKS = 1 << 20\n\n/** Chunks that make up the image, after which EXIF and XMP belong. */\nconst IMAGE_CHUNKS = new Set([\n  'VP8X',\n  'ICCP',\n  'ANIM',\n  'ANMF',\n  'ALPH',\n  'VP8 ',\n  'VP8L',\n])\n\ninterface RiffChunk {\n  fourcc: string\n  start: number\n  dataStart: number\n  size: number\n  /** One past the data and its pad byte (clamped to the RIFF payload). */\n  end: number\n}\n\ninterface WebpLayout {\n  chunks: RiffChunk[]\n  /** One past the RIFF payload the header declares, clamped to the file. */\n  riffEnd: number\n  /** False when a chunk runs past the RIFF payload or the file. */\n  complete: boolean\n}\n\n/** Walks the RIFF chunks. `null` when the bytes are not `RIFF….WEBP`. */\nfunction walkWebp(bytes: Uint8Array): WebpLayout | null {\n  if (!bytesAt(bytes, 0, RIFF) || !bytesAt(bytes, 8, WEBP)) return null\n  const declared = 8 + readU32LE(bytes, 4)\n  const riffEnd = Math.min(declared, bytes.length)\n  const chunks: RiffChunk[] = []\n  let offset = 12\n  let complete = declared <= bytes.length\n  while (offset + 8 <= riffEnd && chunks.length < MAX_CHUNKS) {\n    const size = readU32LE(bytes, offset + 4)\n    const dataEnd = offset + 8 + size\n    if (dataEnd > riffEnd) {\n      complete = false\n      break\n    }\n    const end = Math.min(dataEnd + (size & 1), riffEnd)\n    chunks.push({\n      fourcc: readAscii(bytes, offset, 4),\n      start: offset,\n      dataStart: offset + 8,\n      size,\n      end,\n    })\n    offset = end\n  }\n  // Bytes left inside the RIFF payload that are not a whole chunk.\n  if (offset < riffEnd) complete = false\n  return { chunks, riffEnd, complete }\n}\n\n/** Strips the `Exif\\0\\0` prefix some writers put in front of the TIFF bytes. */\nfunction bareTiff(exif: Uint8Array): Uint8Array {\n  return bytesAt(exif, 0, EXIF_HEADER)\n    ? exif.subarray(EXIF_HEADER.length)\n    : exif\n}\n\n/**\n * Reads the metadata blocks of a WebP. Returns `null` when the bytes are not\n * a WebP; a damaged file yields what came before the damage.\n */\nexport function readWebpBlocks(bytes: Uint8Array): ImageBlocks | null {\n  const layout = walkWebp(bytes)\n  if (!layout) return null\n  const blocks: ImageBlocks = {}\n  for (const chunk of layout.chunks) {\n    const data = bytes.subarray(chunk.dataStart, chunk.dataStart + chunk.size)\n    if (chunk.fourcc === 'EXIF' && !blocks.exif)\n      blocks.exif = bareTiff(data).slice()\n    if (chunk.fourcc === 'XMP ' && blocks.xmp === undefined) {\n      blocks.xmp = trimNul(utf8Decode(data))\n    }\n    if (chunk.fourcc === 'ICCP' && !blocks.icc) blocks.icc = data.slice()\n  }\n  return blocks\n}\n\n/** Builds a chunk: FourCC, little-endian size, data, and the pad byte. */\nfunction buildChunk(fourcc: string, data: Uint8Array): Uint8Array {\n  if (data.length > MAX_RIFF_SIZE)\n    throw new EmbeddedWriteError(METADATA_TOO_LARGE)\n  const out = new Uint8Array(8 + data.length + (data.length & 1))\n  out.set(asciiBytes(fourcc), 0)\n  writeU32LE(out, 4, data.length)\n  out.set(data, 8)\n  return out\n}\n\n/**\n * The canvas size and alpha of a simple file's image chunk, for the `VP8X`\n * a conversion adds, or `null` when the bitstream header is unreadable.\n *\n * - `VP8 `: a 3-byte frame tag whose low bit is 0 on a key frame, the start\n *   code `9D 01 2A`, then 14-bit width and height (RFC 6386, 9.1).\n * - `VP8L`: the signature `0x2F`, then 14 bits of width − 1, 14 of\n *   height − 1 and the alpha hint (RFC 9649, section 3, the lossless header).\n */\nfunction simpleCanvas(\n  bytes: Uint8Array,\n  chunk: RiffChunk,\n): { width: number; height: number; alpha: boolean } | null {\n  const data = bytes.subarray(chunk.dataStart, chunk.dataStart + chunk.size)\n  if (chunk.fourcc === 'VP8 ') {\n    if (data.length < 10 || (data[0] ?? 1) & 1) return null\n    if (data[3] !== 0x9d || data[4] !== 0x01 || data[5] !== 0x2a) return null\n    const width = readU16LE(data, 6) & 0x3fff\n    const height = readU16LE(data, 8) & 0x3fff\n    return width && height ? { width, height, alpha: false } : null\n  }\n  if (chunk.fourcc === 'VP8L') {\n    if (data.length < 5 || data[0] !== 0x2f) return null\n    const bits = readU32LE(data, 1)\n    return {\n      width: (bits & 0x3fff) + 1,\n      height: ((bits >>> 14) & 0x3fff) + 1,\n      alpha: ((bits >>> 28) & 1) === 1,\n    }\n  }\n  return null\n}\n\n/** A `VP8X` chunk (RFC 9649, 2.7): flags, 3 reserved bytes, canvas − 1. */\nfunction vp8xChunk(flags: number, width: number, height: number): Uint8Array {\n  const data = new Uint8Array(10)\n  data[0] = flags\n  data[4] = (width - 1) & 0xff\n  data[5] = ((width - 1) >>> 8) & 0xff\n  data[6] = ((width - 1) >>> 16) & 0xff\n  data[7] = (height - 1) & 0xff\n  data[8] = ((height - 1) >>> 8) & 0xff\n  data[9] = ((height - 1) >>> 16) & 0xff\n  return buildChunk('VP8X', data)\n}\n\ninterface Piece {\n  fourcc: string\n  bytes: Uint8Array\n}\n\n/**\n * Writes an update into a WebP and returns the new file.\n *\n * An existing `EXIF` or `XMP ` chunk is replaced in place (later duplicates\n * removed); a new one goes after the image — EXIF before any existing XMP,\n * XMP after EXIF — as the extended format orders them. `null` removes every\n * copy. The `VP8X` EXIF and XMP flags are set to match what the file then\n * holds; ICC, alpha and animation flags are left as they were.\n *\n * Throws `EmbeddedWriteError` for a file that is not a WebP or is truncated,\n * for a layout that is neither simple nor extended, for a simple file whose\n * bitstream header cannot give the canvas size a conversion needs, and for\n * an IRB or PNG text update.\n */\nexport function writeWebpBlocks(\n  bytes: Uint8Array,\n  update: ImageBlockUpdate,\n): Uint8Array {\n  const layout = walkWebp(bytes)\n  if (!layout) throw new EmbeddedWriteError('This file is not a WebP image.')\n  if (!layout.complete) throw new EmbeddedWriteError(FILE_DAMAGED)\n  if (update.irb?.length) {\n    throw new EmbeddedWriteError(\n      'A WebP has no place for Photoshop or IPTC metadata.',\n    )\n  }\n  if (\n    update.pngText &&\n    Object.values(update.pngText).some((value) => value !== null)\n  ) {\n    throw new EmbeddedWriteError(\n      'PNG text fields can only be written to a PNG.',\n    )\n  }\n\n  const first = layout.chunks[0]\n  const extended = first?.fourcc === 'VP8X'\n  if (\n    !first ||\n    (!extended && first.fourcc !== 'VP8 ' && first.fourcc !== 'VP8L')\n  ) {\n    throw new EmbeddedWriteError(FILE_DAMAGED)\n  }\n\n  const pieces: Piece[] = layout.chunks.map((chunk) => {\n    const expected = 8 + chunk.size + (chunk.size & 1)\n    const original = bytes.subarray(chunk.start, chunk.end)\n    // A last chunk missing its pad byte gets one, or anything after it\n    // would start on an odd offset.\n    const padded =\n      original.length < expected\n        ? concatBytes([original, new Uint8Array(1)])\n        : original\n    return { fourcc: chunk.fourcc, bytes: padded }\n  })\n\n  const lastImage = () => {\n    for (let i = pieces.length - 1; i >= 0; i -= 1) {\n      if (IMAGE_CHUNKS.has(pieces[i]?.fourcc ?? '')) return i + 1\n    }\n    return pieces.length\n  }\n  const indexOf = (fourcc: string) =>\n    pieces.findIndex((p) => p.fourcc === fourcc)\n\n  const place = (\n    fourcc: string,\n    data: Uint8Array | null,\n    anchor: () => number,\n  ) => {\n    const chunk = data && data.length ? buildChunk(fourcc, data) : null\n    const at = indexOf(fourcc)\n    for (let i = pieces.length - 1; i > at; i -= 1) {\n      if (pieces[i]?.fourcc === fourcc) pieces.splice(i, 1)\n    }\n    const existing = pieces[at]\n    if (existing && chunk) existing.bytes = chunk\n    else if (existing) pieces.splice(at, 1)\n    else if (chunk) pieces.splice(anchor(), 0, { fourcc, bytes: chunk })\n  }\n\n  if (update.exif !== undefined) {\n    place('EXIF', update.exif && bareTiff(update.exif), () => {\n      const xmp = indexOf('XMP ')\n      return xmp >= lastImage() ? xmp : lastImage()\n    })\n  }\n  if (update.xmp !== undefined) {\n    place('XMP ', update.xmp ? utf8Encode(update.xmp) : null, () => {\n      const exif = indexOf('EXIF')\n      return exif >= 0 ? Math.max(exif + 1, lastImage()) : lastImage()\n    })\n  }\n\n  const hasExif = indexOf('EXIF') >= 0\n  const hasXmp = indexOf('XMP ') >= 0\n  const vp8x = pieces[0]\n  if (extended && vp8x) {\n    const chunk = vp8x.bytes.slice()\n    let flags = chunk[8] ?? 0\n    flags = hasExif ? flags | FLAG_EXIF : flags & ~FLAG_EXIF\n    flags = hasXmp ? flags | FLAG_XMP : flags & ~FLAG_XMP\n    chunk[8] = flags\n    vp8x.bytes = chunk\n  } else if (hasExif || hasXmp) {\n    const canvas = simpleCanvas(bytes, first)\n    if (!canvas) throw new EmbeddedWriteError(FILE_DAMAGED)\n    let flags = (hasExif ? FLAG_EXIF : 0) | (hasXmp ? FLAG_XMP : 0)\n    if (canvas.alpha) flags |= FLAG_ALPHA\n    if (indexOf('ICCP') >= 0) flags |= FLAG_ICC\n    pieces.unshift({\n      fourcc: 'VP8X',\n      bytes: vp8xChunk(flags, canvas.width, canvas.height),\n    })\n  }\n\n  const body = concatBytes(pieces.map((piece) => piece.bytes))\n  if (body.length + 4 > MAX_RIFF_SIZE)\n    throw new EmbeddedWriteError(METADATA_TOO_LARGE)\n  const header = new Uint8Array(12)\n  header.set(RIFF, 0)\n  writeU32LE(header, 4, body.length + 4)\n  header.set(WEBP, 8)\n  return concatBytes([header, body, bytes.subarray(layout.riffEnd)])\n}\n"],"names":["EmbeddedWriteError","FILE_DAMAGED","METADATA_TOO_LARGE","asciiBytes","bytesAt","concatBytes","readAscii","readU16LE","readU32LE","trimNul","utf8Decode","utf8Encode","writeU32LE","RIFF","WEBP","EXIF_HEADER","FLAG_ICC","FLAG_ALPHA","FLAG_EXIF","FLAG_XMP","MAX_RIFF_SIZE","MAX_CHUNKS","IMAGE_CHUNKS","Set","walkWebp","bytes","declared","riffEnd","Math","min","length","chunks","offset","complete","size","dataEnd","end","push","fourcc","start","dataStart","bareTiff","exif","subarray","readWebpBlocks","layout","blocks","chunk","data","slice","xmp","undefined","icc","buildChunk","out","Uint8Array","set","simpleCanvas","width","height","alpha","bits","vp8xChunk","flags","writeWebpBlocks","update","irb","pngText","Object","values","some","value","first","extended","pieces","map","expected","original","padded","lastImage","i","has","indexOf","findIndex","p","place","anchor","at","splice","existing","max","hasExif","hasXmp","vp8x","canvas","unshift","body","piece","header"],"mappings":"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"}

package/src/lib/app-utils/media-embedded-metadata/xml.d.ts

@@ -0,0 +1,231 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * A minimal, FAITHFUL XML DOM for editing XMP packets in place (AGL-3331).
+ *
+ * ## Why not a general XML library
+ *
+ * An XMP packet written by Lightroom or Photoshop carries structures this
+ * module does not understand — `xmpMM:History`, `crs:*` tone curves,
+ * `mwg-rs` face regions, contact-info structs — and an edit of one caption
+ * must leave every one of them exactly as it was. A conventional DOM
+ * normalizes on the way in (quote style, attribute whitespace, entity
+ * spelling, `<a/>` versus `<a></a>`), so a round trip through it rewrites
+ * the whole packet. This one keeps the raw text of everything it parses
+ * next to the decoded value, and {@link serializeXml} writes the raw text
+ * back, so `serializeXml(parseXml(s)) === s` for any input it accepts and
+ * only the nodes an edit touched come out different.
+ *
+ * ## What it refuses
+ *
+ * The input is hostile: it arrives inside an uploaded file. There is NO DTD
+ * support at all — `<!DOCTYPE`, and with it `<!ENTITY`, external entities
+ * and entity expansion ("billion laughs"), are unparseable, as is any named
+ * entity other than the five XML predefines (XML 1.0 §4.6). Depth, node
+ * count and input length are bounded. Everything that is not well-formed
+ * returns `null`; nothing here throws on input.
+ *
+ * It is deliberately lenient in one direction only: content outside the
+ * root element (the `<?xpacket?>` wrappers, trailing padding, a BOM) is
+ * kept as nodes of the document rather than rejected, because XMP packets
+ * live in exactly that space and a fragment handed over from an SVG's
+ * `<metadata>` may have several top-level elements.
+ */
+/** The `xml:` prefix is bound by definition (Namespaces in XML 1.0 §3). */
+export declare const XML_NAMESPACE = "http://www.w3.org/XML/1998/namespace";
+/** The `xmlns:` prefix is bound by definition (Namespaces in XML 1.0 §3). */
+export declare const XMLNS_NAMESPACE = "http://www.w3.org/2000/xmlns/";
+/** Default parse bounds. XMP packets are kilobytes; these are generous. */
+export declare const XML_MAX_DEPTH = 64;
+export declare const XML_MAX_NODES = 50000;
+export declare const XML_MAX_LENGTH: number;
+export interface XmlLimits {
+    /** Element nesting depth; the root element is depth 1. */
+    maxDepth?: number;
+    /** Elements, attributes, text, CDATA, comments and PIs together. */
+    maxNodes?: number;
+    /** Input length in UTF-16 code units. */
+    maxLength?: number;
+}
+export interface XmlDocument {
+    type: 'document';
+    children: XmlNode[];
+}
+export type XmlNode = XmlElement | XmlText | XmlCData | XmlComment | XmlProcessingInstruction;
+export type XmlParent = XmlDocument | XmlElement;
+export interface XmlElement {
+    type: 'element';
+    /** The qualified name as written, prefix included. */
+    name: string;
+    /** In source order; order is part of what a round trip preserves. */
+    attributes: XmlAttribute[];
+    children: XmlNode[];
+    parent: XmlParent | null;
+    /**
+     * Written as `<a/>`. Only honored while the element has no children, so
+     * appending to a self-closed element serializes it as `<a>…</a>`.
+     */
+    selfClosing: boolean;
+    /** Whitespace after the last attribute (or the name), before `>`/`/>`. */
+    tagTail: string;
+    /** Whitespace between the name and `>` of the end tag: `</a >`. */
+    endTagTail: string;
+}
+export interface XmlAttribute {
+    /** The qualified name as written. */
+    name: string;
+    /**
+     * The decoded, normalized value (XML 1.0 §3.3.3): entity and character
+     * references resolved, literal tabs and newlines turned into spaces.
+     */
+    value: string;
+    /** Exactly what was between the quotes. Serialized as-is. */
+    raw: string;
+    quote: '"' | "'";
+    /** Whitespace before the name — a space, or a newline and an indent. */
+    leading: string;
+    /** The `=` with whatever whitespace the author put around it. */
+    equals: string;
+}
+export interface XmlText {
+    type: 'text';
+    /** Decoded (references resolved, line ends normalized, XML 1.0 §2.11). */
+    value: string;
+    /** Exactly as written. Serialized as-is. */
+    raw: string;
+}
+export interface XmlCData {
+    type: 'cdata';
+    value: string;
+}
+export interface XmlComment {
+    type: 'comment';
+    value: string;
+}
+export interface XmlProcessingInstruction {
+    type: 'pi';
+    target: string;
+    /** Everything after the target up to `?>`, leading whitespace included. */
+    data: string;
+}
+/**
+ * Decode the raw text of a text node or an attribute value.
+ *
+ * Applies the normalizations a conforming parser applies, in the order the
+ * spec gives them: line ends first (§2.11, CRLF and lone CR become LF),
+ * then — for attributes only — each literal whitespace character becomes a
+ * space (§3.3.3), then references are replaced. A character produced by a
+ * reference is NOT normalized, which is how `&#xA;` survives in an
+ * attribute. Returns null for an undeclared entity, a bare `&` or a
+ * reference to a character XML cannot hold.
+ */
+export declare function decodeXmlText(raw: string, attribute?: boolean): string | null;
+/**
+ * Escape a value for a text node. `>` is escaped too so a value can never
+ * spell `]]>`, and CR is written as a reference because a parser would
+ * otherwise normalize it away (§2.11).
+ */
+export declare function escapeXmlText(value: string): string;
+/**
+ * Escape a value for an attribute delimited by `quote`. Tab, LF and CR are
+ * written as references so attribute-value normalization (§3.3.3) does not
+ * turn them into spaces on the next read.
+ */
+export declare function escapeXmlAttribute(value: string, quote?: '"' | "'"): string;
+/**
+ * Whether a string holds a character that XML 1.0 cannot represent at all,
+ * not even as a reference (§2.2): C0 controls other than tab/LF/CR, U+FFFE,
+ * U+FFFF and unpaired surrogates. A writer must refuse such a value rather
+ * than emit a packet no reader will parse.
+ */
+export declare function hasNonXmlCharacters(value: string): boolean;
+/**
+ * Parse `input` into a faithful DOM, or return null when it is not
+ * well-formed, declares a DTD, or exceeds a bound. Never throws.
+ *
+ * The parser is iterative — an explicit stack, not recursion — so a
+ * hostile nesting depth costs a counter check, not the call stack.
+ */
+export declare function parseXml(input: string, limits?: XmlLimits): XmlDocument | null;
+/** Serialize a document or node back to text, raw spellings preserved. */
+export declare function serializeXml(node: XmlDocument | XmlNode): string;
+/** A text node whose raw spelling is the escaped value. */
+export declare function createText(value: string): XmlText;
+/**
+ * A whitespace-only text node written verbatim — indentation copied from
+ * the document, where escaping a CR would turn `\r\n` into `&#xD;\n`.
+ * Anything that is not XML whitespace is dropped.
+ */
+export declare function createWhitespace(raw: string): XmlText;
+/** A new element; attributes are `[name, value]` pairs, space-separated. */
+export declare function createElement(name: string, attributes?: ReadonlyArray<readonly [string, string]>, children?: XmlNode[], quote?: '"' | "'"): XmlElement;
+/** Insert nodes at `index`, adopting any elements among them. */
+export declare function insertChildren(parent: XmlParent, index: number, nodes: XmlNode[]): void;
+/** Replace every child of `parent`. */
+export declare function replaceChildren(parent: XmlParent, nodes: XmlNode[]): void;
+/** Remove one child. Returns false when it was not a child of `parent`. */
+export declare function removeChild(parent: XmlParent, node: XmlNode): boolean;
+export declare function getAttribute(element: XmlElement, name: string): XmlAttribute | undefined;
+/**
+ * Set an attribute's value. An existing attribute keeps its position,
+ * quote style and surrounding whitespace; a new one is appended with
+ * `leading` before it.
+ */
+export declare function setAttribute(element: XmlElement, name: string, value: string, options?: {
+    leading?: string;
+    quote?: '"' | "'";
+    index?: number;
+}): XmlAttribute;
+export declare function removeAttribute(element: XmlElement, name: string): boolean;
+/** Replace an element's content with one text node (none for ''). */
+export declare function setTextContent(element: XmlElement, value: string): void;
+/** The decoded text of an element's direct text and CDATA children. */
+export declare function textContent(element: XmlElement): string;
+export declare function elementChildren(parent: XmlParent): XmlElement[];
+/** Whether a text node is nothing but XML whitespace. */
+export declare function isWhitespaceText(node: XmlNode | undefined): node is XmlText;
+/**
+ * Visit every element in document order, iteratively. Return `false` from
+ * `visit` to skip an element's descendants.
+ */
+export declare function walkElements(root: XmlParent, visit: (element: XmlElement) => boolean | void): void;
+/** `dc:title` → `{ prefix: 'dc', local: 'title' }`; no colon → prefix ''. */
+export declare function splitQName(name: string): {
+    prefix: string;
+    local: string;
+};
+/**
+ * The namespace URI `prefix` is bound to at `element`, through the nearest
+ * `xmlns:prefix` (or, for `''`, `xmlns`) on it or an ancestor. Null when
+ * unbound — or, for the default namespace, explicitly undeclared (§6.2).
+ */
+export declare function resolvePrefix(element: XmlElement, prefix: string): string | null;
+/** An element's namespace URI: its prefix's, or the default namespace. */
+export declare function elementNamespace(element: XmlElement): string | null;
+/**
+ * An attribute's namespace URI. An unprefixed attribute is in NO namespace
+ * — the default namespace does not apply to attributes (§6.2).
+ */
+export declare function attributeNamespace(element: XmlElement, attr: XmlAttribute): string | null;
+/** Whether an attribute is a namespace declaration. */
+export declare function isNamespaceDeclaration(attr: XmlAttribute): boolean;
+/**
+ * A prefix bound to `uri` in scope at `element` and not shadowed by a
+ * nearer declaration of the same prefix, or null. The default namespace is
+ * never returned: an attribute cannot use it.
+ */
+export declare function prefixForNamespace(element: XmlElement, uri: string): string | null;