dicom-synth 1.16.0 → 1.17.0

package/dist/esm/collection/writer.js

@@ -56,6 +56,9 @@ function isImageType(type) {
   return TYPE_CAPABILITIES[type].image;
 }
 var HEX_TAG_RE = /^[0-9a-fA-F]{8}$/;
+function isRawTagValue(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) && typeof value.vr === "string";
+}
 function positionalName(prefix, ordinal) {
   return `${prefix}-${String(ordinal).padStart(3, "0")}`;
 }
@@ -148,27 +151,50 @@ function buildTagToKeyword() {
   return map;
 }
 var tagToKeyword = buildTagToKeyword();
+function toRawElement(raw) {
+  const value = raw.vr === "SQ" ? raw.value.map(
+    (item) => Object.fromEntries(
+      Object.entries(item).map(([tag, nested]) => [
+        tag.toUpperCase(),
+        toRawElement(nested)
+      ])
+    )
+  ) : raw.value;
+  return { vr: raw.vr, Value: Array.isArray(value) ? value : [value] };
+}
 function applyTagOverrides(dataset, tags) {
-  if (!tags) return;
+  if (!tags) return void 0;
+  let raw;
   for (const [key, value] of Object.entries(tags)) {
-    if (HEX_TAG_RE.test(key)) {
+    if (isRawTagValue(value)) {
+      raw ?? (raw = {});
+      raw[key.toUpperCase()] = toRawElement(value);
+    } else if (HEX_TAG_RE.test(key)) {
       const keyword = tagToKeyword.get(key.toUpperCase());
-      if (keyword) {
-        dataset[keyword] = value;
-      } else {
-        console.warn(`dicom-synth: unknown hex tag "${key}" \u2014 skipping`);
+      if (!keyword) {
+        throw new Error(
+          `dicom-synth: unknown hex tag "${key}" \u2014 dictionary tags take plain values; private/unknown tags require the raw { vr, value } form`
+        );
       }
+      dataset[keyword] = value;
     } else {
       dataset[key] = value;
     }
   }
+  return raw;
 }
-function syncMetaWithDataset(meta, dataset) {
-  if (typeof dataset.SOPInstanceUID === "string") {
-    meta.MediaStorageSOPInstanceUID = dataset.SOPInstanceUID;
+function rawScalarString(rawElements, tag) {
+  const value = rawElements?.[tag]?.Value;
+  return value?.length === 1 && typeof value[0] === "string" ? value[0] : void 0;
+}
+function syncMetaWithDataset(meta, dataset, rawElements) {
+  const sopInstance = rawScalarString(rawElements, "00080018") ?? (typeof dataset.SOPInstanceUID === "string" ? dataset.SOPInstanceUID : void 0);
+  if (sopInstance !== void 0) {
+    meta.MediaStorageSOPInstanceUID = sopInstance;
   }
-  if (typeof dataset.SOPClassUID === "string") {
-    meta.MediaStorageSOPClassUID = dataset.SOPClassUID;
+  const sopClass = rawScalarString(rawElements, "00080016") ?? (typeof dataset.SOPClassUID === "string" ? dataset.SOPClassUID : void 0);
+  if (sopClass !== void 0) {
+    meta.MediaStorageSOPClassUID = sopClass;
   }
 }
 function buildMeta(uid, modality, transferSyntax = "explicit-vr-little-endian") {
@@ -208,7 +234,7 @@ function buildBaseImageDataset(uid, modality) {
     ...preset.attributes
   };
 }
-function serializeDict(meta, dataset) {
+function serializeDict(meta, dataset, rawElements) {
   const dicomDict = new dcmjs.data.DicomDict(
     dcmjs.data.DicomMetaDictionary.denaturalizeDataset(
       meta
@@ -217,14 +243,17 @@ function serializeDict(meta, dataset) {
   dicomDict.dict = dcmjs.data.DicomMetaDictionary.denaturalizeDataset(
     dataset
   );
+  if (rawElements) {
+    Object.assign(dicomDict.dict, rawElements);
+  }
   return Buffer.from(dicomDict.write({ allowInvalidVRLength: true }));
 }
 var MAX_DIMENSION = 65535;
-function applySizing(dataset, meta, spec) {
+function applySizing(dataset, meta, spec, rawElements) {
   if (spec.targetSizeKb !== void 0) {
     const clampDim = (n) => Math.min(MAX_DIMENSION, Math.max(1, Math.round(n)));
     const minimalPixelBytes = dataset.PixelData.byteLength;
-    const overhead = serializeDict(meta, dataset).length - minimalPixelBytes;
+    const overhead = serializeDict(meta, dataset, rawElements).length - minimalPixelBytes;
     const cells = Math.max(
       1,
       Math.round((spec.targetSizeKb * 1024 - overhead) / 2)
@@ -255,11 +284,11 @@ function buildImageBuffer(spec, uid) {
     dataset.Laterality = "";
     dataset.PatientWeight = "0";
   }
-  applyTagOverrides(dataset, spec.tags);
+  const rawElements = applyTagOverrides(dataset, spec.tags);
   const meta = buildMeta(effectiveUid, modality, spec.transferSyntax);
-  syncMetaWithDataset(meta, dataset);
-  applySizing(dataset, meta, spec);
-  return serializeDict(meta, dataset);
+  syncMetaWithDataset(meta, dataset, rawElements);
+  applySizing(dataset, meta, spec, rawElements);
+  return { buffer: serializeDict(meta, dataset, rawElements), rawElements };
 }
 function buildFakeSignatureBuffer() {
   const buf = Buffer.alloc(200, 0);
@@ -281,11 +310,11 @@ function buildBufferForSpec(spec, uid) {
     case "vendor-warnings-image":
       return buildImageBuffer(spec, uid);
     case "fake-signature":
-      return buildFakeSignatureBuffer();
+      return { buffer: buildFakeSignatureBuffer() };
     case "non-dicom":
-      return buildNonDicomBuffer(spec);
+      return { buffer: buildNonDicomBuffer(spec) };
     case "dicomdir":
-      return buildDicomdirBuffer();
+      return { buffer: buildDicomdirBuffer() };
     case "large-image":
       throw new Error(
         "large-image cannot be generated in memory \u2014 use writeCollectionFromSpec (disk-only streaming)"
@@ -366,12 +395,12 @@ function writeNative(outPath, params, dims, zeroChunk) {
   const { modality, uid, tags } = params;
   const meta = buildMeta(uid, modality);
   const dataset = buildBaseImageDataset(uid, modality);
-  applyTagOverrides(dataset, tags);
-  syncMetaWithDataset(meta, dataset);
+  const rawElements = applyTagOverrides(dataset, tags);
+  syncMetaWithDataset(meta, dataset, rawElements);
   dataset.Rows = dims.rows;
   dataset.Columns = dims.columns;
   const minimalPixelBytes = dataset.PixelData.byteLength;
-  const probe = serializeDict(meta, dataset);
+  const probe = serializeDict(meta, dataset, rawElements);
   const pixelElement = Buffer.alloc(12);
   PIXEL_DATA_OW_HEADER.copy(pixelElement);
   pixelElement.writeUInt32LE(minimalPixelBytes, 8);
@@ -400,11 +429,11 @@ function writeEncapsulated(outPath, params, pixelBytes, fragmentBytes, zeroChunk
     TransferSyntaxUID: RLE_TRANSFER_SYNTAX_UID
   };
   const dataset = buildBaseImageDataset(uid, modality);
-  applyTagOverrides(dataset, tags);
-  syncMetaWithDataset(meta, dataset);
+  const rawElements = applyTagOverrides(dataset, tags);
+  syncMetaWithDataset(meta, dataset, rawElements);
   dataset.PixelData = [new Uint8Array([]).buffer, new Uint8Array([0, 0]).buffer];
   dataset._vrMap = { PixelData: "OB" };
-  const probe = serializeDict(meta, dataset);
+  const probe = serializeDict(meta, dataset, rawElements);
   const idx = probe.indexOf(PIXEL_DATA_OB_HEADER);
   if (idx < 0 || probe.readUInt32LE(idx + 8) !== 4294967295) {
     throw new Error("failed to locate encapsulated PixelData element header");
@@ -501,7 +530,7 @@ var VIOLATION_LEVEL = {
   "missing-meta-header": "byte",
   "malformed-sq-delimiter": "byte"
 };
-function applyTagLevel(buffer, violations) {
+function applyTagLevel(buffer, violations, rawElements) {
   if (violations.length === 0) return buffer;
   let parsed;
   try {
@@ -535,6 +564,9 @@ function applyTagLevel(buffer, violations) {
     }
   }
   parsed.dict = dcmjsAny.data.DicomMetaDictionary.denaturalizeDataset(natural);
+  if (rawElements) {
+    Object.assign(parsed.dict, rawElements);
+  }
   if (violations.includes("uid-too-long")) {
     ;
     parsed.dict["00080018"] = {
@@ -567,11 +599,14 @@ function applyByteLevel(buffer, violations) {
   }
   return result;
 }
-function applyViolations(buffer, violations) {
+function applyViolations(buffer, violations, rawElements) {
   if (violations.length === 0) return buffer;
   const tagViolations = violations.filter((v) => VIOLATION_LEVEL[v] === "tag");
   const byteViolations = violations.filter((v) => VIOLATION_LEVEL[v] === "byte");
-  return applyByteLevel(applyTagLevel(buffer, tagViolations), byteViolations);
+  return applyByteLevel(
+    applyTagLevel(buffer, tagViolations, rawElements),
+    byteViolations
+  );
 }
 
 // src/collection/writer.ts
@@ -645,10 +680,11 @@ async function generateFile(spec, options) {
     ...spec,
     tags: resolveTagTemplates(spec.tags, { index, ...options?.context })
   } : spec;
-  let buffer = buildBufferForSpec(resolvedSpec, uid);
+  const built = buildBufferForSpec(resolvedSpec, uid);
+  let buffer = built.buffer;
   const violations = "violations" in spec ? spec.violations : void 0;
   if (violations?.length) {
-    buffer = applyViolations(buffer, violations);
+    buffer = applyViolations(buffer, violations, built.rawElements);
   }
   const name = filename(spec.type, index, padWidth);
   return {

package/dist/esm/describe/describe.js

@@ -92,6 +92,92 @@ var VALID_VIOLATIONS = {
 };
 var HEX_TAG_RE = /^[0-9a-fA-F]{8}$/;
 var KEYWORD_RE = /^[A-Z][A-Za-z0-9]*$/;
+var VALID_VRS = /* @__PURE__ */ new Set([
+  "AE",
+  "AS",
+  "AT",
+  "CS",
+  "DA",
+  "DS",
+  "DT",
+  "FL",
+  "FD",
+  "IS",
+  "LO",
+  "LT",
+  "OB",
+  "OD",
+  "OF",
+  "OL",
+  "OV",
+  "OW",
+  "PN",
+  "SH",
+  "SL",
+  "SQ",
+  "SS",
+  "ST",
+  "SV",
+  "TM",
+  "UC",
+  "UI",
+  "UL",
+  "UN",
+  "UR",
+  "US",
+  "UT",
+  "UV"
+]);
+function isPrivateHexTag(key) {
+  return HEX_TAG_RE.test(key) && Number.parseInt(key.slice(0, 4), 16) % 2 === 1;
+}
+function isRawTagValue(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) && typeof value.vr === "string";
+}
+function validateRawTagValue(raw, path) {
+  for (const key of Object.keys(raw)) {
+    if (key !== "vr" && key !== "value") {
+      throw new Error(
+        `${path}: raw tag form accepts only "vr" and "value"; got "${key}"`
+      );
+    }
+  }
+  const vr = raw.vr;
+  if (!VALID_VRS.has(vr)) {
+    throw new Error(`${path}.vr: "${vr}" is not a standard DICOM VR`);
+  }
+  if (!("value" in raw)) {
+    throw new Error(`${path}.value: is required in the raw tag form`);
+  }
+  if (vr === "SQ") {
+    if (!Array.isArray(raw.value)) {
+      throw new Error(`${path}.value: an SQ raw tag requires an array of items`);
+    }
+    raw.value.forEach((item, i) => {
+      if (typeof item !== "object" || item === null || Array.isArray(item)) {
+        throw new Error(
+          `${path}.value[${i}]: must be an object of hex-tag entries`
+        );
+      }
+      for (const [tag, nested] of Object.entries(item)) {
+        if (!HEX_TAG_RE.test(tag)) {
+          throw new Error(
+            `${path}.value[${i}]: invalid item tag "${tag}" \u2014 SQ items use 8-hex-char tags`
+          );
+        }
+        if (!isRawTagValue(nested)) {
+          throw new Error(
+            `${path}.value[${i}].${tag}: SQ item entries must use the raw { vr, value } form`
+          );
+        }
+        validateRawTagValue(
+          nested,
+          `${path}.value[${i}].${tag}`
+        );
+      }
+    });
+  }
+}
 function validatePositiveInt(value, path) {
   if (typeof value !== "number" || !Number.isInteger(value) || value < 1) {
     throw new Error(
@@ -289,13 +375,33 @@ function validateEntry(entry, path) {
   return e;
 }
 var MODALITY_TAG = "00080060";
-function validateTagValue(key, value, path) {
+function validateModalityGuard(key, candidate, path) {
   const isModalityKey = key === "Modality" || key.toUpperCase() === MODALITY_TAG;
-  if (isModalityKey && typeof value === "string" && Object.hasOwn(VALID_MODALITIES, value)) {
+  if (isModalityKey && typeof candidate === "string" && Object.hasOwn(VALID_MODALITIES, candidate)) {
     throw new Error(
       `${path}.${key}: set a preset modality (${Object.keys(VALID_MODALITIES).join("/")}) via the "modality" field, not tags \u2014 it is coupled to SOPClassUID and type-1 attributes`
     );
   }
+}
+function validateTagValue(key, value, path) {
+  if (isRawTagValue(value)) {
+    if (!HEX_TAG_RE.test(key)) {
+      throw new Error(
+        `${path}.${key}: the raw { vr, value } form requires an 8-hex-char tag key \u2014 keyword tags take plain values`
+      );
+    }
+    validateRawTagValue(value, `${path}.${key}`);
+    const raw = value.value;
+    const scalar = Array.isArray(raw) && raw.length === 1 ? raw[0] : raw;
+    validateModalityGuard(key, scalar, path);
+    return;
+  }
+  if (isPrivateHexTag(key)) {
+    throw new Error(
+      `${path}.${key}: private tags have no dictionary VR \u2014 use the raw form, e.g. { "vr": "LO", "value": \u2026 }`
+    );
+  }
+  validateModalityGuard(key, value, path);
   if (typeof value === "string") {
     for (const name of findTemplateTokens(value)) {
       if (!TEMPLATE_VOCAB.includes(name)) {

package/dist/esm/index.js

@@ -95,6 +95,92 @@ var VALID_VIOLATIONS = {
 };
 var HEX_TAG_RE = /^[0-9a-fA-F]{8}$/;
 var KEYWORD_RE = /^[A-Z][A-Za-z0-9]*$/;
+var VALID_VRS = /* @__PURE__ */ new Set([
+  "AE",
+  "AS",
+  "AT",
+  "CS",
+  "DA",
+  "DS",
+  "DT",
+  "FL",
+  "FD",
+  "IS",
+  "LO",
+  "LT",
+  "OB",
+  "OD",
+  "OF",
+  "OL",
+  "OV",
+  "OW",
+  "PN",
+  "SH",
+  "SL",
+  "SQ",
+  "SS",
+  "ST",
+  "SV",
+  "TM",
+  "UC",
+  "UI",
+  "UL",
+  "UN",
+  "UR",
+  "US",
+  "UT",
+  "UV"
+]);
+function isPrivateHexTag(key) {
+  return HEX_TAG_RE.test(key) && Number.parseInt(key.slice(0, 4), 16) % 2 === 1;
+}
+function isRawTagValue(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) && typeof value.vr === "string";
+}
+function validateRawTagValue(raw, path) {
+  for (const key of Object.keys(raw)) {
+    if (key !== "vr" && key !== "value") {
+      throw new Error(
+        `${path}: raw tag form accepts only "vr" and "value"; got "${key}"`
+      );
+    }
+  }
+  const vr = raw.vr;
+  if (!VALID_VRS.has(vr)) {
+    throw new Error(`${path}.vr: "${vr}" is not a standard DICOM VR`);
+  }
+  if (!("value" in raw)) {
+    throw new Error(`${path}.value: is required in the raw tag form`);
+  }
+  if (vr === "SQ") {
+    if (!Array.isArray(raw.value)) {
+      throw new Error(`${path}.value: an SQ raw tag requires an array of items`);
+    }
+    raw.value.forEach((item, i) => {
+      if (typeof item !== "object" || item === null || Array.isArray(item)) {
+        throw new Error(
+          `${path}.value[${i}]: must be an object of hex-tag entries`
+        );
+      }
+      for (const [tag, nested] of Object.entries(item)) {
+        if (!HEX_TAG_RE.test(tag)) {
+          throw new Error(
+            `${path}.value[${i}]: invalid item tag "${tag}" \u2014 SQ items use 8-hex-char tags`
+          );
+        }
+        if (!isRawTagValue(nested)) {
+          throw new Error(
+            `${path}.value[${i}].${tag}: SQ item entries must use the raw { vr, value } form`
+          );
+        }
+        validateRawTagValue(
+          nested,
+          `${path}.value[${i}].${tag}`
+        );
+      }
+    });
+  }
+}
 function validatePositiveInt(value, path) {
   if (typeof value !== "number" || !Number.isInteger(value) || value < 1) {
     throw new Error(
@@ -299,13 +385,33 @@ function validateEntry(entry, path) {
   return e;
 }
 var MODALITY_TAG = "00080060";
-function validateTagValue(key, value, path) {
+function validateModalityGuard(key, candidate, path) {
   const isModalityKey = key === "Modality" || key.toUpperCase() === MODALITY_TAG;
-  if (isModalityKey && typeof value === "string" && Object.hasOwn(VALID_MODALITIES, value)) {
+  if (isModalityKey && typeof candidate === "string" && Object.hasOwn(VALID_MODALITIES, candidate)) {
     throw new Error(
       `${path}.${key}: set a preset modality (${Object.keys(VALID_MODALITIES).join("/")}) via the "modality" field, not tags \u2014 it is coupled to SOPClassUID and type-1 attributes`
     );
   }
+}
+function validateTagValue(key, value, path) {
+  if (isRawTagValue(value)) {
+    if (!HEX_TAG_RE.test(key)) {
+      throw new Error(
+        `${path}.${key}: the raw { vr, value } form requires an 8-hex-char tag key \u2014 keyword tags take plain values`
+      );
+    }
+    validateRawTagValue(value, `${path}.${key}`);
+    const raw = value.value;
+    const scalar = Array.isArray(raw) && raw.length === 1 ? raw[0] : raw;
+    validateModalityGuard(key, scalar, path);
+    return;
+  }
+  if (isPrivateHexTag(key)) {
+    throw new Error(
+      `${path}.${key}: private tags have no dictionary VR \u2014 use the raw form, e.g. { "vr": "LO", "value": \u2026 }`
+    );
+  }
+  validateModalityGuard(key, value, path);
   if (typeof value === "string") {
     for (const name of findTemplateTokens(value)) {
       if (!TEMPLATE_VOCAB.includes(name)) {
@@ -802,27 +908,50 @@ function buildTagToKeyword() {
   return map;
 }
 var tagToKeyword = buildTagToKeyword();
+function toRawElement(raw) {
+  const value = raw.vr === "SQ" ? raw.value.map(
+    (item) => Object.fromEntries(
+      Object.entries(item).map(([tag, nested]) => [
+        tag.toUpperCase(),
+        toRawElement(nested)
+      ])
+    )
+  ) : raw.value;
+  return { vr: raw.vr, Value: Array.isArray(value) ? value : [value] };
+}
 function applyTagOverrides(dataset, tags) {
-  if (!tags) return;
+  if (!tags) return void 0;
+  let raw;
   for (const [key, value] of Object.entries(tags)) {
-    if (HEX_TAG_RE.test(key)) {
+    if (isRawTagValue(value)) {
+      raw ?? (raw = {});
+      raw[key.toUpperCase()] = toRawElement(value);
+    } else if (HEX_TAG_RE.test(key)) {
       const keyword = tagToKeyword.get(key.toUpperCase());
-      if (keyword) {
-        dataset[keyword] = value;
-      } else {
-        console.warn(`dicom-synth: unknown hex tag "${key}" \u2014 skipping`);
+      if (!keyword) {
+        throw new Error(
+          `dicom-synth: unknown hex tag "${key}" \u2014 dictionary tags take plain values; private/unknown tags require the raw { vr, value } form`
+        );
       }
+      dataset[keyword] = value;
     } else {
       dataset[key] = value;
     }
   }
+  return raw;
+}
+function rawScalarString(rawElements, tag) {
+  const value = rawElements?.[tag]?.Value;
+  return value?.length === 1 && typeof value[0] === "string" ? value[0] : void 0;
 }
-function syncMetaWithDataset(meta, dataset) {
-  if (typeof dataset.SOPInstanceUID === "string") {
-    meta.MediaStorageSOPInstanceUID = dataset.SOPInstanceUID;
+function syncMetaWithDataset(meta, dataset, rawElements) {
+  const sopInstance = rawScalarString(rawElements, "00080018") ?? (typeof dataset.SOPInstanceUID === "string" ? dataset.SOPInstanceUID : void 0);
+  if (sopInstance !== void 0) {
+    meta.MediaStorageSOPInstanceUID = sopInstance;
   }
-  if (typeof dataset.SOPClassUID === "string") {
-    meta.MediaStorageSOPClassUID = dataset.SOPClassUID;
+  const sopClass = rawScalarString(rawElements, "00080016") ?? (typeof dataset.SOPClassUID === "string" ? dataset.SOPClassUID : void 0);
+  if (sopClass !== void 0) {
+    meta.MediaStorageSOPClassUID = sopClass;
   }
 }
 function buildMeta(uid, modality, transferSyntax = "explicit-vr-little-endian") {
@@ -862,7 +991,7 @@ function buildBaseImageDataset(uid, modality) {
     ...preset.attributes
   };
 }
-function serializeDict(meta, dataset) {
+function serializeDict(meta, dataset, rawElements) {
   const dicomDict = new dcmjs.data.DicomDict(
     dcmjs.data.DicomMetaDictionary.denaturalizeDataset(
       meta
@@ -871,14 +1000,17 @@ function serializeDict(meta, dataset) {
   dicomDict.dict = dcmjs.data.DicomMetaDictionary.denaturalizeDataset(
     dataset
   );
+  if (rawElements) {
+    Object.assign(dicomDict.dict, rawElements);
+  }
   return Buffer.from(dicomDict.write({ allowInvalidVRLength: true }));
 }
 var MAX_DIMENSION = 65535;
-function applySizing(dataset, meta, spec) {
+function applySizing(dataset, meta, spec, rawElements) {
   if (spec.targetSizeKb !== void 0) {
     const clampDim = (n) => Math.min(MAX_DIMENSION, Math.max(1, Math.round(n)));
     const minimalPixelBytes = dataset.PixelData.byteLength;
-    const overhead = serializeDict(meta, dataset).length - minimalPixelBytes;
+    const overhead = serializeDict(meta, dataset, rawElements).length - minimalPixelBytes;
     const cells = Math.max(
       1,
       Math.round((spec.targetSizeKb * 1024 - overhead) / 2)
@@ -909,11 +1041,11 @@ function buildImageBuffer(spec, uid) {
     dataset.Laterality = "";
     dataset.PatientWeight = "0";
   }
-  applyTagOverrides(dataset, spec.tags);
+  const rawElements = applyTagOverrides(dataset, spec.tags);
   const meta = buildMeta(effectiveUid, modality, spec.transferSyntax);
-  syncMetaWithDataset(meta, dataset);
-  applySizing(dataset, meta, spec);
-  return serializeDict(meta, dataset);
+  syncMetaWithDataset(meta, dataset, rawElements);
+  applySizing(dataset, meta, spec, rawElements);
+  return { buffer: serializeDict(meta, dataset, rawElements), rawElements };
 }
 function buildFakeSignatureBuffer() {
   const buf = Buffer.alloc(200, 0);
@@ -935,11 +1067,11 @@ function buildBufferForSpec(spec, uid) {
     case "vendor-warnings-image":
       return buildImageBuffer(spec, uid);
     case "fake-signature":
-      return buildFakeSignatureBuffer();
+      return { buffer: buildFakeSignatureBuffer() };
     case "non-dicom":
-      return buildNonDicomBuffer(spec);
+      return { buffer: buildNonDicomBuffer(spec) };
     case "dicomdir":
-      return buildDicomdirBuffer();
+      return { buffer: buildDicomdirBuffer() };
     case "large-image":
       throw new Error(
         "large-image cannot be generated in memory \u2014 use writeCollectionFromSpec (disk-only streaming)"
@@ -1031,12 +1163,12 @@ function writeNative(outPath, params, dims, zeroChunk) {
   const { modality, uid, tags } = params;
   const meta = buildMeta(uid, modality);
   const dataset = buildBaseImageDataset(uid, modality);
-  applyTagOverrides(dataset, tags);
-  syncMetaWithDataset(meta, dataset);
+  const rawElements = applyTagOverrides(dataset, tags);
+  syncMetaWithDataset(meta, dataset, rawElements);
   dataset.Rows = dims.rows;
   dataset.Columns = dims.columns;
   const minimalPixelBytes = dataset.PixelData.byteLength;
-  const probe = serializeDict(meta, dataset);
+  const probe = serializeDict(meta, dataset, rawElements);
   const pixelElement = Buffer.alloc(12);
   PIXEL_DATA_OW_HEADER.copy(pixelElement);
   pixelElement.writeUInt32LE(minimalPixelBytes, 8);
@@ -1065,11 +1197,11 @@ function writeEncapsulated(outPath, params, pixelBytes, fragmentBytes, zeroChunk
     TransferSyntaxUID: RLE_TRANSFER_SYNTAX_UID
   };
   const dataset = buildBaseImageDataset(uid, modality);
-  applyTagOverrides(dataset, tags);
-  syncMetaWithDataset(meta, dataset);
+  const rawElements = applyTagOverrides(dataset, tags);
+  syncMetaWithDataset(meta, dataset, rawElements);
   dataset.PixelData = [new Uint8Array([]).buffer, new Uint8Array([0, 0]).buffer];
   dataset._vrMap = { PixelData: "OB" };
-  const probe = serializeDict(meta, dataset);
+  const probe = serializeDict(meta, dataset, rawElements);
   const idx = probe.indexOf(PIXEL_DATA_OB_HEADER);
   if (idx < 0 || probe.readUInt32LE(idx + 8) !== 4294967295) {
     throw new Error("failed to locate encapsulated PixelData element header");
@@ -1187,7 +1319,7 @@ var VIOLATION_LEVEL = {
   "missing-meta-header": "byte",
   "malformed-sq-delimiter": "byte"
 };
-function applyTagLevel(buffer, violations) {
+function applyTagLevel(buffer, violations, rawElements) {
   if (violations.length === 0) return buffer;
   let parsed;
   try {
@@ -1221,6 +1353,9 @@ function applyTagLevel(buffer, violations) {
     }
   }
   parsed.dict = dcmjsAny.data.DicomMetaDictionary.denaturalizeDataset(natural);
+  if (rawElements) {
+    Object.assign(parsed.dict, rawElements);
+  }
   if (violations.includes("uid-too-long")) {
     ;
     parsed.dict["00080018"] = {
@@ -1253,11 +1388,14 @@ function applyByteLevel(buffer, violations) {
   }
   return result;
 }
-function applyViolations(buffer, violations) {
+function applyViolations(buffer, violations, rawElements) {
   if (violations.length === 0) return buffer;
   const tagViolations = violations.filter((v) => VIOLATION_LEVEL[v] === "tag");
   const byteViolations = violations.filter((v) => VIOLATION_LEVEL[v] === "byte");
-  return applyByteLevel(applyTagLevel(buffer, tagViolations), byteViolations);
+  return applyByteLevel(
+    applyTagLevel(buffer, tagViolations, rawElements),
+    byteViolations
+  );
 }
 
 // src/collection/writer.ts
@@ -1331,10 +1469,11 @@ async function generateFile(spec, options) {
     ...spec,
     tags: resolveTagTemplates(spec.tags, { index, ...options?.context })
   } : spec;
-  let buffer = buildBufferForSpec(resolvedSpec, uid);
+  const built = buildBufferForSpec(resolvedSpec, uid);
+  let buffer = built.buffer;
   const violations = "violations" in spec ? spec.violations : void 0;
   if (violations?.length) {
-    buffer = applyViolations(buffer, violations);
+    buffer = applyViolations(buffer, violations, built.rawElements);
   }
   const name = filename(spec.type, index, padWidth);
   return {

package/dist/esm/schema/parametric.js

@@ -69,6 +69,92 @@ var VALID_VIOLATIONS = {
 };
 var HEX_TAG_RE = /^[0-9a-fA-F]{8}$/;
 var KEYWORD_RE = /^[A-Z][A-Za-z0-9]*$/;
+var VALID_VRS = /* @__PURE__ */ new Set([
+  "AE",
+  "AS",
+  "AT",
+  "CS",
+  "DA",
+  "DS",
+  "DT",
+  "FL",
+  "FD",
+  "IS",
+  "LO",
+  "LT",
+  "OB",
+  "OD",
+  "OF",
+  "OL",
+  "OV",
+  "OW",
+  "PN",
+  "SH",
+  "SL",
+  "SQ",
+  "SS",
+  "ST",
+  "SV",
+  "TM",
+  "UC",
+  "UI",
+  "UL",
+  "UN",
+  "UR",
+  "US",
+  "UT",
+  "UV"
+]);
+function isPrivateHexTag(key) {
+  return HEX_TAG_RE.test(key) && Number.parseInt(key.slice(0, 4), 16) % 2 === 1;
+}
+function isRawTagValue(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) && typeof value.vr === "string";
+}
+function validateRawTagValue(raw, path) {
+  for (const key of Object.keys(raw)) {
+    if (key !== "vr" && key !== "value") {
+      throw new Error(
+        `${path}: raw tag form accepts only "vr" and "value"; got "${key}"`
+      );
+    }
+  }
+  const vr = raw.vr;
+  if (!VALID_VRS.has(vr)) {
+    throw new Error(`${path}.vr: "${vr}" is not a standard DICOM VR`);
+  }
+  if (!("value" in raw)) {
+    throw new Error(`${path}.value: is required in the raw tag form`);
+  }
+  if (vr === "SQ") {
+    if (!Array.isArray(raw.value)) {
+      throw new Error(`${path}.value: an SQ raw tag requires an array of items`);
+    }
+    raw.value.forEach((item, i) => {
+      if (typeof item !== "object" || item === null || Array.isArray(item)) {
+        throw new Error(
+          `${path}.value[${i}]: must be an object of hex-tag entries`
+        );
+      }
+      for (const [tag, nested] of Object.entries(item)) {
+        if (!HEX_TAG_RE.test(tag)) {
+          throw new Error(
+            `${path}.value[${i}]: invalid item tag "${tag}" \u2014 SQ items use 8-hex-char tags`
+          );
+        }
+        if (!isRawTagValue(nested)) {
+          throw new Error(
+            `${path}.value[${i}].${tag}: SQ item entries must use the raw { vr, value } form`
+          );
+        }
+        validateRawTagValue(
+          nested,
+          `${path}.value[${i}].${tag}`
+        );
+      }
+    });
+  }
+}
 function validatePositiveInt(value, path) {
   if (typeof value !== "number" || !Number.isInteger(value) || value < 1) {
     throw new Error(
@@ -273,13 +359,33 @@ function validateEntry(entry, path) {
   return e;
 }
 var MODALITY_TAG = "00080060";
-function validateTagValue(key, value, path) {
+function validateModalityGuard(key, candidate, path) {
   const isModalityKey = key === "Modality" || key.toUpperCase() === MODALITY_TAG;
-  if (isModalityKey && typeof value === "string" && Object.hasOwn(VALID_MODALITIES, value)) {
+  if (isModalityKey && typeof candidate === "string" && Object.hasOwn(VALID_MODALITIES, candidate)) {
     throw new Error(
       `${path}.${key}: set a preset modality (${Object.keys(VALID_MODALITIES).join("/")}) via the "modality" field, not tags \u2014 it is coupled to SOPClassUID and type-1 attributes`
     );
   }
+}
+function validateTagValue(key, value, path) {
+  if (isRawTagValue(value)) {
+    if (!HEX_TAG_RE.test(key)) {
+      throw new Error(
+        `${path}.${key}: the raw { vr, value } form requires an 8-hex-char tag key \u2014 keyword tags take plain values`
+      );
+    }
+    validateRawTagValue(value, `${path}.${key}`);
+    const raw = value.value;
+    const scalar = Array.isArray(raw) && raw.length === 1 ? raw[0] : raw;
+    validateModalityGuard(key, scalar, path);
+    return;
+  }
+  if (isPrivateHexTag(key)) {
+    throw new Error(
+      `${path}.${key}: private tags have no dictionary VR \u2014 use the raw form, e.g. { "vr": "LO", "value": \u2026 }`
+    );
+  }
+  validateModalityGuard(key, value, path);
   if (typeof value === "string") {
     for (const name of findTemplateTokens(value)) {
       if (!TEMPLATE_VOCAB.includes(name)) {

package/dist/esm/schema/validate.js

@@ -61,6 +61,92 @@ var VALID_VIOLATIONS = {
 };
 var HEX_TAG_RE = /^[0-9a-fA-F]{8}$/;
 var KEYWORD_RE = /^[A-Z][A-Za-z0-9]*$/;
+var VALID_VRS = /* @__PURE__ */ new Set([
+  "AE",
+  "AS",
+  "AT",
+  "CS",
+  "DA",
+  "DS",
+  "DT",
+  "FL",
+  "FD",
+  "IS",
+  "LO",
+  "LT",
+  "OB",
+  "OD",
+  "OF",
+  "OL",
+  "OV",
+  "OW",
+  "PN",
+  "SH",
+  "SL",
+  "SQ",
+  "SS",
+  "ST",
+  "SV",
+  "TM",
+  "UC",
+  "UI",
+  "UL",
+  "UN",
+  "UR",
+  "US",
+  "UT",
+  "UV"
+]);
+function isPrivateHexTag(key) {
+  return HEX_TAG_RE.test(key) && Number.parseInt(key.slice(0, 4), 16) % 2 === 1;
+}
+function isRawTagValue(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) && typeof value.vr === "string";
+}
+function validateRawTagValue(raw, path) {
+  for (const key of Object.keys(raw)) {
+    if (key !== "vr" && key !== "value") {
+      throw new Error(
+        `${path}: raw tag form accepts only "vr" and "value"; got "${key}"`
+      );
+    }
+  }
+  const vr = raw.vr;
+  if (!VALID_VRS.has(vr)) {
+    throw new Error(`${path}.vr: "${vr}" is not a standard DICOM VR`);
+  }
+  if (!("value" in raw)) {
+    throw new Error(`${path}.value: is required in the raw tag form`);
+  }
+  if (vr === "SQ") {
+    if (!Array.isArray(raw.value)) {
+      throw new Error(`${path}.value: an SQ raw tag requires an array of items`);
+    }
+    raw.value.forEach((item, i) => {
+      if (typeof item !== "object" || item === null || Array.isArray(item)) {
+        throw new Error(
+          `${path}.value[${i}]: must be an object of hex-tag entries`
+        );
+      }
+      for (const [tag, nested] of Object.entries(item)) {
+        if (!HEX_TAG_RE.test(tag)) {
+          throw new Error(
+            `${path}.value[${i}]: invalid item tag "${tag}" \u2014 SQ items use 8-hex-char tags`
+          );
+        }
+        if (!isRawTagValue(nested)) {
+          throw new Error(
+            `${path}.value[${i}].${tag}: SQ item entries must use the raw { vr, value } form`
+          );
+        }
+        validateRawTagValue(
+          nested,
+          `${path}.value[${i}].${tag}`
+        );
+      }
+    });
+  }
+}
 function validatePositiveInt(value, path) {
   if (typeof value !== "number" || !Number.isInteger(value) || value < 1) {
     throw new Error(
@@ -265,13 +351,33 @@ function validateEntry(entry, path) {
   return e;
 }
 var MODALITY_TAG = "00080060";
-function validateTagValue(key, value, path) {
+function validateModalityGuard(key, candidate, path) {
   const isModalityKey = key === "Modality" || key.toUpperCase() === MODALITY_TAG;
-  if (isModalityKey && typeof value === "string" && Object.hasOwn(VALID_MODALITIES, value)) {
+  if (isModalityKey && typeof candidate === "string" && Object.hasOwn(VALID_MODALITIES, candidate)) {
     throw new Error(
       `${path}.${key}: set a preset modality (${Object.keys(VALID_MODALITIES).join("/")}) via the "modality" field, not tags \u2014 it is coupled to SOPClassUID and type-1 attributes`
     );
   }
+}
+function validateTagValue(key, value, path) {
+  if (isRawTagValue(value)) {
+    if (!HEX_TAG_RE.test(key)) {
+      throw new Error(
+        `${path}.${key}: the raw { vr, value } form requires an 8-hex-char tag key \u2014 keyword tags take plain values`
+      );
+    }
+    validateRawTagValue(value, `${path}.${key}`);
+    const raw = value.value;
+    const scalar = Array.isArray(raw) && raw.length === 1 ? raw[0] : raw;
+    validateModalityGuard(key, scalar, path);
+    return;
+  }
+  if (isPrivateHexTag(key)) {
+    throw new Error(
+      `${path}.${key}: private tags have no dictionary VR \u2014 use the raw form, e.g. { "vr": "LO", "value": \u2026 }`
+    );
+  }
+  validateModalityGuard(key, value, path);
   if (typeof value === "string") {
     for (const name of findTemplateTokens(value)) {
       if (!TEMPLATE_VOCAB.includes(name)) {
@@ -682,6 +788,7 @@ function validateParametricSpec(raw) {
 export {
   HEX_TAG_RE,
   isImageType,
+  isRawTagValue,
   positionalName,
   validateDatasetSpec,
   validateParametricSpec

package/dist/esm/syntheticFixtures/generator.js

@@ -45,6 +45,9 @@ var MAX_STREAM_BYTES = 50 * 1024 * 1024 * 1024;
 
 // src/schema/validate.ts
 var HEX_TAG_RE = /^[0-9a-fA-F]{8}$/;
+function isRawTagValue(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) && typeof value.vr === "string";
+}
 
 // src/syntheticFixtures/generator.ts
 var MODALITY_PRESETS = {
@@ -93,27 +96,50 @@ function buildTagToKeyword() {
   return map;
 }
 var tagToKeyword = buildTagToKeyword();
+function toRawElement(raw) {
+  const value = raw.vr === "SQ" ? raw.value.map(
+    (item) => Object.fromEntries(
+      Object.entries(item).map(([tag, nested]) => [
+        tag.toUpperCase(),
+        toRawElement(nested)
+      ])
+    )
+  ) : raw.value;
+  return { vr: raw.vr, Value: Array.isArray(value) ? value : [value] };
+}
 function applyTagOverrides(dataset, tags) {
-  if (!tags) return;
+  if (!tags) return void 0;
+  let raw;
   for (const [key, value] of Object.entries(tags)) {
-    if (HEX_TAG_RE.test(key)) {
+    if (isRawTagValue(value)) {
+      raw ?? (raw = {});
+      raw[key.toUpperCase()] = toRawElement(value);
+    } else if (HEX_TAG_RE.test(key)) {
       const keyword = tagToKeyword.get(key.toUpperCase());
-      if (keyword) {
-        dataset[keyword] = value;
-      } else {
-        console.warn(`dicom-synth: unknown hex tag "${key}" \u2014 skipping`);
+      if (!keyword) {
+        throw new Error(
+          `dicom-synth: unknown hex tag "${key}" \u2014 dictionary tags take plain values; private/unknown tags require the raw { vr, value } form`
+        );
       }
+      dataset[keyword] = value;
     } else {
       dataset[key] = value;
     }
   }
+  return raw;
 }
-function syncMetaWithDataset(meta, dataset) {
-  if (typeof dataset.SOPInstanceUID === "string") {
-    meta.MediaStorageSOPInstanceUID = dataset.SOPInstanceUID;
+function rawScalarString(rawElements, tag) {
+  const value = rawElements?.[tag]?.Value;
+  return value?.length === 1 && typeof value[0] === "string" ? value[0] : void 0;
+}
+function syncMetaWithDataset(meta, dataset, rawElements) {
+  const sopInstance = rawScalarString(rawElements, "00080018") ?? (typeof dataset.SOPInstanceUID === "string" ? dataset.SOPInstanceUID : void 0);
+  if (sopInstance !== void 0) {
+    meta.MediaStorageSOPInstanceUID = sopInstance;
   }
-  if (typeof dataset.SOPClassUID === "string") {
-    meta.MediaStorageSOPClassUID = dataset.SOPClassUID;
+  const sopClass = rawScalarString(rawElements, "00080016") ?? (typeof dataset.SOPClassUID === "string" ? dataset.SOPClassUID : void 0);
+  if (sopClass !== void 0) {
+    meta.MediaStorageSOPClassUID = sopClass;
   }
 }
 function buildMeta(uid, modality, transferSyntax = "explicit-vr-little-endian") {
@@ -153,7 +179,7 @@ function buildBaseImageDataset(uid, modality) {
     ...preset.attributes
   };
 }
-function serializeDict(meta, dataset) {
+function serializeDict(meta, dataset, rawElements) {
   const dicomDict = new dcmjs.data.DicomDict(
     dcmjs.data.DicomMetaDictionary.denaturalizeDataset(
       meta
@@ -162,14 +188,17 @@ function serializeDict(meta, dataset) {
   dicomDict.dict = dcmjs.data.DicomMetaDictionary.denaturalizeDataset(
     dataset
   );
+  if (rawElements) {
+    Object.assign(dicomDict.dict, rawElements);
+  }
   return Buffer.from(dicomDict.write({ allowInvalidVRLength: true }));
 }
 var MAX_DIMENSION = 65535;
-function applySizing(dataset, meta, spec) {
+function applySizing(dataset, meta, spec, rawElements) {
   if (spec.targetSizeKb !== void 0) {
     const clampDim = (n) => Math.min(MAX_DIMENSION, Math.max(1, Math.round(n)));
     const minimalPixelBytes = dataset.PixelData.byteLength;
-    const overhead = serializeDict(meta, dataset).length - minimalPixelBytes;
+    const overhead = serializeDict(meta, dataset, rawElements).length - minimalPixelBytes;
     const cells = Math.max(
       1,
       Math.round((spec.targetSizeKb * 1024 - overhead) / 2)
@@ -200,11 +229,11 @@ function buildImageBuffer(spec, uid) {
     dataset.Laterality = "";
     dataset.PatientWeight = "0";
   }
-  applyTagOverrides(dataset, spec.tags);
+  const rawElements = applyTagOverrides(dataset, spec.tags);
   const meta = buildMeta(effectiveUid, modality, spec.transferSyntax);
-  syncMetaWithDataset(meta, dataset);
-  applySizing(dataset, meta, spec);
-  return serializeDict(meta, dataset);
+  syncMetaWithDataset(meta, dataset, rawElements);
+  applySizing(dataset, meta, spec, rawElements);
+  return { buffer: serializeDict(meta, dataset, rawElements), rawElements };
 }
 function buildFakeSignatureBuffer() {
   const buf = Buffer.alloc(200, 0);
@@ -226,11 +255,11 @@ function buildBufferForSpec(spec, uid) {
     case "vendor-warnings-image":
       return buildImageBuffer(spec, uid);
     case "fake-signature":
-      return buildFakeSignatureBuffer();
+      return { buffer: buildFakeSignatureBuffer() };
     case "non-dicom":
-      return buildNonDicomBuffer(spec);
+      return { buffer: buildNonDicomBuffer(spec) };
     case "dicomdir":
-      return buildDicomdirBuffer();
+      return { buffer: buildDicomdirBuffer() };
     case "large-image":
       throw new Error(
         "large-image cannot be generated in memory \u2014 use writeCollectionFromSpec (disk-only streaming)"

package/dist/esm/syntheticFixtures/streamWrite.js

@@ -31,6 +31,9 @@ import { resolve } from "node:path";
 
 // src/schema/validate.ts
 var HEX_TAG_RE = /^[0-9a-fA-F]{8}$/;
+function isRawTagValue(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) && typeof value.vr === "string";
+}
 
 // src/syntheticFixtures/generator.ts
 var MODALITY_PRESETS = {
@@ -79,27 +82,50 @@ function buildTagToKeyword() {
   return map;
 }
 var tagToKeyword = buildTagToKeyword();
+function toRawElement(raw) {
+  const value = raw.vr === "SQ" ? raw.value.map(
+    (item) => Object.fromEntries(
+      Object.entries(item).map(([tag, nested]) => [
+        tag.toUpperCase(),
+        toRawElement(nested)
+      ])
+    )
+  ) : raw.value;
+  return { vr: raw.vr, Value: Array.isArray(value) ? value : [value] };
+}
 function applyTagOverrides(dataset, tags) {
-  if (!tags) return;
+  if (!tags) return void 0;
+  let raw;
   for (const [key, value] of Object.entries(tags)) {
-    if (HEX_TAG_RE.test(key)) {
+    if (isRawTagValue(value)) {
+      raw ?? (raw = {});
+      raw[key.toUpperCase()] = toRawElement(value);
+    } else if (HEX_TAG_RE.test(key)) {
       const keyword = tagToKeyword.get(key.toUpperCase());
-      if (keyword) {
-        dataset[keyword] = value;
-      } else {
-        console.warn(`dicom-synth: unknown hex tag "${key}" \u2014 skipping`);
+      if (!keyword) {
+        throw new Error(
+          `dicom-synth: unknown hex tag "${key}" \u2014 dictionary tags take plain values; private/unknown tags require the raw { vr, value } form`
+        );
       }
+      dataset[keyword] = value;
     } else {
       dataset[key] = value;
     }
   }
+  return raw;
 }
-function syncMetaWithDataset(meta, dataset) {
-  if (typeof dataset.SOPInstanceUID === "string") {
-    meta.MediaStorageSOPInstanceUID = dataset.SOPInstanceUID;
+function rawScalarString(rawElements, tag) {
+  const value = rawElements?.[tag]?.Value;
+  return value?.length === 1 && typeof value[0] === "string" ? value[0] : void 0;
+}
+function syncMetaWithDataset(meta, dataset, rawElements) {
+  const sopInstance = rawScalarString(rawElements, "00080018") ?? (typeof dataset.SOPInstanceUID === "string" ? dataset.SOPInstanceUID : void 0);
+  if (sopInstance !== void 0) {
+    meta.MediaStorageSOPInstanceUID = sopInstance;
   }
-  if (typeof dataset.SOPClassUID === "string") {
-    meta.MediaStorageSOPClassUID = dataset.SOPClassUID;
+  const sopClass = rawScalarString(rawElements, "00080016") ?? (typeof dataset.SOPClassUID === "string" ? dataset.SOPClassUID : void 0);
+  if (sopClass !== void 0) {
+    meta.MediaStorageSOPClassUID = sopClass;
   }
 }
 function buildMeta(uid, modality, transferSyntax = "explicit-vr-little-endian") {
@@ -139,7 +165,7 @@ function buildBaseImageDataset(uid, modality) {
     ...preset.attributes
   };
 }
-function serializeDict(meta, dataset) {
+function serializeDict(meta, dataset, rawElements) {
   const dicomDict = new dcmjs.data.DicomDict(
     dcmjs.data.DicomMetaDictionary.denaturalizeDataset(
       meta
@@ -148,6 +174,9 @@ function serializeDict(meta, dataset) {
   dicomDict.dict = dcmjs.data.DicomMetaDictionary.denaturalizeDataset(
     dataset
   );
+  if (rawElements) {
+    Object.assign(dicomDict.dict, rawElements);
+  }
   return Buffer.from(dicomDict.write({ allowInvalidVRLength: true }));
 }
 
@@ -211,12 +240,12 @@ function writeNative(outPath, params, dims, zeroChunk) {
   const { modality, uid, tags } = params;
   const meta = buildMeta(uid, modality);
   const dataset = buildBaseImageDataset(uid, modality);
-  applyTagOverrides(dataset, tags);
-  syncMetaWithDataset(meta, dataset);
+  const rawElements = applyTagOverrides(dataset, tags);
+  syncMetaWithDataset(meta, dataset, rawElements);
   dataset.Rows = dims.rows;
   dataset.Columns = dims.columns;
   const minimalPixelBytes = dataset.PixelData.byteLength;
-  const probe = serializeDict(meta, dataset);
+  const probe = serializeDict(meta, dataset, rawElements);
   const pixelElement = Buffer.alloc(12);
   PIXEL_DATA_OW_HEADER.copy(pixelElement);
   pixelElement.writeUInt32LE(minimalPixelBytes, 8);
@@ -245,11 +274,11 @@ function writeEncapsulated(outPath, params, pixelBytes, fragmentBytes, zeroChunk
     TransferSyntaxUID: RLE_TRANSFER_SYNTAX_UID
   };
   const dataset = buildBaseImageDataset(uid, modality);
-  applyTagOverrides(dataset, tags);
-  syncMetaWithDataset(meta, dataset);
+  const rawElements = applyTagOverrides(dataset, tags);
+  syncMetaWithDataset(meta, dataset, rawElements);
   dataset.PixelData = [new Uint8Array([]).buffer, new Uint8Array([0, 0]).buffer];
   dataset._vrMap = { PixelData: "OB" };
-  const probe = serializeDict(meta, dataset);
+  const probe = serializeDict(meta, dataset, rawElements);
   const idx = probe.indexOf(PIXEL_DATA_OB_HEADER);
   if (idx < 0 || probe.readUInt32LE(idx + 8) !== 4294967295) {
     throw new Error("failed to locate encapsulated PixelData element header");

package/dist/esm/syntheticFixtures/violations.js

@@ -38,7 +38,7 @@ var VIOLATION_LEVEL = {
   "missing-meta-header": "byte",
   "malformed-sq-delimiter": "byte"
 };
-function applyTagLevel(buffer, violations) {
+function applyTagLevel(buffer, violations, rawElements) {
   if (violations.length === 0) return buffer;
   let parsed;
   try {
@@ -72,6 +72,9 @@ function applyTagLevel(buffer, violations) {
     }
   }
   parsed.dict = dcmjsAny.data.DicomMetaDictionary.denaturalizeDataset(natural);
+  if (rawElements) {
+    Object.assign(parsed.dict, rawElements);
+  }
   if (violations.includes("uid-too-long")) {
     ;
     parsed.dict["00080018"] = {
@@ -104,11 +107,14 @@ function applyByteLevel(buffer, violations) {
   }
   return result;
 }
-function applyViolations(buffer, violations) {
+function applyViolations(buffer, violations, rawElements) {
   if (violations.length === 0) return buffer;
   const tagViolations = violations.filter((v) => VIOLATION_LEVEL[v] === "tag");
   const byteViolations = violations.filter((v) => VIOLATION_LEVEL[v] === "byte");
-  return applyByteLevel(applyTagLevel(buffer, tagViolations), byteViolations);
+  return applyByteLevel(
+    applyTagLevel(buffer, tagViolations, rawElements),
+    byteViolations
+  );
 }
 export {
   applyViolations

package/dist/types/index.d.ts

@@ -4,7 +4,7 @@ export { defaultPublicCasesPath, loadCaseById, loadCasesFromJson, loadDefaultCas
 export { caseCachePath, fetchPublicCaseToCache, verifySha256, } from './public-fixtures/fetch.js';
 export { MAX_PIXEL_BYTES, MAX_STREAM_BYTES } from './schema/limits.js';
 export { resolveParametricSpec } from './schema/parametric.js';
-export type { DatasetLayout, DatasetSpec, DicomdirSpec, DicomTagOverrides, EntrySpec, FakeSignatureSpec, FileSpec, ImageSpec, InvalidUidImageSpec, LargeFileSpec, Modality, NonDicomSpec, ParametricEdgeCase, ParametricSpec, ParametricStudies, PathQuirk, Range, SeriesEntrySpec, SeriesInstances, SeriesSpec, StudySpec, TransferSyntax, TreeDirNode, TreeFileNode, TreeNode, ValidImageSpec, VendorWarningsImageSpec, ViolationClass, } from './schema/types.js';
+export type { DatasetLayout, DatasetSpec, DicomdirSpec, DicomTagOverrides, EntrySpec, FakeSignatureSpec, FileSpec, ImageSpec, InvalidUidImageSpec, LargeFileSpec, Modality, NonDicomSpec, ParametricEdgeCase, ParametricSpec, ParametricStudies, PathQuirk, Range, RawTagValue, SeriesEntrySpec, SeriesInstances, SeriesSpec, StudySpec, TransferSyntax, TreeDirNode, TreeFileNode, TreeNode, ValidImageSpec, VendorWarningsImageSpec, ViolationClass, } from './schema/types.js';
 export { validateDatasetSpec, validateParametricSpec, } from './schema/validate.js';
 export { type LargeFileEncoding, type LargeFileResult, type LargeImageSpec, type StreamLargeImageOptions, streamLargeImage, writeLargeImageFile, } from './syntheticFixtures/streamWrite.js';
 export { resolveTagTemplates, type TagContext, TEMPLATE_VOCAB, } from './syntheticFixtures/tagTemplate.js';

package/dist/types/schema/types.d.ts

@@ -1,4 +1,8 @@
 export type TransferSyntax = 'explicit-vr-little-endian' | 'implicit-vr-little-endian';
+export type RawTagValue = {
+    vr: string;
+    value: unknown;
+};
 export type DicomTagOverrides = {
     PatientID?: string;
     PatientName?: string;

package/dist/types/schema/validate.d.ts

@@ -1,6 +1,10 @@
 import type { DatasetSpec, FileSpec, ParametricSpec } from './types.js';
 export declare function isImageType(type: FileSpec['type']): boolean;
 export declare const HEX_TAG_RE: RegExp;
+export declare function isRawTagValue(value: unknown): value is {
+    vr: string;
+    value: unknown;
+};
 export declare function positionalName(prefix: string, ordinal: number): string;
 export declare function validateDatasetSpec(raw: unknown): DatasetSpec;
 export declare function validateParametricSpec(raw: unknown): ParametricSpec;

package/dist/types/syntheticFixtures/generator.d.ts

@@ -1,9 +1,17 @@
 import type { DicomTagOverrides, FileSpec, Modality, NonDicomSpec, TransferSyntax } from '../schema/types.js';
 import type { UidSet } from './uid.js';
-export declare function applyTagOverrides(dataset: Record<string, unknown>, tags: DicomTagOverrides | undefined): void;
-export declare function syncMetaWithDataset(meta: Record<string, unknown>, dataset: Record<string, unknown>): void;
+export type RawElement = {
+    vr: string;
+    Value: unknown[];
+};
+export type RawElementMap = Record<string, RawElement>;
+export declare function applyTagOverrides(dataset: Record<string, unknown>, tags: DicomTagOverrides | undefined): RawElementMap | undefined;
+export declare function syncMetaWithDataset(meta: Record<string, unknown>, dataset: Record<string, unknown>, rawElements?: RawElementMap): void;
 export declare function buildMeta(uid: UidSet, modality: Modality, transferSyntax?: TransferSyntax): Record<string, unknown>;
 export declare function buildBaseImageDataset(uid: UidSet, modality: Modality): Record<string, unknown>;
-export declare function serializeDict(meta: Record<string, unknown>, dataset: Record<string, unknown>): Buffer;
+export declare function serializeDict(meta: Record<string, unknown>, dataset: Record<string, unknown>, rawElements?: RawElementMap): Buffer;
 export declare function sizedNonDicomBytes(spec: NonDicomSpec): number | undefined;
-export declare function buildBufferForSpec(spec: FileSpec, uid: UidSet): Buffer;
+export declare function buildBufferForSpec(spec: FileSpec, uid: UidSet): {
+    buffer: Buffer;
+    rawElements?: RawElementMap;
+};

package/dist/types/syntheticFixtures/violations.d.ts

@@ -1,2 +1,3 @@
 import type { ViolationClass } from '../schema/types.js';
-export declare function applyViolations(buffer: Buffer, violations: ViolationClass[]): Buffer;
+import type { RawElementMap } from './generator.js';
+export declare function applyViolations(buffer: Buffer, violations: ViolationClass[], rawElements?: RawElementMap): Buffer;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dicom-synth",
-  "version": "1.16.0",
+  "version": "1.17.0",
   "description": "Toolkit for synthetic DICOM fixtures and public fixture fetch/cache.",
   "license": "Apache-2.0",
   "type": "module",
@@ -49,6 +49,7 @@
     "build:data": "mkdir -p dist/data && cp data/public-cases.json dist/data/",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
     "test:watch": "vitest",
     "lint": "eslint src test scripts --ext .ts",
     "lint:fix": "eslint src test scripts --ext .ts --fix",
@@ -82,6 +83,7 @@
     "@types/node": "^22.15.3",
     "@typescript-eslint/eslint-plugin": "^8.46.1",
     "@typescript-eslint/parser": "^8.46.1",
+    "@vitest/coverage-v8": "3.2.6",
     "dcmjs": "^0.51.1",
     "esbuild": "^0.28.1",
     "eslint": "^9.38.0",