@poe-platform/safe-bash 0.1.810 → 0.1.812

package/dist/audio-ast/flac-source.d.ts

@@ -0,0 +1,13 @@
+import type { AudioProbeSource } from "./wav-source.js";
+import type { AudioAst } from "./types.js";
+/** UTF-8 comment bytes; block identity preserves replacement across comment blocks. */
+export interface FlacCommentSpan {
+    readonly block: number;
+    readonly offset: number;
+    readonly length: number;
+}
+/** Strict FLAC validation without AST/picture/frame models. onComment avoids collecting tag strings. */
+export declare function probeFlacSource(source: AudioProbeSource, options?: {
+    signal?: AbortSignal;
+    onComment?: (span: FlacCommentSpan) => Promise<void>;
+}): Promise<Omit<AudioAst, "data" | "nodes" | "pictures">>;

package/dist/audio-ast/index.d.ts

@@ -1,3 +1,5 @@
+export { normalizeVorbisCommentKey } from "./vorbis.js";
+export { probeFlacSource, type FlacCommentSpan } from "./flac-source.js";
 export { probeWavSource, type AudioProbeSource, type WavTagSpan } from "./wav-source.js";
 export * from "./types.js";
 export { decodePcm, encodeWav } from "./wav.js";

package/dist/audio-ast/index.js

@@ -74,6 +74,253 @@ function duration(samples, sampleRate) {
   return samples / sampleRate;
 }
 
+// packages/audio-ast/src/vorbis.ts
+var names = {
+  TITLE: "title",
+  ARTIST: "artist",
+  ALBUM: "album",
+  ALBUMARTIST: "albumArtist",
+  TRACKNUMBER: "track",
+  DISCNUMBER: "disc",
+  DATE: "date",
+  GENRE: "genre",
+  COMMENT: "comment",
+  DESCRIPTION: "comment",
+  ENCODER: "encoder",
+  COPYRIGHT: "copyright"
+};
+function parseComments(bytes) {
+  const r = new Reader(bytes), vendorSize = r.u32(0, true), vendor = new TextDecoder().decode(r.slice(4, vendorSize));
+  let offset = 4 + vendorSize;
+  const count = r.u32(offset, true);
+  offset += 4;
+  if (count > (bytes.length - offset) / 4) throw new Error("Invalid Vorbis comment count");
+  const tags = {}, comments = [];
+  for (let i = 0; i < count; i++) {
+    const size = r.u32(offset, true);
+    offset += 4;
+    const value = new TextDecoder().decode(r.slice(offset, size));
+    offset += size;
+    comments.push(value);
+    addVorbisComment(tags, value);
+  }
+  return { tags, vendor, comments, size: offset };
+}
+function encodeComments(tags, vendor = "poe-code/audio-ast") {
+  const encoder = new TextEncoder(), v = encoder.encode(vendor), comments = [];
+  for (const [name, value] of Object.entries(tags)) {
+    const key = Object.keys(names).find((key2) => names[key2] === name) ?? name.toUpperCase();
+    if (key.includes("=") || Array.from(key).some((c) => c.charCodeAt(0) < 32 || c.charCodeAt(0) > 125))
+      throw new Error("Invalid Vorbis comment key");
+    for (const part of value.split("\n")) {
+      const bytes = encoder.encode(`${key}=${part}`);
+      comments.push(join([uint32(bytes.length, true), bytes]));
+    }
+  }
+  return join([uint32(v.length, true), v, uint32(comments.length, true), ...comments]);
+}
+function parsePicture(bytes) {
+  const r = new Reader(bytes), type = r.u32(0), mimeSize = r.u32(4), mime = r.text(8, mimeSize);
+  let offset = 8 + mimeSize;
+  const descriptionSize = r.u32(offset);
+  offset += 4;
+  const description = new TextDecoder().decode(r.slice(offset, descriptionSize));
+  offset += descriptionSize;
+  const width = r.u32(offset), height = r.u32(offset + 4), depth = r.u32(offset + 8), colors = r.u32(offset + 12), size = r.u32(offset + 16);
+  offset += 20;
+  const data = r.slice(offset, size);
+  if (offset + size !== bytes.length) throw new Error("Trailing FLAC picture bytes");
+  return { type, mime, description, width, height, depth, colors, data };
+}
+function encodePicture(p) {
+  const description = new TextEncoder().encode(p.description), mime = ascii(p.mime);
+  return join([
+    uint32(p.type),
+    uint32(mime.length),
+    mime,
+    uint32(description.length),
+    description,
+    uint32(p.width ?? 0),
+    uint32(p.height ?? 0),
+    uint32(p.depth ?? 0),
+    uint32(p.colors ?? 0),
+    uint32(p.data.length),
+    p.data
+  ]);
+}
+function pictureBase64(picture) {
+  const bytes = encodePicture(picture);
+  let binary = "";
+  for (let i = 0; i < bytes.length; i += 8192)
+    binary += String.fromCharCode(...bytes.subarray(i, i + 8192));
+  return btoa(binary);
+}
+function addVorbisComment(tags, value) {
+  const split = value.indexOf("=");
+  if (split > 0) {
+    const name = normalizeVorbisCommentKey(value.slice(0, split));
+    tags[name] = tags[name] ? `${tags[name]}
+${value.slice(split + 1)}` : value.slice(split + 1);
+  }
+}
+function normalizeVorbisCommentKey(value) {
+  const key = value.toUpperCase();
+  return names[key] ?? key;
+}
+
+// packages/audio-ast/src/flac.ts
+function parseFlac(bytes) {
+  const r = new Reader(bytes), nodes = [], pictures = [];
+  const tags = {};
+  let offset = 4, last = false, stream;
+  while (!last) {
+    const header = r.u8(offset), type = header & 127, size = r.u24(offset + 1);
+    last = !!(header & 128);
+    const data = r.slice(offset + 4, size), node = {
+      type: [
+        "STREAMINFO",
+        "PADDING",
+        "APPLICATION",
+        "SEEKTABLE",
+        "VORBIS_COMMENT",
+        "CUESHEET",
+        "PICTURE"
+      ][type] ?? `BLOCK_${type}`,
+      offset,
+      size: size + 4,
+      data
+    };
+    nodes.push(node);
+    const block = new Reader(data);
+    if (type === 0) {
+      if (stream || offset !== 4 || size !== 34)
+        throw new Error("FLAC requires first unique STREAMINFO");
+      stream = flacStream(block, bytes.length);
+      const { sampleRate, channels, bitsPerSample, samples } = stream;
+      node.fields = {
+        minBlockSize: block.u16(0),
+        maxBlockSize: block.u16(2),
+        minFrameSize: block.u24(4),
+        maxFrameSize: block.u24(7),
+        sampleRate,
+        channels,
+        bitsPerSample,
+        totalSamples: samples,
+        md5: Array.from(block.slice(18, 16), (b) => b.toString(16).padStart(2, "0")).join("")
+      };
+    } else if (type === 4) {
+      const parsed = parseComments(data);
+      if (parsed.size !== size) throw new Error("Trailing Vorbis comment bytes");
+      Object.assign(tags, parsed.tags);
+      node.fields = { vendor: parsed.vendor, comments: parsed.comments };
+    } else if (type === 6) pictures.push(parsePicture(data));
+    else if (type === 3) {
+      if (size % 18) throw new Error("Invalid FLAC seek table");
+      const points = [];
+      for (let pos = 0; pos < size; pos += 18)
+        points.push({
+          sample: block.u64(pos),
+          offset: block.u64(pos + 8),
+          samples: block.u16(pos + 16)
+        });
+      node.fields = { points };
+    } else if (type === 127) throw new Error("Invalid FLAC metadata block");
+    offset += 4 + size;
+  }
+  if (!stream) throw new Error("Missing FLAC STREAMINFO");
+  if (offset < bytes.length)
+    nodes.push({
+      type: "FRAMES",
+      offset,
+      size: bytes.length - offset,
+      data: r.slice(offset, bytes.length - offset)
+    });
+  return {
+    format: "flac",
+    data: bytes,
+    nodes,
+    tags,
+    pictures,
+    streams: [stream],
+    duration: stream.duration,
+    bitrate: stream.bitrate
+  };
+}
+function flacStream(block, byteLength) {
+  const packed = block.u64(10), sampleRate = Number(packed >> 44n), channels = Number(packed >> 41n & 7n) + 1, bitsPerSample = Number(packed >> 36n & 31n) + 1, samples = Number(packed & 0xfffffffffn), seconds2 = duration(samples, sampleRate);
+  return { codec: "flac", sampleRate, channels, bitsPerSample, samples, duration: seconds2, bitrate: seconds2 ? byteLength * 8 / seconds2 : 0 };
+}
+
+// packages/audio-ast/src/flac-source.ts
+async function probeFlacSource(source, options = {}) {
+  const check = (offset2, length, end = source.size) => {
+    options.signal?.throwIfAborted();
+    if (!Number.isSafeInteger(source.size) || !Number.isSafeInteger(offset2) || !Number.isSafeInteger(length) || offset2 < 0 || length < 0 || length > end - offset2)
+      throw new Error("Truncated or invalid audio structure");
+  };
+  const read = async (offset2, length, end = source.size) => {
+    check(offset2, length, end);
+    const bytes = await source.read(offset2, length);
+    options.signal?.throwIfAborted();
+    if (bytes.length !== length) throw new Error("Truncated or invalid audio structure");
+    return new Reader(bytes);
+  };
+  if ((await read(0, 4)).text(0, 4) !== "fLaC") throw new Error("Expected FLAC signature");
+  let offset = 4, last = false, stream;
+  const tags = {};
+  while (!last) {
+    const header = await read(offset, 4), type = header.u8(0) & 127, length = header.u24(1), start = offset + 4, end = start + length;
+    last = !!(header.u8(0) & 128);
+    check(start, length);
+    if (type === 0) {
+      if (stream || offset !== 4 || length !== 34) throw new Error("FLAC requires first unique STREAMINFO");
+      stream = flacStream(await read(start, 34, end), source.size);
+    } else if (type === 4) {
+      const vendorLength = (await read(start, 4, end)).u32(0, true);
+      check(start + 4, vendorLength, end);
+      let pos = start + 4 + vendorLength;
+      const count = (await read(pos, 4, end)).u32(0, true);
+      pos += 4;
+      if (count > (end - pos) / 4) throw new Error("Invalid Vorbis comment count");
+      const blockTags = {};
+      for (let i = 0; i < count; i++) {
+        const size = (await read(pos, 4, end)).u32(0, true);
+        pos += 4;
+        check(pos, size, end);
+        if (options.onComment) {
+          await options.onComment({ block: offset, offset: pos, length: size });
+          options.signal?.throwIfAborted();
+        } else {
+          const decoder = new TextDecoder();
+          let text2 = "";
+          for (let at = 0; at < size; at += 16384) text2 += decoder.decode((await read(pos + at, Math.min(16384, size - at), end)).bytes, { stream: true });
+          addVorbisComment(blockTags, text2 + decoder.decode());
+        }
+        pos += size;
+      }
+      if (pos !== end) throw new Error("Trailing Vorbis comment bytes");
+      Object.assign(tags, blockTags);
+    } else if (type === 6) {
+      const prefix = await read(start, 8, end), mimeLength = prefix.u32(4);
+      check(start + 8, mimeLength, end);
+      let pos = start + 8 + mimeLength;
+      const descriptionLength = (await read(pos, 4, end)).u32(0);
+      pos += 4;
+      check(pos, descriptionLength, end);
+      pos += descriptionLength;
+      const size = (await read(pos, 20, end)).u32(16);
+      pos += 20;
+      check(pos, size, end);
+      if (pos + size !== end) throw new Error("Trailing FLAC picture bytes");
+    } else if (type === 3 && length % 18) throw new Error("Invalid FLAC seek table");
+    else if (type === 127) throw new Error("Invalid FLAC metadata block");
+    offset = end;
+  }
+  if (!stream) throw new Error("Missing FLAC STREAMINFO");
+  options.signal?.throwIfAborted();
+  return { format: "flac", streams: [stream], tags, duration: stream.duration, bitrate: stream.bitrate };
+}
+
 // packages/audio-ast/src/wav.ts
 var infoNames = {
   INAM: "title",
@@ -543,7 +790,7 @@ function transformAudio(pcm, effects) {
 }
 
 // packages/audio-ast/src/id3.ts
-var names = {
+var names2 = {
   TIT2: "title",
   TPE1: "artist",
   TPE2: "albumArtist",
@@ -636,7 +883,7 @@ function parseId3(bytes) {
       if (version === 4 && frameFlags & 1) prefix += 4;
       data = data.subarray(prefix);
       if (id.startsWith("T") && id !== "TXXX" && id !== "TXX")
-        tags[names[id] ?? id] = text(data.subarray(1), data[0]);
+        tags[names2[id] ?? id] = text(data.subarray(1), data[0]);
       else if (id === "COMM" || id === "COM") {
         const encoding = data[0], end = terminated(data, 4, encoding), width = encoding === 1 || encoding === 2 ? 2 : 1;
         tags.comment = text(data.subarray(end + width), encoding);
@@ -676,13 +923,13 @@ function encodeId3(tags, retained = [], pictures = []) {
     if (flags & (node.fields?.version === 3 ? 192 : 12)) {
       throw new Error(`Cannot safely rewrite transformed ID3 frame ${node.type}`);
     }
-    if (node.type === "APIC" || node.type === "PIC" || names[node.type] || node.type.startsWith("T") && node.type !== "TXXX" && node.type !== "TXX" || node.type === "COMM" || node.type === "COM")
+    if (node.type === "APIC" || node.type === "PIC" || names2[node.type] || node.type.startsWith("T") && node.type !== "TXXX" && node.type !== "TXX" || node.type === "COMM" || node.type === "COM")
       continue;
     if (node.type.length === 4 && !node.fields?.flags) frame(node.type, node.data);
     else throw new Error(`Cannot safely rewrite ID3 frame ${node.type}`);
   }
   for (const [name, value] of Object.entries(tags)) {
-    const id = Object.keys(names).find((key) => key.length === 4 && names[key] === name) ?? name;
+    const id = Object.keys(names2).find((key) => key.length === 4 && names2[key] === name) ?? name;
     if (name === "comment")
       frame(
         "COMM",
@@ -865,181 +1112,6 @@ function parseMp3(bytes) {
   };
 }
 
-// packages/audio-ast/src/vorbis.ts
-var names2 = {
-  TITLE: "title",
-  ARTIST: "artist",
-  ALBUM: "album",
-  ALBUMARTIST: "albumArtist",
-  TRACKNUMBER: "track",
-  DISCNUMBER: "disc",
-  DATE: "date",
-  GENRE: "genre",
-  COMMENT: "comment",
-  DESCRIPTION: "comment",
-  ENCODER: "encoder",
-  COPYRIGHT: "copyright"
-};
-function parseComments(bytes) {
-  const r = new Reader(bytes), vendorSize = r.u32(0, true), vendor = new TextDecoder().decode(r.slice(4, vendorSize));
-  let offset = 4 + vendorSize;
-  const count = r.u32(offset, true);
-  offset += 4;
-  if (count > (bytes.length - offset) / 4) throw new Error("Invalid Vorbis comment count");
-  const tags = {}, comments = [];
-  for (let i = 0; i < count; i++) {
-    const size = r.u32(offset, true);
-    offset += 4;
-    const value = new TextDecoder().decode(r.slice(offset, size));
-    offset += size;
-    comments.push(value);
-    const split = value.indexOf("=");
-    if (split > 0) {
-      const key = value.slice(0, split).toUpperCase(), name = names2[key] ?? key;
-      tags[name] = tags[name] ? `${tags[name]}
-${value.slice(split + 1)}` : value.slice(split + 1);
-    }
-  }
-  return { tags, vendor, comments, size: offset };
-}
-function encodeComments(tags, vendor = "poe-code/audio-ast") {
-  const encoder = new TextEncoder(), v = encoder.encode(vendor), comments = [];
-  for (const [name, value] of Object.entries(tags)) {
-    const key = Object.keys(names2).find((key2) => names2[key2] === name) ?? name.toUpperCase();
-    if (key.includes("=") || Array.from(key).some((c) => c.charCodeAt(0) < 32 || c.charCodeAt(0) > 125))
-      throw new Error("Invalid Vorbis comment key");
-    for (const part of value.split("\n")) {
-      const bytes = encoder.encode(`${key}=${part}`);
-      comments.push(join([uint32(bytes.length, true), bytes]));
-    }
-  }
-  return join([uint32(v.length, true), v, uint32(comments.length, true), ...comments]);
-}
-function parsePicture(bytes) {
-  const r = new Reader(bytes), type = r.u32(0), mimeSize = r.u32(4), mime = r.text(8, mimeSize);
-  let offset = 8 + mimeSize;
-  const descriptionSize = r.u32(offset);
-  offset += 4;
-  const description = new TextDecoder().decode(r.slice(offset, descriptionSize));
-  offset += descriptionSize;
-  const width = r.u32(offset), height = r.u32(offset + 4), depth = r.u32(offset + 8), colors = r.u32(offset + 12), size = r.u32(offset + 16);
-  offset += 20;
-  const data = r.slice(offset, size);
-  if (offset + size !== bytes.length) throw new Error("Trailing FLAC picture bytes");
-  return { type, mime, description, width, height, depth, colors, data };
-}
-function encodePicture(p) {
-  const description = new TextEncoder().encode(p.description), mime = ascii(p.mime);
-  return join([
-    uint32(p.type),
-    uint32(mime.length),
-    mime,
-    uint32(description.length),
-    description,
-    uint32(p.width ?? 0),
-    uint32(p.height ?? 0),
-    uint32(p.depth ?? 0),
-    uint32(p.colors ?? 0),
-    uint32(p.data.length),
-    p.data
-  ]);
-}
-function pictureBase64(picture) {
-  const bytes = encodePicture(picture);
-  let binary = "";
-  for (let i = 0; i < bytes.length; i += 8192)
-    binary += String.fromCharCode(...bytes.subarray(i, i + 8192));
-  return btoa(binary);
-}
-
-// packages/audio-ast/src/flac.ts
-function parseFlac(bytes) {
-  const r = new Reader(bytes), nodes = [], pictures = [];
-  const tags = {};
-  let offset = 4, last = false, stream;
-  while (!last) {
-    const header = r.u8(offset), type = header & 127, size = r.u24(offset + 1);
-    last = !!(header & 128);
-    const data = r.slice(offset + 4, size), node = {
-      type: [
-        "STREAMINFO",
-        "PADDING",
-        "APPLICATION",
-        "SEEKTABLE",
-        "VORBIS_COMMENT",
-        "CUESHEET",
-        "PICTURE"
-      ][type] ?? `BLOCK_${type}`,
-      offset,
-      size: size + 4,
-      data
-    };
-    nodes.push(node);
-    const block = new Reader(data);
-    if (type === 0) {
-      if (stream || offset !== 4 || size !== 34)
-        throw new Error("FLAC requires first unique STREAMINFO");
-      const packed = block.u64(10), sampleRate = Number(packed >> 44n), channels = Number(packed >> 41n & 7n) + 1, bitsPerSample = Number(packed >> 36n & 31n) + 1, samples = Number(packed & 0xfffffffffn);
-      const seconds2 = duration(samples, sampleRate);
-      stream = {
-        codec: "flac",
-        sampleRate,
-        channels,
-        bitsPerSample,
-        samples,
-        duration: seconds2,
-        bitrate: seconds2 ? bytes.length * 8 / seconds2 : 0
-      };
-      node.fields = {
-        minBlockSize: block.u16(0),
-        maxBlockSize: block.u16(2),
-        minFrameSize: block.u24(4),
-        maxFrameSize: block.u24(7),
-        sampleRate,
-        channels,
-        bitsPerSample,
-        totalSamples: samples,
-        md5: Array.from(block.slice(18, 16), (b) => b.toString(16).padStart(2, "0")).join("")
-      };
-    } else if (type === 4) {
-      const parsed = parseComments(data);
-      if (parsed.size !== size) throw new Error("Trailing Vorbis comment bytes");
-      Object.assign(tags, parsed.tags);
-      node.fields = { vendor: parsed.vendor, comments: parsed.comments };
-    } else if (type === 6) pictures.push(parsePicture(data));
-    else if (type === 3) {
-      if (size % 18) throw new Error("Invalid FLAC seek table");
-      const points = [];
-      for (let pos = 0; pos < size; pos += 18)
-        points.push({
-          sample: block.u64(pos),
-          offset: block.u64(pos + 8),
-          samples: block.u16(pos + 16)
-        });
-      node.fields = { points };
-    } else if (type === 127) throw new Error("Invalid FLAC metadata block");
-    offset += 4 + size;
-  }
-  if (!stream) throw new Error("Missing FLAC STREAMINFO");
-  if (offset < bytes.length)
-    nodes.push({
-      type: "FRAMES",
-      offset,
-      size: bytes.length - offset,
-      data: r.slice(offset, bytes.length - offset)
-    });
-  return {
-    format: "flac",
-    data: bytes,
-    nodes,
-    tags,
-    pictures,
-    streams: [stream],
-    duration: stream.duration,
-    bitrate: stream.bitrate
-  };
-}
-
 // packages/audio-ast/src/ogg.ts
 function oggCrc(bytes) {
   let crc = 0;
@@ -1626,9 +1698,11 @@ export {
   extractChannels,
   fade,
   normalize,
+  normalizeVorbisCommentKey,
   pad,
   parseAudio,
   probeAudio,
+  probeFlacSource,
   probeWavSource,
   remix,
   resample,

package/dist/audio-ast/vorbis.d.ts

@@ -0,0 +1,14 @@
+import type { AudioPicture, AudioTags } from "./types.js";
+export declare function parseComments(bytes: Uint8Array): {
+    tags: AudioTags;
+    vendor: string;
+    comments: string[];
+    size: number;
+};
+export declare function encodeComments(tags: AudioTags, vendor?: string): Uint8Array;
+export declare function parsePicture(bytes: Uint8Array): AudioPicture;
+export declare function encodePicture(p: AudioPicture): Uint8Array;
+export declare function pictureBase64(picture: AudioPicture): string;
+/** Preserve normalization and duplicate joining for decoded Vorbis comments. */
+export declare function addVorbisComment(tags: AudioTags, value: string): void;
+export declare function normalizeVorbisCommentKey(value: string): string;

package/dist/image-ast/index.js

@@ -1762,7 +1762,7 @@ async function openPdfImage(source, fs, directory, signal, options, storage) {
     if (failure) throw failure.error;
   };
   try {
-    document = await PdfRetainedDocument.open(retained, { fs, directory }, { signal, recovery: "repair", chunkBytes: 16384, maxNodes: 1 / 0, maxTokenBytes: 1 / 0, maxRecursionDepth: 1 / 0, maxPageTreeDepth: 1 / 0, xref: { arrayStorage: values, storedArrayKeys: ["Index"] }, valueArrays: { stringStorage: values, storedStringKeys: ["ActualText"], arrayStorage: values, storedArrayKeys: ["Contents", "Annots", "Kids", "Widths", "W", "Differences", "ON", "OFF", "OCGs"], storedArrayPaths: [["ExtGState", "*", "D"]] } });
+    document = await PdfRetainedDocument.open(retained, { fs, directory }, { signal, recovery: "repair", chunkBytes: 16384, maxNodes: 1 / 0, maxTokenBytes: 1 / 0, maxRecursionDepth: 1 / 0, maxPageTreeDepth: 1 / 0, xref: { arrayStorage: values, storedArrayKeys: ["Index"] }, valueArrays: { containerStorage: values, stringStorage: values, storedStringKeys: ["ActualText"], arrayStorage: values, storedArrayKeys: ["Contents", "Annots", "Kids", "Widths", "W", "Differences", "ON", "OFF", "OCGs"], storedArrayPaths: [["ExtGState", "*", "D"]] } });
     let pages = 0, selected;
     for await (let page of document.pages())
       pages++, page.index <= Math.max(0, settings.page ?? 0) && (selected = page);

package/dist/json-ast/backed-json-parser.d.ts

@@ -1,6 +1,17 @@
 import type { PagedStorage } from "@poe-platform/safe-fs/storage";
 import type { BackedJson } from "./backed-json.js";
+type Mode = "value" | "arrayFirst" | "keyFirst" | "key" | "colon" | "separator" | "done";
+type NumberState = "start" | "minus" | "zero" | "int" | "dot" | "frac" | "exp" | "expSign" | "expDigits";
+export interface JsonSyntaxContext {
+    readonly mode: Mode;
+    readonly token: "string" | "number" | "keyword" | undefined;
+    readonly number: NumberState;
+    readonly escape: boolean;
+    readonly hex: number;
+    readonly container: "array" | "object" | undefined;
+}
 /** JSON syntax and duplicate-key validation over streamed UTF-16 fragments.
  * Numeric spellings stay on tape; format-specific range/rounding validation is
  * separate. Both nesting state and the key index live in caller storage. */
-export declare function parseBackedJson(chunks: AsyncIterable<string>, tree: BackedJson, index: PagedStorage, cooperate: (units?: number) => Promise<void>, error: (offset: number, message: string, tokenOffset?: number) => never, validateNumber?: (node: number, offset: number) => Promise<void>, allowDuplicateKeys?: boolean, checkDepth?: (depth: number, container?: boolean) => void, node?: (kind: "object" | "array" | "key" | "scalar", complete?: boolean) => void, reference?: () => void, retained?: (bytes: number) => void): Promise<void>;
+export declare function parseBackedJson(chunks: AsyncIterable<string>, tree: BackedJson, index: PagedStorage, cooperate: (units?: number) => Promise<void>, onError: (offset: number, message: string, tokenOffset?: number, context?: JsonSyntaxContext) => never, validateNumber?: (node: number, offset: number) => Promise<void>, allowDuplicateKeys?: boolean, checkDepth?: (depth: number, container?: boolean) => void, node?: (kind: "object" | "array" | "key" | "scalar", complete?: boolean) => void, reference?: () => void, retained?: (bytes: number) => void): Promise<void>;
+export {};

package/dist/json-ast/index.d.ts

@@ -1,4 +1,4 @@
 export { BackedJson } from "./backed-json.js";
-export { parseBackedJson } from "./backed-json-parser.js";
+export { parseBackedJson, type JsonSyntaxContext } from "./backed-json-parser.js";
 export { JsonNumberError, readJsonNumber } from "./json-number.js";
 export { indexJsonObjects } from "./object-order.js";

package/dist/office-xml/index.d.ts

@@ -2,3 +2,4 @@ export * from "./office-errors.js";
 export * from "./office-resources.js";
 export * from "./retained-xml.js";
 export * from "./retained-xml-document.js";
+export * from "./retained-xml-edits.js";

package/dist/office-xml/retained-xml-edits.d.ts

@@ -0,0 +1,22 @@
+import type { ByteSource } from "../office-package/index.js";
+import { type RetainedXmlContext } from './office-resources.js';
+import { type RetainedXml, type XmlRange } from './retained-xml.js';
+export interface RetainedXmlEdit {
+    /** Original decoded UTF-8 coordinates. Edits must be ordered and disjoint;
+     * consecutive zero-length insertions at the same coordinate preserve order. */
+    readonly range: XmlRange;
+    /** Borrowed UTF-8 replacement, consumed before the next edit is requested. */
+    readonly replacement: ByteSource;
+}
+export interface StagedXmlMutation {
+    readonly byteLength: number;
+    bytes(): ByteSource;
+    write(sink: {
+        write(bytes: Uint8Array): Promise<void>;
+    }): Promise<void>;
+    close(): Promise<void>;
+}
+/** Admit source and result, then expose an owned staged mutation. The edit
+ * factory may traverse the immutable lexical view; that view expires before
+ * return. Neither a whole XML part nor the edit collection is retained in RAM. */
+export declare function stageRetainedXmlEdits(source: ByteSource, edits: (original: RetainedXml) => AsyncIterable<RetainedXmlEdit>, settings: RetainedXmlContext): Promise<StagedXmlMutation>;

package/dist/pdf-ast/cos/qpdf-json-document.d.ts

@@ -1,3 +1,4 @@
+import { type JsonSyntaxContext } from "../../json-ast/index.js";
 import { type PdfCosRef } from "../ast.js";
 import { PdfFileSource } from "../source.js";
 import type { PdfRetainedDocument } from "../retained-document.js";
@@ -6,7 +7,7 @@ export interface ApplyQpdfJsonOptions {
     /** The caller retains ownership of datafile handles. */
     readonly dataFile?: (path: string) => Promise<PdfFileSource | undefined>;
     readonly maxInputBytes?: number;
-    readonly syntaxError?: (offset: number, message: string, tokenOffset?: number) => never;
+    readonly syntaxError?: (offset: number, message: string, tokenOffset?: number, context?: JsonSyntaxContext) => never;
 }
 /** A mutable JSON-import document backed only by the caller filesystem. Apply
  * updates sequentially and publish chunks only after all updates succeed.

package/dist/pdf-ast/cos/value-parser.d.ts

@@ -1,7 +1,9 @@
-import type { PdfCosNode, PdfCosDict, PdfPixelStorage } from "../ast.js";
+import type { PdfCosNode, PdfCosDict, PdfDictEntry, PdfPixelStorage, PdfStoredItems } from "../ast.js";
 import type { CosToken } from "./lexer.js";
 export interface ValueArrayStorage {
     readonly arrayStorage?: PdfPixelStorage;
+    /** Back suspended parser containers; selected descriptors must share this storage. */
+    readonly containerStorage?: PdfPixelStorage;
     /** Select decoded source strings without changing other string consumers. */
     readonly stringStorage?: PdfPixelStorage;
     readonly storedStringKeys?: readonly string[];
@@ -14,11 +16,30 @@ export interface ValueArrayStorage {
     readonly arrayPathPrefix?: readonly string[];
     readonly storeRootArray?: boolean;
 }
+export type ValueContainer = ({
+    kind: "array";
+    start: number;
+    items: PdfCosNode[];
+    storedItems?: PdfStoredItems;
+    tail: number;
+} | {
+    kind: "dict";
+    start: number;
+    entries: PdfDictEntry[];
+    key?: PdfDictEntry["key"];
+}) & {
+    path: readonly (string | null)[];
+};
 export type ValueWork<T> = Generator<void | "token" | PdfCosDict | {
     kind: "array-append";
     node: PdfCosNode;
     previous: number;
-}, T, CosToken | PdfCosNode | number | undefined>;
+} | {
+    kind: "container-push";
+    container: ValueContainer;
+} | {
+    kind: "container-pop";
+}, T, CosToken | PdfCosNode | ValueContainer | number | undefined>;
 export declare function parseValueSteps(lexer: {
     offset: number;
     setStringStorage?: (storage: PdfPixelStorage | undefined) => void;

package/dist/pdf-ast/extract/retained-form-field-details.d.ts

@@ -0,0 +1,20 @@
+import type { PdfIndexStorage } from "../cos/object-index.js";
+import type { PdfFormFieldInfo } from "../edit/forms.js";
+import type { PdfRetainedDocument } from "../retained-document.js";
+import { type RetainedFieldOptions } from "./retained-form-fields.js";
+/** Borrowed field metadata. Consume values/options before advancing the field
+ * iterator. Both iterators close when their field or document is released. */
+export interface PdfRetainedFormFieldDetails {
+    readonly name: string;
+    readonly type: PdfFormFieldInfo["type"];
+    readonly flags: number;
+    readonly justification: "Left" | "Centered" | "Right";
+    readonly maxLength: number | undefined;
+    readonly altName: string | undefined;
+    readonly defaultValue: string | undefined;
+    readonly stateValue: string | undefined;
+    readonly checked: boolean | undefined;
+    values(): AsyncGenerator<string, void, void>;
+    options(): AsyncGenerator<string, void, void>;
+}
+export declare function walkRetainedFormFieldDetails(document: PdfRetainedDocument, storage: PdfIndexStorage, options?: RetainedFieldOptions): AsyncGenerator<PdfRetainedFormFieldDetails, void, void>;