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

package/dist/io/ooxml/export.js

@@ -1,365 +1,365 @@
-// P6 piece (3): export orchestration. The whole import -> edit -> export path
-// in one call: which containers changed (dirty), splice each one's new
-// txbxContent into the untouched document.xml (piece 4b), then repack into a
-// valid .docx (piece 2). This is where the FIRST real .docx comes out.
-//
-// LIMITS (narrow, by design): plain-text only (no rPr/pPr — piece 7); existing
-// containers' text changes only (no new anchor).
-//
-// DIRTY SOURCE (piece 5 / Dilim B, 2026-08-29): content dirty is the model's
-// own structural sharing (identity inequality); geometry dirty is a VALUE
-// compare of the layout branch (`dirtyGeometry`). Both stay the PRODUCTION
-// source — a taşı-sonra-geri-al must export byte-identical, which only a
-// value compare gives for free. `recordForwardDirty`/`verifyInverseDirty`
-// below are the HISTORY-driven half ADR-0023 originally expected to be the
-// dirty source itself; it turned out narrower and more useful as a
-// TRACEABILITY layer: `recordForwardDirty` remembers which keys a forward
-// setLayout named, `verifyInverseDirty` checks an undo's inverse step never
-// names a key no forward step named — HIST7's own guarantee
-// ("invertSetLayout restores only the patched keys"), made observable at the
-// one point in the codebase that rule has a real consequence. A same-set
-// check ("history exactly equals value-dirty") was tried and REJECTED,
-// measured to false-positive on two healthy paths: `commands/box.js`'s own
-// full-key patch (`{x, y}` for an x-only move, so drag coalescing keeps
-// working) and a taşı-sonra-geri-al itself (history stays populated, value
-// compare goes empty — §3.5's own guarantee, not a bug). `exportDocx`'s
-// optional `historyDirty` gate is the third, complementary check: it catches
-// a layout-mutating path that was never wired to this tracker at all.
-
-import { spliceDirty } from "./export-splice.js";
-import { writePackage } from "./opc-write.js";
-import { resolveMainDocumentPart } from "./zip-container.js";
-import { containerById, LAYOUT_KEYS } from "../../model/node.js";
-
-/**
- * The layout keys the geometry splice can WRITE today.
- *
- * `x`/`y` live in `wp:posOffset` as plain digits and have exactly one live copy
- * (measured: `a:off` is `x="0" y="0"` on 7,990/7,990 corpus containers).
- * @type {ReadonlySet<string>}
- */
-export const WRITABLE_LAYOUT_KEYS = new Set(["x", "y"]);
-
-/**
- * Every other layout key, with the reason it is refused. Together with
- * `WRITABLE_LAYOUT_KEYS` this must PARTITION `LAYOUT_KEYS` — a key that is
- * neither written nor deliberately refused would export as silent nothing,
- * which is exactly the bug this slice exists to fix, moved one layer up. The
- * partition is a gate in `test/io/export-geometry.test.js`.
- * @type {Readonly<Record<string, string>>}
- */
-export const REFUSED_LAYOUT_KEYS = Object.freeze({
-  cx: "size has TWO live copies in mc:Choice (wp:extent AND wps:spPr/a:xfrm/a:ext, 7990/7990) — writing one leaves the other stale; own slice",
-  cy: "same as cx",
-  z: "z is wp:anchor@relativeHeight, an ATTRIBUTE — xml-scan keeps no attribute offsets, so it needs the open-tag re-emit path; own slice",
-  page: "changing the page means MOVING the w:drawing inside the body, not editing an attribute — permanently out of this design",
-  rot: "rotation is never rendered by this editor (FIDELITY: DEGRADED); writing it would claim a fidelity we do not have",
-  flipH: "same as rot",
-  flipV: "same as rot",
-  locked: "a model-only affordance flag; it has no OOXML counterpart to write",
-});
-
-/**
- * The `pPrOverride` keys the pPr splice can WRITE today (ADR-0030).
- *
- * All four live as attributes of a single `<w:ind>` element, and the corpus
- * carries no others on it: measured 2026-08-31 across 46/46 documents, `w:ind`
- * appears with exactly these four attribute names in 9 distinct combinations,
- * every one a subset of this set — `w:start`/`w:end`/`w:leftChars`/
- * `w:rightChars`/`w:firstLineChars`/`w:hangingChars` are 0/46. So these four
- * fully cover this corpus; the emitter still carries unmodelled attributes
- * forward, because they exist in the schema and the protection is free.
- * @type {ReadonlySet<string>}
- */
-export const WRITABLE_PPR_KEYS = new Set([
-  "ind.left",
-  "ind.right",
-  "ind.firstLine",
-  "ind.hanging",
-]);
-
-/**
- * Every other key `readPPr` can produce, with the reason it is refused.
- * Together with `WRITABLE_PPR_KEYS` this must PARTITION `readPPr`'s own output
- * — the same contract, and the same reason, as
- * `WRITABLE_LAYOUT_KEYS`/`REFUSED_LAYOUT_KEYS` above: a key that is neither
- * written nor deliberately refused would export as silent nothing. The
- * partition is a gate in `test/io/export-rpr.test.js` ("GATE (ADR-0030): ...
- * PARTITION readPPr's own output"; a separate `export-ppr.test.js` was never
- * created), driven by calling
- * `readPPr` on a pPr carrying every field rather than by a hand-written list.
- * @type {Readonly<Record<string, string>>}
- */
-export const REFUSED_PPR_KEYS = Object.freeze({
-  jc: "not an override key at all — alignment is its own Paragraph.jc field (ADR-0029/ADR-0030 Karar 2), emitted by emitParagraphProps' own jc branch",
-  "spacing.before": "own slice; the spacing measurement is recorded in ADR-0030 but no decision was made",
-  "spacing.after": "same as spacing.before (and measured to have exactly ONE distinct corpus value, \"0\")",
-  "spacing.line": "same as spacing.before, and coupled to spacing.lineRule — the two always co-occur (4256/4256)",
-  "spacing.lineRule":
-    "the UI's 1.0/1.15/1.5 multipliers only mean anything under lineRule=auto, but 52% of corpus line-carrying paragraphs use `exact`; writing a multiplier would CHANGE the rule. Measured, not decided — ADR-0030 kapsam dışı",
-  "numPr.ilvl": "list numbering is a separate subsystem (numbering.xml), never a direct paragraph override",
-  "numPr.numId": "same as numPr.ilvl",
-  "numPr.marker":
-    "not a readPPr key at all — import.js ADDS it after the style cascade, resolved from numbering.xml; display-only, never written back",
-});
-
-/**
- * Container ids whose content changed between the imported document and the
- * current one. Relies on the model's structural sharing: an edit rebuilds only
- * the touched container (and its ancestors), leaving every other container `===`
- * its original — so identity inequality means "touched". A container present in
- * `currentDoc` but not `originalDoc` (a NEW box) is reported dirty too; export
- * then rejects it (no anchor range) — new-anchor writing is a later slice.
- *
- * @param {import("../../model/node.js").Doc} originalDoc  the imported document
- * @param {import("../../model/node.js").Doc} currentDoc   the edited document
- * @returns {Set<import("../../model/node.js").NodeId>}
- */
-export function dirtyContainers(originalDoc, currentDoc) {
-  /** @type {Set<import("../../model/node.js").NodeId>} */
-  const dirty = new Set();
-  for (const container of currentDoc.content) {
-    const original = containerById(originalDoc, container.id);
-    if (original === null || original !== container) {
-      dirty.add(container.id);
-    }
-  }
-  return dirty;
-}
-
-/**
- * Which boxes' GEOMETRY changed, and which layout keys changed on each.
- *
- * The layout branch is compared by VALUE, key by key — the mirror of
- * `dirtyContainers`' identity compare on the content branch, and for the same
- * reason: `applySetLayout` rebuilds only `doc.layout`, so a move leaves every
- * `Container` `===` and the content-side signal cannot see it at all.
- *
- * Value (not identity) compare on purpose, twice over:
- *   - `patchLayout` mints a NEW entry object even when a drag returns a box to
- *     where it started, so identity would report a move that did not happen;
- *   - the commands deliberately patch the FULL key set (`{x, y}` for a move even
- *     when only x changed) so `HistoryEngine`'s drag coalescing keeps working —
- *     value compare narrows that back down to the keys that really moved, which
- *     is what §3.5's dirty-KEY guarantee needs.
- *
- * Iterates `currentDoc.content`, never `provenance.anchorRanges`: that map also
- * holds DECORATION ids, and decorations (like images) are render-only and must
- * never be written (ADR-0015 / ADR-0020 K6).
- *
- * @param {import("../../model/node.js").Doc} originalDoc  the imported document
- * @param {import("../../model/node.js").Doc} currentDoc   the edited document
- * @returns {Map<import("../../model/node.js").NodeId, Set<string>>}  id -> changed keys
- */
-export function dirtyGeometry(originalDoc, currentDoc) {
-  /** @type {Map<import("../../model/node.js").NodeId, Set<string>>} */
-  const dirty = new Map();
-  for (const container of currentDoc.content) {
-    const before = originalDoc.layout[container.id];
-    const after = currentDoc.layout[container.id];
-    if (before === undefined || after === undefined || before === after) {
-      continue; // not a positioned box, brand new, or provably untouched
-    }
-    /** @type {Set<string>} */
-    const changed = new Set();
-    for (const key of LAYOUT_KEYS) {
-      if (before[key] !== after[key]) {
-        changed.add(key);
-      }
-    }
-    if (changed.size > 0) {
-      dirty.set(container.id, changed);
-    }
-  }
-  return dirty;
-}
-
-/**
- * Folds the layout keys ONE transaction's steps NAME into a running dirty map —
- * P6 parça (5) / Dilim B's history-driven tracking.
- *
- * 🔴 This is NOT the production dirty source (that stays `dirtyGeometry`'s value
- * compare — see the module doc comment on why). Its job is narrower and real:
- * it is what makes `invertSetLayout`'s "restores only the PATCHED keys, not
- * every key" guarantee (`step-invert.js`) have an actual consumer. Before this,
- * that guarantee was checked only by a shape assertion inspecting a returned
- * step's own `patch` object (`step-invert.test.js`) — HIST7's mutation record
- * could not point at any behavior it broke, because nothing downstream ever
- * READ which keys a step named. This function is that reader: call it on every
- * dispatched transaction's `steps`/`docBefore` (forward, undo, AND redo — a
- * `HistoryEngine.undo()`/`redo()` result is a real `Transaction`, walked the
- * same way), and the accumulated set becomes:
- *   - a REAL behavioral test for HIST7 (see the mutation's own test file), and
- *   - `exportDocx`'s optional consistency gate (`historyDirty` param below):
- *     every key the value compare finds dirty must appear here too, or a
- *     layout-mutating path exists that this tracker was never wired to.
- *
- * Only `setLayout` steps carry layout keys; every other step type is a no-op
- * here (mirrors `dirtyContainerIds`' own switch).
- *
- * @param {Map<import("../../model/node.js").NodeId, Set<string>>} dirty  mutated in place
- * @param {import("../../model/node.js").Doc} docBefore  unused today (kept for
- *   symmetry with `dirtyContainerIds(doc, step)` and because a future step type
- *   may need to resolve state that only `docBefore` has)
- * @param {import("../../model/step.js").Step[]} steps
- * @returns {Map<import("../../model/node.js").NodeId, Set<string>>}  `dirty`, for chaining
- */
-export function recordForwardDirty(dirty, docBefore, steps) {
-  void docBefore;
-  for (const step of steps) {
-    if (step.type !== "setLayout") {
-      continue;
-    }
-    const keys = dirty.get(step.containerId) ?? new Set();
-    for (const key of Object.keys(step.patch)) {
-      keys.add(key);
-    }
-    dirty.set(step.containerId, keys);
-  }
-  return dirty;
-}
-
-/**
- * Verifies an INVERSE transaction's `setLayout` steps (a `HistoryEngine.undo()`
- * result) name ONLY keys a forward step already recorded via
- * `recordForwardDirty` — i.e. `invertSetLayout` never invents a key no forward
- * step ever patched.
- *
- * This is HIST7's guarantee made observable, and observable in a way a naive
- * "history set equals value-dirty set" check is NOT: that check has two false-
- * positive sources that are both completely healthy —
- *   (a) `commands/box.js` deliberately patches the FULL key set (`{x, y}` for a
- *       move even when only x changed, so `HistoryEngine`'s drag coalescing
- *       keeps working) — a value compare narrows this, but `dirty` here still
- *       legitimately carries `y` even when only `x` moved;
- *   (b) a taşı-sonra-geri-al leaves `dirty` populated (traceability) while the
- *       value compare is empty (nothing to write) — that is §3.5's own "zero
- *       touch = zero difference" guarantee, not a bug.
- * Both would make a same-set check throw on healthy input. The check that
- * actually isolates HIST7's own claim is narrower: an INVERSE step may only
- * name keys its OWN forward step already named — box.js's `{x, y}` patch is
- * still fine (both keys were forward-named), but a whole-entry inverse
- * (`{...before}`, the HIST7 mutation) names `page`/`cx`/`cy`/`z`/… that no
- * forward step for that container ever patched, and THAT throws.
- *
- * @param {Map<import("../../model/node.js").NodeId, Set<string>>} known  the
- *   Map `recordForwardDirty` has been accumulating — read, never mutated here
- * @param {import("../../model/node.js").Doc} docBefore  unused today, kept for
- *   symmetry with `recordForwardDirty`/`dirtyContainerIds`
- * @param {import("../../model/step.js").Step[]} steps  an inverse transaction's steps
- * @returns {void}
- */
-export function verifyInverseDirty(known, docBefore, steps) {
-  void docBefore;
-  for (const step of steps) {
-    if (step.type !== "setLayout") {
-      continue;
-    }
-    const knownKeys = known.get(step.containerId);
-    for (const key of Object.keys(step.patch)) {
-      if (knownKeys === undefined || !knownKeys.has(key)) {
-        throw new Error(
-          `verifyInverseDirty: container ${step.containerId}'s inverse names '${key}', which no forward ` +
-            "step ever patched — invertSetLayout is restoring a key it should not (HIST7)",
-        );
-      }
-    }
-  }
-}
-
-/**
- * @typedef {object} DegradedImageWarning
- * @property {string | null} name
- * @property {number[]} sharedContainerIds  the editable container id(s) from
- *   this image's own anchor — the box the user would be editing when this
- *   image is at risk
- */
-
-/**
- * @typedef {object} ExportReport
- * @property {import("./export-splice.js").SkippedGeometry[]} skippedGeometry
- *   geometry changes this export could NOT write, with the reason. NEVER
- *   silent: a box the user moved on screen whose new position did not reach the
- *   file has to be visible, or we repeat the exact surprise this slice fixes.
- * @property {DegradedImageWarning[]} degradedImages  ADR-0020 Karar 6's
- *   DEGRADED images (`importResult.report.skippedImages`, filtered) —
- *   surfaced again HERE, not just at import time, because export/save is the
- *   moment the risk (P6 anchor regeneration would silently drop this image)
- *   actually matters to the user. Classification itself is untouched: this
- *   reads what `importDocx` already computed, it does not recompute anything.
- *   Bytes are unaffected — `word/media/*` stays verbatim/PRESERVED either
- *   way (§3.5); this field is warning-only, like `skippedGeometry`.
- */
-
-/**
- * A .docx for `currentDoc`, produced by splicing only the touched containers'
- * text and geometry into `importResult`'s untouched original bytes and
- * repacking. Zero edits -> a byte-identical copy of the imported file (no part
- * is re-compressed): the strongest form of §3.5's "zero touch = zero difference".
- *
- * Returns the report alongside the bytes — deliberately, so a caller cannot get
- * the file without also receiving what did not make it into the file. Mirrors
- * `importDocx`'s own `{doc, …, report}` shape.
- *
- * @param {import("./import.js").ConvertResult} importResult  what `importDocx` returned (carries `doc` + `provenance`)
- * @param {import("../../model/node.js").Doc} currentDoc  the edited document (from EditorState)
- * @param {object} [options]
- * @param {Map<import("../../model/node.js").NodeId, Set<string>>} [options.historyDirty]
- *   the running `recordForwardDirty` map, if the caller tracks one. NOT the
- *   dirty source — `dirtyGeometry`'s value compare still decides what gets
- *   written, so a taşı-sonra-geri-al still exports byte-identical even though
- *   `historyDirty` still names the keys those steps touched. When given, it is
- *   a ONE-WAY consistency gate: every key the value compare finds dirty MUST
- *   be present here, or a layout-mutating path exists that never called
- *   `recordForwardDirty` — a real bug, thrown loudly rather than silently
- *   exported with no traceability. The reverse (a key tracked but not
- *   value-dirty) is the NORMAL taşı-sonra-geri-al case and is not an error.
- *   This gate catches a DIFFERENT regression than `verifyInverseDirty`: a
- *   forgotten wiring, not an inverse naming a key it should not.
- * @returns {Promise<{bytes: Uint8Array, report: ExportReport}>}
- */
-export async function exportDocx(importResult, currentDoc, { historyDirty } = {}) {
-  const { provenance } = importResult;
-  if (provenance.packageBytes === undefined || provenance.entries === undefined) {
-    // convertDocument's provenance is document-level only; export needs the
-    // retained package importDocx adds (piece 1). This guards a misuse and
-    // narrows the optional fields for the type checker.
-    throw new Error("exportDocx requires importDocx's provenance (packageBytes + entries)");
-  }
-  const dirty = dirtyContainers(importResult.doc, currentDoc);
-  const geometry = dirtyGeometry(importResult.doc, currentDoc);
-
-  if (historyDirty !== undefined) {
-    for (const [id, keys] of geometry) {
-      const tracked = historyDirty.get(id);
-      for (const key of keys) {
-        if (tracked === undefined || !tracked.has(key)) {
-          throw new Error(
-            `exportDocx: container ${id}'s '${key}' is dirty by value but was never tracked by ` +
-              "recordForwardDirty — a layout-mutating path exists that history tracking is not wired to",
-          );
-        }
-      }
-    }
-  }
-
-  const { bytes: newDocumentXml, skippedGeometry } = spliceDirty(provenance, currentDoc, {
-    textIds: dirty,
-    geometry,
-    originalDoc: importResult.doc,
-  });
-  // spliceDirty returns the ORIGINAL bytes (same reference) when nothing was
-  // written; in that case repack with NO replacement, so document.xml is copied
-  // verbatim and the whole .docx comes out byte-identical (not merely
-  // inflate-identical). Otherwise the changed document.xml is the one replacement.
-  const replacements =
-    newDocumentXml === provenance.documentXmlBytes
-      ? {}
-      : { [resolveMainDocumentPart(provenance.entries).name]: newDocumentXml };
-
-  const bytes = await writePackage(provenance.packageBytes, provenance.entries, replacements);
-  const degradedImages = importResult.report.skippedImages
-    .filter((img) => img.fidelity === "DEGRADED")
-    .map((img) => ({ name: img.name, sharedContainerIds: img.sharedContainerIds }));
-  return { bytes, report: { skippedGeometry, degradedImages } };
-}
+// P6 piece (3): export orchestration. The whole import -> edit -> export path
+// in one call: which containers changed (dirty), splice each one's new
+// txbxContent into the untouched document.xml (piece 4b), then repack into a
+// valid .docx (piece 2). This is where the FIRST real .docx comes out.
+//
+// LIMITS (narrow, by design): plain-text only (no rPr/pPr — piece 7); existing
+// containers' text changes only (no new anchor).
+//
+// DIRTY SOURCE (piece 5 / Dilim B, 2026-08-29): content dirty is the model's
+// own structural sharing (identity inequality); geometry dirty is a VALUE
+// compare of the layout branch (`dirtyGeometry`). Both stay the PRODUCTION
+// source — a taşı-sonra-geri-al must export byte-identical, which only a
+// value compare gives for free. `recordForwardDirty`/`verifyInverseDirty`
+// below are the HISTORY-driven half ADR-0023 originally expected to be the
+// dirty source itself; it turned out narrower and more useful as a
+// TRACEABILITY layer: `recordForwardDirty` remembers which keys a forward
+// setLayout named, `verifyInverseDirty` checks an undo's inverse step never
+// names a key no forward step named — HIST7's own guarantee
+// ("invertSetLayout restores only the patched keys"), made observable at the
+// one point in the codebase that rule has a real consequence. A same-set
+// check ("history exactly equals value-dirty") was tried and REJECTED,
+// measured to false-positive on two healthy paths: `commands/box.js`'s own
+// full-key patch (`{x, y}` for an x-only move, so drag coalescing keeps
+// working) and a taşı-sonra-geri-al itself (history stays populated, value
+// compare goes empty — §3.5's own guarantee, not a bug). `exportDocx`'s
+// optional `historyDirty` gate is the third, complementary check: it catches
+// a layout-mutating path that was never wired to this tracker at all.
+
+import { spliceDirty } from "./export-splice.js";
+import { writePackage } from "./opc-write.js";
+import { resolveMainDocumentPart } from "./zip-container.js";
+import { containerById, LAYOUT_KEYS } from "../../model/node.js";
+
+/**
+ * The layout keys the geometry splice can WRITE today.
+ *
+ * `x`/`y` live in `wp:posOffset` as plain digits and have exactly one live copy
+ * (measured: `a:off` is `x="0" y="0"` on 7,990/7,990 corpus containers).
+ * @type {ReadonlySet<string>}
+ */
+export const WRITABLE_LAYOUT_KEYS = new Set(["x", "y"]);
+
+/**
+ * Every other layout key, with the reason it is refused. Together with
+ * `WRITABLE_LAYOUT_KEYS` this must PARTITION `LAYOUT_KEYS` — a key that is
+ * neither written nor deliberately refused would export as silent nothing,
+ * which is exactly the bug this slice exists to fix, moved one layer up. The
+ * partition is a gate in `test/io/export-geometry.test.js`.
+ * @type {Readonly<Record<string, string>>}
+ */
+export const REFUSED_LAYOUT_KEYS = Object.freeze({
+  cx: "size has TWO live copies in mc:Choice (wp:extent AND wps:spPr/a:xfrm/a:ext, 7990/7990) — writing one leaves the other stale; own slice",
+  cy: "same as cx",
+  z: "z is wp:anchor@relativeHeight, an ATTRIBUTE — xml-scan keeps no attribute offsets, so it needs the open-tag re-emit path; own slice",
+  page: "changing the page means MOVING the w:drawing inside the body, not editing an attribute — permanently out of this design",
+  rot: "rotation is never rendered by this editor (FIDELITY: DEGRADED); writing it would claim a fidelity we do not have",
+  flipH: "same as rot",
+  flipV: "same as rot",
+  locked: "a model-only affordance flag; it has no OOXML counterpart to write",
+});
+
+/**
+ * The `pPrOverride` keys the pPr splice can WRITE today (ADR-0030).
+ *
+ * All four live as attributes of a single `<w:ind>` element, and the corpus
+ * carries no others on it: measured 2026-08-31 across 46/46 documents, `w:ind`
+ * appears with exactly these four attribute names in 9 distinct combinations,
+ * every one a subset of this set — `w:start`/`w:end`/`w:leftChars`/
+ * `w:rightChars`/`w:firstLineChars`/`w:hangingChars` are 0/46. So these four
+ * fully cover this corpus; the emitter still carries unmodelled attributes
+ * forward, because they exist in the schema and the protection is free.
+ * @type {ReadonlySet<string>}
+ */
+export const WRITABLE_PPR_KEYS = new Set([
+  "ind.left",
+  "ind.right",
+  "ind.firstLine",
+  "ind.hanging",
+]);
+
+/**
+ * Every other key `readPPr` can produce, with the reason it is refused.
+ * Together with `WRITABLE_PPR_KEYS` this must PARTITION `readPPr`'s own output
+ * — the same contract, and the same reason, as
+ * `WRITABLE_LAYOUT_KEYS`/`REFUSED_LAYOUT_KEYS` above: a key that is neither
+ * written nor deliberately refused would export as silent nothing. The
+ * partition is a gate in `test/io/export-rpr.test.js` ("GATE (ADR-0030): ...
+ * PARTITION readPPr's own output"; a separate `export-ppr.test.js` was never
+ * created), driven by calling
+ * `readPPr` on a pPr carrying every field rather than by a hand-written list.
+ * @type {Readonly<Record<string, string>>}
+ */
+export const REFUSED_PPR_KEYS = Object.freeze({
+  jc: "not an override key at all — alignment is its own Paragraph.jc field (ADR-0029/ADR-0030 Karar 2), emitted by emitParagraphProps' own jc branch",
+  "spacing.before": "own slice; the spacing measurement is recorded in ADR-0030 but no decision was made",
+  "spacing.after": "same as spacing.before (and measured to have exactly ONE distinct corpus value, \"0\")",
+  "spacing.line": "same as spacing.before, and coupled to spacing.lineRule — the two always co-occur (4256/4256)",
+  "spacing.lineRule":
+    "the UI's 1.0/1.15/1.5 multipliers only mean anything under lineRule=auto, but 52% of corpus line-carrying paragraphs use `exact`; writing a multiplier would CHANGE the rule. Measured, not decided — ADR-0030 kapsam dışı",
+  "numPr.ilvl": "list numbering is a separate subsystem (numbering.xml), never a direct paragraph override",
+  "numPr.numId": "same as numPr.ilvl",
+  "numPr.marker":
+    "not a readPPr key at all — import.js ADDS it after the style cascade, resolved from numbering.xml; display-only, never written back",
+});
+
+/**
+ * Container ids whose content changed between the imported document and the
+ * current one. Relies on the model's structural sharing: an edit rebuilds only
+ * the touched container (and its ancestors), leaving every other container `===`
+ * its original — so identity inequality means "touched". A container present in
+ * `currentDoc` but not `originalDoc` (a NEW box) is reported dirty too; export
+ * then rejects it (no anchor range) — new-anchor writing is a later slice.
+ *
+ * @param {import("../../model/node.js").Doc} originalDoc  the imported document
+ * @param {import("../../model/node.js").Doc} currentDoc   the edited document
+ * @returns {Set<import("../../model/node.js").NodeId>}
+ */
+export function dirtyContainers(originalDoc, currentDoc) {
+  /** @type {Set<import("../../model/node.js").NodeId>} */
+  const dirty = new Set();
+  for (const container of currentDoc.content) {
+    const original = containerById(originalDoc, container.id);
+    if (original === null || original !== container) {
+      dirty.add(container.id);
+    }
+  }
+  return dirty;
+}
+
+/**
+ * Which boxes' GEOMETRY changed, and which layout keys changed on each.
+ *
+ * The layout branch is compared by VALUE, key by key — the mirror of
+ * `dirtyContainers`' identity compare on the content branch, and for the same
+ * reason: `applySetLayout` rebuilds only `doc.layout`, so a move leaves every
+ * `Container` `===` and the content-side signal cannot see it at all.
+ *
+ * Value (not identity) compare on purpose, twice over:
+ *   - `patchLayout` mints a NEW entry object even when a drag returns a box to
+ *     where it started, so identity would report a move that did not happen;
+ *   - the commands deliberately patch the FULL key set (`{x, y}` for a move even
+ *     when only x changed) so `HistoryEngine`'s drag coalescing keeps working —
+ *     value compare narrows that back down to the keys that really moved, which
+ *     is what §3.5's dirty-KEY guarantee needs.
+ *
+ * Iterates `currentDoc.content`, never `provenance.anchorRanges`: that map also
+ * holds DECORATION ids, and decorations (like images) are render-only and must
+ * never be written (ADR-0015 / ADR-0020 K6).
+ *
+ * @param {import("../../model/node.js").Doc} originalDoc  the imported document
+ * @param {import("../../model/node.js").Doc} currentDoc   the edited document
+ * @returns {Map<import("../../model/node.js").NodeId, Set<string>>}  id -> changed keys
+ */
+export function dirtyGeometry(originalDoc, currentDoc) {
+  /** @type {Map<import("../../model/node.js").NodeId, Set<string>>} */
+  const dirty = new Map();
+  for (const container of currentDoc.content) {
+    const before = originalDoc.layout[container.id];
+    const after = currentDoc.layout[container.id];
+    if (before === undefined || after === undefined || before === after) {
+      continue; // not a positioned box, brand new, or provably untouched
+    }
+    /** @type {Set<string>} */
+    const changed = new Set();
+    for (const key of LAYOUT_KEYS) {
+      if (before[key] !== after[key]) {
+        changed.add(key);
+      }
+    }
+    if (changed.size > 0) {
+      dirty.set(container.id, changed);
+    }
+  }
+  return dirty;
+}
+
+/**
+ * Folds the layout keys ONE transaction's steps NAME into a running dirty map —
+ * P6 parça (5) / Dilim B's history-driven tracking.
+ *
+ * 🔴 This is NOT the production dirty source (that stays `dirtyGeometry`'s value
+ * compare — see the module doc comment on why). Its job is narrower and real:
+ * it is what makes `invertSetLayout`'s "restores only the PATCHED keys, not
+ * every key" guarantee (`step-invert.js`) have an actual consumer. Before this,
+ * that guarantee was checked only by a shape assertion inspecting a returned
+ * step's own `patch` object (`step-invert.test.js`) — HIST7's mutation record
+ * could not point at any behavior it broke, because nothing downstream ever
+ * READ which keys a step named. This function is that reader: call it on every
+ * dispatched transaction's `steps`/`docBefore` (forward, undo, AND redo — a
+ * `HistoryEngine.undo()`/`redo()` result is a real `Transaction`, walked the
+ * same way), and the accumulated set becomes:
+ *   - a REAL behavioral test for HIST7 (see the mutation's own test file), and
+ *   - `exportDocx`'s optional consistency gate (`historyDirty` param below):
+ *     every key the value compare finds dirty must appear here too, or a
+ *     layout-mutating path exists that this tracker was never wired to.
+ *
+ * Only `setLayout` steps carry layout keys; every other step type is a no-op
+ * here (mirrors `dirtyContainerIds`' own switch).
+ *
+ * @param {Map<import("../../model/node.js").NodeId, Set<string>>} dirty  mutated in place
+ * @param {import("../../model/node.js").Doc} docBefore  unused today (kept for
+ *   symmetry with `dirtyContainerIds(doc, step)` and because a future step type
+ *   may need to resolve state that only `docBefore` has)
+ * @param {import("../../model/step.js").Step[]} steps
+ * @returns {Map<import("../../model/node.js").NodeId, Set<string>>}  `dirty`, for chaining
+ */
+export function recordForwardDirty(dirty, docBefore, steps) {
+  void docBefore;
+  for (const step of steps) {
+    if (step.type !== "setLayout") {
+      continue;
+    }
+    const keys = dirty.get(step.containerId) ?? new Set();
+    for (const key of Object.keys(step.patch)) {
+      keys.add(key);
+    }
+    dirty.set(step.containerId, keys);
+  }
+  return dirty;
+}
+
+/**
+ * Verifies an INVERSE transaction's `setLayout` steps (a `HistoryEngine.undo()`
+ * result) name ONLY keys a forward step already recorded via
+ * `recordForwardDirty` — i.e. `invertSetLayout` never invents a key no forward
+ * step ever patched.
+ *
+ * This is HIST7's guarantee made observable, and observable in a way a naive
+ * "history set equals value-dirty set" check is NOT: that check has two false-
+ * positive sources that are both completely healthy —
+ *   (a) `commands/box.js` deliberately patches the FULL key set (`{x, y}` for a
+ *       move even when only x changed, so `HistoryEngine`'s drag coalescing
+ *       keeps working) — a value compare narrows this, but `dirty` here still
+ *       legitimately carries `y` even when only `x` moved;
+ *   (b) a taşı-sonra-geri-al leaves `dirty` populated (traceability) while the
+ *       value compare is empty (nothing to write) — that is §3.5's own "zero
+ *       touch = zero difference" guarantee, not a bug.
+ * Both would make a same-set check throw on healthy input. The check that
+ * actually isolates HIST7's own claim is narrower: an INVERSE step may only
+ * name keys its OWN forward step already named — box.js's `{x, y}` patch is
+ * still fine (both keys were forward-named), but a whole-entry inverse
+ * (`{...before}`, the HIST7 mutation) names `page`/`cx`/`cy`/`z`/… that no
+ * forward step for that container ever patched, and THAT throws.
+ *
+ * @param {Map<import("../../model/node.js").NodeId, Set<string>>} known  the
+ *   Map `recordForwardDirty` has been accumulating — read, never mutated here
+ * @param {import("../../model/node.js").Doc} docBefore  unused today, kept for
+ *   symmetry with `recordForwardDirty`/`dirtyContainerIds`
+ * @param {import("../../model/step.js").Step[]} steps  an inverse transaction's steps
+ * @returns {void}
+ */
+export function verifyInverseDirty(known, docBefore, steps) {
+  void docBefore;
+  for (const step of steps) {
+    if (step.type !== "setLayout") {
+      continue;
+    }
+    const knownKeys = known.get(step.containerId);
+    for (const key of Object.keys(step.patch)) {
+      if (knownKeys === undefined || !knownKeys.has(key)) {
+        throw new Error(
+          `verifyInverseDirty: container ${step.containerId}'s inverse names '${key}', which no forward ` +
+            "step ever patched — invertSetLayout is restoring a key it should not (HIST7)",
+        );
+      }
+    }
+  }
+}
+
+/**
+ * @typedef {object} DegradedImageWarning
+ * @property {string | null} name
+ * @property {number[]} sharedContainerIds  the editable container id(s) from
+ *   this image's own anchor — the box the user would be editing when this
+ *   image is at risk
+ */
+
+/**
+ * @typedef {object} ExportReport
+ * @property {import("./export-splice.js").SkippedGeometry[]} skippedGeometry
+ *   geometry changes this export could NOT write, with the reason. NEVER
+ *   silent: a box the user moved on screen whose new position did not reach the
+ *   file has to be visible, or we repeat the exact surprise this slice fixes.
+ * @property {DegradedImageWarning[]} degradedImages  ADR-0020 Karar 6's
+ *   DEGRADED images (`importResult.report.skippedImages`, filtered) —
+ *   surfaced again HERE, not just at import time, because export/save is the
+ *   moment the risk (P6 anchor regeneration would silently drop this image)
+ *   actually matters to the user. Classification itself is untouched: this
+ *   reads what `importDocx` already computed, it does not recompute anything.
+ *   Bytes are unaffected — `word/media/*` stays verbatim/PRESERVED either
+ *   way (§3.5); this field is warning-only, like `skippedGeometry`.
+ */
+
+/**
+ * A .docx for `currentDoc`, produced by splicing only the touched containers'
+ * text and geometry into `importResult`'s untouched original bytes and
+ * repacking. Zero edits -> a byte-identical copy of the imported file (no part
+ * is re-compressed): the strongest form of §3.5's "zero touch = zero difference".
+ *
+ * Returns the report alongside the bytes — deliberately, so a caller cannot get
+ * the file without also receiving what did not make it into the file. Mirrors
+ * `importDocx`'s own `{doc, …, report}` shape.
+ *
+ * @param {import("./import.js").ConvertResult} importResult  what `importDocx` returned (carries `doc` + `provenance`)
+ * @param {import("../../model/node.js").Doc} currentDoc  the edited document (from EditorState)
+ * @param {object} [options]
+ * @param {Map<import("../../model/node.js").NodeId, Set<string>>} [options.historyDirty]
+ *   the running `recordForwardDirty` map, if the caller tracks one. NOT the
+ *   dirty source — `dirtyGeometry`'s value compare still decides what gets
+ *   written, so a taşı-sonra-geri-al still exports byte-identical even though
+ *   `historyDirty` still names the keys those steps touched. When given, it is
+ *   a ONE-WAY consistency gate: every key the value compare finds dirty MUST
+ *   be present here, or a layout-mutating path exists that never called
+ *   `recordForwardDirty` — a real bug, thrown loudly rather than silently
+ *   exported with no traceability. The reverse (a key tracked but not
+ *   value-dirty) is the NORMAL taşı-sonra-geri-al case and is not an error.
+ *   This gate catches a DIFFERENT regression than `verifyInverseDirty`: a
+ *   forgotten wiring, not an inverse naming a key it should not.
+ * @returns {Promise<{bytes: Uint8Array, report: ExportReport}>}
+ */
+export async function exportDocx(importResult, currentDoc, { historyDirty } = {}) {
+  const { provenance } = importResult;
+  if (provenance.packageBytes === undefined || provenance.entries === undefined) {
+    // convertDocument's provenance is document-level only; export needs the
+    // retained package importDocx adds (piece 1). This guards a misuse and
+    // narrows the optional fields for the type checker.
+    throw new Error("exportDocx requires importDocx's provenance (packageBytes + entries)");
+  }
+  const dirty = dirtyContainers(importResult.doc, currentDoc);
+  const geometry = dirtyGeometry(importResult.doc, currentDoc);
+
+  if (historyDirty !== undefined) {
+    for (const [id, keys] of geometry) {
+      const tracked = historyDirty.get(id);
+      for (const key of keys) {
+        if (tracked === undefined || !tracked.has(key)) {
+          throw new Error(
+            `exportDocx: container ${id}'s '${key}' is dirty by value but was never tracked by ` +
+              "recordForwardDirty — a layout-mutating path exists that history tracking is not wired to",
+          );
+        }
+      }
+    }
+  }
+
+  const { bytes: newDocumentXml, skippedGeometry } = spliceDirty(provenance, currentDoc, {
+    textIds: dirty,
+    geometry,
+    originalDoc: importResult.doc,
+  });
+  // spliceDirty returns the ORIGINAL bytes (same reference) when nothing was
+  // written; in that case repack with NO replacement, so document.xml is copied
+  // verbatim and the whole .docx comes out byte-identical (not merely
+  // inflate-identical). Otherwise the changed document.xml is the one replacement.
+  const replacements =
+    newDocumentXml === provenance.documentXmlBytes
+      ? {}
+      : { [resolveMainDocumentPart(provenance.entries).name]: newDocumentXml };
+
+  const bytes = await writePackage(provenance.packageBytes, provenance.entries, replacements);
+  const degradedImages = importResult.report.skippedImages
+    .filter((img) => img.fidelity === "DEGRADED")
+    .map((img) => ({ name: img.name, sharedContainerIds: img.sharedContainerIds }));
+  return { bytes, report: { skippedGeometry, degradedImages } };
+}