@cosyte/dicom 0.0.4 → 0.0.6

package/dist/index.cjs

@@ -11,7 +11,7 @@ var __export = (target, all) => {
 };
 
 // src/version.ts
-var VERSION = "0.0.4";
+var VERSION = "0.0.6";
 
 // src/dictionary/index.ts
 var dictionary_exports = {};
@@ -11574,6 +11574,13 @@ var ByteCursor = class {
   }
 };
 
+// src/parser/tokens.ts
+var WITHHELD = "<withheld>";
+function safePrivateCreator(creator, profile) {
+  if (profile === void 0) return WITHHELD;
+  return profile.privateDictionary.has(creator) ? creator : WITHHELD;
+}
+
 // src/dataset/vr/charset.ts
 var TERM_TO_LABEL = /* @__PURE__ */ new Map([
   // Default repertoire (ISO 646 IRV / ASCII). Latin-1 is a lenient,
@@ -11626,7 +11633,7 @@ var MULTIBYTE_LABELS = /* @__PURE__ */ new Set([
 ]);
 function parseSpecificCharacterSet(bytes) {
   const raw = bytes.toString("latin1");
-  return raw.split("\\").map((t) => t.replace(/[ ]+$/u, "").replace(/^[ ]+/u, ""));
+  return raw.split("\\").map((t) => t.replace(/[ ]+$/u, "").replace(/^[ ]+/u, "")).map((t) => t === "" || TERM_TO_LABEL.has(t) ? t : WITHHELD);
 }
 function isKnownCharsetTerm(term) {
   return TERM_TO_LABEL.has(term);
@@ -11655,6 +11662,48 @@ function decodeText(bytes, terms) {
   }
 }
 
+// src/parser/endian.ts
+var BE_VR_STRIDE = Object.freeze({
+  // 2-byte swaps
+  AT: 2,
+  US: 2,
+  SS: 2,
+  OW: 2,
+  // 4-byte swaps
+  UL: 4,
+  SL: 4,
+  FL: 4,
+  OF: 4,
+  OL: 4,
+  // 8-byte swaps (64-bit floats + 2018 64-bit integer additions)
+  FD: 8,
+  OD: 8,
+  OV: 8,
+  SV: 8,
+  UV: 8,
+  // No swap - byte streams (D-24) and ASCII / spec-defined VRs.
+  OB: 0,
+  UN: 0,
+  AE: 0,
+  AS: 0,
+  CS: 0,
+  DA: 0,
+  DS: 0,
+  DT: 0,
+  IS: 0,
+  LO: 0,
+  LT: 0,
+  PN: 0,
+  SH: 0,
+  ST: 0,
+  TM: 0,
+  UC: 0,
+  UI: 0,
+  UR: 0,
+  UT: 0,
+  SQ: 0
+});
+
 // src/parser/warnings.ts
 var WARNING_CODES = {
   // === Phase 2 actively emits (D-08 active list - alphabetical-within-prefix per CONTEXT specifics §) ===
@@ -11668,6 +11717,7 @@ var WARNING_CODES = {
   DICOM_ODD_LENGTH_VALUE_PADDED: "DICOM_ODD_LENGTH_VALUE_PADDED",
   DICOM_PIXEL_DATA_LENGTH_MISMATCH: "DICOM_PIXEL_DATA_LENGTH_MISMATCH",
   DICOM_PRIVATE_TAG_NO_CREATOR: "DICOM_PRIVATE_TAG_NO_CREATOR",
+  DICOM_SQ_NOT_DESCENDED: "DICOM_SQ_NOT_DESCENDED",
   DICOM_UN_PARSED_AS_SQ: "DICOM_UN_PARSED_AS_SQ",
   DICOM_UNDEFINED_LENGTH_IN_EXPLICIT_VR: "DICOM_UNDEFINED_LENGTH_IN_EXPLICIT_VR",
   DICOM_VR_MISMATCH: "DICOM_VR_MISMATCH",
@@ -11688,159 +11738,123 @@ var WARNING_CODES = {
   DICOM_PRIVATE_CREATOR_UNKNOWN: "DICOM_PRIVATE_CREATOR_UNKNOWN"
   // reserved by Phase 6 - not emitted in Phase 2
 };
+var WARNING_MESSAGES = Object.freeze({
+  DICOM_MISSING_PREAMBLE: "No DICM magic at offset 128; falling back to offset-0 dataset.",
+  DICOM_FILE_META_GROUP_LENGTH_MISSING: "(0002,0000) FileMetaInformationGroupLength missing; scanning forward to first non-(0002,xxxx) element.",
+  DICOM_FILE_META_GROUP_LENGTH_MISMATCH: "(0002,0000) FileMetaInformationGroupLength declared {n} bytes; actual File Meta group size is {n2} bytes. Trusting actual.",
+  DICOM_UNDEFINED_LENGTH_IN_EXPLICIT_VR: "Element ({tag}) uses undefined length (0xFFFFFFFF) under an Explicit VR transfer syntax.",
+  DICOM_ODD_LENGTH_VALUE_PADDED: "Element ({tag}) has odd declared length {n}; cursor advanced by one padding byte to maintain alignment.",
+  DICOM_VR_MISMATCH: "Element ({tag}) on-wire VR is {vr2}; dictionary lists {vr}. Trusting on-wire VR.",
+  DICOM_PRIVATE_TAG_NO_CREATOR: "Private element ({tag}) has no Private Creator registered for its block; treating as VR=UN.",
+  DICOM_GROUP_LENGTH_IN_DATASET: "Retired Group Length element ({tag}) encountered in dataset; preserved as-is.",
+  DICOM_NONZERO_RESERVED_BYTES: "Element ({tag}) has non-zero reserved bytes between VR and length (first byte {n}, second byte {n2}); ignoring.",
+  DICOM_SQ_NOT_DESCENDED: "Element ({tag}) resolved to VR=SQ from the dictionary but its defined-length value is not a valid item stream; kept as opaque bytes and NOT descended, so nothing nested inside it is visible to navigation or de-identification.",
+  DICOM_UN_PARSED_AS_SQ: "Element ({tag}) has VR=UN with undefined length; descended as Implicit VR LE sequence per CP-246.",
+  DICOM_EMPTY_ITEM_IN_SEQUENCE: "Sequence ({tag}) contains an empty item (length=0); tolerated.",
+  DICOM_PIXEL_DATA_LENGTH_MISMATCH: "(7FE0,0010) PixelData declared length {n} does not match computed {n2} bytes.",
+  DICOM_IMPLICIT_VR_FOR_PRIVATE_TAG_WITHOUT_VR: "Private element ({tag}) under Implicit VR LE has no VR override; falling back to UN.",
+  DICOM_PRIVATE_CREATOR_UNKNOWN: "Private element ({tag}) has a Private Creator the active profile's private dictionary does not name; falling back to UN. The creator string is not reproduced here - read the (gggg,00EE) element if you need it.",
+  DICOM_BURNED_IN_ANNOTATION_NOT_REMOVED: "Pixel Data is present and Burned In Annotation is not 'NO'; this metadata-only de-identifier cannot inspect or clean pixels. Recognizable text may remain burned into the image.",
+  DICOM_BOM_IN_TEXT_VR: "Element ({tag}) {vr} value begins with a UTF-8 BOM; stripped on decode.",
+  DICOM_TRAILING_NULL_IN_TEXT_VR: "Element ({tag}) {vr} value has a trailing NULL pad where SPACE is expected; trimmed.",
+  DICOM_UI_TRAILING_SPACE: "Element ({tag}) UI value is SPACE-padded; UI requires NULL padding (PS3.5 \xA76.2). Trimmed.",
+  DICOM_NON_ASCII_IN_ASCII_VR: "Element ({tag}) {vr} is an ASCII-only VR but contains non-ASCII bytes; decoded as Latin-1 best-effort.",
+  DICOM_IS_NONINTEGER_VALUE: "Element ({tag}) IS value is not a base-10 integer; surfaced as null with raw bytes preserved.",
+  DICOM_DA_LEGACY_FORMAT: "Element ({tag}) DA value is not in canonical YYYYMMDD form; decoded best-effort, raw preserved.",
+  DICOM_DT_NONSTANDARD_OFFSET: "Element ({tag}) DT value has a non-standard UTC offset; decoded best-effort, raw preserved.",
+  DICOM_UNSUPPORTED_CHARSET: "(0008,0005) Specific Character Set value {n} names a defined term this build does not support; decoding text as UTF-8 best-effort. The term is not reproduced here - read the element if you need it.",
+  DICOM_CHARSET_AMBIGUOUS_SEPARATOR: "(0008,0005) Specific Character Set value {n} is ambiguous under the active code extensions; decoding text as UTF-8 best-effort."
+});
+var KNOWN_VRS = new Set(Object.keys(BE_VR_STRIDE));
+var TAG_SHAPE = /^[0-9A-F]{8}$/u;
+function renderTag(tag) {
+  return tag !== void 0 && TAG_SHAPE.test(tag) ? tag : WITHHELD;
+}
+function renderVr(vr) {
+  return vr !== void 0 && KNOWN_VRS.has(vr) ? vr : WITHHELD;
+}
+function build(code, position, tokens = {}) {
+  const message = WARNING_MESSAGES[code].replace("{tag}", renderTag(tokens.tag)).replace("{vr2}", renderVr(tokens.vr2)).replace("{vr}", renderVr(tokens.vr)).replace("{n2}", String(tokens.n2 ?? 0)).replace("{n}", String(tokens.n ?? 0));
+  return { code, message, position };
+}
 function missingPreamble(position) {
-  return {
-    code: WARNING_CODES.DICOM_MISSING_PREAMBLE,
-    message: "No DICM magic at offset 128; falling back to offset-0 dataset.",
-    position
-  };
+  return build(WARNING_CODES.DICOM_MISSING_PREAMBLE, position);
 }
 function fileMetaGroupLengthMissing(position) {
-  return {
-    code: WARNING_CODES.DICOM_FILE_META_GROUP_LENGTH_MISSING,
-    message: "(0002,0000) FileMetaInformationGroupLength missing; scanning forward to first non-(0002,xxxx) element.",
-    position
-  };
+  return build(WARNING_CODES.DICOM_FILE_META_GROUP_LENGTH_MISSING, position);
 }
 function fileMetaGroupLengthMismatch(position, declared, actual) {
-  return {
-    code: WARNING_CODES.DICOM_FILE_META_GROUP_LENGTH_MISMATCH,
-    message: `(0002,0000) FileMetaInformationGroupLength declared ${String(declared)} bytes; actual File Meta group size is ${String(actual)} bytes. Trusting actual.`,
-    position
-  };
+  return build(WARNING_CODES.DICOM_FILE_META_GROUP_LENGTH_MISMATCH, position, {
+    n: declared,
+    n2: actual
+  });
 }
 function undefinedLengthInExplicitVR(position, tag) {
-  return {
-    code: WARNING_CODES.DICOM_UNDEFINED_LENGTH_IN_EXPLICIT_VR,
-    message: `Element (${tag}) uses undefined length (0xFFFFFFFF) under an Explicit VR transfer syntax.`,
-    position
-  };
+  return build(WARNING_CODES.DICOM_UNDEFINED_LENGTH_IN_EXPLICIT_VR, position, { tag });
 }
 function oddLengthValuePadded(position, tag, declaredLength) {
-  return {
-    code: WARNING_CODES.DICOM_ODD_LENGTH_VALUE_PADDED,
-    message: `Element (${tag}) has odd declared length ${String(declaredLength)}; cursor advanced by one padding byte to maintain alignment.`,
-    position
-  };
+  return build(WARNING_CODES.DICOM_ODD_LENGTH_VALUE_PADDED, position, {
+    tag,
+    n: declaredLength
+  });
 }
 function vrMismatch(position, tag, dictVR, fileVR) {
-  return {
-    code: WARNING_CODES.DICOM_VR_MISMATCH,
-    message: `Element (${tag}) on-wire VR is ${fileVR}; dictionary lists ${dictVR}. Trusting on-wire VR.`,
-    position
-  };
+  return build(WARNING_CODES.DICOM_VR_MISMATCH, position, { tag, vr: dictVR, vr2: fileVR });
 }
 function privateTagNoCreator(position, tag) {
-  return {
-    code: WARNING_CODES.DICOM_PRIVATE_TAG_NO_CREATOR,
-    message: `Private element (${tag}) has no Private Creator registered for its block; treating as VR=UN.`,
-    position
-  };
+  return build(WARNING_CODES.DICOM_PRIVATE_TAG_NO_CREATOR, position, { tag });
 }
 function groupLengthInDataset(position, tag) {
-  return {
-    code: WARNING_CODES.DICOM_GROUP_LENGTH_IN_DATASET,
-    message: `Retired Group Length element (${tag}) encountered in dataset; preserved as-is.`,
-    position
-  };
+  return build(WARNING_CODES.DICOM_GROUP_LENGTH_IN_DATASET, position, { tag });
 }
-function nonzeroReservedBytes(position, tag, observed) {
-  return {
-    code: WARNING_CODES.DICOM_NONZERO_RESERVED_BYTES,
-    message: `Element (${tag}) has non-zero reserved bytes (${observed}) between VR and length; ignoring.`,
-    position
-  };
+function nonzeroReservedBytes(position, tag, first, second) {
+  return build(WARNING_CODES.DICOM_NONZERO_RESERVED_BYTES, position, {
+    tag,
+    n: first,
+    n2: second
+  });
 }
 function unParsedAsSQ(position, tag) {
-  return {
-    code: WARNING_CODES.DICOM_UN_PARSED_AS_SQ,
-    message: `Element (${tag}) declared VR=UN with undefined length; descended as Implicit VR LE sequence per CP-246.`,
-    position
-  };
+  return build(WARNING_CODES.DICOM_UN_PARSED_AS_SQ, position, { tag });
+}
+function sqNotDescended(position, tag) {
+  return build(WARNING_CODES.DICOM_SQ_NOT_DESCENDED, position, { tag });
 }
 function emptyItemInSequence(position, tag) {
-  return {
-    code: WARNING_CODES.DICOM_EMPTY_ITEM_IN_SEQUENCE,
-    message: `Sequence (${tag}) contains an empty item (length=0); tolerated.`,
-    position
-  };
+  return build(WARNING_CODES.DICOM_EMPTY_ITEM_IN_SEQUENCE, position, { tag });
 }
 function implicitVRForPrivateTagWithoutVR(position, tag) {
-  return {
-    code: WARNING_CODES.DICOM_IMPLICIT_VR_FOR_PRIVATE_TAG_WITHOUT_VR,
-    message: `Private element (${tag}) under Implicit VR LE has no VR override; falling back to UN.`,
-    position
-  };
+  return build(WARNING_CODES.DICOM_IMPLICIT_VR_FOR_PRIVATE_TAG_WITHOUT_VR, position, { tag });
 }
-function privateCreatorUnknown(position, tag, creator) {
-  return {
-    code: WARNING_CODES.DICOM_PRIVATE_CREATOR_UNKNOWN,
-    message: `Private element (${tag}) creator "${creator}" is not in the active profile's private dictionary; falling back to UN.`,
-    position
-  };
+function privateCreatorUnknown(position, tag) {
+  return build(WARNING_CODES.DICOM_PRIVATE_CREATOR_UNKNOWN, position, { tag });
 }
 function burnedInAnnotationNotRemoved(position) {
-  return {
-    code: WARNING_CODES.DICOM_BURNED_IN_ANNOTATION_NOT_REMOVED,
-    message: "Pixel Data is present and Burned In Annotation is not 'NO'; this metadata-only de-identifier cannot inspect or clean pixels. Recognizable text may remain burned into the image.",
-    position
-  };
+  return build(WARNING_CODES.DICOM_BURNED_IN_ANNOTATION_NOT_REMOVED, position);
 }
 function bomInTextVR(position, tag, vr) {
-  return {
-    code: WARNING_CODES.DICOM_BOM_IN_TEXT_VR,
-    message: `Element (${tag}) ${vr} value begins with a UTF-8 BOM; stripped on decode.`,
-    position
-  };
+  return build(WARNING_CODES.DICOM_BOM_IN_TEXT_VR, position, { tag, vr });
 }
 function trailingNullInTextVR(position, tag, vr) {
-  return {
-    code: WARNING_CODES.DICOM_TRAILING_NULL_IN_TEXT_VR,
-    message: `Element (${tag}) ${vr} value has a trailing NULL pad where SPACE is expected; trimmed.`,
-    position
-  };
+  return build(WARNING_CODES.DICOM_TRAILING_NULL_IN_TEXT_VR, position, { tag, vr });
 }
 function uiTrailingSpace(position, tag) {
-  return {
-    code: WARNING_CODES.DICOM_UI_TRAILING_SPACE,
-    message: `Element (${tag}) UI value is SPACE-padded; UI requires NULL padding (PS3.5 \xA76.2). Trimmed.`,
-    position
-  };
+  return build(WARNING_CODES.DICOM_UI_TRAILING_SPACE, position, { tag });
 }
 function nonAsciiInAsciiVR(position, tag, vr) {
-  return {
-    code: WARNING_CODES.DICOM_NON_ASCII_IN_ASCII_VR,
-    message: `Element (${tag}) ${vr} is an ASCII-only VR but contains non-ASCII bytes; decoded as Latin-1 best-effort.`,
-    position
-  };
+  return build(WARNING_CODES.DICOM_NON_ASCII_IN_ASCII_VR, position, { tag, vr });
 }
 function isNonintegerValue(position, tag) {
-  return {
-    code: WARNING_CODES.DICOM_IS_NONINTEGER_VALUE,
-    message: `Element (${tag}) IS value is not a base-10 integer; surfaced as null with raw bytes preserved.`,
-    position
-  };
+  return build(WARNING_CODES.DICOM_IS_NONINTEGER_VALUE, position, { tag });
 }
 function daLegacyFormat(position, tag) {
-  return {
-    code: WARNING_CODES.DICOM_DA_LEGACY_FORMAT,
-    message: `Element (${tag}) DA value is not in canonical YYYYMMDD form; decoded best-effort, raw preserved.`,
-    position
-  };
+  return build(WARNING_CODES.DICOM_DA_LEGACY_FORMAT, position, { tag });
 }
 function dtNonstandardOffset(position, tag) {
-  return {
-    code: WARNING_CODES.DICOM_DT_NONSTANDARD_OFFSET,
-    message: `Element (${tag}) DT value has a non-standard UTC offset; decoded best-effort, raw preserved.`,
-    position
-  };
+  return build(WARNING_CODES.DICOM_DT_NONSTANDARD_OFFSET, position, { tag });
 }
-function unsupportedCharset(position, term) {
-  return {
-    code: WARNING_CODES.DICOM_UNSUPPORTED_CHARSET,
-    message: `Specific Character Set term "${term}" is not supported; decoding text as UTF-8 best-effort.`,
-    position
-  };
+function unsupportedCharset(position, valueIndex) {
+  return build(WARNING_CODES.DICOM_UNSUPPORTED_CHARSET, position, { n: valueIndex });
 }
 
 // src/profiles/lookup.ts
@@ -11860,9 +11874,9 @@ var SPECIFIC_CHARACTER_SET_TAG = "00080005";
 function applySpecificCharacterSet(tag, value, ctx, emit, position) {
   if (tag !== SPECIFIC_CHARACTER_SET_TAG) return;
   const terms = parseSpecificCharacterSet(value);
-  for (const term of terms) {
-    if (!isKnownCharsetTerm(term)) emit(unsupportedCharset(position, term));
-  }
+  terms.forEach((term, index) => {
+    if (!isKnownCharsetTerm(term)) emit(unsupportedCharset(position, index + 1));
+  });
   ctx.currentCharset = terms;
 }
 var LONG_FORM_VRS = /* @__PURE__ */ new Set([
@@ -11898,7 +11912,7 @@ function resolveImplicitVR(tag, ctx, emit, position) {
       const def = resolvePrivateTag(ctx.profile, tag, creator);
       if (def !== void 0) return def.vr;
       if (!ctx.profile.privateDictionary.has(creator)) {
-        emit(privateCreatorUnknown(position, tag, creator));
+        emit(privateCreatorUnknown(position, tag));
       }
     }
     emit(implicitVRForPrivateTagWithoutVR(position, tag));
@@ -11923,6 +11937,9 @@ function resolvePrivateCreator(tag, ctx) {
   if (blockId < 16 || blockId > 255) return void 0;
   return ctx.creators.get(group)?.get(blockId);
 }
+function safeModelCreator(creator, ctx) {
+  return creator === void 0 ? void 0 : safePrivateCreator(creator, ctx.profile);
+}
 function registerPrivateCreator(tag, value, ctx) {
   const group = parseInt(tag.slice(0, 4), 16);
   if (group % 2 === 0) return;
@@ -11982,8 +11999,7 @@ function readExplicitElementHeader(cursor, _ctx, emit) {
     const reserved1 = cursor.buffer[cursor.position + 1];
     cursor.position += 2;
     if ((reserved0 ?? 0) !== 0 || (reserved1 ?? 0) !== 0) {
-      const observed = (reserved0 ?? 0).toString(16).padStart(2, "0") + (reserved1 ?? 0).toString(16).padStart(2, "0");
-      emit(nonzeroReservedBytes({ byteOffset: headerStart }, tag, observed));
+      emit(nonzeroReservedBytes({ byteOffset: headerStart }, tag, reserved0 ?? 0, reserved1 ?? 0));
     }
     length = cursor.readUInt32();
     headerLength = 12;
@@ -12619,6 +12635,13 @@ function parseSequence(buffer, valueStart, ctx, emit, opts) {
       ctx.currentCharset = parentCharset;
     }
   };
+  const parentCreators = ctx.creators;
+  const restoreParentCreators = () => {
+    ctx.creators = parentCreators;
+  };
+  const beginItemCreatorScope = () => {
+    ctx.creators = /* @__PURE__ */ new Map();
+  };
   try {
     const cursor = new ByteCursor(buffer, opts.littleEndian, valueStart);
     const items = [];
@@ -12683,6 +12706,7 @@ function parseSequence(buffer, valueStart, ctx, emit, opts) {
         continue;
       }
       restoreParentCharset();
+      beginItemCreatorScope();
       if (itemLength === UNDEFINED_LENGTH) {
         const inner = opts.innerStrategy(buffer, cursor.position, ctx, emit, {
           stopOnItemDelim: true
@@ -12710,9 +12734,39 @@ function parseSequence(buffer, valueStart, ctx, emit, opts) {
     ctx.nestingDepth -= 1;
     ctx.encodingContextStack.pop();
     restoreParentCharset();
+    restoreParentCreators();
   }
 }
-function tryParseUnAsSQ(buffer, valueStart, valueLength, ctx, emit, implicitLeInner) {
+function isStrictEscalation(err) {
+  if (!(err instanceof DicomParseError)) return false;
+  return Object.values(WARNING_CODES).includes(err.code);
+}
+function tryParseDefinedLengthSQ(buffer, valueStart, valueLength, ctx, emit, implicitLeInner, tag) {
+  const savedDepth = ctx.nestingDepth;
+  const savedStackLen = ctx.encodingContextStack.length;
+  const savedWarningsLen = ctx.warnings.length;
+  try {
+    const slice = buffer.subarray(valueStart, valueStart + valueLength);
+    const result = parseSequence(slice, 0, ctx, emit, {
+      explicitLength: valueLength,
+      littleEndian: true,
+      innerStrategy: implicitLeInner
+    });
+    return { success: true, items: result.items };
+  } catch (err) {
+    if (isStrictEscalation(err)) throw err;
+    ctx.nestingDepth = savedDepth;
+    while (ctx.encodingContextStack.length > savedStackLen) {
+      ctx.encodingContextStack.pop();
+    }
+    while (ctx.warnings.length > savedWarningsLen) {
+      ctx.warnings.pop();
+    }
+    emit(sqNotDescended({ byteOffset: valueStart }, tag));
+    return { success: false, items: [] };
+  }
+}
+function tryParseUnAsSQ(buffer, valueStart, valueLength, ctx, emit, implicitLeInner, tag) {
   const savedDepth = ctx.nestingDepth;
   const savedStackLen = ctx.encodingContextStack.length;
   const savedWarningsLen = ctx.warnings.length;
@@ -12725,18 +12779,15 @@ function tryParseUnAsSQ(buffer, valueStart, valueLength, ctx, emit, implicitLeIn
       innerStrategy: implicitLeInner
     };
     const result = parseSequence(slice, 0, ctx, emit, opts);
-    emit(unParsedAsSQ({ byteOffset: valueStart }, "UN"));
+    emit(unParsedAsSQ({ byteOffset: valueStart }, tag));
     return {
       success: true,
       items: result.items,
       endOffset: valueStart + result.endOffset
     };
   } catch (err) {
-    if (err instanceof DicomParseError) {
-      const warningCodeValues = Object.values(WARNING_CODES);
-      if (warningCodeValues.includes(err.code)) {
-        throw err;
-      }
+    if (isStrictEscalation(err)) {
+      throw err;
     }
     ctx.nestingDepth = savedDepth;
     while (ctx.encodingContextStack.length > savedStackLen) {
@@ -12797,7 +12848,7 @@ function parseImplicitLE(buffer, datasetStart, ctx, emit, opts = {}) {
         const valueRawStart = headerStart;
         cursor.position = seq.endOffset;
         const rawBytes = ctx.copyValues ? copyValueBytes(buffer.subarray(valueRawStart, cursor.position)) : buffer.subarray(valueRawStart, cursor.position);
-        const privateCreator2 = resolvePrivateCreator(tag, ctx);
+        const privateCreator2 = safeModelCreator(resolvePrivateCreator(tag, ctx), ctx);
         elements.set(
           tag,
           new Element({
@@ -12814,6 +12865,40 @@ function parseImplicitLE(buffer, datasetStart, ctx, emit, opts = {}) {
         );
         continue;
       }
+      if (vr === "UN") {
+        const cp246 = tryParseUnAsSQ(
+          buffer,
+          cursor.position,
+          4294967295,
+          ctx,
+          emit,
+          parseImplicitLE,
+          tag
+        );
+        if (cp246.success) {
+          const valueRawStart = headerStart;
+          cursor.position = cp246.endOffset;
+          const rawBytes = ctx.copyValues ? copyValueBytes(buffer.subarray(valueRawStart, cursor.position)) : buffer.subarray(valueRawStart, cursor.position);
+          const privateCreator2 = safeModelCreator(resolvePrivateCreator(tag, ctx), ctx);
+          elements.set(
+            tag,
+            new Element({
+              tag,
+              vr: "SQ",
+              // Promoted, exactly as the Explicit-VR path promotes it.
+              vm: cp246.items.length,
+              length: 4294967295,
+              rawBytes,
+              byteOffset: headerStart,
+              cp246Promoted: true,
+              littleEndian: true,
+              items: cp246.items,
+              ...privateCreator2 !== void 0 ? { privateCreator: privateCreator2 } : {}
+            })
+          );
+          continue;
+        }
+      }
       throw new DicomParseError(
         FATAL_CODES.INVALID_FILE_META,
         `Undefined length on non-SQ element ${tag} (vr=${vr}) under Implicit VR LE.`,
@@ -12833,6 +12918,35 @@ function parseImplicitLE(buffer, datasetStart, ctx, emit, opts = {}) {
     const valueEnd = valueStart + length;
     const valueSlice = ctx.copyValues ? copyValueBytes(buffer.subarray(valueStart, valueEnd)) : buffer.subarray(valueStart, valueEnd);
     cursor.position = valueEnd;
+    if (vr === "SQ") {
+      const seq = tryParseDefinedLengthSQ(
+        buffer,
+        valueStart,
+        length,
+        ctx,
+        emit,
+        parseImplicitLE,
+        tag
+      );
+      if (seq.success) {
+        const privateCreator2 = safeModelCreator(resolvePrivateCreator(tag, ctx), ctx);
+        elements.set(
+          tag,
+          new Element({
+            tag,
+            vr,
+            vm: seq.items.length,
+            length,
+            rawBytes: valueSlice,
+            byteOffset: headerStart,
+            littleEndian: true,
+            items: seq.items,
+            ...privateCreator2 !== void 0 ? { privateCreator: privateCreator2 } : {}
+          })
+        );
+        continue;
+      }
+    }
     if (element === 0 && group !== 2) {
       emit(groupLengthInDataset(position, tag));
     }
@@ -12840,7 +12954,7 @@ function parseImplicitLE(buffer, datasetStart, ctx, emit, opts = {}) {
       registerPrivateCreator(tag, valueSlice, ctx);
     }
     applySpecificCharacterSet(tag, valueSlice, ctx, emit, position);
-    const privateCreator = resolvePrivateCreator(tag, ctx);
+    const privateCreator = safeModelCreator(resolvePrivateCreator(tag, ctx), ctx);
     elements.set(
       tag,
       new Element({
@@ -12960,7 +13074,7 @@ function _parseExplicit(buffer, datasetStart, ctx, emit, mode, opts = {}) {
       }
       cursor.position = seqResult.endOffset;
       const rawBytes = ctx.copyValues ? copyValueBytes(buffer.subarray(headerStart, cursor.position)) : buffer.subarray(headerStart, cursor.position);
-      const privateCreator2 = resolvePrivateCreator(tag, ctx);
+      const privateCreator2 = safeModelCreator(resolvePrivateCreator(tag, ctx), ctx);
       elements.set(
         tag,
         new Element({
@@ -13012,12 +13126,13 @@ function _parseExplicit(buffer, datasetStart, ctx, emit, mode, opts = {}) {
         UNDEFINED_LENGTH2,
         ctx,
         emit,
-        parseImplicitLE
+        parseImplicitLE,
+        tag
       );
       if (cp246.success) {
         cursor.position = cp246.endOffset;
         const rawBytes = ctx.copyValues ? copyValueBytes(buffer.subarray(headerStart, cursor.position)) : buffer.subarray(headerStart, cursor.position);
-        const privateCreator3 = resolvePrivateCreator(tag, ctx);
+        const privateCreator3 = safeModelCreator(resolvePrivateCreator(tag, ctx), ctx);
         elements.set(
           tag,
           new Element({
@@ -13036,7 +13151,7 @@ function _parseExplicit(buffer, datasetStart, ctx, emit, mode, opts = {}) {
         );
         continue;
       }
-      const privateCreator2 = resolvePrivateCreator(tag, ctx);
+      const privateCreator2 = safeModelCreator(resolvePrivateCreator(tag, ctx), ctx);
       const fallbackEnd = buffer.length;
       const fallbackBytes = ctx.copyValues ? copyValueBytes(buffer.subarray(headerStart, fallbackEnd)) : buffer.subarray(headerStart, fallbackEnd);
       elements.set(
@@ -13083,7 +13198,7 @@ function _parseExplicit(buffer, datasetStart, ctx, emit, mode, opts = {}) {
       registerPrivateCreator(tag, valueSlice, ctx);
     }
     applySpecificCharacterSet(tag, valueSlice, ctx, emit, position);
-    const privateCreator = resolvePrivateCreator(tag, ctx);
+    const privateCreator = safeModelCreator(resolvePrivateCreator(tag, ctx), ctx);
     const finalVr = vr;
     elements.set(
       tag,
@@ -13136,20 +13251,22 @@ function parseDeflatedLEWithCap(buffer, datasetStart, ctx, emit, maxInflatedByte
         buildSnippet(buffer, datasetStart)
       );
     }
+    const zlibCode = typeof code === "string" && code.length > 0 ? code : "unknown";
     throw new DicomParseError(
       FATAL_CODES.INVALID_FILE_META,
-      `Failed to inflate Deflated TS payload: ${message}`,
+      `Failed to inflate Deflated TS payload (zlib error code: ${zlibCode}).`,
       datasetStart,
       buildSnippet(buffer, datasetStart)
     );
   }
   const innerCtx = { ...ctx, buffer: inflated };
+  const innerChokepoint = makeEmitter(innerCtx);
   const innerEmit = (w) => {
     const wrapped = {
       ...w,
       position: { ...w.position, deflated: true }
     };
-    emit(wrapped);
+    innerChokepoint(wrapped);
   };
   const result = parseExplicitLE(inflated, 0, innerCtx, innerEmit);
   return { elements: result.elements, endOffset: buffer.length };
@@ -13176,6 +13293,7 @@ var TRANSFER_SYNTAX_PARSERS = Object.freeze({
 });
 
 // src/parser/index.ts
+var SUPPORTED_TRANSFER_SYNTAXES = Object.keys(TRANSFER_SYNTAX_PARSERS).join(", ");
 function parseDicom(input, options = {}) {
   if (rawInputIsEmpty(input)) {
     throw new DicomParseError(FATAL_CODES.EMPTY_INPUT, "Input is empty.", 0, "");
@@ -13198,9 +13316,10 @@ function parseDicom(input, options = {}) {
   const strategy = TRANSFER_SYNTAX_PARSERS[tsUid];
   if (strategy === void 0) {
     const tsName = uid(tsUid)?.name ?? "";
+    const named = tsName.length > 0 ? `Transfer Syntax ${tsName}` : "The Transfer Syntax UID";
     throw new DicomParseError(
       FATAL_CODES.UNSUPPORTED_TRANSFER_SYNTAX,
-      `Transfer Syntax UID "${tsUid}" is not supported by @cosyte/dicom v1.`,
+      `${named} in (0002,0010) is not supported by @cosyte/dicom v1 (supported: ${SUPPORTED_TRANSFER_SYNTAXES}).`,
       fileMetaEnd,
       tsName.length > 0 ? tsName : buildSnippet(buffer, fileMetaEnd)
     );
@@ -13438,7 +13557,7 @@ function serializeDicom(ds) {
   if (encoding === void 0) {
     throw new DicomSerializeError(
       SERIALIZE_ERROR_CODES.UNSUPPORTED_TRANSFER_SYNTAX,
-      `Transfer Syntax UID "${tsUid}" is not supported by the @cosyte/dicom v1 writer.`
+      `The Dataset's File Meta Transfer Syntax UID is not supported by the @cosyte/dicom v1 writer (supported: ${Object.keys(BODY_ENCODING).join(", ")}).`
     );
   }
   const preamble = part10Preamble();
@@ -14721,12 +14840,25 @@ function isPrivateCreatorElement(tag) {
   const { element } = splitTag(tag);
   return element >= 16 && element <= 255;
 }
-function keepsPrivate(el, ctx) {
+function creatorsInScope(source) {
+  const byBlock = /* @__PURE__ */ new Map();
+  for (const el of source) {
+    if (!isPrivateTag(el.tag) || !isPrivateCreatorElement(el.tag)) continue;
+    const { group, element } = splitTag(el.tag);
+    byBlock.set(`${String(group)}:${String(element & 255)}`, decodeCreator(el));
+  }
+  return byBlock;
+}
+function creatorFor(tag, creators) {
+  const { group, element } = splitTag(tag);
+  return creators.get(`${String(group)}:${String(element >> 8 & 255)}`);
+}
+function keepsPrivate(el, ctx, creators) {
   if (!ctx.active.has("RetainSafePrivate") || ctx.profile === void 0) return false;
   if (isPrivateCreatorElement(el.tag)) {
     return ctx.profile.privateDictionary.has(decodeCreator(el));
   }
-  const creator = el.privateCreator;
+  const creator = creatorFor(el.tag, creators);
   if (creator === void 0) return false;
   return resolvePrivateTag(ctx.profile, el.tag, creator) !== void 0;
 }
@@ -14736,9 +14868,10 @@ function processElements(source, ctx, contextPath) {
     attributes: [],
     removedPrivateTags: []
   };
+  const creators = creatorsInScope(source);
   for (const el of source) {
     if (isPrivateTag(el.tag)) {
-      if (keepsPrivate(el, ctx)) out.elements.set(el.tag, el);
+      if (keepsPrivate(el, ctx, creators)) out.elements.set(el.tag, el);
       else out.removedPrivateTags.push(el.tag);
       continue;
     }