@poe-platform/safe-bash 0.1.812 → 0.1.813

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

@@ -0,0 +1,18 @@
+import { type Id3TextSpan } from "./id3-source.js";
+import type { AudioAst } from "./types.js";
+import type { AudioProbeSource } from "./wav-source.js";
+/** ID3v1 fields are bounded literals; ID3v2 values remain replayable source spans. */
+export type Mp3Tag = Id3TextSpan | {
+    readonly key: string;
+    readonly value: string;
+};
+/** Strict MPEG/ID3 validation with bounded reads and no encoded sample or picture payloads.
+ * One bounded first-frame descriptor preserves declared VBR byte rates for probe writers.
+ * onTag preserves ID3v1 insertion order and subsequent ID3v2 replacement. It may run
+ * before later validation fails; keep the caller-owned source alive and publish only on success.
+ */
+export declare function probeMp3Source(source: AudioProbeSource, options?: {
+    signal?: AbortSignal;
+    checkpoint?: () => Promise<void>;
+    onTag?: (tag: Mp3Tag) => Promise<void>;
+}): Promise<Omit<AudioAst, "data" | "pictures">>;

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

@@ -0,0 +1,25 @@
+import type { AudioProbeSource } from "./wav-source.js";
+/** A checksum-verified physical page. Payload stays in the caller's source. */
+export interface OggPageSpan {
+    readonly offset: number;
+    readonly size: number;
+    readonly payloadOffset: number;
+    readonly flags: number;
+    readonly granule: bigint;
+    readonly serial: number;
+    readonly sequence: number;
+    readonly checksum: number;
+    /** Owned segment lengths, at most 255 bytes; 255 continues the packet. */
+    readonly lacing: Uint8Array;
+}
+/**
+ * Scan physical pages without retaining payloads, packet lists or logical-stream
+ * state. The consumer owns packet/codec validation and any backing indexes.
+ * Ranges and owned byte buffers are at most 16 KiB. A retained source stays open;
+ * a sequential iterator is retired on failure or early return. Earlier pages may
+ * precede a later error, so publish only after consuming the complete iterator.
+ */
+export declare function scanOggPages(source: AudioProbeSource | AsyncIterable<Uint8Array>, options?: {
+    signal?: AbortSignal;
+    checkpoint?: () => void | Promise<void>;
+}): AsyncGenerator<OggPageSpan, void>;

package/dist/audio-ast/ogg-stream-source.d.ts

@@ -0,0 +1,22 @@
+import type { AudioProbeSource } from "./wav-source.js";
+import type { AudioStream } from "./types.js";
+/** Raw UTF-8 comment within the logical comment packet, including its field name. */
+export interface OggCommentSpan {
+    readonly offset: number;
+    readonly length: number;
+}
+/**
+ * Inspect one already-indexed Opus/Vorbis logical stream. Physical Ogg validation,
+ * stream ordering, aggregate tags/pictures and source lifetime belong to callers.
+ * onComment avoids materializing comments; without it, raw stream tags are collected.
+ */
+export declare function probeOggStreamSource(input: {
+    readonly head: AudioProbeSource;
+    readonly comments?: AudioProbeSource | undefined;
+    readonly granule: bigint;
+    readonly size: number;
+}, options?: {
+    signal?: AbortSignal;
+    checkpoint?: () => void | Promise<void>;
+    onComment?: (span: OggCommentSpan) => void | Promise<void>;
+}): Promise<AudioStream>;

package/dist/image-ast/index.js

@@ -158,6 +158,134 @@ async function rejectUnknownImage(source, signal) {
   throw new UnsupportedImageFormat();
 }
 
+// src/pdf-value-storage.ts
+import { PdfFileSource } from "../pdf-ast/index.js";
+var pageBytes = 16384, recordBytes = pageBytes + 8;
+async function pageNumber(source, index, signal) {
+  let bytes = await source.read(index * recordBytes, 8, signal);
+  return new DataView(bytes.buffer, bytes.byteOffset, 8).getFloat64(0);
+}
+var PdfValueStorage = class {
+  constructor(fs, directory, signal) {
+    this.fs = fs;
+    this.directory = directory;
+    this.signal = signal;
+  }
+  fs;
+  directory;
+  signal;
+  pages = /* @__PURE__ */ new Map();
+  runs = [];
+  owned = /* @__PURE__ */ new Set();
+  end = 8;
+  active = Promise.resolve();
+  closing;
+  allocate(length) {
+    if (this.signal.throwIfAborted(), this.closing) throw new Error("PDF value storage is closed");
+    if (!Number.isSafeInteger(length) || length < 0 || length > Number.MAX_SAFE_INTEGER - this.end) throw new RangeError("Invalid PDF backing allocation");
+    let position = this.end;
+    return this.end += length, position;
+  }
+  operation(position, length, signal, action) {
+    let combined = signal ? AbortSignal.any([signal, this.signal]) : this.signal;
+    if (combined.throwIfAborted(), this.closing) throw new Error("PDF value storage is closed");
+    if (!Number.isSafeInteger(position) || position < 0 || !Number.isSafeInteger(length) || length < 0 || length > this.end - position) throw new RangeError("Invalid PDF backing range");
+    let work = this.active.then(() => (combined.throwIfAborted(), action(combined)));
+    return this.active = work.then(() => {
+    }, () => {
+    }), work;
+  }
+  read(position, length, options) {
+    return this.operation(position, length, options?.signal, async (signal) => {
+      let result = new Uint8Array(length);
+      for (let offset = 0, turns = 0; offset < length; ) {
+        ++turns % 64 === 0 && await new Promise((resolve) => setTimeout(resolve, 0)), signal.throwIfAborted();
+        let at = position + offset, page = await this.page(Math.floor(at / pageBytes), signal), start = at % pageBytes, count = Math.min(length - offset, pageBytes - start);
+        result.set(page.bytes.subarray(start, start + count), offset), offset += count;
+      }
+      return signal.throwIfAborted(), result;
+    });
+  }
+  write(position, bytes, options) {
+    return this.operation(position, bytes.length, options?.signal, async (signal) => {
+      for (let offset = 0, turns = 0; offset < bytes.length; ) {
+        ++turns % 64 === 0 && await new Promise((resolve) => setTimeout(resolve, 0)), signal.throwIfAborted();
+        let at = position + offset, page = await this.page(Math.floor(at / pageBytes), signal), start = at % pageBytes, count = Math.min(bytes.length - offset, pageBytes - start);
+        page.bytes.set(bytes.subarray(offset, offset + count), start), page.dirty = !0, offset += count;
+      }
+      signal.throwIfAborted();
+    });
+  }
+  async page(number, signal) {
+    let cached = this.pages.get(number);
+    if (cached)
+      return this.pages.delete(number), this.pages.set(number, cached), cached;
+    this.pages.size === 4 && (await this.flush(signal), this.pages.delete(this.pages.keys().next().value));
+    let bytes;
+    for (let run of this.runs)
+      if (run)
+        try {
+          let low = 0, high = run.size / recordBytes;
+          for (; low < high; ) {
+            let middle = Math.floor((low + high) / 2);
+            await pageNumber(run, middle, signal) < number ? low = middle + 1 : high = middle;
+          }
+          if (low < run.size / recordBytes && await pageNumber(run, low, signal) === number) {
+            bytes = await run.read(low * recordBytes + 8, pageBytes, signal);
+            break;
+          }
+        } finally {
+          await run.releaseCache();
+        }
+    signal.throwIfAborted();
+    let page = { bytes: bytes ?? new Uint8Array(pageBytes), dirty: !1 };
+    return this.pages.set(number, page), page;
+  }
+  async stage(chunks2, signal) {
+    let source = await PdfFileSource.fromStream(this.fs, this.directory, chunks2, { signal, chunkBytes: pageBytes, cacheBytes: pageBytes });
+    return this.owned.add(source), source;
+  }
+  async flush(signal) {
+    let dirty = [...this.pages].filter(([, page]) => page.dirty).sort(([a], [b]) => a - b);
+    if (!dirty.length) return;
+    function* records() {
+      for (let [number, page] of dirty) {
+        let header = new Uint8Array(8);
+        new DataView(header.buffer).setFloat64(0, number), yield header, yield page.bytes;
+      }
+    }
+    let current = await this.stage(records(), signal), level = 0;
+    for (; this.runs[level]; ) {
+      let older = this.runs[level];
+      async function* merge() {
+        let a = 0, b = 0, turns = 0;
+        for (; a < current.size / recordBytes || b < older.size / recordBytes; ) {
+          ++turns % 64 === 0 && await new Promise((resolve) => setTimeout(resolve, 0)), signal.throwIfAborted();
+          let left = a < current.size / recordBytes ? await pageNumber(current, a, signal) : 1 / 0, right = b < older.size / recordBytes ? await pageNumber(older, b, signal) : 1 / 0, source = left <= right ? current : older, index = left <= right ? a : b;
+          yield await source.read(index * recordBytes, 8, signal), yield await source.read(index * recordBytes + 8, pageBytes, signal), left <= right && a++, right <= left && b++;
+        }
+      }
+      let merged = await this.stage(merge(), signal);
+      await current.close(), this.owned.delete(current), await older.close(), this.owned.delete(older), this.runs[level] = void 0, current = merged, level++;
+    }
+    this.runs[level] = current;
+    for (let [, page] of dirty) page.dirty = !1;
+  }
+  close() {
+    return this.closing ??= (async () => {
+      await this.active, this.pages.clear();
+      let failure;
+      for (let source of this.owned)
+        try {
+          await source.close();
+        } catch (error) {
+          failure ??= { error };
+        }
+      if (this.owned.clear(), this.runs.length = 0, failure) throw failure.error;
+    })();
+  }
+};
+
 // src/image-pdf.ts
 import { PagedStorage } from "@poe-platform/safe-fs/storage";
 
@@ -169,7 +297,7 @@ function checkLimitInputPixels(width, height, options) {
 }
 
 // src/image-pdf.ts
-import { PdfFileSource, PdfRetainedDocument, PdfError, renderRetainedPagePixels } from "../pdf-ast/index.js";
+import { PdfFileSource as PdfFileSource2, PdfRetainedDocument, PdfError, renderRetainedPagePixels } from "../pdf-ast/index.js";
 import { normalizePath } from "@poe-platform/safe-fs/contracts";
 
 // src/codecs/svg-transform.ts
@@ -1742,7 +1870,7 @@ async function openPdfImage(source, fs, directory, signal, options, storage) {
       if (signal.throwIfAborted(), !(bytes instanceof Uint8Array) || bytes.length !== length2) throw new Error("Truncated PDF image source");
       yield bytes;
     }
-  })(), retained = await PdfFileSource.fromStream(fs, directory, chunks2, { signal, chunkBytes: 16384, cacheBytes: 65536 }), document, owned = storage ? void 0 : new PagedStorage({ fs, cwd: directory, env: {}, signal }, 4), values = storage ?? owned, cleanup = async () => {
+  })(), retained = await PdfFileSource2.fromStream(fs, directory, chunks2, { signal, chunkBytes: 16384, cacheBytes: 65536 }), document, owned = storage ? void 0 : capabilities.open !== !1 && capabilities.randomAccessWrite !== !1 && fs.open && fs.removeFileConditional ? new PagedStorage({ fs, cwd: directory, env: {}, signal }, 4) : new PdfValueStorage(fs, directory, signal), values = storage ?? owned, cleanup = async () => {
     let failure;
     try {
       await document?.close();
@@ -1762,7 +1890,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: { containerStorage: values, 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", compactNumbers: !0, compactKeywords: !0, chunkBytes: 16384, maxNodes: 1 / 0, maxTokenBytes: 1 / 0, maxRecursionDepth: 1 / 0, maxPageTreeDepth: 1 / 0, xref: { arrayStorage: values, storedArrayKeys: ["Index"] }, valueArrays: { dictionaryStorage: values, storedDictionaryKeys: ["Font"], 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);
@@ -1784,7 +1912,7 @@ async function tryPdfDecode(source, storage, fs, directory, signal, options = {}
   if (!owner) return;
   let failed = !1;
   try {
-    let rendered = await renderRetainedPagePixels(owner.page, { fs, directory }, { signal, scale: (settings.density ?? 72) / 72, imageStorage: storage, retainActualText: !0, chunkBytes: 4096, tileSize: 64 }), { width, height } = rendered, length = width * height * 4;
+    let rendered = await renderRetainedPagePixels(owner.page, { fs, directory }, { signal, scale: (settings.density ?? 72) / 72, imageStorage: storage, retainActualText: !0, compactNumbers: !0, compactKeywords: !0, chunkBytes: 4096, tileSize: 64 }), { width, height } = rendered, length = width * height * 4;
     checkLimitInputPixels(width, height, settings);
     let position = storage.allocate(length);
     if (!Number.isSafeInteger(position) || position < 0 || !Number.isSafeInteger(position + length)) throw new RangeError("Invalid PDF image backing allocation");
@@ -7557,7 +7685,7 @@ function* resampleRawBitmapSteps(src, srcW, srcH, dstW, dstH, kernel = "lanczos3
 function* resizeImageSteps(img, spec, postScaleTransform) {
   let work = 0;
   if (img.pages && img.pages > 1 && img.pageHeight && img.height === img.pages * img.pageHeight) {
-    let pages = img.pages, pageH = img.pageHeight, pageBytes = img.width * pageH * 4, resizedPages = [];
+    let pages = img.pages, pageH = img.pageHeight, pageBytes2 = img.width * pageH * 4, resizedPages = [];
     for (let p = 0; p < pages; p++) {
       ++work % 16384 === 0 && (yield);
       let singlePage = {
@@ -7565,7 +7693,7 @@ function* resizeImageSteps(img, spec, postScaleTransform) {
         height: pageH,
         pages: 1,
         pageHeight: pageH,
-        data: img.data.subarray(p * pageBytes, (p + 1) * pageBytes)
+        data: img.data.subarray(p * pageBytes2, (p + 1) * pageBytes2)
       };
       resizedPages.push(yield* resizeImageSteps(singlePage, spec, postScaleTransform));
     }
@@ -8120,11 +8248,11 @@ function* trimImageSteps(img, options) {
 function* extendImageSteps(img, spec) {
   let work = 0;
   if (img.pages && img.pages > 1 && img.pageHeight && img.height === img.pages * img.pageHeight) {
-    let pages = img.pages, pageH = img.pageHeight, pageBytes = img.width * pageH * 4, extendedPages = [];
+    let pages = img.pages, pageH = img.pageHeight, pageBytes2 = img.width * pageH * 4, extendedPages = [];
     for (let p = 0; p < pages; p++)
       ++work % 16384 === 0 && (yield), extendedPages.push(
         yield* extendImageSteps(
-          { ...img, height: pageH, pages: 1, pageHeight: pageH, data: img.data.subarray(p * pageBytes, (p + 1) * pageBytes) },
+          { ...img, height: pageH, pages: 1, pageHeight: pageH, data: img.data.subarray(p * pageBytes2, (p + 1) * pageBytes2) },
           spec
         )
       );
@@ -11441,7 +11569,9 @@ async function tryInspectImageMetadata(input, options, operations, encoding, loa
   let supplied = options.filesystem;
   if (!supplied?.capabilities || typeof input == "string" && !supplied.openReadFile) return;
   if (!joined && (options.text || options.create) && !operations.length) return { value: await consume(readImageMetadata(void 0, options)) };
-  let storage = supplied.open && supplied.removeFileConditional && supplied.stat ? new PagedStorage5({ fs: supplied, cwd: options.workingDirectory ?? (typeof input == "string" ? dirname4(input) : "."), env: {}, signal }) : void 0, failure, result, consumed = !1;
+  let directory = options.workingDirectory ?? (typeof input == "string" ? dirname4(input) : "."), capabilities = await supplied.capabilitiesFor?.(directory, { signal, create: !0 }) ?? supplied.capabilities;
+  signal.throwIfAborted();
+  let storage = capabilities.open !== !1 && capabilities.randomAccessWrite !== !1 && supplied.open && supplied.removeFileConditional && supplied.stat ? new PagedStorage5({ fs: supplied, cwd: directory, env: {}, signal }) : void 0, failure, result, consumed = !1;
   try {
     let inspect = async (source) => {
       let generated = options.text || options.create;

package/dist/mp4-ast/containers/adapters.d.ts

@@ -1,3 +1,4 @@
+import { type AudioStream } from "../../audio-ast/index.js";
 import { type MediaAstPlugin, type MediaDocument, type MediaProbeResult, type MediaProbeRecords, type MediaSourceProbeOptions, type MediaProbeSource, type ParseMediaOptions } from "../types.js";
 export declare function isY4mSignature(bytes: Uint8Array): boolean;
 export declare function parseY4m(bytes: Uint8Array): MediaDocument;
@@ -26,6 +27,12 @@ export declare function wavAst(): MediaAstPlugin;
 export declare function isMp3Signature(bytes: Uint8Array): boolean;
 export declare function mp3Ast(): MediaAstPlugin;
 export declare function flacAst(): MediaAstPlugin;
+/** Format a validated Ogg audio stream without materializing its sample payload. */
+export declare function probeOggStreamMetadata(stream: AudioStream, size: number, options?: MediaSourceProbeOptions): MediaProbeRecords;
+/** Bounded FLAC-mapped Ogg probe; undefined admits the other Ogg codecs. */
+export declare function probeOggFlacSource(source: MediaProbeSource, options?: MediaSourceProbeOptions & {
+    checkpoint?: () => void | Promise<void>;
+}): Promise<MediaProbeRecords | undefined>;
 export declare function oggAst(): MediaAstPlugin;
 export declare function isGifSignature(bytes: Uint8Array): boolean;
 export declare function isPngSignature(bytes: Uint8Array): boolean;

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

@@ -16,6 +16,14 @@ export interface RetainedXmlDocument {
     resolveNamespace(node: RetainedXmlNode, prefix: () => ByteSource): Promise<ByteSource | undefined>;
     children(node: RetainedXmlNode): AsyncGenerator<RetainedXmlNode>;
     attributes(node: RetainedXmlNode): AsyncGenerator<RetainedXmlNode>;
+    /** Local xmlns attributes, in source order. */
+    declarations(node: RetainedXmlNode): AsyncGenerator<RetainedXmlNode>;
+    /** Element-only document order, including the selected root, without a heap stack. */
+    elements(node: RetainedXmlNode): AsyncGenerator<RetainedXmlNode>;
+    /** Exact decoded UTF-8 source markup; neither standalone namespace injection nor normalization. */
+    markup(node: RetainedXmlNode): ByteSource;
+    /** Source markup with direct element children removed; retains text, comments and instructions. */
+    shell(node: RetainedXmlNode): ByteSource;
     namespace(node: RetainedXmlNode): ByteSource;
     text(node: RetainedXmlNode): ByteSource;
     raw(range: XmlRange): ByteSource;

package/dist/pdf-ast/ast.d.ts

@@ -46,6 +46,8 @@ export interface PdfDictEntry {
     readonly value: PdfCosNode;
 }
 export interface PdfCosDict {
+    /** Caller-backed ordered entries; entries is empty when this descriptor is present. */
+    readonly storedEntries?: PdfStoredItems;
     readonly kind: "dict";
     readonly entries: PdfDictEntry[];
     readonly span?: ByteSpan | undefined;

package/dist/pdf-ast/content/dictionary-cursor.d.ts

@@ -0,0 +1,15 @@
+import type { PdfCosDict, PdfDictEntry, PdfStoredItems } from "../ast.js";
+export interface PdfDictionaryEntryRequest {
+    readonly kind: "dictionary-entry";
+    readonly entries: PdfStoredItems;
+    readonly position: number;
+}
+/** Pull one entry through a driver's I/O boundary, retaining source order. */
+export declare class PdfDictionaryCursor {
+    private readonly dict;
+    private index;
+    private position;
+    private readonly length;
+    constructor(dict: PdfCosDict);
+    next(): Generator<PdfDictionaryEntryRequest, IteratorResult<PdfDictEntry, void>, unknown>;
+}

package/dist/pdf-ast/content/range-operator-parser.d.ts

@@ -2,6 +2,10 @@ import type { PdfIndexStorage } from "../cos/object-index.js";
 import type { PdfFileSource } from "../source.js";
 import { type PdfContentOperator } from "./operator-parser.js";
 export interface ParseContentRangeOptions {
+    /** Bound ignored keyword spellings while preserving command recovery. */
+    readonly compactKeywords?: boolean;
+    /** Bound numeric token spelling without changing operand values. */
+    readonly compactNumbers?: boolean;
     /** Preserve inline ActualText bytes on pathStorage for retained consumers. */
     readonly retainActualText?: boolean;
     readonly pathStorage?: import("../ast.js").PdfPixelStorage;

package/dist/pdf-ast/content/stored-dictionary.d.ts

@@ -0,0 +1,10 @@
+import { type PdfIndexStorage } from "../cos/object-index.js";
+import type { PdfCosDict, PdfCosNode, PdfDictEntry } from "../ast.js";
+/** Preserve source order and duplicates while keeping only one entry resident. */
+export declare function readPdfDictionaryEntries(dict: PdfCosDict, signal?: AbortSignal): AsyncGenerator<PdfDictEntry, void>;
+/** Same last-key-wins semantics as dictGet, without collecting a retained map. */
+export declare function readPdfDictionaryValue(dict: PdfCosDict, key: string, signal?: AbortSignal): Promise<PdfCosNode | undefined>;
+/** Clone a resource map and fill missing keys from an appearance. Destination
+ * duplicates keep their first insertion order and last value; source keys keep
+ * their first value. External indexes replace an unbounded resident name map. */
+export declare function mergePdfResourceDictionaries(destination: PdfCosDict, source: PdfCosDict | undefined, indexStorage: PdfIndexStorage, signal?: AbortSignal): Promise<PdfCosDict>;

package/dist/pdf-ast/cos/lexer.d.ts

@@ -1,7 +1,3 @@
-/*! Numeric recovery and malformed-command handling adapted from Mozilla PDF.js.
- * Copyright 2017 Mozilla Foundation. Licensed under Apache-2.0.
- * See licenses/PDFJS-APACHE-2.0.txt and THIRD_PARTY_NOTICES.md.
- */
 import { type ByteSpan, type PdfPixelStorage, type PdfStoredBytes } from "../ast.js";
 import type { PdfFileSource } from "../source.js";
 export type CosToken = {
@@ -49,6 +45,7 @@ export type CosToken = {
 } | {
     readonly kind: "keyword";
     readonly value: string;
+    readonly truncated?: true;
     readonly span: ByteSpan;
 };
 export declare function isPdfWhitespace(byte: number): boolean;
@@ -61,12 +58,14 @@ declare class CosLexerState {
     readonly knownCommands?: ReadonlySet<string> | undefined;
     private readonly onTokenAllocation?;
     stringMode: StringMode;
+    private readonly compactNumbers;
     private window;
     private windowStart;
     pos: number;
     readonly end: number;
     readonly maxTokenBytes: number;
-    constructor(bytes: Uint8Array, start?: number, end?: number, maxTokenBytes?: number, knownCommands?: ReadonlySet<string> | undefined, onTokenAllocation?: ((bytes: number) => void) | undefined, stringMode?: StringMode);
+    private readonly keywordLimit;
+    constructor(bytes: Uint8Array, start?: number, end?: number, maxTokenBytes?: number, knownCommands?: ReadonlySet<string> | undefined, onTokenAllocation?: ((bytes: number) => void) | undefined, stringMode?: StringMode, compactNumbers?: boolean, compactKeywords?: boolean);
     private byte;
     private spanBytes;
     get offset(): number;
@@ -86,6 +85,10 @@ export declare class CosByteLexer extends CosLexerState {
     skipWhitespaceAndComments(): void;
 }
 export interface CosRangeLexerOptions {
+    /** Retain only a prefix of unknown keywords, marking them truncated. */
+    readonly compactKeywords?: boolean;
+    /** Canonicalize number spellings longer than 2048 characters with bounded scratch. */
+    readonly compactNumbers?: boolean;
     readonly onBackingError?: (error: unknown) => void;
     /** Decoded string payloads use caller-owned backing instead of token arrays. */
     readonly stringStorage?: PdfPixelStorage;

package/dist/pdf-ast/cos/object-reader.d.ts

@@ -5,9 +5,9 @@ import { type PdfStreamDecodeOptions } from "./filter-stream.js";
 import { type PdfCrossReference, type PdfCrossReferenceOptions } from "./cross-reference.js";
 import { PdfObjectIndex, type PdfIndexStorage } from "./object-index.js";
 import { type ParseCosRangeOptions, type PdfRangeObject } from "./range-parser.js";
-export interface PdfObjectReaderOptions extends Omit<ParseCosRangeOptions, "resolveLength" | keyof ValueArrayStorage | "onBackingError">, PdfStreamDecodeOptions {
-    /** Default backing for selected structural arrays in explicit object lookups.
-     * Cross-reference bootstrap and stream filter dictionaries remain independent. */
+export interface PdfObjectReaderOptions extends Omit<ParseCosRangeOptions, "resolveLength" | keyof ValueArrayStorage>, PdfStreamDecodeOptions {
+    /** Default backing for selected values in object and stream dictionary lookups.
+     * Cross-reference bootstrap remains independently configured. */
     readonly valueArrays?: ValueArrayStorage;
     readonly cacheBytes?: number;
     readonly encryption?: PdfEncryptionState;
@@ -28,6 +28,7 @@ export declare class PdfObjectReader {
     private readonly index;
     private readonly storage;
     private readonly streams;
+    private readonly backingFailures;
     private readonly repairedOffsets;
     private readonly options;
     private readonly capacity;

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

@@ -2,6 +2,10 @@ import { type ByteSpan, type PdfCosNode, type PdfCosRef } from "../ast.js";
 import type { PdfFileSource } from "../source.js";
 import { type ValueArrayStorage } from "./value-parser.js";
 export interface ParseCosRangeOptions extends ValueArrayStorage {
+    /** Bound unknown keyword spellings without changing recognition or source spans. */
+    readonly compactKeywords?: boolean;
+    /** Bound numeric spelling scratch; long raw spellings become equivalent canonical numbers. */
+    readonly compactNumbers?: boolean;
     /** @internal Distinguish caller storage failures from recoverable PDF syntax. */
     readonly onBackingError?: (error: unknown) => void;
     /** Exclusive direct-value boundary, used for object-stream members. */

package/dist/pdf-ast/cos/retained-objects.d.ts

@@ -3,6 +3,7 @@ import type { PdfIndexStorage } from "./object-index.js";
 import type { PdfRetainedOutputObject } from "./retained-writer.js";
 export interface PdfRetainedObjectsOptions {
     readonly normalizeContent?: boolean;
+    readonly streamMode?: "preserve" | "compress" | "uncompress";
     /** Number of live indirect objects admitted before parsing their values. */
     readonly maxObjects?: number;
     /** Encoded output payload bytes per stream, after decryption. */

package/dist/pdf-ast/cos/retained-writer.d.ts

@@ -25,6 +25,7 @@ export interface PdfSerializedOutputObject {
 }
 export declare function pdfOutputStreamDictionary(value: PdfCosNode, length: number): {
     entries: import("../ast.js").PdfDictEntry[];
+    storedEntries?: import("../ast.js").PdfStoredItems;
     kind: "dict";
     span?: import("../ast.js").ByteSpan | undefined;
 };

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

@@ -1,6 +1,9 @@
 import type { PdfCosNode, PdfCosDict, PdfDictEntry, PdfPixelStorage, PdfStoredItems } from "../ast.js";
 import type { CosToken } from "./lexer.js";
 export interface ValueArrayStorage {
+    readonly dictionaryStorage?: PdfPixelStorage;
+    readonly storedDictionaryKeys?: readonly string[];
+    readonly storeRootDictionary?: boolean;
     readonly arrayStorage?: PdfPixelStorage;
     /** Back suspended parser containers; selected descriptors must share this storage. */
     readonly containerStorage?: PdfPixelStorage;
@@ -26,11 +29,17 @@ export type ValueContainer = ({
     kind: "dict";
     start: number;
     entries: PdfDictEntry[];
+    storedEntries?: PdfStoredItems;
+    tail: number;
     key?: PdfDictEntry["key"];
 }) & {
     path: readonly (string | null)[];
 };
 export type ValueWork<T> = Generator<void | "token" | PdfCosDict | {
+    kind: "dictionary-append";
+    entry: PdfDictEntry;
+    previous: number;
+} | {
     kind: "array-append";
     node: PdfCosNode;
     previous: number;

package/dist/pdf-ast/edit/retained-append-attachments.d.ts

@@ -0,0 +1,13 @@
+import { PdfMutableObjectStore } from "../cos/mutable-object-store.js";
+import type { PdfIndexStorage } from "../cos/object-index.js";
+import type { PdfRetainedDocument } from "../retained-document.js";
+export interface RetainedAppendAttachment {
+    readonly filename: string;
+    readonly chunks: AsyncIterable<Uint8Array>;
+}
+/** Append compressed attachments, preserving existing name-tree structure and
+ * duplicate names. Optionally add PushPin annotations to a zero-based page. */
+export declare function appendRetainedAttachments(document: PdfRetainedDocument, target: PdfMutableObjectStore, storage: PdfIndexStorage, attachments: AsyncIterable<RetainedAppendAttachment>, options?: {
+    pageIndex?: number;
+    signal?: AbortSignal;
+}): Promise<void>;

package/dist/pdf-ast/edit/retained-bookmarks.d.ts

@@ -0,0 +1,13 @@
+import { type PdfCosRef } from "../ast.js";
+import type { PdfMutableObjectStore } from "../cos/mutable-object-store.js";
+import type { PdfIndexStorage } from "../cos/object-index.js";
+export interface RetainedBookmark {
+    readonly title: string;
+    /** One-based hierarchy depth; jumps descend through the last child only. */
+    readonly level: number;
+    /** One-based destination, clamped to the document's page range. */
+    readonly pageNumber: number;
+}
+/** Replace outlines in producer order. Parent frames live in caller storage,
+ * including their last sibling and immediate child count. */
+export declare function setRetainedBookmarks(store: PdfMutableObjectStore, storage: PdfIndexStorage, root: PdfCosRef, pageCount: number, pageReference: (index: number) => Promise<PdfCosRef>, bookmarks: Iterable<RetainedBookmark> | AsyncIterable<RetainedBookmark>, signal: AbortSignal, maxDepth?: number): Promise<void>;

package/dist/pdf-ast/edit/retained-graph.d.ts

@@ -1,3 +1,6 @@
+import { type RetainedBookmark } from "./retained-bookmarks.js";
+export type { RetainedBookmark } from "./retained-bookmarks.js";
+import { type RetainedAppendAttachment } from "./retained-append-attachments.js";
 import { type RetainedStampInput } from "./retained-stamps.js";
 export type { RetainedStampInput } from "./retained-stamps.js";
 import { type RetainedInlineImageOptions } from "./retained-inline-images.js";
@@ -10,6 +13,9 @@ import type { PdfIndexStorage } from "../cos/object-index.js";
 import { PdfRetainedDocument, PdfRetainedPage } from "../retained-document.js";
 import type { SaveRetainedDocumentOptions } from "./retained-save.js";
 export type EditRetainedDocumentOptions = Pick<SaveRetainedDocumentOptions, "linearize" | "rotations" | "removeInfo" | "removeMetadata" | "removeStructure" | "removeAcroform" | "removePageLabels" | "maxObjects" | "maxPages" | "maxRecursionDepth" | "signal"> & {
+    readonly bookmarks?: Iterable<RetainedBookmark> | AsyncIterable<RetainedBookmark>;
+    readonly appendAttachments?: AsyncIterable<RetainedAppendAttachment>;
+    readonly attachmentPageIndex?: number;
     readonly stamps?: Iterable<RetainedStampInput> | AsyncIterable<RetainedStampInput>;
     readonly generateAppearances?: boolean;
     readonly flattenAnnotations?: "all" | "print" | "screen";

package/dist/pdf-ast/edit/retained-save.d.ts

@@ -11,6 +11,8 @@ export interface SaveRetainedDocumentOptions {
     readonly linearize?: boolean;
     /** Retained snapshots keep their encoded streams; normalization prevents packing. */
     readonly normalizeContent?: boolean;
+    /** Decode and rewrite every stream using caller-backed staging. */
+    readonly streamMode?: "preserve" | "compress" | "uncompress";
     readonly objectStreams?: "generate" | "disable" | "preserve";
     /** Ordered edits; duplicate page selections apply cumulatively. */
     readonly rotations?: Iterable<RetainedPageRotation> | AsyncIterable<RetainedPageRotation>;

package/dist/pdf-ast/edit/retained-stamps.d.ts

@@ -4,6 +4,8 @@ import type { PdfRetainedDocument, PdfRetainedPage } from "../retained-document.
 export interface RetainedStampInput {
     readonly source: PdfRetainedDocument;
     readonly mode: "overlay" | "underlay";
+    /** Preserve encoded content streams and apply collision renames simultaneously. */
+    readonly preserveStreams?: boolean;
     /** Zero-based page pairs, consumed in order; duplicates are applied repeatedly. */
     readonly pages: Iterable<{
         sourceIndex: number;
@@ -15,3 +17,10 @@ export interface RetainedStampInput {
 }
 /** Stamp one page at a time; content, clone identities and page indexes use caller backing. */
 export declare function stampRetainedPages(document: PdfRetainedDocument, store: PdfMutableObjectStore, storage: PdfIndexStorage, getPage: (index: number) => Promise<PdfRetainedPage>, stamps: Iterable<RetainedStampInput> | AsyncIterable<RetainedStampInput>, signal: AbortSignal): Promise<void>;
+export declare function retainedStampTransform(dstAttributes: {
+    mediaBox: readonly [number, number, number, number];
+    rotation: number;
+}, srcAttributes: {
+    mediaBox: readonly [number, number, number, number];
+    rotation: number;
+}): string;

package/dist/pdf-ast/fonts/resolve.d.ts

@@ -1,3 +1,4 @@
+import { type PdfDictionaryEntryRequest } from "../content/dictionary-cursor.js";
 import type { StoredFontEncoding } from "./stored-encoding.js";
 import { StoredFontWidths } from "./stored-widths.js";
 import type { StoredCffFont } from "./stored-cff.js";
@@ -13,7 +14,7 @@ import type { ParsedCosDocument } from "../cos/parser.js";
 import { type ParsedToUnicodeCMap } from "./cmap.js";
 import { type ParsedTrueTypeFont } from "./truetype.js";
 type Matrix6 = [number, number, number, number, number, number];
-export type FontResolutionRequest = {
+export type FontResolutionRequest = PdfDictionaryEntryRequest | {
     kind: "font-encoding";
     array: PdfCosArray;
 } | {
@@ -39,6 +40,7 @@ export type FontResolutionRequest = {
     kind: "resolve";
     node: PdfCosNode | undefined;
     storeRootArray?: boolean;
+    storeRootDictionary?: boolean;
 } | {
     kind: "decode";
     stream: PdfCosStream;

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

@@ -25,6 +25,7 @@ export { parseContentOperators, type PdfContentOperator } from "./content/operat
 export * from "./content/range-operator-parser.js";
 export * from "./content/range-events.js";
 export { readStoredItems } from "./content/stored-record.js";
+export { readPdfDictionaryEntries, readPdfDictionaryValue } from "./content/stored-dictionary.js";
 export * from "./content/serializer.js";
 export * from "./content/evaluator.js";
 export * from "./content/retained-evaluator.js";
@@ -70,10 +71,11 @@ export { createRetainedPageCopy, type PdfRetainedPageCopy, copyRetainedPageChunk
 export { PdfRawTextIndex, type PdfRawTextGlyph, type PdfRawTextIndexOptions, type PdfStoredTextWord, type PdfStoredTextLine, type PdfStoredTextBlock } from "./extract/raw-text-index.js";
 export { retainedCosObjects, type PdfRetainedObjectsOptions } from "./cos/retained-objects.js";
 export { saveRetainedDocumentChunks, type SaveRetainedDocumentOptions, type RetainedPageRotation } from "./edit/retained-save.js";
-export { editRetainedDocument, PdfDuplicateAttachment, type RetainedAttachmentInput, type EditRetainedDocumentOptions, type RetainedStampInput, type RetainedPageLabel } from "./edit/retained-graph.js";
+export { editRetainedDocument, PdfDuplicateAttachment, type RetainedAttachmentInput, type EditRetainedDocumentOptions, type RetainedBookmark, type RetainedStampInput, type RetainedPageLabel } from "./edit/retained-graph.js";
 export { copyRetainedAttachments } from "./edit/retained-attachment-copies.js";
 export { retainedObjectOrder } from "./cos/retained-object-order.js";
 export { encryptRetainedPdfChunks } from "./cos/retained-encryption.js";
 export { replaceRetainedPdfName } from "./edit/retained-name-replacement.js";
 export { QpdfJsonValues } from "./cos/qpdf-json-values.js";
 export { QpdfJsonDocument, type ApplyQpdfJsonOptions } from "./cos/qpdf-json-document.js";
+export type { RetainedAppendAttachment } from "./edit/retained-append-attachments.js";