@sametalmdr/word-editor 0.2.0-alpha → 0.3.0-alpha

package/dist/io/ooxml/opc-write.js

@@ -1,171 +1,171 @@
-// P6 piece (2): package writer (repack). A field-for-field JS port of
-// scripts/opc-bytes.py's write_package, which was measured 46/46 byte-identical
-// on a no-op round-trip across the real corpus. Untouched parts are copied
-// VERBATIM — original local header AND compressed bytes, never re-derived — so
-// Word's own zip signature (compress method, flag bits, versions, one shared
-// timestamp) survives; only the CHANGED part is re-compressed and only CRC-32,
-// the two size fields, local-header offsets and the EOCD's cd-size/offset are
-// rewritten. That verbatim copy is §3.5 at the package level: N parts changed =
-// exactly N parts differ.
-//
-// The changed part is re-compressed with deflate-raw via CompressionStream —
-// M5 (examples/static/m5-deflate-probe.html) confirmed CompressionStream
-// ("deflate-raw") exists, round-trips and is run-to-run DETERMINISTIC in
-// Chrome AND Firefox 154 (2026-08-30, user-run, ADR-0023). Its output is NOT
-// byte-identical to Python zlib level 9 (different encoder), but §3.5
-// compares the INFLATED content, not the compressed bytes, so that is fine.
-//
-// This piece turns bytes into a valid .docx; it does NOT orchestrate the full
-// export (finding dirty parts, running the splice) — that is a later piece. Its
-// input is the original package bytes, its parsed entries (piece 1), and
-// { partName -> new UNCOMPRESSED bytes }.
-
-import { crc32 } from "./inflate.js";
-
-// Field offsets — verbatim from scripts/opc-bytes.py's constants block.
-const LOC_CRC = 14;
-const LOC_CSIZE = 18;
-const LOC_USIZE = 22;
-const CEN_CRC = 16;
-const CEN_CSIZE = 20;
-const CEN_USIZE = 24;
-const CEN_LOCAL_OFFSET = 42;
-const EOCD_CD_SIZE = 12;
-const EOCD_CD_OFFSET = 16;
-const EOCD_SIG = [0x50, 0x4b, 0x05, 0x06]; // "PK\x05\x06"
-const METHOD_STORE = 0;
-
-/**
- * The EOCD's offset — scanned backwards over the largest legal window (a zip
- * comment up to 65535 bytes may follow it). Mirrors opc-bytes.py's _find_eocd.
- * @param {Uint8Array} bytes
- * @returns {number}
- */
-function findEocd(bytes) {
-  const window = Math.min(bytes.length, 22 + 0xffff);
-  for (let i = bytes.length - 4; i >= bytes.length - window; i -= 1) {
-    if (bytes[i] === EOCD_SIG[0] && bytes[i + 1] === EOCD_SIG[1] && bytes[i + 2] === EOCD_SIG[2] && bytes[i + 3] === EOCD_SIG[3]) {
-      return i;
-    }
-  }
-  throw new Error("opc-write: no end-of-central-directory record — not a zip file");
-}
-
-/**
- * Raw DEFLATE of `bytes` via the platform CompressionStream (M5). Async.
- * @param {Uint8Array} bytes
- * @returns {Promise<Uint8Array>}
- */
-async function deflateRaw(bytes) {
-  // ReadableStream + pipeThrough (as inflate.js does for DecompressionStream) —
-  // avoids the writer.write chunk-type friction and collects via Response.
-  const source = new ReadableStream({
-    start(controller) {
-      controller.enqueue(bytes);
-      controller.close();
-    },
-  });
-  const compressed = source.pipeThrough(new CompressionStream("deflate-raw"));
-  return new Uint8Array(await new Response(compressed).arrayBuffer());
-}
-
-/**
- * LE u32 write in place.
- * @param {Uint8Array} buf
- * @param {number} off
- * @param {number} value
- * @returns {void}
- */
-function patchU32(buf, off, value) {
-  buf[off] = value & 0xff;
-  buf[off + 1] = (value >>> 8) & 0xff;
-  buf[off + 2] = (value >>> 16) & 0xff;
-  buf[off + 3] = (value >>> 24) & 0xff;
-}
-
-/** @param {Uint8Array[]} parts @param {number} total @returns {Uint8Array} */
-function concatBytes(parts, total) {
-  const out = new Uint8Array(total);
-  let at = 0;
-  for (const p of parts) {
-    out.set(p, at);
-    at += p.length;
-  }
-  return out;
-}
-
-/**
- * Serialise the package, substituting new UNCOMPRESSED content for the part
- * names in `replacements`. Parts not named there are emitted as the exact
- * original bytes. `entries` must be the `parseZipContainer(packageBytes)` output
- * (piece 1's provenance), and `packageBytes` the buffer those offsets address.
- *
- * @param {Uint8Array} packageBytes  the original .docx bytes
- * @param {import("./zip-container.js").ZipEntry[]} entries  physical order (parseZipContainer sorts them)
- * @param {Record<string, Uint8Array>} replacements  partName -> new uncompressed bytes
- * @returns {Promise<Uint8Array>}
- */
-export async function writePackage(packageBytes, entries, replacements) {
-  const names = new Set(entries.map((e) => e.name));
-  for (const name of Object.keys(replacements)) {
-    if (!names.has(name)) {
-      throw new Error(`opc-write: replacement names a part not in the package: ${JSON.stringify(name)}`);
-    }
-  }
-
-  const eocdOffset = findEocd(packageBytes);
-  const eocdBytes = packageBytes.subarray(eocdOffset); // to the end (any zip comment included)
-
-  /** @type {Uint8Array[]} */
-  const outParts = [];
-  let outLen = 0;
-  /** @type {Map<string, number>} */
-  const newOffsets = new Map();
-  /** @type {Map<string, [number, number, number]>} */
-  const newMeta = new Map();
-
-  for (const entry of entries) {
-    newOffsets.set(entry.name, outLen);
-    const localHeader = packageBytes.subarray(entry.localHeaderOffset, entry.compressedRange.start);
-
-    if (Object.prototype.hasOwnProperty.call(replacements, entry.name)) {
-      const content = replacements[entry.name];
-      const blob = entry.method === METHOD_STORE ? content : await deflateRaw(content);
-      const header = new Uint8Array(localHeader); // OWN copy — Buffer.slice() shares memory in Node, so patch a real copy
-      const crc = crc32(content) >>> 0;
-      patchU32(header, LOC_CRC, crc);
-      patchU32(header, LOC_CSIZE, blob.length);
-      patchU32(header, LOC_USIZE, content.length);
-      outParts.push(header, blob);
-      outLen += header.length + blob.length;
-      newMeta.set(entry.name, [crc, blob.length, content.length]);
-    } else {
-      // Verbatim — the whole point (opc-bytes.py:267-269).
-      const compressed = packageBytes.subarray(entry.compressedRange.start, entry.compressedRange.end);
-      outParts.push(localHeader, compressed);
-      outLen += localHeader.length + compressed.length;
-      newMeta.set(entry.name, [entry.crc32 >>> 0, entry.compressedSize, entry.uncompressedSize]);
-    }
-  }
-
-  const cdOffset = outLen;
-  for (const entry of entries) {
-    const meta = /** @type {[number, number, number]} */ (newMeta.get(entry.name));
-    const central = new Uint8Array(packageBytes.subarray(entry.centralEntryRange.start, entry.centralEntryRange.end));
-    patchU32(central, CEN_CRC, meta[0]);
-    patchU32(central, CEN_CSIZE, meta[1]);
-    patchU32(central, CEN_USIZE, meta[2]);
-    patchU32(central, CEN_LOCAL_OFFSET, /** @type {number} */ (newOffsets.get(entry.name)));
-    outParts.push(central);
-    outLen += central.length;
-  }
-  const cdSize = outLen - cdOffset;
-
-  const eocd = new Uint8Array(eocdBytes); // real copy (see header note — Buffer.slice() aliases)
-  patchU32(eocd, EOCD_CD_SIZE, cdSize);
-  patchU32(eocd, EOCD_CD_OFFSET, cdOffset);
-  outParts.push(eocd);
-  outLen += eocd.length;
-
-  return concatBytes(outParts, outLen);
-}
+// P6 piece (2): package writer (repack). A field-for-field JS port of
+// scripts/opc-bytes.py's write_package, which was measured 46/46 byte-identical
+// on a no-op round-trip across the real corpus. Untouched parts are copied
+// VERBATIM — original local header AND compressed bytes, never re-derived — so
+// Word's own zip signature (compress method, flag bits, versions, one shared
+// timestamp) survives; only the CHANGED part is re-compressed and only CRC-32,
+// the two size fields, local-header offsets and the EOCD's cd-size/offset are
+// rewritten. That verbatim copy is §3.5 at the package level: N parts changed =
+// exactly N parts differ.
+//
+// The changed part is re-compressed with deflate-raw via CompressionStream —
+// M5 (examples/static/m5-deflate-probe.html) confirmed CompressionStream
+// ("deflate-raw") exists, round-trips and is run-to-run DETERMINISTIC in
+// Chrome AND Firefox 154 (2026-08-30, user-run, ADR-0023). Its output is NOT
+// byte-identical to Python zlib level 9 (different encoder), but §3.5
+// compares the INFLATED content, not the compressed bytes, so that is fine.
+//
+// This piece turns bytes into a valid .docx; it does NOT orchestrate the full
+// export (finding dirty parts, running the splice) — that is a later piece. Its
+// input is the original package bytes, its parsed entries (piece 1), and
+// { partName -> new UNCOMPRESSED bytes }.
+
+import { crc32 } from "./inflate.js";
+
+// Field offsets — verbatim from scripts/opc-bytes.py's constants block.
+const LOC_CRC = 14;
+const LOC_CSIZE = 18;
+const LOC_USIZE = 22;
+const CEN_CRC = 16;
+const CEN_CSIZE = 20;
+const CEN_USIZE = 24;
+const CEN_LOCAL_OFFSET = 42;
+const EOCD_CD_SIZE = 12;
+const EOCD_CD_OFFSET = 16;
+const EOCD_SIG = [0x50, 0x4b, 0x05, 0x06]; // "PK\x05\x06"
+const METHOD_STORE = 0;
+
+/**
+ * The EOCD's offset — scanned backwards over the largest legal window (a zip
+ * comment up to 65535 bytes may follow it). Mirrors opc-bytes.py's _find_eocd.
+ * @param {Uint8Array} bytes
+ * @returns {number}
+ */
+function findEocd(bytes) {
+  const window = Math.min(bytes.length, 22 + 0xffff);
+  for (let i = bytes.length - 4; i >= bytes.length - window; i -= 1) {
+    if (bytes[i] === EOCD_SIG[0] && bytes[i + 1] === EOCD_SIG[1] && bytes[i + 2] === EOCD_SIG[2] && bytes[i + 3] === EOCD_SIG[3]) {
+      return i;
+    }
+  }
+  throw new Error("opc-write: no end-of-central-directory record — not a zip file");
+}
+
+/**
+ * Raw DEFLATE of `bytes` via the platform CompressionStream (M5). Async.
+ * @param {Uint8Array} bytes
+ * @returns {Promise<Uint8Array>}
+ */
+async function deflateRaw(bytes) {
+  // ReadableStream + pipeThrough (as inflate.js does for DecompressionStream) —
+  // avoids the writer.write chunk-type friction and collects via Response.
+  const source = new ReadableStream({
+    start(controller) {
+      controller.enqueue(bytes);
+      controller.close();
+    },
+  });
+  const compressed = source.pipeThrough(new CompressionStream("deflate-raw"));
+  return new Uint8Array(await new Response(compressed).arrayBuffer());
+}
+
+/**
+ * LE u32 write in place.
+ * @param {Uint8Array} buf
+ * @param {number} off
+ * @param {number} value
+ * @returns {void}
+ */
+function patchU32(buf, off, value) {
+  buf[off] = value & 0xff;
+  buf[off + 1] = (value >>> 8) & 0xff;
+  buf[off + 2] = (value >>> 16) & 0xff;
+  buf[off + 3] = (value >>> 24) & 0xff;
+}
+
+/** @param {Uint8Array[]} parts @param {number} total @returns {Uint8Array} */
+function concatBytes(parts, total) {
+  const out = new Uint8Array(total);
+  let at = 0;
+  for (const p of parts) {
+    out.set(p, at);
+    at += p.length;
+  }
+  return out;
+}
+
+/**
+ * Serialise the package, substituting new UNCOMPRESSED content for the part
+ * names in `replacements`. Parts not named there are emitted as the exact
+ * original bytes. `entries` must be the `parseZipContainer(packageBytes)` output
+ * (piece 1's provenance), and `packageBytes` the buffer those offsets address.
+ *
+ * @param {Uint8Array} packageBytes  the original .docx bytes
+ * @param {import("./zip-container.js").ZipEntry[]} entries  physical order (parseZipContainer sorts them)
+ * @param {Record<string, Uint8Array>} replacements  partName -> new uncompressed bytes
+ * @returns {Promise<Uint8Array>}
+ */
+export async function writePackage(packageBytes, entries, replacements) {
+  const names = new Set(entries.map((e) => e.name));
+  for (const name of Object.keys(replacements)) {
+    if (!names.has(name)) {
+      throw new Error(`opc-write: replacement names a part not in the package: ${JSON.stringify(name)}`);
+    }
+  }
+
+  const eocdOffset = findEocd(packageBytes);
+  const eocdBytes = packageBytes.subarray(eocdOffset); // to the end (any zip comment included)
+
+  /** @type {Uint8Array[]} */
+  const outParts = [];
+  let outLen = 0;
+  /** @type {Map<string, number>} */
+  const newOffsets = new Map();
+  /** @type {Map<string, [number, number, number]>} */
+  const newMeta = new Map();
+
+  for (const entry of entries) {
+    newOffsets.set(entry.name, outLen);
+    const localHeader = packageBytes.subarray(entry.localHeaderOffset, entry.compressedRange.start);
+
+    if (Object.prototype.hasOwnProperty.call(replacements, entry.name)) {
+      const content = replacements[entry.name];
+      const blob = entry.method === METHOD_STORE ? content : await deflateRaw(content);
+      const header = new Uint8Array(localHeader); // OWN copy — Buffer.slice() shares memory in Node, so patch a real copy
+      const crc = crc32(content) >>> 0;
+      patchU32(header, LOC_CRC, crc);
+      patchU32(header, LOC_CSIZE, blob.length);
+      patchU32(header, LOC_USIZE, content.length);
+      outParts.push(header, blob);
+      outLen += header.length + blob.length;
+      newMeta.set(entry.name, [crc, blob.length, content.length]);
+    } else {
+      // Verbatim — the whole point (opc-bytes.py:267-269).
+      const compressed = packageBytes.subarray(entry.compressedRange.start, entry.compressedRange.end);
+      outParts.push(localHeader, compressed);
+      outLen += localHeader.length + compressed.length;
+      newMeta.set(entry.name, [entry.crc32 >>> 0, entry.compressedSize, entry.uncompressedSize]);
+    }
+  }
+
+  const cdOffset = outLen;
+  for (const entry of entries) {
+    const meta = /** @type {[number, number, number]} */ (newMeta.get(entry.name));
+    const central = new Uint8Array(packageBytes.subarray(entry.centralEntryRange.start, entry.centralEntryRange.end));
+    patchU32(central, CEN_CRC, meta[0]);
+    patchU32(central, CEN_CSIZE, meta[1]);
+    patchU32(central, CEN_USIZE, meta[2]);
+    patchU32(central, CEN_LOCAL_OFFSET, /** @type {number} */ (newOffsets.get(entry.name)));
+    outParts.push(central);
+    outLen += central.length;
+  }
+  const cdSize = outLen - cdOffset;
+
+  const eocd = new Uint8Array(eocdBytes); // real copy (see header note — Buffer.slice() aliases)
+  patchU32(eocd, EOCD_CD_SIZE, cdSize);
+  patchU32(eocd, EOCD_CD_OFFSET, cdOffset);
+  outParts.push(eocd);
+  outLen += eocd.length;
+
+  return concatBytes(outParts, outLen);
+}

package/dist/io/ooxml/provenance.js

@@ -1,93 +1,93 @@
-// anchorRanges: ContainerId/DecorationId -> the anchor's own byte range in
-// the untouched document.xml (ADR-0020 §3.5 / Karar 2). The wrapping
-// `w:drawing`/`mc:AlternateContent` is deliberately EXCLUDED — "N touched
-// boxes = exactly N anchor ranges" (§3.5), and including the wrapper would
-// pull `mc:Fallback`'s VML duplicate into the range too (ADR-0017
-// DOĞRULANMALI #5, still open — P6 must confirm this before relying on it).
-//
-// This module is intentionally thin: xml-scan.js's own elements ALREADY
-// carry `start`/`end`, so there is nothing to compute here beyond recording
-// which id owns which anchor's own range.
-
-/**
- * @typedef {Map<number, {start: number, end: number}>} AnchorRanges
- */
-
-/**
- * @returns {AnchorRanges}
- */
-export function createAnchorRanges() {
-  return new Map();
-}
-
-/**
- * @param {AnchorRanges} ranges
- * @param {number} id
- * @param {import("./xml-scan.js").XmlElement} anchor
- * @returns {void}
- */
-export function recordAnchorRange(ranges, id, anchor) {
-  ranges.set(id, { start: anchor.start, end: anchor.end });
-}
-
-/**
- * `ContainerId -> (PropRef -> the pPr/rPr byte range in the untouched
- * document.xml)`. ADR-0017's opaque blobs: the model stores only the opaque
- * `pPrRef`/`rPrRef` token, so export (P6) needs this to know WHERE to copy the
- * original bytes back from. Same `start`/`end` discipline as `anchorRanges` —
- * the elements already carry offsets, nothing is computed here.
- * @typedef {Map<number, Map<string, {start: number, end: number}>>} PropBlobs
- */
-
-/**
- * The §3.5 provenance an export must have surviving import. `packageBytes`/
- * `entries` come only from `importDocx` (the zip entry point); `convertDocument`
- * is handed an already-inflated document.xml and never sees the package, so it
- * omits them (both optional).
- *
- * 🔴 `dirty` stays UNUSED (2026-08-29, P6 parça 5 / Dilim B): it was reserved
- * for a dirty set carried on provenance itself, but both dirty sources that
- * actually shipped compute their own — `dirtyContainers`/`dirtyGeometry`
- * (value/identity compare, export.js) and the history layer's
- * `recordForwardDirty`/`verifyInverseDirty` (also export.js; the first pass
- * called it `accumulateHistoryDirty`, split in 0c67481) — neither reads or
- * writes this field.
- * Left in place rather than removed: changing `Provenance`'s shape is its own
- * decision, not a side effect of closing HIST7.
- * @typedef {object} Provenance
- * @property {Uint8Array} documentXmlBytes  inflated word/document.xml — piece 3 splices this
- * @property {AnchorRanges} anchorRanges     the same Map as the top-level `anchorRanges` field
- * @property {PropBlobs} propBlobs           ADR-0017 opaque pPr/rPr blob ranges
- * @property {Set<number>} dirty             UNUSED — see note above
- * @property {Uint8Array} [packageBytes]     original .docx bytes — piece 2 repack byte-copies untouched parts (§3.5 step 1)
- * @property {import("./zip-container.js").ZipEntry[]} [entries]  parsed zip entries (re-derivable from packageBytes)
- */
-
-/**
- * @returns {PropBlobs}
- */
-export function createPropBlobs() {
-  return new Map();
-}
-
-/**
- * Records `containerId`'s `ref` -> the element's byte range. FIRST WINS: a ref
- * recurs iff its byte content is identical (interning is by content), so every
- * occurrence's bytes reproduce the same blob — the first range is as good as
- * any, and keeping it makes the table deterministic.
- * @param {PropBlobs} propBlobs
- * @param {number} containerId
- * @param {string} ref
- * @param {import("./xml-scan.js").XmlElement} el
- * @returns {void}
- */
-export function recordPropBlob(propBlobs, containerId, ref, el) {
-  let byRef = propBlobs.get(containerId);
-  if (byRef === undefined) {
-    byRef = new Map();
-    propBlobs.set(containerId, byRef);
-  }
-  if (!byRef.has(ref)) {
-    byRef.set(ref, { start: el.start, end: el.end });
-  }
-}
+// anchorRanges: ContainerId/DecorationId -> the anchor's own byte range in
+// the untouched document.xml (ADR-0020 §3.5 / Karar 2). The wrapping
+// `w:drawing`/`mc:AlternateContent` is deliberately EXCLUDED — "N touched
+// boxes = exactly N anchor ranges" (§3.5), and including the wrapper would
+// pull `mc:Fallback`'s VML duplicate into the range too (ADR-0017
+// DOĞRULANMALI #5, still open — P6 must confirm this before relying on it).
+//
+// This module is intentionally thin: xml-scan.js's own elements ALREADY
+// carry `start`/`end`, so there is nothing to compute here beyond recording
+// which id owns which anchor's own range.
+
+/**
+ * @typedef {Map<number, {start: number, end: number}>} AnchorRanges
+ */
+
+/**
+ * @returns {AnchorRanges}
+ */
+export function createAnchorRanges() {
+  return new Map();
+}
+
+/**
+ * @param {AnchorRanges} ranges
+ * @param {number} id
+ * @param {import("./xml-scan.js").XmlElement} anchor
+ * @returns {void}
+ */
+export function recordAnchorRange(ranges, id, anchor) {
+  ranges.set(id, { start: anchor.start, end: anchor.end });
+}
+
+/**
+ * `ContainerId -> (PropRef -> the pPr/rPr byte range in the untouched
+ * document.xml)`. ADR-0017's opaque blobs: the model stores only the opaque
+ * `pPrRef`/`rPrRef` token, so export (P6) needs this to know WHERE to copy the
+ * original bytes back from. Same `start`/`end` discipline as `anchorRanges` —
+ * the elements already carry offsets, nothing is computed here.
+ * @typedef {Map<number, Map<string, {start: number, end: number}>>} PropBlobs
+ */
+
+/**
+ * The §3.5 provenance an export must have surviving import. `packageBytes`/
+ * `entries` come only from `importDocx` (the zip entry point); `convertDocument`
+ * is handed an already-inflated document.xml and never sees the package, so it
+ * omits them (both optional).
+ *
+ * 🔴 `dirty` stays UNUSED (2026-08-29, P6 parça 5 / Dilim B): it was reserved
+ * for a dirty set carried on provenance itself, but both dirty sources that
+ * actually shipped compute their own — `dirtyContainers`/`dirtyGeometry`
+ * (value/identity compare, export.js) and the history layer's
+ * `recordForwardDirty`/`verifyInverseDirty` (also export.js; the first pass
+ * called it `accumulateHistoryDirty`, split in 0c67481) — neither reads or
+ * writes this field.
+ * Left in place rather than removed: changing `Provenance`'s shape is its own
+ * decision, not a side effect of closing HIST7.
+ * @typedef {object} Provenance
+ * @property {Uint8Array} documentXmlBytes  inflated word/document.xml — piece 3 splices this
+ * @property {AnchorRanges} anchorRanges     the same Map as the top-level `anchorRanges` field
+ * @property {PropBlobs} propBlobs           ADR-0017 opaque pPr/rPr blob ranges
+ * @property {Set<number>} dirty             UNUSED — see note above
+ * @property {Uint8Array} [packageBytes]     original .docx bytes — piece 2 repack byte-copies untouched parts (§3.5 step 1)
+ * @property {import("./zip-container.js").ZipEntry[]} [entries]  parsed zip entries (re-derivable from packageBytes)
+ */
+
+/**
+ * @returns {PropBlobs}
+ */
+export function createPropBlobs() {
+  return new Map();
+}
+
+/**
+ * Records `containerId`'s `ref` -> the element's byte range. FIRST WINS: a ref
+ * recurs iff its byte content is identical (interning is by content), so every
+ * occurrence's bytes reproduce the same blob — the first range is as good as
+ * any, and keeping it makes the table deterministic.
+ * @param {PropBlobs} propBlobs
+ * @param {number} containerId
+ * @param {string} ref
+ * @param {import("./xml-scan.js").XmlElement} el
+ * @returns {void}
+ */
+export function recordPropBlob(propBlobs, containerId, ref, el) {
+  let byRef = propBlobs.get(containerId);
+  if (byRef === undefined) {
+    byRef = new Map();
+    propBlobs.set(containerId, byRef);
+  }
+  if (!byRef.has(ref)) {
+    byRef.set(ref, { start: el.start, end: el.end });
+  }
+}