@ubercode/dcmtk 1.0.0-rc.1 → 1.0.0-rc.3

package/dist/dicom.js

@@ -3,10 +3,12 @@ import { stderr, tryCatch } from 'stderr-lib';
 import { spawn, execSync } from 'child_process';
 import kill from 'tree-kill';
 import { existsSync } from 'fs';
-import { copyFile, unlink, stat, rm, mkdtemp } from 'fs/promises';
+import { copyFile, unlink, stat, rm, mkdtemp, readFile, open } from 'fs/promises';
 import { tmpdir } from 'os';
 import { z } from 'zod';
 import { XMLParser } from 'fast-xml-parser';
+import { inflateRawSync } from 'zlib';
+import dicomParser2 from 'dicom-parser';
 
 var __defProp = Object.defineProperty;
 var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
@@ -29667,6 +29669,8 @@ var REQUIRED_BINARIES = ["dcm2json", "dcm2xml", "dcmodify", "dcmdump", "dcmrecv"
 var MAX_TRAVERSAL_DEPTH = 50;
 var MAX_CHANGESET_OPERATIONS = 1e4;
 var MAX_OUTPUT_BYTES = 100 * 1024 * 1024;
+var BOUNDED_READ_THRESHOLD_BYTES = 8 * 1024 * 1024;
+var BOUNDED_READ_CHUNK_BYTES = 1024 * 1024;
 
 // src/dicom/tagPath.ts
 var SEGMENT_PATTERN = /^\(([0-9A-Fa-f]{4}),([0-9A-Fa-f]{4})\)(?:\[(\d+|\*)\])?/;
@@ -30386,9 +30390,9 @@ var ToolExecutionError = class extends Error {
     this.exitCode = details.exitCode;
   }
 };
-function createToolError(toolName, args, exitCode, stderr4, stdout = "") {
+function createToolError(toolName, args, exitCode, stderr5, stdout = "") {
   const argsStr = truncate(args.join(" "), MAX_ARGS_LENGTH);
-  const stderrStr = truncate(stderr4.trim(), MAX_STDERR_LENGTH);
+  const stderrStr = truncate(stderr5.trim(), MAX_STDERR_LENGTH);
   const parts = [`${toolName} failed (exit code ${String(exitCode)})`];
   if (argsStr.length > 0) {
     parts.push(`args: ${argsStr}`);
@@ -30396,7 +30400,7 @@ function createToolError(toolName, args, exitCode, stderr4, stdout = "") {
   if (stderrStr.length > 0) {
     parts.push(`stderr: ${stderrStr}`);
   }
-  return new ToolExecutionError(parts.join(" | "), { stdout, stderr: stderr4, exitCode });
+  return new ToolExecutionError(parts.join(" | "), { stdout, stderr: stderr5, exitCode });
 }
 function createValidationError(toolName, zodError) {
   const parts = [];
@@ -30428,7 +30432,7 @@ async function execCommand(binary, args, options) {
 }
 function wireSpawnListeners(binary, child, timeoutMs, resolve) {
   let stdout = "";
-  let stderr4 = "";
+  let stderr5 = "";
   let settled = false;
   const name = binary.split("/").pop() ?? binary;
   const settle = (result) => {
@@ -30443,14 +30447,14 @@ function wireSpawnListeners(binary, child, timeoutMs, resolve) {
   }, timeoutMs);
   child.stdout?.on("data", (chunk) => {
     stdout += String(chunk);
-    if (stdout.length + stderr4.length > MAX_OUTPUT_BYTES) {
+    if (stdout.length + stderr5.length > MAX_OUTPUT_BYTES) {
       if (child.pid !== void 0 && child.pid !== null) killTree(child.pid);
       settle(err(new Error(`${name} output exceeded ${MAX_OUTPUT_BYTES} bytes`)));
     }
   });
   child.stderr?.on("data", (chunk) => {
-    stderr4 += String(chunk);
-    if (stdout.length + stderr4.length > MAX_OUTPUT_BYTES) {
+    stderr5 += String(chunk);
+    if (stdout.length + stderr5.length > MAX_OUTPUT_BYTES) {
       if (child.pid !== void 0 && child.pid !== null) killTree(child.pid);
       settle(err(new Error(`${name} output exceeded ${MAX_OUTPUT_BYTES} bytes`)));
     }
@@ -30460,7 +30464,7 @@ function wireSpawnListeners(binary, child, timeoutMs, resolve) {
     settle(err(new Error(`${name} error: ${error.message}`)));
   });
   child.on("close", (code) => {
-    settle(ok({ stdout, stderr: stderr4, exitCode: code ?? 1 }));
+    settle(ok({ stdout, stderr: stderr5, exitCode: code ?? 1 }));
   });
 }
 async function spawnCommand(binary, args, options) {
@@ -30682,8 +30686,8 @@ function unwrapValue(v) {
   const obj = v;
   if ("#text" in obj) return obj["#text"];
   const keys = Object.keys(obj);
-  if (keys.length === 1 && keys[0] !== void 0 && keys[0].startsWith("@_")) {
-    return obj[keys[0]];
+  if (keys.every((k) => k.startsWith("@_"))) {
+    return "";
   }
   return v;
 }
@@ -30889,16 +30893,948 @@ async function dcm2json(inputPath, options) {
   const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
   const signal = options?.signal;
   const startTime = Date.now();
-  const remaining = () => Math.max(1e3, timeoutMs - (Date.now() - startTime));
+  const remaining = () => Math.max(0, timeoutMs - (Date.now() - startTime));
   const verbosity = options?.verbosity;
   if (options?.directOnly === true) {
-    return tryDirectPath(inputPath, remaining(), signal, verbosity);
+    return tryDirectPath(inputPath, timeoutMs, signal, verbosity);
   }
-  const xmlResult = await tryXmlPath(inputPath, remaining(), signal, buildXmlOpts(options));
+  const xmlResult = await tryXmlPath(inputPath, timeoutMs, signal, buildXmlOpts(options));
   if (xmlResult.ok) {
     return xmlResult;
   }
-  return tryDirectPath(inputPath, remaining(), signal, verbosity);
+  return fallbackToDirect(inputPath, xmlResult.error, { budget: remaining(), timeoutMs, signal, verbosity });
+}
+async function fallbackToDirect(inputPath, xmlError, context) {
+  if (context.budget === 0) {
+    return err(
+      new Error(
+        `dcm2json: XML path failed and timeout budget (${String(context.timeoutMs)}ms) is exhausted (skipping direct fallback) | xml: ${xmlError.message}`
+      )
+    );
+  }
+  const directResult = await tryDirectPath(inputPath, context.budget, context.signal, context.verbosity);
+  if (directResult.ok) {
+    return directResult;
+  }
+  return err(new Error(`dcm2json: both paths failed | xml: ${xmlError.message} | direct: ${directResult.error.message}`));
+}
+
+// src/tools/_charset.ts
+var LATIN1 = { kind: "latin1" };
+function label(name) {
+  return { kind: "label", label: name };
+}
+var CHARSET_DECODERS = {
+  "ISO_IR 6": LATIN1,
+  "ISO_IR 100": LATIN1,
+  "ISO_IR 101": label("iso-8859-2"),
+  "ISO_IR 109": label("iso-8859-3"),
+  "ISO_IR 110": label("iso-8859-4"),
+  "ISO_IR 144": label("iso-8859-5"),
+  "ISO_IR 127": label("iso-8859-6"),
+  "ISO_IR 126": label("iso-8859-7"),
+  "ISO_IR 138": label("iso-8859-8"),
+  "ISO_IR 148": label("iso-8859-9"),
+  "ISO_IR 203": label("iso-8859-15"),
+  "ISO_IR 13": label("shift_jis"),
+  "ISO_IR 166": label("windows-874"),
+  "ISO_IR 192": label("utf-8"),
+  GB18030: label("gb18030"),
+  GBK: label("gbk")
+};
+var ISO2022_INITIAL = {
+  "ISO 2022 IR 6": LATIN1,
+  "ISO 2022 IR 13": label("shift_jis"),
+  "ISO 2022 IR 87": LATIN1,
+  "ISO 2022 IR 159": LATIN1,
+  "ISO 2022 IR 149": label("euc-kr"),
+  "ISO 2022 IR 58": label("gbk"),
+  "ISO 2022 IR 100": LATIN1,
+  "ISO 2022 IR 101": label("iso-8859-2"),
+  "ISO 2022 IR 109": label("iso-8859-3"),
+  "ISO 2022 IR 110": label("iso-8859-4"),
+  "ISO 2022 IR 144": label("iso-8859-5"),
+  "ISO 2022 IR 127": label("iso-8859-6"),
+  "ISO 2022 IR 126": label("iso-8859-7"),
+  "ISO 2022 IR 138": label("iso-8859-8"),
+  "ISO 2022 IR 148": label("iso-8859-9"),
+  "ISO 2022 IR 166": label("windows-874"),
+  "ISO 2022 IR 203": label("iso-8859-15")
+};
+var ESCAPE_DECODERS = {
+  "(B": LATIN1,
+  // G0 = ASCII
+  "(J": LATIN1,
+  // G0 = JIS X 0201 romaji
+  ")I": { kind: "katakana" },
+  // G1 = JIS X 0201 katakana
+  "$@": { kind: "iso2022jp", escape: [27, 36, 64] },
+  // G0 = JIS X 0208-1978
+  $B: { kind: "iso2022jp", escape: [27, 36, 66] },
+  // G0 = JIS X 0208
+  "$(D": { kind: "iso2022jp", escape: [27, 36, 40, 68] },
+  // G0 = JIS X 0212
+  "$)C": label("euc-kr"),
+  // G1 = KS X 1001
+  "$)A": label("gbk"),
+  // G1 = GB 2312
+  "-A": LATIN1,
+  // G1 = ISO-8859-1
+  "-B": label("iso-8859-2"),
+  "-C": label("iso-8859-3"),
+  "-D": label("iso-8859-4"),
+  "-F": label("iso-8859-7"),
+  "-G": label("iso-8859-6"),
+  "-H": label("iso-8859-8"),
+  "-L": label("iso-8859-5"),
+  "-M": label("iso-8859-9"),
+  "-T": label("windows-874"),
+  "-b": label("iso-8859-15")
+};
+var CHARSET_ALIASES = {
+  ascii: "ISO_IR 6",
+  "latin-1": "ISO_IR 100",
+  latin1: "ISO_IR 100",
+  "iso-8859-1": "ISO_IR 100",
+  "latin-2": "ISO_IR 101",
+  "latin-3": "ISO_IR 109",
+  "latin-4": "ISO_IR 110",
+  "latin-5": "ISO_IR 148",
+  "latin-9": "ISO_IR 203",
+  cyrillic: "ISO_IR 144",
+  arabic: "ISO_IR 127",
+  greek: "ISO_IR 126",
+  hebrew: "ISO_IR 138",
+  thai: "ISO_IR 166",
+  "shift-jis": "ISO_IR 13",
+  shift_jis: "ISO_IR 13",
+  "utf-8": "ISO_IR 192",
+  utf8: "ISO_IR 192",
+  gb18030: "GB18030",
+  gbk: "GBK"
+};
+var SINGLE_BYTE_LABELS = /* @__PURE__ */ new Set([
+  "iso-8859-2",
+  "iso-8859-3",
+  "iso-8859-4",
+  "iso-8859-5",
+  "iso-8859-6",
+  "iso-8859-7",
+  "iso-8859-8",
+  "iso-8859-9",
+  "iso-8859-15",
+  "windows-874"
+]);
+function isSingleByteDecoder(decoder) {
+  return decoder.kind === "latin1" || decoder.kind === "label" && SINGLE_BYTE_LABELS.has(decoder.label);
+}
+var decoderCache = /* @__PURE__ */ new Map();
+function getTextDecoder(labelName) {
+  if (decoderCache.has(labelName)) {
+    return decoderCache.get(labelName);
+  }
+  let decoder;
+  try {
+    decoder = new TextDecoder(labelName);
+  } catch {
+    decoder = void 0;
+  }
+  decoderCache.set(labelName, decoder);
+  return decoder;
+}
+function decodeLatin1(bytes) {
+  return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString("latin1");
+}
+function decodeSegment(bytes, decoder) {
+  if (bytes.length === 0) return "";
+  switch (decoder.kind) {
+    case "latin1":
+      return decodeLatin1(bytes);
+    case "label": {
+      const td = getTextDecoder(decoder.label);
+      if (td === void 0) return decodeLatin1(bytes);
+      return td.decode(bytes);
+    }
+    case "iso2022jp": {
+      const td = getTextDecoder("iso-2022-jp");
+      if (td === void 0) return decodeLatin1(bytes);
+      const wrapped = new Uint8Array(decoder.escape.length + bytes.length);
+      wrapped.set(decoder.escape, 0);
+      wrapped.set(bytes, decoder.escape.length);
+      return td.decode(wrapped);
+    }
+    case "katakana": {
+      const td = getTextDecoder("shift_jis");
+      if (td === void 0) return decodeLatin1(bytes);
+      return td.decode(bytes);
+    }
+  }
+}
+function readEscape(bytes, start) {
+  let i = start + 1;
+  while (i < bytes.length && bytes[i] >= 32 && bytes[i] <= 47) {
+    i++;
+  }
+  if (i < bytes.length && bytes[i] >= 48 && bytes[i] <= 126) {
+    i++;
+  }
+  const seq = bytes.subarray(start + 1, i);
+  return { key: decodeLatin1(seq), length: i - start };
+}
+function decodeIso2022(bytes, initial) {
+  let out = "";
+  let current = initial;
+  let segStart = 0;
+  let i = 0;
+  while (i < bytes.length) {
+    if (bytes[i] !== 27) {
+      i++;
+      continue;
+    }
+    out += decodeSegment(bytes.subarray(segStart, i), current);
+    const esc = readEscape(bytes, i);
+    current = ESCAPE_DECODERS[esc.key] ?? current;
+    i += esc.length;
+    segStart = i;
+  }
+  out += decodeSegment(bytes.subarray(segStart), current);
+  return out;
+}
+var DEFAULT_CONTEXT = { terms: ["ISO_IR 6"], iso2022: false, initial: LATIN1, singleByte: true };
+function normalizeCharsetName(input) {
+  const trimmed = input.trim();
+  if (CHARSET_DECODERS[trimmed] !== void 0 || ISO2022_INITIAL[trimmed] !== void 0) {
+    return trimmed;
+  }
+  return CHARSET_ALIASES[trimmed.toLowerCase()];
+}
+function buildContext(terms) {
+  const iso2022 = terms.length > 1 || terms.some((t) => t.startsWith("ISO 2022"));
+  const first = terms[0] ?? "ISO_IR 6";
+  const initial = iso2022 ? ISO2022_INITIAL[first] : CHARSET_DECODERS[first];
+  if (initial === void 0) return void 0;
+  return { terms, iso2022, initial, singleByte: !iso2022 && isSingleByteDecoder(initial) };
+}
+function parseSpecificCharacterSet(raw) {
+  const values = raw.split("\\").map((v) => v.trim());
+  return values.map((v, idx) => v === "" && idx === 0 ? "ISO 2022 IR 6" : v).filter((v) => v !== "");
+}
+function contextFromTerms(terms, fallback, source) {
+  const context = buildContext(terms);
+  if (context !== void 0) {
+    return ok(context);
+  }
+  if (fallback !== void 0) {
+    const fallbackTerm = normalizeCharsetName(fallback);
+    const fallbackContext = fallbackTerm !== void 0 ? buildContext([fallbackTerm]) : void 0;
+    if (fallbackContext !== void 0) {
+      return ok(fallbackContext);
+    }
+    return err(new Error(`Unsupported charset fallback '${fallback}' (while handling unsupported ${source})`));
+  }
+  return err(new Error(`Unsupported character set: ${source} \u2014 provide charsetFallback (e.g. 'latin-1') to decode best-effort`));
+}
+function resolveCharsetContext(specificCharacterSet, charsetAssume, charsetFallback) {
+  if (specificCharacterSet === void 0 || specificCharacterSet.trim() === "") {
+    if (charsetAssume === void 0) {
+      return ok(DEFAULT_CONTEXT);
+    }
+    const term = normalizeCharsetName(charsetAssume);
+    if (term === void 0) {
+      return contextFromTerms([charsetAssume], charsetFallback, `charsetAssume '${charsetAssume}'`);
+    }
+    return contextFromTerms([term], charsetFallback, `charsetAssume '${charsetAssume}'`);
+  }
+  const terms = parseSpecificCharacterSet(specificCharacterSet);
+  return contextFromTerms(terms, charsetFallback, `'${specificCharacterSet}' (0008,0005)`);
+}
+function decodeDicomText(bytes, context) {
+  if (context.iso2022) {
+    return decodeIso2022(bytes, context.initial);
+  }
+  return decodeSegment(bytes, context.initial);
+}
+var strictUtf8;
+function isProbableUtf8Mislabel(bytes) {
+  let hasHighByte = false;
+  for (const byte of bytes) {
+    if (byte >= 128) {
+      hasHighByte = true;
+      break;
+    }
+  }
+  if (!hasHighByte) return false;
+  strictUtf8 ?? (strictUtf8 = new TextDecoder("utf-8", { fatal: true }));
+  try {
+    strictUtf8.decode(bytes);
+    return true;
+  } catch {
+    return false;
+  }
+}
+var UTF8_DECODER = label("utf-8");
+function decodeUtf8(bytes) {
+  return decodeSegment(bytes, UTF8_DECODER);
+}
+
+// src/tools/_p10ToJson.ts
+var BINARY_VRS = /* @__PURE__ */ new Set(["OB", "OW", "OD", "OF", "OL", "OV", "UN"]);
+var CHARSET_VRS = /* @__PURE__ */ new Set(["SH", "LO", "ST", "LT", "UC", "UT", "PN"]);
+var NO_SPLIT_VRS = /* @__PURE__ */ new Set(["ST", "LT", "UT", "UR"]);
+var NUMERIC_VR_SIZE = { US: 2, SS: 2, UL: 4, SL: 4, FL: 4, FD: 8, SV: 8, UV: 8 };
+var MAX_DATASETS = 1e5;
+function toJsonTag(tag) {
+  return tag.slice(1).toUpperCase();
+}
+function isEncodingArtifact(tag) {
+  return tag.endsWith("0000") && tag.length === 9 || tag.startsWith("xfffe");
+}
+function resolveVr(element) {
+  const vr = element.vr;
+  if (vr !== void 0 && KNOWN_VR_CODES.has(vr)) {
+    return vr;
+  }
+  return "UN";
+}
+function valueBytes(element, byteArray) {
+  return byteArray.subarray(element.dataOffset, element.dataOffset + element.length);
+}
+function trimPadding(value) {
+  let end = value.length;
+  while (end > 0) {
+    const ch = value.charCodeAt(end - 1);
+    if (ch !== 32 && ch !== 0) break;
+    end--;
+  }
+  return value.slice(0, end);
+}
+function readNumericAt(view, offset, vr, littleEndian) {
+  switch (vr) {
+    case "US":
+      return view.getUint16(offset, littleEndian);
+    case "SS":
+      return view.getInt16(offset, littleEndian);
+    case "UL":
+      return view.getUint32(offset, littleEndian);
+    case "SL":
+      return view.getInt32(offset, littleEndian);
+    case "FL":
+      return view.getFloat32(offset, littleEndian);
+    case "FD":
+      return view.getFloat64(offset, littleEndian);
+    case "SV":
+      return Number(view.getBigInt64(offset, littleEndian));
+    /* v8 ignore next 2 -- 'UV' is the only remaining caller-provided VR */
+    default:
+      return Number(view.getBigUint64(offset, littleEndian));
+  }
+}
+function convertNumeric(element, byteArray, vr, littleEndian) {
+  const size = NUMERIC_VR_SIZE[vr];
+  const count = Math.floor(element.length / size);
+  if (count === 0) {
+    return { vr };
+  }
+  const view = new DataView(byteArray.buffer, byteArray.byteOffset + element.dataOffset, element.length);
+  const values = [];
+  for (let i = 0; i < count; i++) {
+    values.push(readNumericAt(view, i * size, vr, littleEndian));
+  }
+  return { vr, Value: values };
+}
+function convertAttributeTag(element, byteArray, littleEndian) {
+  const count = Math.floor(element.length / 4);
+  if (count === 0) {
+    return { vr: "AT" };
+  }
+  const view = new DataView(byteArray.buffer, byteArray.byteOffset + element.dataOffset, element.length);
+  const values = [];
+  for (let i = 0; i < count; i++) {
+    const group = view.getUint16(i * 4, littleEndian);
+    const elem = view.getUint16(i * 4 + 2, littleEndian);
+    values.push(group.toString(16).padStart(4, "0").toUpperCase() + elem.toString(16).padStart(4, "0").toUpperCase());
+  }
+  return { vr: "AT", Value: values };
+}
+function personNameToJson(value) {
+  const groups = trimPadding(value).split("=");
+  const result = {};
+  const names = ["Alphabetic", "Ideographic", "Phonetic"];
+  for (let i = 0; i < names.length; i++) {
+    const group = (groups[i] ?? "").replace(/\^+$/u, "");
+    const name = names[i];
+    if (group !== "" && name !== void 0) {
+      result[name] = group;
+    }
+  }
+  return result;
+}
+function decodeTextChecked(bytes, tag, settings) {
+  const { charset, mislabel } = settings;
+  if (charset.singleByte && isProbableUtf8Mislabel(bytes)) {
+    if (!mislabel.seen.has(tag)) {
+      mislabel.seen.add(tag);
+      const action = mislabel.promote ? "decoded as UTF-8" : `decoded as '${charset.terms.join("\\")}'`;
+      mislabel.warnings.push(`possible UTF-8 mislabel: ${tag} (${action})`);
+    }
+    if (mislabel.promote) {
+      return decodeUtf8(bytes);
+    }
+  }
+  return decodeDicomText(bytes, charset);
+}
+function convertPersonName2(element, byteArray, settings) {
+  const decoded = decodeTextChecked(valueBytes(element, byteArray), toJsonTag(element.tag), settings);
+  const values = decoded.split("\\").map(personNameToJson);
+  return { vr: "PN", Value: values };
+}
+function convertString(element, byteArray, vr, settings) {
+  const bytes = valueBytes(element, byteArray);
+  const decoded = CHARSET_VRS.has(vr) ? decodeTextChecked(bytes, toJsonTag(element.tag), settings) : Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString("latin1");
+  const rawValues = NO_SPLIT_VRS.has(vr) ? [decoded] : decoded.split("\\");
+  const values = rawValues.map((v) => {
+    const trimmed = trimPadding(v);
+    return vr === "DS" || vr === "IS" ? coerceNumeric(trimmed.trim()) : trimmed;
+  });
+  if (values.length === 1 && values[0] === "") {
+    return { vr };
+  }
+  return { vr, Value: values };
+}
+function convertLeaf(element, byteArray, vr, settings) {
+  if (element.fragments !== void 0) {
+    return { vr: "OB" };
+  }
+  if (BINARY_VRS.has(vr)) {
+    return { vr };
+  }
+  if (element.length === 0) {
+    return { vr };
+  }
+  if (NUMERIC_VR_SIZE[vr] !== void 0) {
+    return convertNumeric(element, byteArray, vr, settings.littleEndian);
+  }
+  if (vr === "AT") {
+    return convertAttributeTag(element, byteArray, settings.littleEndian);
+  }
+  if (vr === "PN") {
+    return convertPersonName2(element, byteArray, settings);
+  }
+  return convertString(element, byteArray, vr, settings);
+}
+function datasetCharset(src, parent, options) {
+  const raw = src.string("x00080005");
+  if (raw === void 0) {
+    return ok(parent);
+  }
+  return resolveCharsetContext(raw, void 0, options?.charsetFallback);
+}
+function convertSequence2(element, stack, charset) {
+  const items = element.items ?? [];
+  const values = [];
+  for (const item of items) {
+    const model = {};
+    values.push(model);
+    if (item.dataSet !== void 0) {
+      stack.push({ src: item.dataSet, out: model, parentCharset: charset });
+    }
+  }
+  if (values.length === 0) {
+    return { vr: "SQ" };
+  }
+  return { vr: "SQ", Value: values };
+}
+function isSequence(element, vr) {
+  if (element.fragments !== void 0) {
+    return false;
+  }
+  return vr === "SQ" || element.vr === void 0 && element.items !== void 0;
+}
+function convertDataset(unit, stack, state) {
+  const charsetResult = datasetCharset(unit.src, unit.parentCharset, state.options);
+  if (!charsetResult.ok) {
+    return err(charsetResult.error);
+  }
+  const charset = charsetResult.value;
+  const keys = Object.keys(unit.src.elements).sort();
+  for (const key of keys) {
+    const element = unit.src.elements[key];
+    if (element === void 0) continue;
+    if (isEncodingArtifact(element.tag)) continue;
+    const tag = toJsonTag(element.tag);
+    const vr = resolveVr(element);
+    if (isSequence(element, vr)) {
+      unit.out[tag] = convertSequence2(element, stack, charset);
+    } else {
+      unit.out[tag] = convertLeaf(element, unit.src.byteArray, vr, { charset, littleEndian: state.littleEndian, mislabel: state.mislabel });
+    }
+  }
+  return ok(void 0);
+}
+function inflateDeflated(byteArray, position) {
+  const inflated = inflateRawSync(byteArray.subarray(position));
+  const combined = new Uint8Array(position + inflated.byteLength);
+  combined.set(byteArray.subarray(0, position), 0);
+  combined.set(inflated, position);
+  return combined;
+}
+function implicitVrLookup(tag) {
+  return lookupTag(tag.slice(1))?.vr;
+}
+function parseDicomBuffer(buffer, options) {
+  let dataSet;
+  try {
+    dataSet = dicomParser2.parseDicom(buffer, { vrCallback: implicitVrLookup, inflater: inflateDeflated });
+  } catch (error) {
+    return err(new Error(`Failed to parse DICOM data: ${stderr(error).message}`));
+  }
+  const littleEndian = dataSet.string("x00020010") !== "1.2.840.10008.1.2.2";
+  const rootCharset = resolveCharsetContext(void 0, options?.charsetAssume, options?.charsetFallback);
+  if (!rootCharset.ok) {
+    return err(rootCharset.error);
+  }
+  const data = {};
+  const stack = [{ src: dataSet, out: data, parentCharset: rootCharset.value }];
+  const mislabel = { promote: options?.utf8MislabelPromote === true, warnings: [], seen: /* @__PURE__ */ new Set() };
+  const state = { littleEndian, options, mislabel };
+  let processed = 0;
+  while (stack.length > 0) {
+    processed++;
+    if (processed > MAX_DATASETS) {
+      return err(new Error(`Failed to parse DICOM data: more than ${String(MAX_DATASETS)} nested datasets`));
+    }
+    const unit = stack.pop();
+    if (unit === void 0) break;
+    const converted = convertDataset(unit, stack, state);
+    if (!converted.ok) {
+      return err(converted.error);
+    }
+  }
+  return ok({ data, warnings: [...dataSet.warnings, ...mislabel.warnings] });
+}
+var TS_IMPLICIT_LE = "1.2.840.10008.1.2";
+var TS_EXPLICIT_BE = "1.2.840.10008.1.2.2";
+var TS_DEFLATED_LE = "1.2.840.10008.1.2.1.99";
+var BULK_VRS = /* @__PURE__ */ new Set(["OB", "OW", "OD", "OF", "OL", "OV", "UN"]);
+var LONG_FORM_VRS = /* @__PURE__ */ new Set(["OB", "OW", "OF", "OD", "OL", "OV", "SQ", "UC", "UR", "UT", "UN", "SV", "UV"]);
+var UNDEFINED_LENGTH = 4294967295;
+var MAX_HEADER_BYTES = 12;
+var MAX_ITERATIONS = 1e4;
+var MAX_FRAGMENT_HOPS = 1e5;
+var MAX_READ_CALLS = 1e4;
+async function readRange(handle, position, length) {
+  const buffer = Buffer.alloc(length);
+  let total = 0;
+  for (let i = 0; i < MAX_READ_CALLS && total < length; i++) {
+    const { bytesRead } = await handle.read(buffer, total, length - total, position + total);
+    if (bytesRead === 0) {
+      return err(new Error(`unexpected EOF at offset ${String(position + total)}`));
+    }
+    total += bytesRead;
+  }
+  if (total < length) {
+    return err(new Error(`short read at offset ${String(position)}`));
+  }
+  return ok(buffer);
+}
+function checkAbort(state) {
+  if (state.signal?.aborted === true) {
+    return new Error("aborted");
+  }
+  if (Date.now() > state.deadline) {
+    return new Error(`timed out after ${String(state.timeoutMs)}ms`);
+  }
+  return void 0;
+}
+var readPart10Header = dicomParser2.readPart10Header;
+function probeMeta(head) {
+  let meta;
+  try {
+    meta = readPart10Header(head);
+  } catch {
+    return void 0;
+  }
+  const tsElement = meta.elements["x00020010"];
+  if (meta.position === void 0 || tsElement === void 0) {
+    return void 0;
+  }
+  const transferSyntax = head.subarray(tsElement.dataOffset, tsElement.dataOffset + tsElement.length).toString("latin1").replace(/[\0 ]+$/u, "");
+  return { metaEnd: meta.position, transferSyntax };
+}
+function hasPartialDataSet(e) {
+  return typeof e === "object" && e !== null && "dataSet" in e;
+}
+function probeParse(assembled) {
+  try {
+    return { dataSet: dicomParser2.parseDicom(assembled, { vrCallback: implicitVrLookup }), threw: false };
+  } catch (e) {
+    return { dataSet: hasPartialDataSet(e) ? e.dataSet : void 0, threw: true };
+  }
+}
+function maxExtentElement(dataSet) {
+  let best;
+  let bestEnd = -1;
+  for (const key of Object.keys(dataSet.elements)) {
+    const element = dataSet.elements[key];
+    if (element === void 0) continue;
+    const end = element.dataOffset + element.length;
+    if (end > bestEnd) {
+      bestEnd = end;
+      best = element;
+    }
+  }
+  return best;
+}
+function formatTag(group, elementNum) {
+  return group.toString(16).padStart(4, "0") + elementNum.toString(16).padStart(4, "0");
+}
+function parseElementHeader(assembled, position, state) {
+  if (position + MAX_HEADER_BYTES > assembled.length) {
+    return void 0;
+  }
+  if (!state.explicitVr) {
+    const tag2 = formatTag(assembled.readUInt16LE(position), assembled.readUInt16LE(position + 2));
+    const vr2 = implicitVrLookup(`x${tag2}`) ?? "UN";
+    return { tag: tag2, vr: vr2, length: assembled.readUInt32LE(position + 4), headerLen: 8, lengthOffset: 4 };
+  }
+  const tag = state.bigEndian ? formatTag(assembled.readUInt16BE(position), assembled.readUInt16BE(position + 2)) : formatTag(assembled.readUInt16LE(position), assembled.readUInt16LE(position + 2));
+  const vr = assembled.subarray(position + 4, position + 6).toString("latin1");
+  if (!/^[A-Z]{2}$/u.test(vr)) {
+    return void 0;
+  }
+  if (LONG_FORM_VRS.has(vr)) {
+    const length2 = state.bigEndian ? assembled.readUInt32BE(position + 8) : assembled.readUInt32LE(position + 8);
+    return { tag, vr, length: length2, headerLen: 12, lengthOffset: 8 };
+  }
+  const length = state.bigEndian ? assembled.readUInt16BE(position + 6) : assembled.readUInt16LE(position + 6);
+  return { tag, vr, length, headerLen: 8, lengthOffset: 6 };
+}
+function decideAfterThrow(probe, state) {
+  if (state.filePos >= state.fileSize) {
+    return { kind: "fullRead" };
+  }
+  if (probe.dataSet === void 0) {
+    return { kind: "grow" };
+  }
+  const last = maxExtentElement(probe.dataSet);
+  const maxEnd = last === void 0 ? state.metaEnd : last.dataOffset + last.length;
+  if (last !== void 0 && maxEnd > state.assembled.length) {
+    return decideOversized(last, last.hadUndefinedLength === true, state);
+  }
+  const header = parseElementHeader(state.assembled, maxEnd, state);
+  if (header === void 0) {
+    return { kind: "grow" };
+  }
+  return decideWithHeader(state, maxEnd, header, header.length === UNDEFINED_LENGTH);
+}
+function decideWithHeader(state, position, header, undefinedLength) {
+  if (undefinedLength) {
+    if (header.tag === "7fe00010" && (header.vr === "OB" || header.vr === "OW") && state.explicitVr && !state.bigEndian) {
+      rewriteHeader(state.assembled, position, header, true);
+      return { kind: "skipEncapsulated", headerStart: position, headerEnd: position + header.headerLen };
+    }
+    return { kind: "grow" };
+  }
+  if (BULK_VRS.has(header.vr)) {
+    return rewriteAndSkip(state, position, header);
+  }
+  return { kind: "grow" };
+}
+function rewriteHeader(assembled, position, header, forceObVr) {
+  if (header.lengthOffset === 6) {
+    assembled.writeUInt16LE(0, position + header.lengthOffset);
+  } else {
+    assembled.writeUInt32LE(0, position + header.lengthOffset);
+  }
+  if (forceObVr) {
+    assembled.write("OB", position + 4, "latin1");
+  }
+}
+function rewriteAndSkip(state, position, header) {
+  rewriteHeader(state.assembled, position, header, false);
+  return { kind: "skipDefined", headerEnd: position + header.headerLen, valueLength: header.length };
+}
+function decideAfterSuccess(probe, state) {
+  if (probe.dataSet === void 0) return { kind: "fullRead" };
+  const last = maxExtentElement(probe.dataSet);
+  const maxEnd = last === void 0 ? state.metaEnd : last.dataOffset + last.length;
+  const undefinedAtEnd = last?.hadUndefinedLength === true && maxEnd >= state.assembled.length;
+  if (state.filePos >= state.fileSize) {
+    return { kind: "done" };
+  }
+  if (maxEnd <= state.assembled.length && !undefinedAtEnd) {
+    return { kind: "grow" };
+  }
+  if (last === void 0) return { kind: "grow" };
+  return decideOversized(last, undefinedAtEnd, state);
+}
+function decideOversized(last, undefinedAtEnd, state) {
+  const headerStart = findHeaderStart(state.assembled, last, state);
+  if (headerStart === void 0) {
+    return { kind: "grow" };
+  }
+  const header = parseElementHeader(state.assembled, headerStart, state);
+  if (header === void 0) return { kind: "grow" };
+  if (!undefinedAtEnd && header.length !== last.length) {
+    return { kind: "grow" };
+  }
+  return decideWithHeader(state, headerStart, header, undefinedAtEnd);
+}
+function findHeaderStart(assembled, element, state) {
+  const candidates = state.explicitVr ? [12, 8] : [8];
+  for (const headerLen of candidates) {
+    const start = element.dataOffset - headerLen;
+    if (start < 0) continue;
+    const header = parseElementHeader(assembled, start, state);
+    if (header !== void 0 && header.headerLen === headerLen) {
+      return start;
+    }
+  }
+  return void 0;
+}
+function fileOffsetOf(state, assembledPos) {
+  return state.filePos - (state.assembled.length - assembledPos);
+}
+function applyDefinedSkip(state, headerEnd, valueLength) {
+  const valueStartInFile = fileOffsetOf(state, headerEnd);
+  if (valueStartInFile + valueLength > state.fileSize) {
+    return err(new Error("declared value length extends beyond EOF"));
+  }
+  state.filePos = valueStartInFile + valueLength;
+  state.assembled = state.assembled.subarray(0, headerEnd);
+  state.growSize = state.chunkBytes;
+  return ok(void 0);
+}
+async function hopFragments(handle, start, fileSize) {
+  let position = start;
+  for (let i = 0; i < MAX_FRAGMENT_HOPS; i++) {
+    if (position + 8 > fileSize) {
+      return err(new Error("encapsulated data truncated"));
+    }
+    const headerResult = await readRange(handle, position, 8);
+    if (!headerResult.ok) {
+      return err(headerResult.error);
+    }
+    const group = headerResult.value.readUInt16LE(0);
+    const elementNum = headerResult.value.readUInt16LE(2);
+    const itemLength = headerResult.value.readUInt32LE(4);
+    if (group !== 65534) {
+      return err(new Error("unexpected tag between fragments"));
+    }
+    if (elementNum === 57565) {
+      return ok(position + 8);
+    }
+    if (elementNum !== 57344 || itemLength === UNDEFINED_LENGTH) {
+      return err(new Error("malformed fragment item"));
+    }
+    position += 8 + itemLength;
+  }
+  return err(new Error("fragment count exceeded bound"));
+}
+async function applyEncapsulatedSkip(state, headerEnd) {
+  const valueStartInFile = fileOffsetOf(state, headerEnd);
+  const afterDelimiter = await hopFragments(state.handle, valueStartInFile, state.fileSize);
+  if (!afterDelimiter.ok) {
+    return err(afterDelimiter.error);
+  }
+  state.filePos = afterDelimiter.value;
+  state.assembled = state.assembled.subarray(0, headerEnd);
+  state.growSize = state.chunkBytes;
+  return ok(void 0);
+}
+async function appendChunk(state) {
+  const length = Math.min(state.growSize, state.fileSize - state.filePos);
+  if (length <= 0) return err(new Error("no bytes left to grow"));
+  const chunk = await readRange(state.handle, state.filePos, length);
+  if (!chunk.ok) {
+    return err(chunk.error);
+  }
+  state.assembled = Buffer.concat([state.assembled, chunk.value]);
+  state.filePos += length;
+  state.growSize = Math.min(state.growSize * 2, state.fileSize);
+  return ok(void 0);
+}
+async function applyAction(action, state) {
+  switch (action.kind) {
+    case "done":
+      return "done";
+    case "fullRead":
+      return "fullRead";
+    case "grow":
+      return (await appendChunk(state)).ok ? "continue" : "fullRead";
+    case "skipDefined":
+      return applyDefinedSkip(state, action.headerEnd, action.valueLength).ok ? "continue" : "fullRead";
+    case "skipEncapsulated":
+      return (await applyEncapsulatedSkip(state, action.headerEnd)).ok ? "continue" : "fullRead";
+  }
+}
+async function boundedLoop(state) {
+  for (let i = 0; i < MAX_ITERATIONS; i++) {
+    const abort = checkAbort(state);
+    if (abort !== void 0) {
+      return err(abort);
+    }
+    const probe = probeParse(state.assembled);
+    const action = probe.threw ? decideAfterThrow(probe, state) : decideAfterSuccess(probe, state);
+    const outcome = await applyAction(action, state);
+    if (outcome === "done") {
+      return ok(state.assembled);
+    }
+    if (outcome === "fullRead") {
+      return "fullRead";
+    }
+  }
+  return "fullRead";
+}
+async function readWhole(handle, fileSize, state) {
+  const abort = checkAbort(state);
+  if (abort !== void 0) {
+    return err(abort);
+  }
+  return readRange(handle, 0, fileSize);
+}
+async function readWithHandle(handle, options) {
+  const fileSize = (await handle.stat()).size;
+  const deadline = Date.now() + options.timeoutMs;
+  const guard = { deadline, signal: options.signal, timeoutMs: options.timeoutMs };
+  const threshold = options.thresholdBytes ?? BOUNDED_READ_THRESHOLD_BYTES;
+  const chunkBytes = options.chunkBytes ?? BOUNDED_READ_CHUNK_BYTES;
+  if (fileSize <= threshold) {
+    return readWhole(handle, fileSize, guard);
+  }
+  const headResult = await readRange(handle, 0, Math.min(chunkBytes, fileSize));
+  if (!headResult.ok) {
+    return err(headResult.error);
+  }
+  const meta = probeMeta(headResult.value);
+  if (meta === void 0 || meta.transferSyntax === TS_DEFLATED_LE) {
+    return readWhole(handle, fileSize, guard);
+  }
+  const state = {
+    handle,
+    fileSize,
+    chunkBytes,
+    explicitVr: meta.transferSyntax !== TS_IMPLICIT_LE,
+    bigEndian: meta.transferSyntax === TS_EXPLICIT_BE,
+    metaEnd: meta.metaEnd,
+    deadline,
+    timeoutMs: options.timeoutMs,
+    signal: options.signal,
+    assembled: headResult.value,
+    filePos: headResult.value.length,
+    growSize: chunkBytes
+  };
+  const result = await boundedLoop(state);
+  if (result === "fullRead") {
+    return readWhole(handle, fileSize, guard);
+  }
+  return result;
+}
+async function readDicomHead(inputPath, options) {
+  let handle;
+  try {
+    handle = await open(inputPath, "r");
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return err(new Error(`failed to read '${inputPath}': ${message}`));
+  }
+  try {
+    const result = await readWithHandle(handle, options);
+    if (result.ok) {
+      return result;
+    }
+    return err(new Error(`reading '${inputPath}' failed: ${result.error.message}`));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return err(new Error(`failed to read '${inputPath}': ${message}`));
+  } finally {
+    await handle.close();
+  }
+}
+
+// src/tools/dicom2json.ts
+var Dicom2jsonOptionsSchema = z.object({
+  timeoutMs: z.number().int().positive().optional(),
+  signal: z.instanceof(AbortSignal).optional(),
+  charsetAssume: z.string().min(1).optional(),
+  charsetFallback: z.string().min(1).optional(),
+  utf8MislabelPromote: z.boolean().optional(),
+  dcmtkFallback: z.boolean().optional(),
+  boundedRead: z.boolean().optional()
+}).strict().optional();
+z.object({
+  charsetAssume: z.string().min(1).optional(),
+  charsetFallback: z.string().min(1).optional(),
+  utf8MislabelPromote: z.boolean().optional()
+}).strict().optional();
+async function readFileBounded(inputPath, timeoutMs, signal) {
+  const timeoutSignal = AbortSignal.timeout(timeoutMs);
+  const combined = signal !== void 0 ? AbortSignal.any([signal, timeoutSignal]) : timeoutSignal;
+  try {
+    return ok(await readFile(inputPath, { signal: combined }));
+  } catch (error) {
+    if (timeoutSignal.aborted) {
+      return err(new Error(`dicom2json: reading '${inputPath}' timed out after ${String(timeoutMs)}ms`));
+    }
+    if (signal?.aborted === true) {
+      return err(new Error(`dicom2json: aborted while reading '${inputPath}'`));
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return err(new Error(`dicom2json: failed to read '${inputPath}': ${message}`));
+  }
+}
+async function runDcmtkFallback(inputPath, jsError, remainingMs, options) {
+  if (remainingMs <= 0) {
+    return err(new Error(`dicom2json: JS parse failed and timeout budget exhausted (skipping DCMTK fallback) | js: ${jsError.message}`));
+  }
+  const fallback = await dcm2json(inputPath, {
+    timeoutMs: remainingMs,
+    signal: options?.signal,
+    charsetAssume: options?.charsetAssume,
+    charsetFallback: options?.charsetFallback
+  });
+  if (!fallback.ok) {
+    return err(new Error(`dicom2json: both engines failed | js: ${jsError.message} | dcmtk: ${fallback.error.message}`));
+  }
+  return ok({ data: fallback.value.data, warnings: [], source: fallback.value.source });
+}
+async function dicom2json(inputPath, options) {
+  const validation = Dicom2jsonOptionsSchema.safeParse(options);
+  if (!validation.success) {
+    return err(createValidationError("dicom2json", validation.error));
+  }
+  const timeoutMs = options?.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const startTime = Date.now();
+  const parsed = await parseFromFile(inputPath, timeoutMs, options);
+  if (parsed.ok) {
+    return parsed;
+  }
+  if (options?.dcmtkFallback === true) {
+    return runDcmtkFallback(inputPath, parsed.error, timeoutMs - (Date.now() - startTime), options);
+  }
+  return err(parsed.error);
+}
+async function readHeadBounded(inputPath, timeoutMs, signal) {
+  const result = await readDicomHead(inputPath, { timeoutMs, signal });
+  if (result.ok) {
+    return result;
+  }
+  return err(new Error(`dicom2json: ${result.error.message}`));
+}
+async function parseFromFile(inputPath, timeoutMs, options) {
+  const fileResult = options?.boundedRead === false ? await readFileBounded(inputPath, timeoutMs, options?.signal) : await readHeadBounded(inputPath, timeoutMs, options?.signal);
+  if (!fileResult.ok) {
+    return err(fileResult.error);
+  }
+  const parsed = parseDicomBuffer(fileResult.value, {
+    charsetAssume: options?.charsetAssume,
+    charsetFallback: options?.charsetFallback,
+    utf8MislabelPromote: options?.utf8MislabelPromote
+  });
+  if (!parsed.ok) {
+    return err(parsed.error);
+  }
+  return ok({ data: parsed.value.data, warnings: parsed.value.warnings, source: "js" });
 }
 var TAG_OR_PATH_PATTERN = /^\([0-9A-Fa-f]{4},[0-9A-Fa-f]{4}\)(\[\d+\]\.\([0-9A-Fa-f]{4},[0-9A-Fa-f]{4}\))*(\[\d+\])?$/;
 var TagModificationSchema = z.object({
@@ -31005,16 +31941,56 @@ async function unlinkFile(path) {
 }
 
 // src/dicom/DicomInstance.ts
+async function readViaDcmtk(path, shared) {
+  const result = await dcm2json(path, shared);
+  if (!result.ok) return err(result.error);
+  return ok({ data: result.value.data, warnings: [] });
+}
+async function readViaJs(path, shared, options) {
+  const result = await dicom2json(path, {
+    ...shared,
+    utf8MislabelPromote: options?.utf8MislabelPromote,
+    boundedRead: options?.boundedRead,
+    dcmtkFallback: true
+  });
+  if (!result.ok) return err(result.error);
+  return ok({ data: result.value.data, warnings: result.value.warnings });
+}
+async function readDicomJson(path, options) {
+  const shared = {
+    timeoutMs: options?.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+    signal: options?.signal,
+    charsetAssume: options?.charsetAssume,
+    charsetFallback: options?.charsetFallback
+  };
+  if (options?.engine === "dcmtk") {
+    return readViaDcmtk(path, shared);
+  }
+  return readViaJs(path, shared, options);
+}
 var DicomInstance = class _DicomInstance {
-  constructor(dataset, changes, filePath, metadata) {
+  constructor(state) {
     __publicField(this, "dicomDataset");
     __publicField(this, "changeSet");
     __publicField(this, "filepath");
     __publicField(this, "meta");
-    this.dicomDataset = dataset;
-    this.changeSet = changes;
-    this.filepath = filePath;
-    this.meta = metadata;
+    __publicField(this, "warningList");
+    this.dicomDataset = state.dataset;
+    this.changeSet = state.changes;
+    this.filepath = state.filePath;
+    this.meta = state.metadata;
+    this.warningList = state.warnings;
+  }
+  /** Creates a copy with the given fields replaced. */
+  derive(overrides) {
+    return new _DicomInstance({
+      dataset: this.dicomDataset,
+      changes: this.changeSet,
+      filePath: this.filepath,
+      metadata: this.meta,
+      warnings: this.warningList,
+      ...overrides
+    });
   }
   // -----------------------------------------------------------------------
   // Factories
@@ -31029,16 +32005,19 @@ var DicomInstance = class _DicomInstance {
   static async open(path, options) {
     const filePathResult = createDicomFilePath(path);
     if (!filePathResult.ok) return err(filePathResult.error);
-    const jsonResult = await dcm2json(path, {
-      timeoutMs: options?.timeoutMs ?? DEFAULT_TIMEOUT_MS,
-      signal: options?.signal,
-      charsetAssume: options?.charsetAssume,
-      charsetFallback: options?.charsetFallback
-    });
+    const jsonResult = await readDicomJson(path, options);
     if (!jsonResult.ok) return err(jsonResult.error);
     const datasetResult = DicomDataset.fromJson(jsonResult.value.data);
     if (!datasetResult.ok) return err(datasetResult.error);
-    return ok(new _DicomInstance(datasetResult.value, ChangeSet.empty(), filePathResult.value, /* @__PURE__ */ new Map()));
+    return ok(
+      new _DicomInstance({
+        dataset: datasetResult.value,
+        changes: ChangeSet.empty(),
+        filePath: filePathResult.value,
+        metadata: /* @__PURE__ */ new Map(),
+        warnings: jsonResult.value.warnings
+      })
+    );
   }
   /**
    * Creates a DicomInstance from an existing DicomDataset.
@@ -31054,7 +32033,7 @@ var DicomInstance = class _DicomInstance {
       if (!fpResult.ok) return err(fpResult.error);
       fp = fpResult.value;
     }
-    return ok(new _DicomInstance(dataset, ChangeSet.empty(), fp, /* @__PURE__ */ new Map()));
+    return ok(new _DicomInstance({ dataset, changes: ChangeSet.empty(), filePath: fp, metadata: /* @__PURE__ */ new Map(), warnings: [] }));
   }
   // -----------------------------------------------------------------------
   // Read accessors (delegate to DicomDataset)
@@ -31075,6 +32054,15 @@ var DicomInstance = class _DicomInstance {
   get filePath() {
     return this.filepath;
   }
+  /**
+   * Non-fatal parser warnings from opening the file (e.g. `possible UTF-8 mislabel: <tag>`).
+   *
+   * Empty for instances created via {@link DicomInstance.fromDataset} or opened with
+   * `engine: 'dcmtk'`. Preserved across fluent modifications.
+   */
+  get warnings() {
+    return this.warningList;
+  }
   /** Patient's Name (0010,0010). */
   get patientName() {
     return this.dicomDataset.patientName;
@@ -31154,7 +32142,7 @@ var DicomInstance = class _DicomInstance {
    * @param value - The new value
    */
   setTag(path, value) {
-    return new _DicomInstance(this.dicomDataset, this.changeSet.setTag(path, value), this.filepath, this.meta);
+    return this.derive({ changes: this.changeSet.setTag(path, value) });
   }
   /**
    * Erases a tag, returning a new DicomInstance.
@@ -31162,11 +32150,11 @@ var DicomInstance = class _DicomInstance {
    * @param path - The DICOM tag path to erase
    */
   eraseTag(path) {
-    return new _DicomInstance(this.dicomDataset, this.changeSet.eraseTag(path), this.filepath, this.meta);
+    return this.derive({ changes: this.changeSet.eraseTag(path) });
   }
   /** Erases all private tags, returning a new DicomInstance. */
   erasePrivateTags() {
-    return new _DicomInstance(this.dicomDataset, this.changeSet.erasePrivateTags(), this.filepath, this.meta);
+    return this.derive({ changes: this.changeSet.erasePrivateTags() });
   }
   /** Sets Patient's Name (0010,0010). */
   setPatientName(value) {
@@ -31220,7 +32208,7 @@ var DicomInstance = class _DicomInstance {
    * @param entries - A record of tag path → value pairs
    */
   setBatch(entries) {
-    return new _DicomInstance(this.dicomDataset, this.changeSet.setBatch(entries), this.filepath, this.meta);
+    return this.derive({ changes: this.changeSet.setBatch(entries) });
   }
   /**
    * Returns a new DicomInstance with the given changes merged into pending changes.
@@ -31229,7 +32217,7 @@ var DicomInstance = class _DicomInstance {
    * @returns A new DicomInstance with accumulated changes
    */
   withChanges(changes) {
-    return new _DicomInstance(this.dicomDataset, this.changeSet.merge(changes), this.filepath, this.meta);
+    return this.derive({ changes: this.changeSet.merge(changes) });
   }
   /**
    * Returns a new DicomInstance pointing to a different file path.
@@ -31243,7 +32231,7 @@ var DicomInstance = class _DicomInstance {
   withFilePath(newPath) {
     const result = createDicomFilePath(newPath);
     if (!result.ok) throw result.error;
-    return new _DicomInstance(this.dicomDataset, this.changeSet, result.value, this.meta);
+    return this.derive({ filePath: result.value });
   }
   // -----------------------------------------------------------------------
   // File I/O
@@ -31281,7 +32269,7 @@ var DicomInstance = class _DicomInstance {
         return err(applyResult.error);
       }
     }
-    return ok(new _DicomInstance(this.dicomDataset, ChangeSet.empty(), outPathResult.value, this.meta));
+    return ok(this.derive({ changes: ChangeSet.empty(), filePath: outPathResult.value }));
   }
   /**
    * Gets the file size in bytes.
@@ -31316,7 +32304,7 @@ var DicomInstance = class _DicomInstance {
   withMetadata(key, value) {
     const newMeta = new Map(this.meta);
     newMeta.set(key, value);
-    return new _DicomInstance(this.dicomDataset, this.changeSet, this.filepath, newMeta);
+    return this.derive({ metadata: newMeta });
   }
   /**
    * Gets application metadata by key.