@poe-platform/safe-bash 0.1.810 → 0.1.811

package/dist/safe-bash-command-pdftk/index.js

@@ -1,35 +1,343 @@
 import "../safe-bash/command-chunks/chunk-65DS4IOB.js";
 
-// packages/safe-bash-command-pdftk/src/index.ts
+// packages/safe-bash-command-pdftk/src/retained.ts
+import { PdfError, PdfFileSource, PdfRetainedDocument, retainedCosObjects } from "../pdf-ast/index.js";
+import { FsError } from "../safe-bash-contracts/errors.js";
+import { writeBytes } from "../safe-bash-contracts/io.js";
 import { resolvePath } from "../safe-bash-contracts/path.js";
-import { yieldTurn, drainCooperativeSteps as drainSteps } from "../safe-bash-contracts/yield.js";
-import { InputByteBudget } from "../safe-bash-contracts/io.js";
 import { writeFileOutput } from "../safe-bash-contracts/filesystem-output-budget.js";
-import {
-  commandRuntimeIdentity,
-  getCommandArguments
-} from "../safe-bash-contracts/command.js";
-import { readBytes, writeBytes } from "../safe-bash-contracts/io.js";
-import { createOutputOperation } from "../safe-bash-contracts/output.js";
-import {
-  PdfDocument,
-  cosArray,
-  cosDict,
-  cosHexString,
-  cosName,
-  cosNumber,
-  cosStream,
-  cosString,
-  decodePdfString,
-  dictDelete,
-  dictGet,
-  dictSet,
-  flattenDocumentFormFields,
-  getDocumentFormFields,
-  parseFormDataBytes,
-  resolveDestinationPageIndex,
-  setDocumentFormField
-} from "../pdf-ast/index.js";
+
+// packages/safe-bash-command-pdftk/src/retained-annots.ts
+import { IntegerTable, PagedStorage } from "@poe-platform/safe-fs/storage";
+import { PdfMutableObjectStore, decodePdfString, dictGet } from "../pdf-ast/index.js";
+async function* retainedAnnotationReport(document, storage, utf8, signal) {
+  const backing = new PagedStorage({ fs: storage.fs, cwd: storage.directory, env: {}, signal }, 4), pages = new IntegerTable(backing, 64);
+  let pageCount = 0, work = 0, failed = false;
+  const encoder = new TextEncoder();
+  async function checkpoint() {
+    signal.throwIfAborted();
+    if (++work % 64 === 0) await new Promise((resolve2) => setTimeout(resolve2, 0));
+    signal.throwIfAborted();
+  }
+  async function resolve(node) {
+    await checkpoint();
+    const result = await document.lookup(node);
+    return result?.stream ? void 0 : result?.value;
+  }
+  async function* line(prefix, value, encode = false) {
+    let part = prefix;
+    for (const char of String(value)) {
+      const code = char.codePointAt(0);
+      part += encode && !utf8 && code > 127 ? `&#${code};` : char;
+      if (part.length >= 4096) {
+        await checkpoint();
+        yield encoder.encode(part);
+        part = "";
+      }
+    }
+    yield encoder.encode(part + "\n");
+  }
+  async function* walk(start, key) {
+    if (!start) return;
+    const stack = new PdfMutableObjectStore(storage, { signal }), seen = new IntegerTable(backing, 64);
+    let pending = 0, failed2 = false;
+    const push = async (value) => {
+      await checkpoint();
+      await stack.set({ objectNumber: ++pending, generationNumber: 0, value });
+    };
+    try {
+      await push(start);
+      while (pending) {
+        await checkpoint();
+        const raw = (await stack.get(pending--)).value;
+        if (raw.kind === "ref") {
+          if (await seen.get(BigInt(raw.objectNumber))) continue;
+          await seen.set(BigInt(raw.objectNumber), 1n);
+        }
+        const value = await resolve(raw);
+        if (value?.kind === "array" && key === "Next") {
+          for (let i = value.items.length - 1; i >= 0; i--) await push(value.items[i]);
+          continue;
+        }
+        if (value?.kind !== "dict") continue;
+        yield value;
+        const child = dictGet(value, key);
+        if (key === "Next") {
+          if (child) await push(child);
+        } else {
+          const kids = await resolve(child);
+          if (kids?.kind === "array") for (let i = kids.items.length - 1; i >= 0; i--) await push(kids.items[i]);
+        }
+      }
+    } catch (error) {
+      failed2 = true;
+      throw error;
+    } finally {
+      await stack.close().catch((error) => {
+        if (!failed2) throw error;
+      });
+    }
+  }
+  async function destinationIndex(raw) {
+    let node = await resolve(raw);
+    if (node?.kind === "dict") {
+      const target = dictGet(node, "D") ?? dictGet(node, "Dest");
+      if (target) node = await resolve(target);
+    }
+    if (node?.kind === "string" || node?.kind === "name") {
+      const name = node.kind === "string" ? decodePdfString(node) : node.decoded;
+      const root = await resolve(document.crossReference.rootRef);
+      let target;
+      if (root?.kind === "dict") {
+        const legacy = await resolve(dictGet(root, "Dests"));
+        if (legacy?.kind === "dict") target = dictGet(legacy, name);
+        if (!target) {
+          const names = await resolve(dictGet(root, "Names"));
+          if (names?.kind === "dict") for await (const branch of walk(dictGet(names, "Dests"), "Kids")) {
+            const pairs = await resolve(dictGet(branch, "Names"));
+            if (pairs?.kind === "array") for (let i = 0; i + 1 < pairs.items.length; i += 2) {
+              const key = await resolve(pairs.items[i]);
+              if ((key?.kind === "string" ? decodePdfString(key) : key?.kind === "name" ? key.decoded : "") === name) {
+                target = pairs.items[i + 1];
+                break;
+              }
+            }
+            if (target) break;
+          }
+        }
+      }
+      node = await resolve(target);
+      if (node?.kind === "dict") {
+        const inner = dictGet(node, "D");
+        if (inner) node = await resolve(inner);
+      }
+    }
+    if (node?.kind !== "array" || !node.items.length) return;
+    const first = node.items[0];
+    if (first.kind === "ref") {
+      const found = await pages.get(BigInt(first.objectNumber));
+      return found ? Number(found) - 1 : void 0;
+    }
+    const number = await resolve(first);
+    return number?.kind === "number" && number.value >= 0 && number.value < pageCount ? Math.round(number.value) : void 0;
+  }
+  async function destinationText(raw) {
+    const node = await resolve(raw);
+    if (node?.kind === "string") return decodePdfString(node);
+    if (node?.kind === "name") return node.decoded;
+    if (node?.kind === "array") {
+      const first = node.items[0];
+      if (first?.kind === "ref") {
+        const found = await pages.get(BigInt(first.objectNumber));
+        if (found) return `page ${found}`;
+      } else if (first?.kind === "number") return `page ${first.value + 1}`;
+    }
+    if (node?.kind === "dict") {
+      const index = await destinationIndex(node);
+      if (index !== void 0) return `page ${index + 1}`;
+    }
+    return;
+  }
+  async function* stringField(dict, key, label) {
+    const node = await resolve(dictGet(dict, key));
+    if (node?.kind === "string") yield* line(label, decodePdfString(node), true);
+  }
+  try {
+    for await (const page of document.pages()) {
+      pageCount++;
+      if (page.reference && !await pages.get(BigInt(page.reference.objectNumber))) await pages.set(BigInt(page.reference.objectNumber), BigInt(page.index + 1));
+    }
+    for (let i = 0; i < 2; i++) {
+      const id = await resolve(document.crossReference.idArray?.items[i]);
+      if (id?.kind !== "string") yield* line(`PdfID${i}: `, "00000000000000000000000000000000");
+      else {
+        yield encoder.encode(`PdfID${i}: `);
+        for (let at = 0; at < id.bytes.length; at += 2048) {
+          await checkpoint();
+          let text = "";
+          for (const byte of id.bytes.subarray(at, at + 2048)) text += byte.toString(16).padStart(2, "0");
+          yield encoder.encode(text);
+        }
+        yield encoder.encode("\n");
+      }
+    }
+    yield* line("NumberOfPages: ", pageCount);
+    for await (const page of document.pages()) {
+      const annotations = await resolve(dictGet(page.dict, "Annots"));
+      if (annotations?.kind !== "array") continue;
+      for (const item of annotations.items) {
+        const annotation = await resolve(item);
+        if (annotation?.kind !== "dict") continue;
+        const subtype = await resolve(dictGet(annotation, "Subtype")), rect = await resolve(dictGet(annotation, "Rect"));
+        const numbers = [];
+        if (rect?.kind === "array") for (const value of rect.items) {
+          const number = await resolve(value);
+          if (numbers.length < 4) numbers.push(number?.kind === "number" ? number.value : 0);
+        }
+        else numbers.push(0, 0, 0, 0);
+        yield encoder.encode("---\n");
+        yield* line("AnnotSubtype: ", subtype?.kind === "name" ? subtype.decoded : "Annot");
+        yield* line("AnnotRect: ", numbers.join(" "));
+        for (const [key, label] of [["NM", "Name"], ["T", "Title"], ["Subj", "Subj"], ["Contents", "Contents"]]) yield* stringField(annotation, key, `Annot${label}: `);
+        const color = await resolve(dictGet(annotation, "C"));
+        if (color?.kind === "array" && color.items.length >= 3) {
+          const channels = [];
+          for (const value of color.items.slice(0, 3)) {
+            const number = await resolve(value);
+            channels.push(number?.kind === "number" ? number.value : 0);
+          }
+          yield* line("AnnotColor: ", channels.join(" "));
+        }
+        const open = await resolve(dictGet(annotation, "Open"));
+        if (open?.kind === "boolean") yield* line("AnnotOpen: ", open.value);
+        yield* stringField(annotation, "M", "AnnotModificationDate: ");
+        const flags = await resolve(dictGet(annotation, "F"));
+        yield* line("AnnotFlags: ", flags?.kind === "number" ? flags.value : 0);
+        yield* line("AnnotPageNumber: ", page.index + 1);
+        const action = dictGet(annotation, "A");
+        if (action) for await (const dict of walk(action, "Next")) {
+          const type = await resolve(dictGet(dict, "S"));
+          if (type?.kind === "name" && type.decoded) yield* line("AnnotActionType: ", type.decoded);
+          yield* stringField(dict, "URI", "AnnotActionURI: ");
+          const dest = dictGet(dict, "D"), text = await destinationText(dest);
+          if (text) yield* line("AnnotActionDest: ", text, true);
+          const index = await destinationIndex(dest ?? dict);
+          if (index !== void 0) yield* line("AnnotActionPageNumber: ", index + 1);
+          const file = await resolve(dictGet(dict, "F"));
+          if (file?.kind === "string") yield* line("AnnotActionFile: ", decodePdfString(file), true);
+          else if (file?.kind === "dict") {
+            const name = await resolve(dictGet(file, "UF") ?? dictGet(file, "F"));
+            if (name?.kind === "string") yield* line("AnnotActionFile: ", decodePdfString(name), true);
+          }
+        }
+        else if (dictGet(annotation, "Dest")) {
+          yield* line("AnnotActionType: ", "GoTo");
+          const dest = dictGet(annotation, "Dest"), text = await destinationText(dest);
+          if (text) yield* line("AnnotActionDest: ", text, true);
+          const index = await destinationIndex(dest);
+          if (index !== void 0) yield* line("AnnotActionPageNumber: ", index + 1);
+        }
+      }
+    }
+  } catch (error) {
+    failed = true;
+    throw error;
+  } finally {
+    await backing.close().catch((error) => {
+      if (!failed) throw error;
+    });
+  }
+}
+
+// packages/safe-bash-command-pdftk/src/retained.ts
+async function executeRetainedPdftk(context, options) {
+  const signal = context.signal, storage = { fs: context.fs, directory: resolvePath(context.cwd, context.env.TMPDIR || "/tmp") };
+  const inputs = /* @__PURE__ */ new Map();
+  let document, output, total = 0, failed = false;
+  const diagnostic = async (message) => {
+    await writeBytes(context.stderr, new TextEncoder().encode(message), signal);
+    return { exitCode: 1 };
+  };
+  try {
+    await context.fs.mkdir(storage.directory, { recursive: true, signal });
+    const maximum = context.inputBudget?.maxBytes ?? Infinity;
+    if (options.inputs.some((input) => input.file === "-")) {
+      const source = await PdfFileSource.fromStream(context.fs, storage.directory, context.stdin, { signal, maxInputBytes: maximum });
+      inputs.set("-", source);
+      total += source.size;
+      context.inputBudget?.check(total);
+    }
+    for (const input of options.inputs) {
+      if (inputs.has(input.file)) continue;
+      let source;
+      try {
+        source = await PdfFileSource.open(context.fs, resolvePath(context.cwd, input.file), { signal, maxInputBytes: maximum - total });
+      } catch (error) {
+        signal.throwIfAborted();
+        if (error instanceof Error && "code" in error && ["ENOENT", "ENOTDIR", "EACCES", "EISDIR"].includes(String(error.code)) || error instanceof PdfError && error.message === "PDF source must be a regular file") {
+          inputs.set(input.file, void 0);
+          continue;
+        }
+        throw error;
+      }
+      inputs.set(input.file, source);
+      total += source.size;
+      context.inputBudget?.check(total);
+    }
+    for (const input of options.inputs) {
+      const source = inputs.get(input.file);
+      if (!source) return await diagnostic(`Error: Unable to find file '${input.file}'
+`);
+      try {
+        document = await PdfRetainedDocument.open(source, storage, { signal, recovery: "strict", ...input.password ? { password: input.password } : {} });
+        for await (const object of retainedCosObjects(document, storage, { signal })) if (object.stream) for await (const ignored of object.stream.chunks) void ignored;
+        for await (const ignored of document.pages()) void ignored;
+      } catch (error) {
+        signal.throwIfAborted();
+        if (!(error instanceof PdfError) || error.code === "E_LIMIT" || error.code === "E_CANCELLED") throw error;
+        return await diagnostic(`Error: Failed to open PDF '${input.file}': ${error.message}
+`);
+      }
+      await document.close();
+      document = void 0;
+      await source.releaseCache();
+    }
+    const primary = options.inputs[0];
+    document = await PdfRetainedDocument.open(inputs.get(primary.file), storage, { signal, recovery: "strict", ...primary.password ? { password: primary.password } : {} });
+    output = await PdfFileSource.fromStream(context.fs, storage.directory, retainedAnnotationReport(document, storage, options.operation.endsWith("_utf8"), signal), { signal });
+    const destination = options.outputTarget;
+    if (!destination || destination === "-") for await (const bytes of output.stream(0, output.size, signal)) await writeBytes(context.stdout, bytes, signal);
+    else {
+      try {
+        await publish(context, resolvePath(context.cwd, destination), output);
+      } catch (error) {
+        signal.throwIfAborted();
+        if (!(error instanceof Error) || !("code" in error)) throw error;
+        return await diagnostic(`Error: Failed to open output file '${destination}': ${error.code}.
+`);
+      }
+    }
+    return { exitCode: 0 };
+  } catch (error) {
+    failed = true;
+    throw error;
+  } finally {
+    const results = await Promise.allSettled([document?.close(), output?.close(), ...[...inputs.values()].map((source) => source?.close())]);
+    if (!failed) {
+      for (const result of results) if (result.status === "rejected") await Promise.reject(result.reason);
+    }
+  }
+}
+async function publish(context, path, source) {
+  const fs = context.fs, signal = context.signal;
+  const capabilities = await fs.capabilitiesFor?.(path, { signal, create: true, stagingAncestry: true }) ?? fs.capabilities;
+  if (!capabilities.atomicFileStaging || !capabilities.retainedStagingWrite || !capabilities.retainedStagingCleanup || !capabilities.atomicStagingAncestry || !fs.prepareStagingResolution || !fs.createStagedFile || !fs.publishStagedFile) throw new FsError("ENOTSUP", { path, message: "PDF output requires retained atomic staging" });
+  const resolution = await fs.prepareStagingResolution(path, { signal }), directory = resolvePath(resolution.path, "..");
+  const staging = await fs.createStagedFile(`${directory}/.pdf-${crypto.randomUUID()}`, "output", { type: "file", data: new Uint8Array() }, { parent: resolution.parent, retainCleanup: true, signal });
+  let failed = false;
+  try {
+    if (!staging.writer || !staging.cleanup) throw new FsError("ENOTSUP", { path, message: "PDF backend omitted retained staging handles" });
+    for await (const bytes of source.stream(0, source.size, signal)) await writeFileOutput(context, bytes, (data) => staging.writer.write(data, { signal }));
+    const stat = await staging.writer.finish({ signal });
+    await fs.publishStagedFile({ ...staging, file: { ...staging.file, stat } }, resolution.path, { parent: resolution.parent, destination: resolution.destination, ancestors: resolution.ancestors, commitGuard: resolution.validate, signal });
+  } catch (error) {
+    failed = true;
+    throw error;
+  } finally {
+    const cleanup = async () => {
+      try {
+        await staging.cleanup?.remove();
+      } finally {
+        await staging.cleanup?.close();
+      }
+    };
+    await cleanup().catch((error) => {
+      if (!failed) throw error;
+    });
+  }
+}
+
+// packages/safe-bash-command-pdftk/src/arguments.ts
 var PDFTK_OPERATIONS = /* @__PURE__ */ new Set([
   "cat",
   "shuffle",
@@ -55,6 +363,175 @@ var PDFTK_OPERATIONS = /* @__PURE__ */ new Set([
   "output",
   "input_pw"
 ]);
+function* parsePdftkArgumentsSteps(argv) {
+  let cooperativeWork = 63;
+  if (argv.length === 0 || argv.includes("--help") || argv.includes("-h")) {
+    return { result: {
+      exitCode: 0,
+      stdout: "Usage: pdftk <input PDF files | [handle]=filename ...> [<operation> <operation arguments>] [output <output filename>] [flatten]\n",
+      stderr: ""
+    } };
+  }
+  if (argv.includes("--version") || argv.includes("-v")) {
+    return { result: { exitCode: 0, stdout: "pdftk port to Java 3.3.3 (safe-bash @poe-code/pdf-ast)\n", stderr: "" } };
+  }
+  const inputPasswords = /* @__PURE__ */ new Map();
+  let defaultInputPassword = "";
+  for (let p = 0; p < argv.length; p++) {
+    if (++cooperativeWork % 64 === 0)
+      yield;
+    if (argv[p]?.toLowerCase() === "input_pw") {
+      for (let q = p + 1; q < argv.length; q++) {
+        if (++cooperativeWork % 64 === 0)
+          yield;
+        const tok = argv[q];
+        if (PDFTK_OPERATIONS.has(tok.toLowerCase()))
+          break;
+        const eq = tok.indexOf("=");
+        if (eq > 0)
+          inputPasswords.set(tok.slice(0, eq), tok.slice(eq + 1));
+        else
+          defaultInputPassword = tok;
+      }
+    }
+  }
+  const inputs = [];
+  let idx = 0;
+  let autoHandleCharCode = 65;
+  while (idx < argv.length) {
+    if (++cooperativeWork % 64 === 0)
+      yield;
+    const token = argv[idx];
+    if (PDFTK_OPERATIONS.has(token.toLowerCase()) || token.toLowerCase() === "input_pw")
+      break;
+    idx++;
+    let handleName = "";
+    let filePath = token;
+    const eqIdx = token.indexOf("=");
+    if (eqIdx > 0) {
+      handleName = token.slice(0, eqIdx);
+      filePath = token.slice(eqIdx + 1);
+    } else {
+      handleName = String.fromCharCode(autoHandleCharCode++);
+    }
+    inputs.push({ handle: handleName, file: filePath, password: inputPasswords.get(handleName) ?? defaultInputPassword });
+  }
+  if (inputs.length === 0) {
+    return { result: { exitCode: 1, stdout: "", stderr: "Error: No input PDF files specified.\n" } };
+  }
+  while (idx < argv.length && argv[idx]?.toLowerCase() === "input_pw") {
+    if (++cooperativeWork % 64 === 0)
+      yield;
+    idx++;
+    while (idx < argv.length && !PDFTK_OPERATIONS.has(argv[idx].toLowerCase())) {
+      if (++cooperativeWork % 64 === 0)
+        yield;
+      idx++;
+    }
+  }
+  const operation = (argv[idx] ?? "cat").toLowerCase();
+  idx++;
+  const opArgs = [];
+  let outputTarget;
+  if (operation === "output") {
+    outputTarget = argv[idx++];
+  }
+  let shouldFlatten = false;
+  let needAppearances = false;
+  let dropXfa = false;
+  let dropXmp = false;
+  let replacementFont;
+  let keepFirstId = false;
+  let keepFinalId = false;
+  let uncompressStreams = false;
+  let compressStreams = false;
+  let userPassword;
+  let ownerPassword;
+  const allowPermissions = /* @__PURE__ */ new Set();
+  const ALLOW_KEYWORDS = /* @__PURE__ */ new Set([
+    "printing",
+    "degradedprinting",
+    "modifycontents",
+    "assembly",
+    "copycontents",
+    "screenreaders",
+    "modifyannotations",
+    "fillin",
+    "allfeatures"
+  ]);
+  while (idx < argv.length) {
+    if (++cooperativeWork % 64 === 0)
+      yield;
+    const tok = argv[idx++];
+    const lower = tok.toLowerCase();
+    if (lower === "output") {
+      outputTarget = argv[idx++];
+    } else if (lower === "flatten") {
+      shouldFlatten = true;
+    } else if (lower === "need_appearances") {
+      needAppearances = true;
+    } else if (lower === "user_pw") {
+      userPassword = argv[idx++];
+    } else if (lower === "owner_pw") {
+      ownerPassword = argv[idx++];
+    } else if (lower === "allow") {
+      while (idx < argv.length && ALLOW_KEYWORDS.has(argv[idx].toLowerCase())) {
+        if (++cooperativeWork % 64 === 0)
+          yield;
+        allowPermissions.add(argv[idx++].toLowerCase());
+      }
+    } else if (lower === "keep_first_id") {
+      keepFirstId = true;
+    } else if (lower === "keep_final_id") {
+      keepFinalId = true;
+    } else if (lower === "uncompress") {
+      uncompressStreams = true;
+    } else if (lower === "compress") {
+      compressStreams = true;
+    } else if (lower === "dont_ask" || lower === "do_ask" || lower === "encrypt_128bit" || lower === "encrypt_40bit" || lower === "verbose") {
+    } else if (lower === "drop_xfa") {
+      dropXfa = true;
+    } else if (lower === "drop_xmp") {
+      dropXmp = true;
+    } else if (lower === "replacement_font") {
+      replacementFont = argv[idx++];
+    } else {
+      opArgs.push(tok);
+    }
+  }
+  return { options: { inputs, operation, opArgs, outputTarget, shouldFlatten, needAppearances, dropXfa, dropXmp, replacementFont, keepFirstId, keepFinalId, uncompressStreams, compressStreams, userPassword, ownerPassword, allowPermissions } };
+}
+
+// packages/safe-bash-command-pdftk/src/index.ts
+import { resolvePath as resolvePath2 } from "../safe-bash-contracts/path.js";
+import { yieldTurn, drainCooperativeSteps as drainSteps } from "../safe-bash-contracts/yield.js";
+import { InputByteBudget } from "../safe-bash-contracts/io.js";
+import { writeFileOutput as writeFileOutput2 } from "../safe-bash-contracts/filesystem-output-budget.js";
+import {
+  commandRuntimeIdentity,
+  getCommandArguments
+} from "../safe-bash-contracts/command.js";
+import { readBytes, writeBytes as writeBytes2 } from "../safe-bash-contracts/io.js";
+import { createOutputOperation } from "../safe-bash-contracts/output.js";
+import {
+  PdfDocument,
+  cosArray,
+  cosDict,
+  cosHexString,
+  cosName,
+  cosNumber,
+  cosStream,
+  cosString,
+  decodePdfString as decodePdfString2,
+  dictDelete,
+  dictGet as dictGet2,
+  dictSet,
+  flattenDocumentFormFields,
+  getDocumentFormFields,
+  parseFormDataBytes,
+  resolveDestinationPageIndex,
+  setDocumentFormField
+} from "../pdf-ast/index.js";
 function parseRotationSuffix(raw) {
   const lower = raw.toLowerCase();
   const wordRotations = [
@@ -263,40 +740,40 @@ function formatDumpDataAnnots(doc, utf8 = false) {
   lines.push(`NumberOfPages: ${doc.pageCount}`);
   for (let p = 0; p < doc.pageCount; p++) {
     const pageDict = doc.getPage(p).pageDict;
-    const annotsArr = doc.cos.resolveArray(dictGet(pageDict, "Annots"));
+    const annotsArr = doc.cos.resolveArray(dictGet2(pageDict, "Annots"));
     if (!annotsArr) continue;
     for (const item of annotsArr.items) {
       const annotDict = doc.cos.resolveDict(item);
       if (!annotDict) continue;
-      const subNode = doc.cos.resolve(dictGet(annotDict, "Subtype"));
+      const subNode = doc.cos.resolve(dictGet2(annotDict, "Subtype"));
       const subtype = subNode?.kind === "name" ? subNode.decoded : "Annot";
-      const rectArr = doc.cos.resolveArray(dictGet(annotDict, "Rect"));
+      const rectArr = doc.cos.resolveArray(dictGet2(annotDict, "Rect"));
       const rectNums = rectArr ? rectArr.items.map((it) => {
         const r = doc.cos.resolve(it);
         return r?.kind === "number" ? r.value : 0;
       }) : [0, 0, 0, 0];
-      const flagsNode = doc.cos.resolve(dictGet(annotDict, "F"));
+      const flagsNode = doc.cos.resolve(dictGet2(annotDict, "F"));
       const flags = flagsNode?.kind === "number" ? flagsNode.value : 0;
       lines.push("---");
       lines.push(`AnnotSubtype: ${subtype}`);
       lines.push(`AnnotRect: ${rectNums.slice(0, 4).join(" ")}`);
-      const nmNode = doc.cos.resolve(dictGet(annotDict, "NM"));
+      const nmNode = doc.cos.resolve(dictGet2(annotDict, "NM"));
       if (nmNode?.kind === "string") {
-        lines.push(`AnnotName: ${encodePdftkText(decodePdfString(nmNode), utf8)}`);
+        lines.push(`AnnotName: ${encodePdftkText(decodePdfString2(nmNode), utf8)}`);
       }
-      const tNode = doc.cos.resolve(dictGet(annotDict, "T"));
+      const tNode = doc.cos.resolve(dictGet2(annotDict, "T"));
       if (tNode?.kind === "string") {
-        lines.push(`AnnotTitle: ${encodePdftkText(decodePdfString(tNode), utf8)}`);
+        lines.push(`AnnotTitle: ${encodePdftkText(decodePdfString2(tNode), utf8)}`);
       }
-      const subjNode = doc.cos.resolve(dictGet(annotDict, "Subj"));
+      const subjNode = doc.cos.resolve(dictGet2(annotDict, "Subj"));
       if (subjNode?.kind === "string") {
-        lines.push(`AnnotSubj: ${encodePdftkText(decodePdfString(subjNode), utf8)}`);
+        lines.push(`AnnotSubj: ${encodePdftkText(decodePdfString2(subjNode), utf8)}`);
       }
-      const cNode = doc.cos.resolve(dictGet(annotDict, "Contents"));
+      const cNode = doc.cos.resolve(dictGet2(annotDict, "Contents"));
       if (cNode?.kind === "string") {
-        lines.push(`AnnotContents: ${encodePdftkText(decodePdfString(cNode), utf8)}`);
+        lines.push(`AnnotContents: ${encodePdftkText(decodePdfString2(cNode), utf8)}`);
       }
-      const colArr = doc.cos.resolveArray(dictGet(annotDict, "C"));
+      const colArr = doc.cos.resolveArray(dictGet2(annotDict, "C"));
       if (colArr && colArr.items.length >= 3) {
         const colNums = colArr.items.slice(0, 3).map((it) => {
           const r = doc.cos.resolve(it);
@@ -304,20 +781,20 @@ function formatDumpDataAnnots(doc, utf8 = false) {
         });
         lines.push(`AnnotColor: ${colNums.join(" ")}`);
       }
-      const openNode = doc.cos.resolve(dictGet(annotDict, "Open"));
+      const openNode = doc.cos.resolve(dictGet2(annotDict, "Open"));
       if (openNode?.kind === "boolean") {
         lines.push(`AnnotOpen: ${openNode.value}`);
       }
-      const mNode = doc.cos.resolve(dictGet(annotDict, "M"));
+      const mNode = doc.cos.resolve(dictGet2(annotDict, "M"));
       if (mNode?.kind === "string") {
-        lines.push(`AnnotModificationDate: ${encodePdftkText(decodePdfString(mNode), utf8)}`);
+        lines.push(`AnnotModificationDate: ${encodePdftkText(decodePdfString2(mNode), utf8)}`);
       }
       lines.push(`AnnotFlags: ${flags}`);
       lines.push(`AnnotPageNumber: ${p + 1}`);
       const formatDestTarget = (dRaw) => {
         if (!dRaw) return void 0;
         const resolved = doc.cos.resolve(dRaw);
-        if (resolved?.kind === "string") return decodePdfString(resolved);
+        if (resolved?.kind === "string") return decodePdfString2(resolved);
         if (resolved?.kind === "name") return resolved.decoded;
         if (resolved?.kind === "array" && resolved.items.length > 0) {
           const first = resolved.items[0];
@@ -350,16 +827,16 @@ function formatDumpDataAnnots(doc, utf8 = false) {
         }
         const actionDict = doc.cos.resolveDict(aNode);
         if (!actionDict) return;
-        const sNode = doc.cos.resolve(dictGet(actionDict, "S"));
+        const sNode = doc.cos.resolve(dictGet2(actionDict, "S"));
         const sType = sNode?.kind === "name" ? sNode.decoded : "";
         if (sType) {
           lines.push(`AnnotActionType: ${sType}`);
         }
-        const uriNode = doc.cos.resolve(dictGet(actionDict, "URI"));
+        const uriNode = doc.cos.resolve(dictGet2(actionDict, "URI"));
         if (uriNode?.kind === "string") {
-          lines.push(`AnnotActionURI: ${encodePdftkText(decodePdfString(uriNode), utf8)}`);
+          lines.push(`AnnotActionURI: ${encodePdftkText(decodePdfString2(uriNode), utf8)}`);
         }
-        const dNode = dictGet(actionDict, "D");
+        const dNode = dictGet2(actionDict, "D");
         const destTarget = formatDestTarget(dNode);
         if (destTarget) {
           lines.push(`AnnotActionDest: ${encodePdftkText(destTarget, utf8)}`);
@@ -368,23 +845,23 @@ function formatDumpDataAnnots(doc, utf8 = false) {
         if (resolvedIdx !== void 0) {
           lines.push(`AnnotActionPageNumber: ${resolvedIdx + 1}`);
         }
-        const fRaw = doc.cos.resolve(dictGet(actionDict, "F"));
+        const fRaw = doc.cos.resolve(dictGet2(actionDict, "F"));
         if (fRaw?.kind === "string") {
-          lines.push(`AnnotActionFile: ${encodePdftkText(decodePdfString(fRaw), utf8)}`);
+          lines.push(`AnnotActionFile: ${encodePdftkText(decodePdfString2(fRaw), utf8)}`);
         } else if (fRaw?.kind === "dict") {
-          const ufNode = doc.cos.resolve(dictGet(fRaw, "UF") ?? dictGet(fRaw, "F"));
+          const ufNode = doc.cos.resolve(dictGet2(fRaw, "UF") ?? dictGet2(fRaw, "F"));
           if (ufNode?.kind === "string") {
-            lines.push(`AnnotActionFile: ${encodePdftkText(decodePdfString(ufNode), utf8)}`);
+            lines.push(`AnnotActionFile: ${encodePdftkText(decodePdfString2(ufNode), utf8)}`);
           }
         }
-        emitActionChain(dictGet(actionDict, "Next"), visited);
+        emitActionChain(dictGet2(actionDict, "Next"), visited);
       };
-      const rawA = dictGet(annotDict, "A");
+      const rawA = dictGet2(annotDict, "A");
       if (rawA) {
         emitActionChain(rawA);
-      } else if (dictGet(annotDict, "Dest")) {
+      } else if (dictGet2(annotDict, "Dest")) {
         lines.push("AnnotActionType: GoTo");
-        const dNode = dictGet(annotDict, "Dest");
+        const dNode = dictGet2(annotDict, "Dest");
         const destTarget = formatDestTarget(dNode);
         if (destTarget) {
           lines.push(`AnnotActionDest: ${encodePdftkText(destTarget, utf8)}`);
@@ -430,18 +907,18 @@ function collectOutlineBookmarks(doc, firstNode, level, out, visited = /* @__PUR
     }
     const dict = doc.cos.resolveDict(curr);
     if (!dict) break;
-    const titleNode = doc.cos.resolve(dictGet(dict, "Title"));
-    const title = titleNode?.kind === "string" ? decodePdfString(titleNode) : titleNode?.kind === "name" ? titleNode.decoded : "";
-    const resolvedIdx = resolveDestinationPageIndex(doc, dictGet(dict, "Dest") ?? dictGet(dict, "A"));
+    const titleNode = doc.cos.resolve(dictGet2(dict, "Title"));
+    const title = titleNode?.kind === "string" ? decodePdfString2(titleNode) : titleNode?.kind === "name" ? titleNode.decoded : "";
+    const resolvedIdx = resolveDestinationPageIndex(doc, dictGet2(dict, "Dest") ?? dictGet2(dict, "A"));
     const pageNumber = resolvedIdx !== void 0 ? resolvedIdx + 1 : 1;
     if (title) {
       out.push({ title, level, pageNumber });
     }
-    const childFirst = dictGet(dict, "First");
+    const childFirst = dictGet2(dict, "First");
     if (childFirst) {
       collectOutlineBookmarks(doc, childFirst, level + 1, out, visited);
     }
-    curr = dictGet(dict, "Next");
+    curr = dictGet2(dict, "Next");
   }
 }
 function collectNameTreePairs(doc, nodeOrRef, out, visited = /* @__PURE__ */ new Set()) {
@@ -452,16 +929,16 @@ function collectNameTreePairs(doc, nodeOrRef, out, visited = /* @__PURE__ */ new
   }
   const dict = doc.cos.resolveDict(nodeOrRef);
   if (!dict) return;
-  const namesArr = doc.cos.resolveArray(dictGet(dict, "Names"));
+  const namesArr = doc.cos.resolveArray(dictGet2(dict, "Names"));
   if (namesArr) {
     for (let i = 0; i + 1 < namesArr.items.length; i += 2) {
       const k = doc.cos.resolve(namesArr.items[i]);
       const v = namesArr.items[i + 1];
-      const name = k?.kind === "string" ? decodePdfString(k) : "attachment.bin";
+      const name = k?.kind === "string" ? decodePdfString2(k) : "attachment.bin";
       out.push({ name, value: v });
     }
   }
-  const kidsArr = doc.cos.resolveArray(dictGet(dict, "Kids"));
+  const kidsArr = doc.cos.resolveArray(dictGet2(dict, "Kids"));
   if (kidsArr) {
     for (const kid of kidsArr.items) {
       collectNameTreePairs(doc, kid, out, visited);
@@ -476,7 +953,7 @@ function collectNumberTreePairs(doc, nodeOrRef, out, visited = /* @__PURE__ */ n
   }
   const dict = doc.cos.resolveDict(nodeOrRef);
   if (!dict) return;
-  const numsArr = doc.cos.resolveArray(dictGet(dict, "Nums"));
+  const numsArr = doc.cos.resolveArray(dictGet2(dict, "Nums"));
   if (numsArr) {
     for (let i = 0; i + 1 < numsArr.items.length; i += 2) {
       const k = doc.cos.resolve(numsArr.items[i]);
@@ -486,7 +963,7 @@ function collectNumberTreePairs(doc, nodeOrRef, out, visited = /* @__PURE__ */ n
       }
     }
   }
-  const kidsArr = doc.cos.resolveArray(dictGet(dict, "Kids"));
+  const kidsArr = doc.cos.resolveArray(dictGet2(dict, "Kids"));
   if (kidsArr) {
     for (const kid of kidsArr.items) {
       collectNumberTreePairs(doc, kid, out, visited);
@@ -540,7 +1017,7 @@ function formatDumpData(doc, utf8 = true) {
         if (emittedKeys.has(k)) continue;
         const r = doc.cos.resolve(entry.value);
         if (r?.kind === "string") {
-          const val = decodePdfString(r);
+          const val = decodePdfString2(r);
           if (val) {
             emittedKeys.add(k);
             lines.push(
@@ -561,10 +1038,10 @@ function formatDumpData(doc, utf8 = true) {
   lines.push(`PdfID1: ${id1Hex}`);
   lines.push(`NumberOfPages: ${doc.pageCount}`);
   const catalog = doc.cos.resolveDict(doc.cos.rootRef);
-  const outlinesDict = catalog ? doc.cos.resolveDict(dictGet(catalog, "Outlines")) : void 0;
+  const outlinesDict = catalog ? doc.cos.resolveDict(dictGet2(catalog, "Outlines")) : void 0;
   if (outlinesDict) {
     const bookmarks = [];
-    collectOutlineBookmarks(doc, dictGet(outlinesDict, "First"), 1, bookmarks);
+    collectOutlineBookmarks(doc, dictGet2(outlinesDict, "First"), 1, bookmarks);
     for (const bm of bookmarks) {
       lines.push(
         "BookmarkBegin",
@@ -578,7 +1055,7 @@ function formatDumpData(doc, utf8 = true) {
     const page = doc.getPage(i);
     const { width, height } = page.getSize();
     const rot = page.getRotation();
-    const mbArr = doc.cos.resolveArray(dictGet(page.pageDict, "MediaBox"));
+    const mbArr = doc.cos.resolveArray(dictGet2(page.pageDict, "MediaBox"));
     let mbRectStr = `0 0 ${width} ${height}`;
     if (mbArr && mbArr.items.length >= 4) {
       const mbNums = mbArr.items.slice(0, 4).map((item) => {
@@ -594,7 +1071,7 @@ function formatDumpData(doc, utf8 = true) {
       `PageMediaRect: ${mbRectStr}`,
       `PageMediaDimensions: ${width} ${height}`
     );
-    const cbArr = doc.cos.resolveArray(dictGet(page.pageDict, "CropBox"));
+    const cbArr = doc.cos.resolveArray(dictGet2(page.pageDict, "CropBox"));
     if (cbArr && cbArr.items.length >= 4) {
       const nums = cbArr.items.slice(0, 4).map((item) => {
         const r = doc.cos.resolve(item);
@@ -606,17 +1083,17 @@ function formatDumpData(doc, utf8 = true) {
   }
   const pageLabelsPairs = [];
   if (catalog) {
-    collectNumberTreePairs(doc, dictGet(catalog, "PageLabels"), pageLabelsPairs);
+    collectNumberTreePairs(doc, dictGet2(catalog, "PageLabels"), pageLabelsPairs);
   }
   for (const pair of pageLabelsPairs) {
     const lblDict = doc.cos.resolveDict(pair.value);
     if (lblDict) {
       const newIndex = Math.max(1, pair.num + 1);
-      const stNode = doc.cos.resolve(dictGet(lblDict, "St"));
+      const stNode = doc.cos.resolve(dictGet2(lblDict, "St"));
       const startNum = stNode?.kind === "number" ? stNode.value : 1;
-      const pNode = doc.cos.resolve(dictGet(lblDict, "P"));
-      const prefix = pNode?.kind === "string" ? decodePdfString(pNode) : void 0;
-      const sNode = doc.cos.resolve(dictGet(lblDict, "S"));
+      const pNode = doc.cos.resolve(dictGet2(lblDict, "P"));
+      const prefix = pNode?.kind === "string" ? decodePdfString2(pNode) : void 0;
+      const sNode = doc.cos.resolve(dictGet2(lblDict, "S"));
       const styleCode = sNode?.kind === "name" ? sNode.decoded : "";
       const numStyle = PDF_TO_PAGE_LABEL_STYLE[styleCode] ?? "NoNumber";
       lines.push(
@@ -647,23 +1124,23 @@ function formatGenerateFdf(doc) {
       }
       return `(${escapeFdfString(String(f.value ?? ""))})`;
     }
-    const vNode = doc.cos.resolve(dictGet(dict, "V"));
+    const vNode = doc.cos.resolve(dictGet2(dict, "V"));
     if (vNode?.kind === "name") return `/${vNode.decoded}`;
-    if (vNode?.kind === "string") return `(${escapeFdfString(decodePdfString(vNode))})`;
+    if (vNode?.kind === "string") return `(${escapeFdfString(decodePdfString2(vNode))})`;
     return "()";
   };
   const serializeCosFieldNode = (nodeOrRef, prefix) => {
     const dict = doc.cos.resolveDict(nodeOrRef);
     if (!dict) return void 0;
-    const tNode = doc.cos.resolve(dictGet(dict, "T"));
-    const partialName = tNode?.kind === "string" ? decodePdfString(tNode) : "";
+    const tNode = doc.cos.resolve(dictGet2(dict, "T"));
+    const partialName = tNode?.kind === "string" ? decodePdfString2(tNode) : "";
     const fullName = prefix && partialName ? `${prefix}.${partialName}` : partialName || prefix;
-    const kidsArr = doc.cos.resolveArray(dictGet(dict, "Kids"));
+    const kidsArr = doc.cos.resolveArray(dictGet2(dict, "Kids"));
     const namedKids = [];
     if (kidsArr) {
       for (const k of kidsArr.items) {
         const kDict = doc.cos.resolveDict(k);
-        if (kDict && dictGet(kDict, "T")) {
+        if (kDict && dictGet2(kDict, "T")) {
           const serializedKid = serializeCosFieldNode(k, fullName);
           if (serializedKid) namedKids.push(serializedKid);
         }
@@ -677,8 +1154,8 @@ function formatGenerateFdf(doc) {
   };
   const entries = [];
   const catalog = doc.cos.resolveDict(doc.cos.rootRef);
-  const acroForm = catalog ? doc.cos.resolveDict(dictGet(catalog, "AcroForm")) : void 0;
-  const fieldsArr = acroForm ? doc.cos.resolveArray(dictGet(acroForm, "Fields")) : void 0;
+  const acroForm = catalog ? doc.cos.resolveDict(dictGet2(catalog, "AcroForm")) : void 0;
+  const fieldsArr = acroForm ? doc.cos.resolveArray(dictGet2(acroForm, "Fields")) : void 0;
   if (fieldsArr && fieldsArr.items.length > 0) {
     for (const item of fieldsArr.items) {
       const s = serializeCosFieldNode(item, "");
@@ -939,17 +1416,17 @@ function applyUpdateInfoText(doc, text) {
 function attachFilesToDocument(doc, filePaths, files, toPageSpec) {
   const catalog = doc.cos.resolveDict(doc.cos.rootRef);
   if (!catalog) return;
-  let namesDict = doc.cos.resolveDict(dictGet(catalog, "Names"));
+  let namesDict = doc.cos.resolveDict(dictGet2(catalog, "Names"));
   if (!namesDict) {
     namesDict = cosDict({});
     dictSet(catalog, "Names", doc.cos.allocateObject(namesDict));
   }
-  let efTree = doc.cos.resolveDict(dictGet(namesDict, "EmbeddedFiles"));
+  let efTree = doc.cos.resolveDict(dictGet2(namesDict, "EmbeddedFiles"));
   if (!efTree) {
     efTree = cosDict({ Names: cosArray([]) });
     dictSet(namesDict, "EmbeddedFiles", doc.cos.allocateObject(efTree));
   }
-  let namesArr = doc.cos.resolveArray(dictGet(efTree, "Names"));
+  let namesArr = doc.cos.resolveArray(dictGet2(efTree, "Names"));
   if (!namesArr) {
     namesArr = cosArray([]);
     dictSet(efTree, "Names", namesArr);
@@ -976,7 +1453,7 @@ function attachFilesToDocument(doc, filePaths, files, toPageSpec) {
     namesArr.items.push(cosString(baseName), filespecRef);
     if (targetPageIdx !== void 0) {
       const pageDict = doc.getPage(targetPageIdx).pageDict;
-      let annotsArr = doc.cos.resolveArray(dictGet(pageDict, "Annots"));
+      let annotsArr = doc.cos.resolveArray(dictGet2(pageDict, "Annots"));
       if (!annotsArr) {
         annotsArr = cosArray([]);
         dictSet(pageDict, "Annots", annotsArr);
@@ -1005,11 +1482,11 @@ function attachmentBasename(name) {
 function unpackFilesFromDocument(doc, outDir, files) {
   const cleanDir = outDir.endsWith("/") ? outDir.slice(0, -1) : outDir;
   const writeSpecDict = (specDict, fallbackName = "attachment.bin") => {
-    const ufNode = doc.cos.resolve(dictGet(specDict, "UF") ?? dictGet(specDict, "F"));
-    const fileName = attachmentBasename(ufNode?.kind === "string" ? decodePdfString(ufNode) : fallbackName);
-    const efDict = doc.cos.resolveDict(dictGet(specDict, "EF"));
+    const ufNode = doc.cos.resolve(dictGet2(specDict, "UF") ?? dictGet2(specDict, "F"));
+    const fileName = attachmentBasename(ufNode?.kind === "string" ? decodePdfString2(ufNode) : fallbackName);
+    const efDict = doc.cos.resolveDict(dictGet2(specDict, "EF"));
     const fStream = efDict ? doc.cos.resolve(
-      dictGet(efDict, "UF") ?? dictGet(efDict, "F") ?? dictGet(efDict, "DOS") ?? dictGet(efDict, "Mac") ?? dictGet(efDict, "Unix")
+      dictGet2(efDict, "UF") ?? dictGet2(efDict, "F") ?? dictGet2(efDict, "DOS") ?? dictGet2(efDict, "Mac") ?? dictGet2(efDict, "Unix")
     ) : void 0;
     if (fStream?.kind === "stream") {
       const decoded = doc.cos.decodeStream(fStream);
@@ -1019,10 +1496,10 @@ function unpackFilesFromDocument(doc, outDir, files) {
   };
   const catalog = doc.cos.resolveDict(doc.cos.rootRef);
   if (catalog) {
-    const namesDict = doc.cos.resolveDict(dictGet(catalog, "Names"));
+    const namesDict = doc.cos.resolveDict(dictGet2(catalog, "Names"));
     const efPairs = [];
     if (namesDict) {
-      collectNameTreePairs(doc, dictGet(namesDict, "EmbeddedFiles"), efPairs);
+      collectNameTreePairs(doc, dictGet2(namesDict, "EmbeddedFiles"), efPairs);
     }
     for (const pair of efPairs) {
       const specDict = doc.cos.resolveDict(pair.value);
@@ -1030,7 +1507,7 @@ function unpackFilesFromDocument(doc, outDir, files) {
         writeSpecDict(specDict, pair.name);
       }
     }
-    const rootAfArr = doc.cos.resolveArray(dictGet(catalog, "AF"));
+    const rootAfArr = doc.cos.resolveArray(dictGet2(catalog, "AF"));
     if (rootAfArr) {
       for (const item of rootAfArr.items) {
         const specDict = doc.cos.resolveDict(item);
@@ -1039,21 +1516,21 @@ function unpackFilesFromDocument(doc, outDir, files) {
     }
   }
   for (let p = 0; p < doc.pageCount; p++) {
-    const pageAfArr = doc.cos.resolveArray(dictGet(doc.getPage(p).pageDict, "AF"));
+    const pageAfArr = doc.cos.resolveArray(dictGet2(doc.getPage(p).pageDict, "AF"));
     if (pageAfArr) {
       for (const item of pageAfArr.items) {
         const specDict = doc.cos.resolveDict(item);
         if (specDict) writeSpecDict(specDict);
       }
     }
-    const annotsArr = doc.cos.resolveArray(dictGet(doc.getPage(p).pageDict, "Annots"));
+    const annotsArr = doc.cos.resolveArray(dictGet2(doc.getPage(p).pageDict, "Annots"));
     if (!annotsArr) continue;
     for (const item of annotsArr.items) {
       const annotDict = doc.cos.resolveDict(item);
       if (!annotDict) continue;
-      const subNode = doc.cos.resolve(dictGet(annotDict, "Subtype"));
+      const subNode = doc.cos.resolve(dictGet2(annotDict, "Subtype"));
       if (subNode?.kind === "name" && subNode.decoded === "FileAttachment") {
-        const specDict = doc.cos.resolveDict(dictGet(annotDict, "FS"));
+        const specDict = doc.cos.resolveDict(dictGet2(annotDict, "FS"));
         if (specDict) writeSpecDict(specDict);
       }
     }
@@ -1187,9 +1664,9 @@ function applyOverlayToDocument(targetDoc, overlayDoc, mode, multi) {
     const srcRes = srcPage.getResourcesDict();
     const renamedResources = /* @__PURE__ */ new Map();
     for (const subKey of ["Font", "XObject", "ExtGState", "ColorSpace", "Pattern", "Shading", "Properties"]) {
-      const srcSub = overlayDoc.cos.resolveDict(dictGet(srcRes, subKey));
+      const srcSub = overlayDoc.cos.resolveDict(dictGet2(srcRes, subKey));
       if (!srcSub) continue;
-      let dstSub = targetDoc.cos.resolveDict(dictGet(dstRes, subKey));
+      let dstSub = targetDoc.cos.resolveDict(dictGet2(dstRes, subKey));
       if (!dstSub) {
         dstSub = cosDict({});
         dictSet(dstRes, subKey, dstSub);
@@ -1198,12 +1675,12 @@ function applyOverlayToDocument(targetDoc, overlayDoc, mode, multi) {
         const origKey = entry.key.decoded;
         const cloned = cloneCosSubgraphInto(overlayDoc, targetDoc, entry.value, memo);
         if (!cloned) continue;
-        if (!dictGet(dstSub, origKey)) {
+        if (!dictGet2(dstSub, origKey)) {
           dictSet(dstSub, origKey, cloned);
         } else {
           let newKey = `Ov_${i}_${origKey}`;
           let suffix = 1;
-          while (dictGet(dstSub, newKey)) {
+          while (dictGet2(dstSub, newKey)) {
             newKey = `Ov_${i}_${suffix++}_${origKey}`;
           }
           dictSet(dstSub, newKey, cloned);
@@ -1211,7 +1688,7 @@ function applyOverlayToDocument(targetDoc, overlayDoc, mode, multi) {
         }
       }
     }
-    const srcContents = dictGet(srcPage.pageDict, "Contents");
+    const srcContents = dictGet2(srcPage.pageDict, "Contents");
     if (!srcContents) continue;
     const rawSrcNodes = [];
     const resolvedSrcContents = overlayDoc.cos.resolve(srcContents);
@@ -1237,7 +1714,7 @@ function applyOverlayToDocument(targetDoc, overlayDoc, mode, multi) {
       }
     }
     if (srcList.length === 0) continue;
-    const dstContents = dictGet(dstPage.pageDict, "Contents");
+    const dstContents = dictGet2(dstPage.pageDict, "Contents");
     const toStreamList = (c) => {
       if (!c) return [];
       const r = targetDoc.cos.resolve(c);
@@ -1296,159 +1773,29 @@ function normalizeQuarterTurn(degrees) {
 }
 function* runPdftkCliSteps(argv, files, signal) {
   let cooperativeWork = 63;
-  if (argv.length === 0 || argv.includes("--help") || argv.includes("-h")) {
-    return {
-      exitCode: 0,
-      stdout: "Usage: pdftk <input PDF files | [handle]=filename ...> [<operation> <operation arguments>] [output <output filename>] [flatten]\n",
-      stderr: ""
-    };
-  }
-  if (argv.includes("--version") || argv.includes("-v")) {
-    return { exitCode: 0, stdout: "pdftk port to Java 3.3.3 (safe-bash @poe-code/pdf-ast)\n", stderr: "" };
-  }
-  const inputPasswords = /* @__PURE__ */ new Map();
-  let defaultInputPassword = "";
-  for (let p = 0; p < argv.length; p++) {
-    if (++cooperativeWork % 64 === 0)
-      yield;
-    if (argv[p]?.toLowerCase() === "input_pw") {
-      for (let q = p + 1; q < argv.length; q++) {
-        if (++cooperativeWork % 64 === 0)
-          yield;
-        const tok = argv[q];
-        if (PDFTK_OPERATIONS.has(tok.toLowerCase()))
-          break;
-        const eq = tok.indexOf("=");
-        if (eq > 0)
-          inputPasswords.set(tok.slice(0, eq), tok.slice(eq + 1));
-        else
-          defaultInputPassword = tok;
-      }
-    }
-  }
+  const parsed = yield* parsePdftkArgumentsSteps(argv);
+  if (parsed.result) return parsed.result;
+  const { inputs, operation, opArgs, outputTarget, shouldFlatten, needAppearances, dropXfa, dropXmp, replacementFont, keepFirstId, keepFinalId, uncompressStreams, compressStreams, userPassword, ownerPassword, allowPermissions } = parsed.options;
   const handles = /* @__PURE__ */ new Map();
   const orderedDocs = [];
-  let idx = 0;
-  let autoHandleCharCode = 65;
-  while (idx < argv.length) {
-    if (++cooperativeWork % 64 === 0)
-      yield;
-    const token = argv[idx];
-    if (PDFTK_OPERATIONS.has(token.toLowerCase()) || token.toLowerCase() === "input_pw")
-      break;
-    idx++;
-    let handleName = "";
-    let filePath = token;
-    const eqIdx = token.indexOf("=");
-    if (eqIdx > 0) {
-      handleName = token.slice(0, eqIdx);
-      filePath = token.slice(eqIdx + 1);
-    } else {
-      handleName = String.fromCharCode(autoHandleCharCode++);
-    }
-    const pdfBytes = files.get(filePath);
-    if (!pdfBytes) {
-      return { exitCode: 1, stdout: "", stderr: `Error: Unable to find file '${filePath}'
+  for (const input of inputs) {
+    signal?.throwIfAborted();
+    if (++cooperativeWork % 64 === 0) yield;
+    const pdfBytes = files.get(input.file);
+    if (!pdfBytes) return { exitCode: 1, stdout: "", stderr: `Error: Unable to find file '${input.file}'
 ` };
-    }
-    const pw = inputPasswords.get(handleName) ?? defaultInputPassword;
     let doc;
     try {
-      doc = PdfDocument.load(pdfBytes, pw ? { password: pw } : void 0);
-    } catch (err) {
-      return { exitCode: 1, stdout: "", stderr: `Error: Failed to open PDF '${filePath}': ${err.message}
+      doc = PdfDocument.load(pdfBytes, input.password ? { password: input.password } : void 0);
+    } catch (error) {
+      return { exitCode: 1, stdout: "", stderr: `Error: Failed to open PDF '${input.file}': ${error.message}
 ` };
     }
-    handles.set(handleName, doc);
-    if (!handles.has(""))
-      handles.set("", doc);
-    orderedDocs.push({ handle: handleName, doc });
-  }
-  if (orderedDocs.length === 0) {
-    return { exitCode: 1, stdout: "", stderr: "Error: No input PDF files specified.\n" };
-  }
-  while (idx < argv.length && argv[idx]?.toLowerCase() === "input_pw") {
-    if (++cooperativeWork % 64 === 0)
-      yield;
-    idx++;
-    while (idx < argv.length && !PDFTK_OPERATIONS.has(argv[idx].toLowerCase())) {
-      if (++cooperativeWork % 64 === 0)
-        yield;
-      idx++;
-    }
-  }
-  const primaryDoc = orderedDocs[0].doc;
-  const primaryHandle = orderedDocs[0].handle;
-  const operation = (argv[idx] ?? "cat").toLowerCase();
-  idx++;
-  const opArgs = [];
-  let outputTarget;
-  if (operation === "output") {
-    outputTarget = argv[idx++];
-  }
-  let shouldFlatten = false;
-  let needAppearances = false;
-  let dropXfa = false;
-  let dropXmp = false;
-  let replacementFont;
-  let keepFirstId = false;
-  let keepFinalId = false;
-  let uncompressStreams = false;
-  let compressStreams = false;
-  let userPassword;
-  let ownerPassword;
-  const allowPermissions = /* @__PURE__ */ new Set();
-  const ALLOW_KEYWORDS = /* @__PURE__ */ new Set([
-    "printing",
-    "degradedprinting",
-    "modifycontents",
-    "assembly",
-    "copycontents",
-    "screenreaders",
-    "modifyannotations",
-    "fillin",
-    "allfeatures"
-  ]);
-  while (idx < argv.length) {
-    if (++cooperativeWork % 64 === 0)
-      yield;
-    const tok = argv[idx++];
-    const lower = tok.toLowerCase();
-    if (lower === "output") {
-      outputTarget = argv[idx++];
-    } else if (lower === "flatten") {
-      shouldFlatten = true;
-    } else if (lower === "need_appearances") {
-      needAppearances = true;
-    } else if (lower === "user_pw") {
-      userPassword = argv[idx++];
-    } else if (lower === "owner_pw") {
-      ownerPassword = argv[idx++];
-    } else if (lower === "allow") {
-      while (idx < argv.length && ALLOW_KEYWORDS.has(argv[idx].toLowerCase())) {
-        if (++cooperativeWork % 64 === 0)
-          yield;
-        allowPermissions.add(argv[idx++].toLowerCase());
-      }
-    } else if (lower === "keep_first_id") {
-      keepFirstId = true;
-    } else if (lower === "keep_final_id") {
-      keepFinalId = true;
-    } else if (lower === "uncompress") {
-      uncompressStreams = true;
-    } else if (lower === "compress") {
-      compressStreams = true;
-    } else if (lower === "dont_ask" || lower === "do_ask" || lower === "encrypt_128bit" || lower === "encrypt_40bit" || lower === "verbose") {
-    } else if (lower === "drop_xfa") {
-      dropXfa = true;
-    } else if (lower === "drop_xmp") {
-      dropXmp = true;
-    } else if (lower === "replacement_font") {
-      replacementFont = argv[idx++];
-    } else {
-      opArgs.push(tok);
-    }
+    handles.set(input.handle, doc);
+    if (!handles.has("")) handles.set("", doc);
+    orderedDocs.push({ handle: input.handle, doc });
   }
+  const primaryDoc = orderedDocs[0].doc, primaryHandle = orderedDocs[0].handle;
   if (operation === "dump_data_fields" || operation === "dump_data_fields_utf8") {
     const text = formatDumpDataFields(primaryDoc, operation === "dump_data_fields_utf8");
     if (outputTarget && outputTarget !== "-") {
@@ -1600,9 +1947,9 @@ function* runPdftkCliSteps(argv, files, signal) {
       if (!cached) {
         cached = [];
         const cat = d.cos.resolveDict(d.cos.rootRef);
-        const outDict = cat ? d.cos.resolveDict(dictGet(cat, "Outlines")) : void 0;
+        const outDict = cat ? d.cos.resolveDict(dictGet2(cat, "Outlines")) : void 0;
         if (outDict) {
-          collectOutlineBookmarks(d, dictGet(outDict, "First"), 1, cached);
+          collectOutlineBookmarks(d, dictGet2(outDict, "First"), 1, cached);
         }
         bookmarksByDoc.set(d, cached);
       }
@@ -1692,7 +2039,7 @@ function* runPdftkCliSteps(argv, files, signal) {
   }
   if (dropXfa) {
     const root = resultDoc.cos.resolveDict(resultDoc.cos.rootRef);
-    const acroForm = root ? resultDoc.cos.resolveDict(dictGet(root, "AcroForm")) : void 0;
+    const acroForm = root ? resultDoc.cos.resolveDict(dictGet2(root, "AcroForm")) : void 0;
     if (acroForm)
       dictDelete(acroForm, "XFA");
   }
@@ -1707,8 +2054,8 @@ function* runPdftkCliSteps(argv, files, signal) {
       if (++cooperativeWork % 64 === 0)
         yield;
       if (obj.value.kind === "dict") {
-        const stNode = dictGet(obj.value, "Subtype");
-        const bfNode = dictGet(obj.value, "BaseFont");
+        const stNode = dictGet2(obj.value, "Subtype");
+        const bfNode = dictGet2(obj.value, "BaseFont");
         const subtype = stNode?.kind === "name" ? stNode.decoded : void 0;
         const baseFont = bfNode?.kind === "name" ? bfNode.decoded : void 0;
         if (subtype === "Type1" && baseFont === "Helvetica") {
@@ -1719,14 +2066,14 @@ function* runPdftkCliSteps(argv, files, signal) {
   }
   if (operation === "fill_form" && !shouldFlatten) {
     const root = resultDoc.cos.resolveDict(resultDoc.cos.rootRef);
-    const acroForm = root ? resultDoc.cos.resolveDict(dictGet(root, "AcroForm")) : void 0;
+    const acroForm = root ? resultDoc.cos.resolveDict(dictGet2(root, "AcroForm")) : void 0;
     if (acroForm) {
       dictSet(acroForm, "NeedAppearances", { kind: "boolean", value: needAppearances });
     }
   } else if (needAppearances && !shouldFlatten) {
     const root = resultDoc.cos.resolveDict(resultDoc.cos.rootRef);
     if (root) {
-      const acroForm = resultDoc.cos.resolveDict(dictGet(root, "AcroForm"));
+      const acroForm = resultDoc.cos.resolveDict(dictGet2(root, "AcroForm"));
       if (acroForm) {
         dictSet(acroForm, "NeedAppearances", { kind: "boolean", value: true });
       }
@@ -1807,6 +2154,10 @@ async function executePdftk(context) {
   try {
     const carrier = getCommandArguments(context);
     const argv = [...carrier.args];
+    const parsed = await drainSteps(parsePdftkArgumentsSteps(argv), invocation.signal);
+    if (parsed.options && ["dump_data_annots", "dump_data_annots_utf8"].includes(parsed.options.operation)) {
+      return await executeRetainedPdftk({ ...context, signal: invocation.signal, stdout: invocation.child(context.stdout).output }, parsed.options);
+    }
     const vfsFiles = /* @__PURE__ */ new Map();
     let accountedBytes = 0;
     const chargeBytes = (delta) => {
@@ -1859,7 +2210,7 @@ async function executePdftk(context) {
       if (++cooperativeWork % 64 === 0) await yieldTurn(context.signal);
       if (filePath === "-") continue;
       try {
-        const bytes = await context.fs.readFile(resolvePath(context.cwd, filePath), { signal: invocation.signal });
+        const bytes = await context.fs.readFile(resolvePath2(context.cwd, filePath), { signal: invocation.signal });
         chargeBytes(bytes.byteLength);
         vfsFiles.set(filePath, bytes);
       } catch {
@@ -1869,26 +2220,26 @@ async function executePdftk(context) {
     const existingSnap = new Map(vfsFiles);
     const res = await runPdftkCli(argv, vfsFiles, invocation.signal);
     if (res.stderr) {
-      await writeBytes(context.stderr, new TextEncoder().encode(res.stderr), invocation.signal);
+      await writeBytes2(context.stderr, new TextEncoder().encode(res.stderr), invocation.signal);
     }
     if (res.stdoutBytes) {
       const stdout = invocation.child(context.stdout);
-      await writeBytes(stdout.output, res.stdoutBytes, invocation.signal);
+      await writeBytes2(stdout.output, res.stdoutBytes, invocation.signal);
     } else if (res.stdout) {
       const outBytes = new TextEncoder().encode(res.stdout);
       const stdout = invocation.child(context.stdout);
-      await writeBytes(stdout.output, outBytes, invocation.signal);
+      await writeBytes2(stdout.output, outBytes, invocation.signal);
     }
     for (const [key, val] of vfsFiles.entries()) {
       if (++cooperativeWork % 64 === 0) await yieldTurn(context.signal);
       if (key !== "-" && existingSnap.get(key) !== val) {
-        const abs = resolvePath(context.cwd, key);
+        const abs = resolvePath2(context.cwd, key);
         try {
-          await writeFileOutput(context, val, (data) => context.fs.writeFile(abs, data, { signal: invocation.signal }));
+          await writeFileOutput2(context, val, (data) => context.fs.writeFile(abs, data, { signal: invocation.signal }));
         } catch (error) {
           invocation.signal.throwIfAborted();
           if (!(error instanceof Error) || !("code" in error)) throw error;
-          await writeBytes(context.stderr, new TextEncoder().encode(`Error: Failed to open output file '${key}': ${error.code}.
+          await writeBytes2(context.stderr, new TextEncoder().encode(`Error: Failed to open output file '${key}': ${error.code}.
 `), invocation.signal);
           return { exitCode: 1 };
         }