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

package/dist/io/ooxml/import.js

@@ -1,691 +1,691 @@
-// Uint8Array (a .docx file's bytes) -> a real Doc. Ported field-for-field
-// from scripts/docx-to-canvas-json.py's convert() (ADR-0020 §2's now-retired
-// differential parity gate enforced this — see Karar 9's 2026-08-27 update).
-// Piece six (2026-08-27) closed the gaps Python's own port had carried
-// silently: a missing posOffset/extent/graphicData, an unparseable group or
-// group-child transform, or an unsupported a:graphicData kind now REJECTS
-// the document (import-gate.js) instead of a bare `continue` — all measured
-// 0/8,737 in the real corpus, so this changes nothing for it, only for a
-// corpus-external document that used to lose content with no signal at all.
-// A text box with zero non-empty runs is a RUN-LESS text box, not a
-// separate class (ADR-0021, 2026-08-27): imported as an editable Container
-// like any other, its id surfaced in report.emptyContainers so a consumer
-// can still flag it as an unfilled form field. Only a decorative shape with
-// neither a custGeom path nor a fill is now reported-not-modeled
-// (report.emptyShapes) — nothing was mis-placed there, there is nothing to
-// place. wps:bodyPr is still never read; paragraph/run formatting is still
-// bold/italic/underline only — extending past those remains a later piece's
-// job.
-//
-// The one impure file in src/io/ooxml/ that wires the pure zip/scan/convert
-// layers together (Karar 8) — DecompressionStream lives in inflate.js, which
-// this file calls, but this file itself touches no platform global directly.
-
-import { DOC_DEFAULT_STYLE_REF } from "../../model/node.js";
-import { parseZipContainer, resolveMainDocumentPart, resolveStylesPart } from "./zip-container.js";
-import { inflateEntry } from "./inflate.js";
-import { scanXml, getAttr, findChild, findChildren } from "./xml-scan.js";
-import { readSections, pageForAnchor } from "./sections.js";
-import { collectAnchors, parseXfrm, paragraphsOf } from "./drawingml.js";
-import {
-  checkGroupIdentity,
-  isShapeLocked,
-  rejectAnchorPlacement,
-  rejectMissingGraphicData,
-  rejectMissingGroupTransform,
-  rejectMissingShapeTransform,
-  rejectUnsupportedGraphicDataKind,
-} from "./import-gate.js";
-import { decorationPaths } from "./custgeom.js";
-import { createAnchorRanges, recordAnchorRange, createPropBlobs, recordPropBlob } from "./provenance.js";
-import { loadStyles, resolve, readPPr, readRPr } from "./styles-resolve.js";
-import { W_NS, WP_NS, A_NS, WPS_NS, WPG_NS, PIC_NS, R_NS } from "./ns.js";
-import { parseRelationships } from "./relationships.js";
-import { parseNumbering, createNumberingCounter, DEFAULT_BULLET } from "./numbering.js";
-import { emuToPt } from "./units.js";
-import { createDoc, createContainer, createParagraph, createRun } from "../../model/node.js";
-import { createIdFactory } from "../../model/ids.js";
-
-// EMU <-> pt lives in units.js — ONE copy, shared with the geometry export's
-// write direction (`ptToEmu`), so the two directions cannot drift apart.
-
-/**
- * @param {import("./xml-scan.js").XmlElement} el
- * @returns {string}
- */
-function textOf(el) {
-  let text = "";
-  for (const child of el.children) {
-    if (child.kind === "text" || child.kind === "cdata") text += child.value;
-  }
-  return text;
-}
-
-/**
- * @param {import("./xml-scan.js").XmlElement} picEl
- * @returns {string | null}
- */
-function picName(picEl) {
-  const nvPicPr = findChild(picEl, PIC_NS, "nvPicPr");
-  const cNvPr = nvPicPr && findChild(nvPicPr, PIC_NS, "cNvPr");
-  return cNvPr ? (getAttr(cNvPr, "", "name") ?? null) : null;
-}
-
-/**
- * A picture's `a:blip r:embed` relationship id (`pic:blipFill/a:blip/@r:embed`) —
- * the only link from a `pic:pic` to its bytes — or null when absent.
- * @param {import("./xml-scan.js").XmlElement} picEl
- * @returns {string | null}
- */
-function picEmbedId(picEl) {
-  const blipFill = findChild(picEl, PIC_NS, "blipFill");
-  const blip = blipFill && findChild(blipFill, A_NS, "blip");
-  return blip ? (getAttr(blip, R_NS, "embed") ?? null) : null;
-}
-
-/**
- * The `word/media/*` part an embed id resolves to, or null (no id, or the id is
- * not in this document's relationships).
- * @param {string | null} embedId
- * @param {Map<string, string>} relsMap
- * @returns {string | null}
- */
-function resolveMedia(embedId, relsMap) {
-  if (embedId === null) return null;
-  return relsMap.get(embedId) ?? null;
-}
-
-/**
- * @param {import("./xml-scan.js").XmlElement | undefined} spPr
- * @returns {string | null}
- */
-function solidFillHex(spPr) {
-  if (!spPr) return null;
-  const fill = findChild(spPr, A_NS, "solidFill");
-  if (!fill) return null;
-  const clr = findChild(fill, A_NS, "srgbClr");
-  return clr ? (getAttr(clr, "", "val") ?? null) : null;
-}
-
-/**
- * @typedef {object} SkippedImage
- * @property {number} anchorIndex
- * @property {string} context
- * @property {string | null} name
- * @property {"PRESERVED" | "DEGRADED"} fidelity  ADR-0020 Karar 6: PRESERVED
- *   if this image's own anchor produced no container (untouched anchor,
- *   byte-identical on export — §3.5); DEGRADED if the SAME anchor also
- *   produced at least one editable container — touching that container
- *   marks the whole anchor `dirty`, and P6 (not built yet) would silently
- *   drop this image when it regenerates the anchor's XML, since no image
- *   render branch exists to re-emit it (Karar 6: "model dalı AÇILMIYOR")
- * @property {number[]} sharedContainerIds  container ids from the SAME
- *   anchor, if any — empty for PRESERVED, non-empty for DEGRADED
- * @property {{start: number, end: number}} anchorRange  the OWN anchor's
- *   byte range in document.xml (§3.5's provenance unit — the same range
- *   `anchorRanges` records for a container/decoration from this anchor)
- */
-
-/**
- * What this report's numbers are, and are not, verified against — same
- * pattern as `src/measure/controller.js`'s own `typographySource` (ADR-0019
- * Karar 8): a result is not empty, but its basis can still be incomplete,
- * and hiding that is the same class of error as silently reporting zero.
- * Fixed per importer version, not computed per document — these are gaps in
- * WHAT THE IMPORTER READS, not facts about any one .docx. Update this list
- * the moment one of these is closed (piece six closed the five silent-skip
- * items that used to belong here — this is what's left).
- * @type {readonly string[]}
- */
-const UNVERIFIED_ASSUMPTIONS = [
-  "wps:bodyPr is not read: inset/autofit/text-anchor are assumed absent (verified only across the reference corpus, ADR-0020 DOĞRULANMALI #25 — not checked against this specific document)",
-  "a:prstGeom and wps:style theme fill/line references (a:fillRef/a:lnRef) are not read — a decorative shape's fill may be incomplete",
-  "run formatting is bold/italic/underline plus Doc.styles resolution only — no other direct run properties are read",
-  "page assignment (pageForAnchor's section-boundary count) is not cross-checked against this document's external ground truth — ADR-0020 Karar 3(c): that cross-check exists only as offline corpus tooling (corpus:pages), which this document has no recorded value in",
-  "numPr rendering (numbering.js): a bullet level whose numbering.xml lvlText is a font-mapped Private Use Area codepoint (measured 387/4,239 real corpus bullet levels, e.g. Wingdings U+F076) falls back to a default bullet character, not the true glyph — the font that maps it is never loaded. Ordinal levels (decimal/lowerLetter/lowerRoman/upperLetter, 27/4,266 real corpus levels) DO get a real running count now (createNumberingCounter, document-order, multi-level restart on a shallower same-numId level) — w:lvlOverride and w:lvlRestart are not implemented (0/474 real corpus w:num entries carry either), and w:numId reuse across genuinely unrelated lists (if any exist beyond this corpus) is not distinguished from one continuous list",
-];
-
-/**
- * @typedef {object} ImportReport
- * @property {string[]} unsupportedCommands
- * @property {{containerId: number, name: string | null, rot: number, flipH: boolean, flipV: boolean}[]} lockedShapes
- * @property {SkippedImage[]} skippedImages
- * @property {EmptyShape[]} emptyShapes
- * @property {number[]} emptyContainers  container ids that were built from a
- *   text box carrying zero non-empty runs — an unfilled form field
- *   (2,482/7,990 real corpus text boxes). ADR-0021: these ARE modeled now,
- *   editable like any container; this list only lets a consumer surface them
- *   as fill targets, it is NOT a "skipped" list.
- * @property {readonly string[]} unverifiedAssumptions
- */
-
-/**
- * A DECORATIVE shape with no visible content at all — ADR-0020 §1's
- * silent-skip audit (2026-08-27): a `continue` dropped these with no trace
- * before. A decoration with neither a `custGeom` path nor a fill has nothing
- * to render (0/2,697 real corpus decorative shapes today — this arm is
- * written but unwitnessed by the corpus). Reported, not rejected — nothing
- * was mis-placed, there was simply nothing to place. (An empty TEXT box is
- * NOT here: ADR-0021 imports it as an editable Container, surfaced instead in
- * report.emptyContainers — `kind` stays a union for forward compatibility,
- * but only "decoration" is produced today.)
- * @typedef {object} EmptyShape
- * @property {number} anchorIndex
- * @property {"text" | "decoration"} kind
- * @property {string | null} name
- */
-
-/**
- * @typedef {object} ConvertResult
- * @property {import("../../model/node.js").Doc} doc
- * @property {import("../../model/ids.js").IdFactory} ids  seeded past every
- *   id this import minted (paragraphs, containers, decorations) — same
- *   contract as `document-json.js`'s `fromJSON`, so an imported Doc is
- *   immediately usable with `CanvasController` (paste, etc.) without the
- *   caller re-deriving a starting id by walking the tree itself
- * @property {import("./provenance.js").AnchorRanges} anchorRanges
- * @property {ImportReport} report
- * @property {import("./provenance.js").Provenance} provenance  §3.5 retention
- *   for P6 export: the untouched bytes to splice/repack from, plus the byte
- *   ranges the model only references by id/PropRef. `convertDocument` fills
- *   the document-level fields; `importDocx` adds `packageBytes`/`entries`.
- *   Additive — existing consumers ({doc, ids, anchorRanges, report}) unaffected.
- */
-
-/**
- * The pure half: an already-scanned document.xml tree (+ its raw bytes, for
- * PropRef content interning) and an already-scanned styles.xml tree -> a
- * real Doc. Split out from `importDocx` so tests can exercise this directly
- * against hand-built XML (via `scanXml`) without wrapping every fixture in a
- * real zip container — `importDocx` below is the thin, impure zip/inflate/
- * scan wrapper around this.
- * @param {import("./xml-scan.js").XmlElement} root
- * @param {Uint8Array} xmlBytes
- * @param {import("./xml-scan.js").XmlElement} stylesRoot
- * @param {Map<string, string>} [relsMap]
- * @param {import("./xml-scan.js").XmlElement | null} [numberingRoot]  word/numbering.xml's
- *   root, if the package carries one (30/46 real corpus documents) — optional,
- *   a numPr paragraph in a document with no numbering.xml still renders (the
- *   default-bullet fallback, numbering.js's resolveMarker)
- * @returns {ConvertResult}
- */
-export function convertDocument(root, xmlBytes, stylesRoot, relsMap = new Map(), numberingRoot = null) {
-  const { page, sectPrStarts } = readSections(root);
-  const anchors = collectAnchors(root);
-  const sx = loadStyles(stylesRoot);
-  // One counter instance for the WHOLE document (numbering.js's own doc
-  // comment): a list's "next item" is a document-order concept, not a
-  // per-container/per-page one — measured against real Word, a list
-  // continues numbering across a container/page boundary. `numDefs` empty
-  // (no numbering.xml, or an unresolved numId/ilvl) makes every `next()`
-  // call return undefined uniformly — the DEFAULT_BULLET fallback below
-  // does not need a separate "no numbering.xml" branch.
-  const numberingCounter = createNumberingCounter(
-    numberingRoot !== null ? parseNumbering(numberingRoot) : new Map(),
-  );
-  const decoder = new TextDecoder("utf-8");
-
-  // PropRef interning (ADR-0020 Karar 7): pPrRef by the pPr byte slice's own
-  // CONTENT (which already includes any w:pStyle child, so a paragraph's own
-  // declared style is baked into the key without needing it separately —
-  // two paragraphs with byte-identical pPr always resolve identically
-  // within one document, since defaultParagraphStyle is document-wide
-  // constant). rPrRef by (effective styleId, rPr byte content) — a run's own
-  // rPr carries no reference to its enclosing paragraph's style, so that
-  // context must be part of the key explicitly, unlike pPrRef.
-  /** @type {Map<string, string>} */
-  const pPrRefByKey = new Map();
-  let nextPPrRefN = 1;
-  /** @type {Map<string, string>} */
-  const rPrRefByKey = new Map();
-  let nextRPrRefN = 1;
-  /** @type {import("../../model/node.js").StyleTable} */
-  const styleTable = {};
-  // ADR-0028: the document's own docDefaults, under a sentinel ref no real
-  // interned pPrRef/rPrRef can ever collide with (those are always
-  // `p${n}`/`r${n}`, above). commands/size.js's effectiveSize falls back to
-  // this ONLY when a run carries neither a direct marks.sz override nor an
-  // rPrRef at all — a freshly typed paragraph, not an imported one (every
-  // real corpus run already carries an rPrRef whose OWN chain already
-  // resolves through docDefaults via `resolve()`, measured 81,973/81,973).
-  // BOTH halves under the one sentinel: `readRPr` never emits a pPr key and
-  // `readPPr` never emits an rPr key, so the two flat records cannot collide
-  // (`sz` comes only from rPr, `jc`/`ind.*`/`spacing.*` only from pPr).
-  // ADR-0029 EKLEME A — and this dal is NOT dead code: measured 46/46 real
-  // corpus documents declare an explicit docDefaults `jc` (all "left").
-  styleTable[DOC_DEFAULT_STYLE_REF] = { ...sx.docDefaults.rPr, ...sx.docDefaults.pPr };
-
-  /**
-   * @param {import("./xml-scan.js").XmlElement | undefined} el
-   * @returns {string}
-   */
-  function contentOf(el) {
-    return el ? decoder.decode(xmlBytes.subarray(el.start, el.end)) : "";
-  }
-
-  /**
-   * @param {Record<string, import("./styles-resolve.js").ResolvedValue>} eff
-   * @returns {Record<string, string>}
-   */
-  function flattenEffective(eff) {
-    /** @type {Record<string, string>} */
-    const out = {};
-    for (const [f, [v]] of Object.entries(eff)) out[f] = v;
-    return out;
-  }
-
-  /**
-   * @param {string | undefined} styleId
-   * @param {import("./xml-scan.js").XmlElement | undefined} pPrEl
-   * @returns {string}
-   */
-  function internPPrRef(styleId, pPrEl) {
-    const key = contentOf(pPrEl);
-    const cached = pPrRefByKey.get(key);
-    if (cached !== undefined) {
-      // A hit here is only ever a NON-numPr paragraph — see below, a numPr
-      // paragraph's ref is never written into this cache in the first place.
-      return cached;
-    }
-    // numId/ilvl computed AFTER the resolve() cascade (not straight off
-    // readPPr's direct output) so a numId inherited from a paragraph STYLE
-    // (not just the paragraph's own direct pPr) is honored too — same
-    // override rule jc/ind already follow.
-    const props = flattenEffective(resolve(sx.docDefaults.pPr, sx.styles, styleId, readPPr(pPrEl), "pPr"));
-    const ref = `p${nextPPrRefN++}`;
-    if (props["numPr.numId"] !== undefined) {
-      // NEVER interned, even though this exact pPrEl's bytes may recur:
-      // numberingCounter.next() must advance once per PARAGRAPH OCCURRENCE
-      // (numbering.js), but consecutive items in the same list commonly
-      // carry byte-identical pPr XML (same numId/ilvl/jc/ind) — caching by
-      // byte content, as the non-numPr path below still correctly does,
-      // would freeze every one of them onto whichever marker the FIRST
-      // occurrence computed (the exact bug this rebuild closes).
-      const resolved = numberingCounter.next(props["numPr.numId"], props["numPr.ilvl"] ?? "0");
-      // Not resolved (missing numbering.xml, orphan numId/ilvl, or a format
-      // numbering.js could not map) -> DEFAULT_BULLET, never guessed, same
-      // fallback numbering.js itself uses. Flagged as a capability gap in
-      // UNVERIFIED_ASSUMPTIONS below, not per-document.
-      props["numPr.marker"] = resolved?.marker ?? DEFAULT_BULLET;
-      styleTable[ref] = props;
-      return ref;
-    }
-    pPrRefByKey.set(key, ref);
-    styleTable[ref] = props;
-    return ref;
-  }
-
-  /**
-   * @param {string | undefined} styleId
-   * @param {import("./xml-scan.js").XmlElement | undefined} rPrEl
-   * @returns {string}
-   */
-  function internRPrRef(styleId, rPrEl) {
-    const key = `${styleId ?? ""}\u0000${contentOf(rPrEl)}`;
-    let ref = rPrRefByKey.get(key);
-    if (ref === undefined) {
-      ref = `r${nextRPrRefN++}`;
-      rPrRefByKey.set(key, ref);
-      styleTable[ref] = flattenEffective(resolve(sx.docDefaults.rPr, sx.styles, styleId, readRPr(rPrEl), "rPr"));
-    }
-    return ref;
-  }
-
-  let nextId = 2; // 1 is the document itself — IdFactory(2) parity
-  /** @type {import("../../model/node.js").Container[]} */
-  const containers = [];
-  /** @type {import("../../model/node.js").LayoutMap} */
-  const layout = {};
-  /** @type {import("../../model/node.js").Decoration[]} */
-  const decorations = [];
-  /** @type {import("../../model/node.js").DocImage[]} */
-  const images = [];
-  const anchorRanges = createAnchorRanges();
-  const propBlobs = createPropBlobs();
-  /** @type {Set<string>} */
-  const unsupportedCommands = new Set();
-  /** @type {ImportReport["lockedShapes"]} */
-  const lockedShapes = [];
-  /** @type {ImportReport["skippedImages"]} */
-  const skippedImages = [];
-  /** @type {ImportReport["emptyShapes"]} */
-  const emptyShapes = [];
-  /** @type {ImportReport["emptyContainers"]} */
-  const emptyContainers = [];
-
-  for (let anchorIndex = 0; anchorIndex < anchors.length; anchorIndex++) {
-    const anchor = anchors[anchorIndex];
-    const pageNumber = pageForAnchor(sectPrStarts, anchor.start, page.count);
-
-    const positionH = findChild(anchor, WP_NS, "positionH");
-    const posOffsetH = positionH && findChild(positionH, WP_NS, "posOffset");
-    const positionV = findChild(anchor, WP_NS, "positionV");
-    const posOffsetV = positionV && findChild(positionV, WP_NS, "posOffset");
-    const extent = findChild(anchor, WP_NS, "extent");
-    if (!posOffsetH || !posOffsetV || !extent) {
-      rejectAnchorPlacement(!posOffsetH, !posOffsetV, !extent, `anchor ${anchorIndex}`);
-    }
-
-    const anchorX = Number.parseInt(textOf(posOffsetH) || "0", 10);
-    const anchorY = Number.parseInt(textOf(posOffsetV) || "0", 10);
-    const z = Number.parseInt(getAttr(anchor, "", "relativeHeight") ?? "0", 10);
-
-    const graphic = findChild(anchor, A_NS, "graphic");
-    const graphicData = graphic && findChild(graphic, A_NS, "graphicData");
-    if (!graphicData) rejectMissingGraphicData(`anchor ${anchorIndex}`);
-
-    /** @type {{el: import("./xml-scan.js").XmlElement, x: number, y: number, cx: number, cy: number, ownXfrm: {rot: number, flipH: boolean, flipV: boolean}}[]} */
-    const shapes = [];
-    // Every container this SAME anchor produces, and every pic:pic this same
-    // anchor contains — collected during this anchor's own processing below,
-    // then reconciled once (after the shapes loop) so each image's fidelity
-    // bucket reflects ALL of this anchor's containers, not just whichever
-    // were created before the image happened to be encountered.
-    /** @type {number[]} */
-    const containerIdsThisAnchor = [];
-    /** @type {{context: string, name: string | null, embedId: string | null, geom: {x: number, y: number, cx: number, cy: number} | null}[]} */
-    const pendingImagesThisAnchor = [];
-
-    const group = findChild(graphicData, WPG_NS, "wgp");
-    if (group) {
-      const gXfrm = parseXfrm(findChild(group, WPG_NS, "grpSpPr"));
-      if (!gXfrm) rejectMissingGroupTransform(`anchor ${anchorIndex} group`);
-      const gCnvPr = findChild(group, WPG_NS, "cNvPr");
-      const gId = gCnvPr ? (getAttr(gCnvPr, "", "id") ?? "?") : "?";
-      const gName = gCnvPr ? (getAttr(gCnvPr, "", "name") ?? "?") : "?";
-      const { scaleX, scaleY } = checkGroupIdentity(
-        gXfrm,
-        group,
-        `anchor ${anchorIndex} group id=${gId} name=${JSON.stringify(gName)}`,
-      );
-
-      for (const pic of findChildren(group, PIC_NS, "pic")) {
-        // Group-child placement uses the SAME transform a wsp sibling does
-        // (the group is identity, checkGroupIdentity above). A pic with no
-        // xfrm has no computable placement -> geom null -> report-only skip.
-        const pXfrm = parseXfrm(findChild(pic, PIC_NS, "spPr"));
-        pendingImagesThisAnchor.push({
-          context: `group id=${gId} name=${JSON.stringify(gName)}`,
-          name: picName(pic),
-          embedId: picEmbedId(pic),
-          geom: pXfrm === null ? null : {
-            x: anchorX + (pXfrm.offX - gXfrm.chOffX) * scaleX,
-            y: anchorY + (pXfrm.offY - gXfrm.chOffY) * scaleY,
-            cx: pXfrm.extCx * scaleX,
-            cy: pXfrm.extCy * scaleY,
-          },
-        });
-      }
-      for (const child of findChildren(group, WPS_NS, "wsp")) {
-        const cXfrm = parseXfrm(findChild(child, WPS_NS, "spPr"));
-        if (!cXfrm) rejectMissingShapeTransform(`anchor ${anchorIndex} group id=${gId} name=${JSON.stringify(gName)}`);
-        shapes.push({
-          el: child,
-          x: anchorX + (cXfrm.offX - gXfrm.chOffX) * scaleX,
-          y: anchorY + (cXfrm.offY - gXfrm.chOffY) * scaleY,
-          cx: cXfrm.extCx * scaleX,
-          cy: cXfrm.extCy * scaleY,
-          ownXfrm: cXfrm,
-        });
-      }
-    } else {
-      const wsp = findChild(graphicData, WPS_NS, "wsp");
-      if (!wsp) {
-        const pic = findChild(graphicData, PIC_NS, "pic");
-        if (!pic) rejectUnsupportedGraphicDataKind(`anchor ${anchorIndex}`);
-        // A non-grouped anchor's graphicData holds EITHER wps:wsp OR pic:pic
-        // (this branch is only reached when wsp was absent) — it structurally
-        // cannot ALSO have produced a container from this same anchor, so it is
-        // always PRESERVED. Placement is the anchor's own posOffset + extent.
-        // Rendered (Doc.images) when its bytes resolve; otherwise report-only.
-        const mediaPartName = resolveMedia(picEmbedId(pic), relsMap);
-        if (mediaPartName !== null) {
-          images.push({
-            id: nextId++,
-            page: pageNumber,
-            x: emuToPt(anchorX),
-            y: emuToPt(anchorY),
-            cx: emuToPt(Number.parseInt(getAttr(extent, "", "cx") ?? "0", 10)),
-            cy: emuToPt(Number.parseInt(getAttr(extent, "", "cy") ?? "0", 10)),
-            z,
-            mediaPartName,
-          });
-        } else {
-          skippedImages.push({
-            anchorIndex,
-            context: "top-level (ungrouped)",
-            name: picName(pic),
-            fidelity: "PRESERVED",
-            sharedContainerIds: [],
-            anchorRange: { start: anchor.start, end: anchor.end },
-          });
-        }
-        continue;
-      }
-      const ownXfrm = parseXfrm(findChild(wsp, WPS_NS, "spPr")) ?? { rot: 0, flipH: false, flipV: false };
-      shapes.push({
-        el: wsp,
-        x: anchorX,
-        y: anchorY,
-        cx: Number.parseInt(getAttr(extent, "", "cx") ?? "0", 10),
-        cy: Number.parseInt(getAttr(extent, "", "cy") ?? "0", 10),
-        ownXfrm,
-      });
-    }
-
-    for (const { el: wsp, x, y, cx, cy, ownXfrm } of shapes) {
-      const spPr = findChild(wsp, WPS_NS, "spPr");
-      const txbxWrap = findChild(wsp, WPS_NS, "txbx");
-      const txbx = txbxWrap && findChild(txbxWrap, W_NS, "txbxContent");
-
-      const shapeRot = ownXfrm.rot ?? 0;
-      const shapeFlipH = ownXfrm.flipH ?? false;
-      const shapeFlipV = ownXfrm.flipV ?? false;
-      const locked = isShapeLocked({ rot: shapeRot, flipH: shapeFlipH, flipV: shapeFlipV });
-
-      if (txbx) {
-        const parsedParagraphs = paragraphsOf(txbx);
-        const paragraphIds = [];
-        // (ref, element) pairs for this container's pPr/rPr byte slices (ADR-0017
-        // opaque blobs). Collected here because the byte ranges are in hand at the
-        // intern sites, but recorded into `propBlobs` only after `containerId` is
-        // minted below — the map runs before that id exists.
-        /** @type {{ref: string, el: import("./xml-scan.js").XmlElement}[]} */
-        const propBlobEls = [];
-        const paragraphs = parsedParagraphs.map((p) => {
-          const id = nextId++;
-          paragraphIds.push(id);
-          const styleId = p.pStyleId ?? sx.defaultParagraphStyle ?? undefined;
-          const pPrRef = internPPrRef(styleId, p.pPrEl);
-          if (p.pPrEl) propBlobEls.push({ ref: pPrRef, el: p.pPrEl });
-          return createParagraph(
-            id,
-            p.runs.map((r) => {
-              const rPrRef = internRPrRef(styleId, r.rPrEl);
-              if (r.rPrEl) propBlobEls.push({ ref: rPrRef, el: r.rPrEl });
-              return createRun(r.text, { ...r.marks, rPrRef });
-            }),
-            { pPrRef },
-          );
-        });
-        // ADR-0021 (2026-08-27): a text box with zero non-empty runs is a
-        // RUN-LESS text box, not a separate class — M7 (commit 8bcc087)
-        // measured every supposed "empty box" signature on all 5,508 FILLED
-        // boxes too, so none of them distinguishes it. It becomes an editable
-        // Container like any other; normalize.js keeps an empty paragraph's
-        // single empty run and render/dom.js prints a <br> filler, so the
-        // model and renderer already accept this (a filled box with a blank
-        // paragraph produces the same zero-run Paragraph today). Its id is
-        // surfaced in emptyContainers so a consumer can still flag it as an
-        // unfilled form field — the very reason these documents are opened —
-        // but it is NOT skipped: it is clickable and editable now.
-        const hasAnyRuns = parsedParagraphs.some((p) => p.runs.length > 0);
-
-        const containerId = nextId++;
-        containers.push(createContainer(containerId, paragraphs));
-        recordAnchorRange(anchorRanges, containerId, anchor);
-        for (const { ref, el } of propBlobEls) recordPropBlob(propBlobs, containerId, ref, el);
-        containerIdsThisAnchor.push(containerId);
-        if (!hasAnyRuns) emptyContainers.push(containerId);
-
-        /** @type {import("../../model/node.js").BoxLayout} */
-        const layoutEntry = { page: pageNumber, x: emuToPt(x), y: emuToPt(y), cx: emuToPt(cx), cy: emuToPt(cy), z };
-        if (locked) {
-          layoutEntry.rot = shapeRot;
-          layoutEntry.flipH = shapeFlipH;
-          layoutEntry.flipV = shapeFlipV;
-          layoutEntry.locked = true;
-          const cnvpr = findChild(wsp, WPS_NS, "cNvPr");
-          lockedShapes.push({
-            containerId,
-            name: cnvpr ? (getAttr(cnvpr, "", "name") ?? null) : null,
-            rot: shapeRot,
-            flipH: shapeFlipH,
-            flipV: shapeFlipV,
-          });
-        }
-        layout[containerId] = layoutEntry;
-        continue;
-      }
-
-      const { paths, unsupported } = decorationPaths(spPr);
-      for (const u of unsupported) unsupportedCommands.add(u);
-      const fillHex = solidFillHex(spPr);
-      if (paths.length === 0 && fillHex === null) {
-        // Symmetric to the text-box case above — a decorative shape with
-        // neither a custGeom path nor a direct fill renders as nothing.
-        // Measured 2026-08-27: 0/2,697 real corpus decorative shapes
-        // trigger this (kural değil enstrüman until the corpus witnesses
-        // one — see OOXML mutation registry).
-        const cnvpr = findChild(wsp, WPS_NS, "cNvPr");
-        emptyShapes.push({ anchorIndex, kind: "decoration", name: cnvpr ? (getAttr(cnvpr, "", "name") ?? null) : null });
-        continue;
-      }
-
-      const decorationId = nextId++;
-      decorations.push({
-        id: decorationId,
-        page: pageNumber,
-        x: emuToPt(x),
-        y: emuToPt(y),
-        cx: emuToPt(cx),
-        cy: emuToPt(cy),
-        z,
-        fillHex,
-        paths,
-      });
-      recordAnchorRange(anchorRanges, decorationId, anchor);
-    }
-
-    // Reconciled once per anchor, after every shape (and so every container
-    // this anchor could produce) has been processed — ADR-0020 Karar 6: an
-    // image is DEGRADED exactly when its OWN anchor also produced at least
-    // one container (an editable text box); touching that container marks
-    // the whole anchor dirty for a future P6 export, which has no image
-    // render branch to re-emit this picture with. Measured 2026-08-27
-    // (46/46 real corpus documents): 0/466 images are DEGRADED under this
-    // rule — every wps:wsp sibling of every pic:pic in this corpus is a
-    // decorative shape (no txbx element at all), never a text box. The rule
-    // is still implemented for the general case (a corpus-external document,
-    // or this app someday allowing decorative-shape edits, could trigger it).
-    const anchorIsDegraded = containerIdsThisAnchor.length > 0;
-    for (const pending of pendingImagesThisAnchor) {
-      const mediaPartName = resolveMedia(pending.embedId, relsMap);
-      // Rendered (Doc.images) only when PRESERVED and BOTH bytes and placement
-      // resolve. DEGRADED (shares an anchor with an editable container — 0/466
-      // in the corpus) or an unresolvable embed/geometry stays a report-only
-      // skip, keeping ADR-0020 Karar 6's at-risk signal for a future export.
-      if (!anchorIsDegraded && mediaPartName !== null && pending.geom !== null) {
-        images.push({
-          id: nextId++,
-          page: pageNumber,
-          x: emuToPt(pending.geom.x),
-          y: emuToPt(pending.geom.y),
-          cx: emuToPt(pending.geom.cx),
-          cy: emuToPt(pending.geom.cy),
-          z,
-          mediaPartName,
-        });
-      } else {
-        skippedImages.push({
-          anchorIndex,
-          context: pending.context,
-          name: pending.name,
-          fidelity: anchorIsDegraded ? "DEGRADED" : "PRESERVED",
-          sharedContainerIds: [...containerIdsThisAnchor],
-          anchorRange: { start: anchor.start, end: anchor.end },
-        });
-      }
-    }
-  }
-
-  const doc = createDoc(1, containers, layout, { page, decorations, images, styles: styleTable });
-
-  return {
-    doc,
-    ids: createIdFactory(nextId),
-    anchorRanges,
-    report: {
-      unsupportedCommands: [...unsupportedCommands].sort(),
-      lockedShapes,
-      skippedImages,
-      emptyShapes,
-      emptyContainers,
-      unverifiedAssumptions: UNVERIFIED_ASSUMPTIONS,
-    },
-    // §3.5 retention (document-level half — `importDocx` adds packageBytes/entries).
-    // documentXmlBytes is the exact inflated word/document.xml piece 3 splices;
-    // dirty starts empty (pieces 4b/5 fill it).
-    provenance: { documentXmlBytes: xmlBytes, anchorRanges, propBlobs, dirty: new Set() },
-  };
-}
-
-/**
- * The relationships (`Id -> resolved part name`) for the main document part.
- * Its rels part is `<dir>/_rels/<name>.rels` beside the part; an absent one (a
- * document with no relationships at all) yields an empty map. Targets resolve
- * against the part's own directory (`<dir>`), the OPC rule.
- * @param {Uint8Array} bytes
- * @param {import("./zip-container.js").ZipEntry[]} entries
- * @param {string} mainPartName  e.g. `"word/document.xml"`
- * @returns {Promise<Map<string, string>>}
- */
-async function loadRelationships(bytes, entries, mainPartName) {
-  const slash = mainPartName.lastIndexOf("/");
-  const dir = slash === -1 ? "" : mainPartName.slice(0, slash);
-  const name = slash === -1 ? mainPartName : mainPartName.slice(slash + 1);
-  const relsName = `${dir === "" ? "" : `${dir}/`}_rels/${name}.rels`;
-  const relsEntry = entries.find((e) => e.name === relsName);
-  if (relsEntry === undefined) return new Map();
-  const relsBytes = await inflateEntry(bytes, relsEntry);
-  const { root } = scanXml(relsBytes);
-  return parseRelationships(root, dir);
-}
-
-/**
- * @param {Uint8Array} bytes  a whole .docx file's bytes
- * @returns {Promise<ConvertResult>}
- */
-export async function importDocx(bytes) {
-  const entries = parseZipContainer(bytes);
-  const mainPart = resolveMainDocumentPart(entries);
-  const stylesPart = resolveStylesPart(entries);
-  const xmlBytes = await inflateEntry(bytes, mainPart);
-  const stylesBytes = await inflateEntry(bytes, stylesPart);
-  const { root } = scanXml(xmlBytes);
-  const { root: stylesRoot } = scanXml(stylesBytes);
-  const relsMap = await loadRelationships(bytes, entries, mainPart.name);
-  // word/numbering.xml is OPTIONAL (30/46 real corpus documents carry it) —
-  // a fixed path lookup like resolveStylesPart's, but tolerant of absence
-  // rather than throwing: a numPr paragraph in a document with no
-  // numbering.xml still renders (numbering.js's default-bullet fallback).
-  const numberingPart = entries.find((e) => e.name === "word/numbering.xml");
-  const numberingRoot =
-    numberingPart !== undefined ? scanXml(await inflateEntry(bytes, numberingPart)).root : null;
-  const result = convertDocument(root, xmlBytes, stylesRoot, relsMap, numberingRoot);
-  // Retain the original OPC package (§3.5 step 1) so piece 2 (repack) can
-  // byte-copy every untouched part verbatim — convertDocument only had the
-  // inflated document.xml. `bytes` is the caller's array (a reference, not a
-  // copy); `entries` is re-derivable from it but kept to avoid a re-parse.
-  return { ...result, provenance: { ...result.provenance, packageBytes: bytes, entries } };
-}
+// Uint8Array (a .docx file's bytes) -> a real Doc. Ported field-for-field
+// from scripts/docx-to-canvas-json.py's convert() (ADR-0020 §2's now-retired
+// differential parity gate enforced this — see Karar 9's 2026-08-27 update).
+// Piece six (2026-08-27) closed the gaps Python's own port had carried
+// silently: a missing posOffset/extent/graphicData, an unparseable group or
+// group-child transform, or an unsupported a:graphicData kind now REJECTS
+// the document (import-gate.js) instead of a bare `continue` — all measured
+// 0/8,737 in the real corpus, so this changes nothing for it, only for a
+// corpus-external document that used to lose content with no signal at all.
+// A text box with zero non-empty runs is a RUN-LESS text box, not a
+// separate class (ADR-0021, 2026-08-27): imported as an editable Container
+// like any other, its id surfaced in report.emptyContainers so a consumer
+// can still flag it as an unfilled form field. Only a decorative shape with
+// neither a custGeom path nor a fill is now reported-not-modeled
+// (report.emptyShapes) — nothing was mis-placed there, there is nothing to
+// place. wps:bodyPr is still never read; paragraph/run formatting is still
+// bold/italic/underline only — extending past those remains a later piece's
+// job.
+//
+// The one impure file in src/io/ooxml/ that wires the pure zip/scan/convert
+// layers together (Karar 8) — DecompressionStream lives in inflate.js, which
+// this file calls, but this file itself touches no platform global directly.
+
+import { DOC_DEFAULT_STYLE_REF } from "../../model/node.js";
+import { parseZipContainer, resolveMainDocumentPart, resolveStylesPart } from "./zip-container.js";
+import { inflateEntry } from "./inflate.js";
+import { scanXml, getAttr, findChild, findChildren } from "./xml-scan.js";
+import { readSections, pageForAnchor } from "./sections.js";
+import { collectAnchors, parseXfrm, paragraphsOf } from "./drawingml.js";
+import {
+  checkGroupIdentity,
+  isShapeLocked,
+  rejectAnchorPlacement,
+  rejectMissingGraphicData,
+  rejectMissingGroupTransform,
+  rejectMissingShapeTransform,
+  rejectUnsupportedGraphicDataKind,
+} from "./import-gate.js";
+import { decorationPaths } from "./custgeom.js";
+import { createAnchorRanges, recordAnchorRange, createPropBlobs, recordPropBlob } from "./provenance.js";
+import { loadStyles, resolve, readPPr, readRPr } from "./styles-resolve.js";
+import { W_NS, WP_NS, A_NS, WPS_NS, WPG_NS, PIC_NS, R_NS } from "./ns.js";
+import { parseRelationships } from "./relationships.js";
+import { parseNumbering, createNumberingCounter, DEFAULT_BULLET } from "./numbering.js";
+import { emuToPt } from "./units.js";
+import { createDoc, createContainer, createParagraph, createRun } from "../../model/node.js";
+import { createIdFactory } from "../../model/ids.js";
+
+// EMU <-> pt lives in units.js — ONE copy, shared with the geometry export's
+// write direction (`ptToEmu`), so the two directions cannot drift apart.
+
+/**
+ * @param {import("./xml-scan.js").XmlElement} el
+ * @returns {string}
+ */
+function textOf(el) {
+  let text = "";
+  for (const child of el.children) {
+    if (child.kind === "text" || child.kind === "cdata") text += child.value;
+  }
+  return text;
+}
+
+/**
+ * @param {import("./xml-scan.js").XmlElement} picEl
+ * @returns {string | null}
+ */
+function picName(picEl) {
+  const nvPicPr = findChild(picEl, PIC_NS, "nvPicPr");
+  const cNvPr = nvPicPr && findChild(nvPicPr, PIC_NS, "cNvPr");
+  return cNvPr ? (getAttr(cNvPr, "", "name") ?? null) : null;
+}
+
+/**
+ * A picture's `a:blip r:embed` relationship id (`pic:blipFill/a:blip/@r:embed`) —
+ * the only link from a `pic:pic` to its bytes — or null when absent.
+ * @param {import("./xml-scan.js").XmlElement} picEl
+ * @returns {string | null}
+ */
+function picEmbedId(picEl) {
+  const blipFill = findChild(picEl, PIC_NS, "blipFill");
+  const blip = blipFill && findChild(blipFill, A_NS, "blip");
+  return blip ? (getAttr(blip, R_NS, "embed") ?? null) : null;
+}
+
+/**
+ * The `word/media/*` part an embed id resolves to, or null (no id, or the id is
+ * not in this document's relationships).
+ * @param {string | null} embedId
+ * @param {Map<string, string>} relsMap
+ * @returns {string | null}
+ */
+function resolveMedia(embedId, relsMap) {
+  if (embedId === null) return null;
+  return relsMap.get(embedId) ?? null;
+}
+
+/**
+ * @param {import("./xml-scan.js").XmlElement | undefined} spPr
+ * @returns {string | null}
+ */
+function solidFillHex(spPr) {
+  if (!spPr) return null;
+  const fill = findChild(spPr, A_NS, "solidFill");
+  if (!fill) return null;
+  const clr = findChild(fill, A_NS, "srgbClr");
+  return clr ? (getAttr(clr, "", "val") ?? null) : null;
+}
+
+/**
+ * @typedef {object} SkippedImage
+ * @property {number} anchorIndex
+ * @property {string} context
+ * @property {string | null} name
+ * @property {"PRESERVED" | "DEGRADED"} fidelity  ADR-0020 Karar 6: PRESERVED
+ *   if this image's own anchor produced no container (untouched anchor,
+ *   byte-identical on export — §3.5); DEGRADED if the SAME anchor also
+ *   produced at least one editable container — touching that container
+ *   marks the whole anchor `dirty`, and P6 (not built yet) would silently
+ *   drop this image when it regenerates the anchor's XML, since no image
+ *   render branch exists to re-emit it (Karar 6: "model dalı AÇILMIYOR")
+ * @property {number[]} sharedContainerIds  container ids from the SAME
+ *   anchor, if any — empty for PRESERVED, non-empty for DEGRADED
+ * @property {{start: number, end: number}} anchorRange  the OWN anchor's
+ *   byte range in document.xml (§3.5's provenance unit — the same range
+ *   `anchorRanges` records for a container/decoration from this anchor)
+ */
+
+/**
+ * What this report's numbers are, and are not, verified against — same
+ * pattern as `src/measure/controller.js`'s own `typographySource` (ADR-0019
+ * Karar 8): a result is not empty, but its basis can still be incomplete,
+ * and hiding that is the same class of error as silently reporting zero.
+ * Fixed per importer version, not computed per document — these are gaps in
+ * WHAT THE IMPORTER READS, not facts about any one .docx. Update this list
+ * the moment one of these is closed (piece six closed the five silent-skip
+ * items that used to belong here — this is what's left).
+ * @type {readonly string[]}
+ */
+const UNVERIFIED_ASSUMPTIONS = [
+  "wps:bodyPr is not read: inset/autofit/text-anchor are assumed absent (verified only across the reference corpus, ADR-0020 DOĞRULANMALI #25 — not checked against this specific document)",
+  "a:prstGeom and wps:style theme fill/line references (a:fillRef/a:lnRef) are not read — a decorative shape's fill may be incomplete",
+  "run formatting is bold/italic/underline plus Doc.styles resolution only — no other direct run properties are read",
+  "page assignment (pageForAnchor's section-boundary count) is not cross-checked against this document's external ground truth — ADR-0020 Karar 3(c): that cross-check exists only as offline corpus tooling (corpus:pages), which this document has no recorded value in",
+  "numPr rendering (numbering.js): a bullet level whose numbering.xml lvlText is a font-mapped Private Use Area codepoint (measured 387/4,239 real corpus bullet levels, e.g. Wingdings U+F076) falls back to a default bullet character, not the true glyph — the font that maps it is never loaded. Ordinal levels (decimal/lowerLetter/lowerRoman/upperLetter, 27/4,266 real corpus levels) DO get a real running count now (createNumberingCounter, document-order, multi-level restart on a shallower same-numId level) — w:lvlOverride and w:lvlRestart are not implemented (0/474 real corpus w:num entries carry either), and w:numId reuse across genuinely unrelated lists (if any exist beyond this corpus) is not distinguished from one continuous list",
+];
+
+/**
+ * @typedef {object} ImportReport
+ * @property {string[]} unsupportedCommands
+ * @property {{containerId: number, name: string | null, rot: number, flipH: boolean, flipV: boolean}[]} lockedShapes
+ * @property {SkippedImage[]} skippedImages
+ * @property {EmptyShape[]} emptyShapes
+ * @property {number[]} emptyContainers  container ids that were built from a
+ *   text box carrying zero non-empty runs — an unfilled form field
+ *   (2,482/7,990 real corpus text boxes). ADR-0021: these ARE modeled now,
+ *   editable like any container; this list only lets a consumer surface them
+ *   as fill targets, it is NOT a "skipped" list.
+ * @property {readonly string[]} unverifiedAssumptions
+ */
+
+/**
+ * A DECORATIVE shape with no visible content at all — ADR-0020 §1's
+ * silent-skip audit (2026-08-27): a `continue` dropped these with no trace
+ * before. A decoration with neither a `custGeom` path nor a fill has nothing
+ * to render (0/2,697 real corpus decorative shapes today — this arm is
+ * written but unwitnessed by the corpus). Reported, not rejected — nothing
+ * was mis-placed, there was simply nothing to place. (An empty TEXT box is
+ * NOT here: ADR-0021 imports it as an editable Container, surfaced instead in
+ * report.emptyContainers — `kind` stays a union for forward compatibility,
+ * but only "decoration" is produced today.)
+ * @typedef {object} EmptyShape
+ * @property {number} anchorIndex
+ * @property {"text" | "decoration"} kind
+ * @property {string | null} name
+ */
+
+/**
+ * @typedef {object} ConvertResult
+ * @property {import("../../model/node.js").Doc} doc
+ * @property {import("../../model/ids.js").IdFactory} ids  seeded past every
+ *   id this import minted (paragraphs, containers, decorations) — same
+ *   contract as `document-json.js`'s `fromJSON`, so an imported Doc is
+ *   immediately usable with `CanvasController` (paste, etc.) without the
+ *   caller re-deriving a starting id by walking the tree itself
+ * @property {import("./provenance.js").AnchorRanges} anchorRanges
+ * @property {ImportReport} report
+ * @property {import("./provenance.js").Provenance} provenance  §3.5 retention
+ *   for P6 export: the untouched bytes to splice/repack from, plus the byte
+ *   ranges the model only references by id/PropRef. `convertDocument` fills
+ *   the document-level fields; `importDocx` adds `packageBytes`/`entries`.
+ *   Additive — existing consumers ({doc, ids, anchorRanges, report}) unaffected.
+ */
+
+/**
+ * The pure half: an already-scanned document.xml tree (+ its raw bytes, for
+ * PropRef content interning) and an already-scanned styles.xml tree -> a
+ * real Doc. Split out from `importDocx` so tests can exercise this directly
+ * against hand-built XML (via `scanXml`) without wrapping every fixture in a
+ * real zip container — `importDocx` below is the thin, impure zip/inflate/
+ * scan wrapper around this.
+ * @param {import("./xml-scan.js").XmlElement} root
+ * @param {Uint8Array} xmlBytes
+ * @param {import("./xml-scan.js").XmlElement} stylesRoot
+ * @param {Map<string, string>} [relsMap]
+ * @param {import("./xml-scan.js").XmlElement | null} [numberingRoot]  word/numbering.xml's
+ *   root, if the package carries one (30/46 real corpus documents) — optional,
+ *   a numPr paragraph in a document with no numbering.xml still renders (the
+ *   default-bullet fallback, numbering.js's resolveMarker)
+ * @returns {ConvertResult}
+ */
+export function convertDocument(root, xmlBytes, stylesRoot, relsMap = new Map(), numberingRoot = null) {
+  const { page, sectPrStarts } = readSections(root);
+  const anchors = collectAnchors(root);
+  const sx = loadStyles(stylesRoot);
+  // One counter instance for the WHOLE document (numbering.js's own doc
+  // comment): a list's "next item" is a document-order concept, not a
+  // per-container/per-page one — measured against real Word, a list
+  // continues numbering across a container/page boundary. `numDefs` empty
+  // (no numbering.xml, or an unresolved numId/ilvl) makes every `next()`
+  // call return undefined uniformly — the DEFAULT_BULLET fallback below
+  // does not need a separate "no numbering.xml" branch.
+  const numberingCounter = createNumberingCounter(
+    numberingRoot !== null ? parseNumbering(numberingRoot) : new Map(),
+  );
+  const decoder = new TextDecoder("utf-8");
+
+  // PropRef interning (ADR-0020 Karar 7): pPrRef by the pPr byte slice's own
+  // CONTENT (which already includes any w:pStyle child, so a paragraph's own
+  // declared style is baked into the key without needing it separately —
+  // two paragraphs with byte-identical pPr always resolve identically
+  // within one document, since defaultParagraphStyle is document-wide
+  // constant). rPrRef by (effective styleId, rPr byte content) — a run's own
+  // rPr carries no reference to its enclosing paragraph's style, so that
+  // context must be part of the key explicitly, unlike pPrRef.
+  /** @type {Map<string, string>} */
+  const pPrRefByKey = new Map();
+  let nextPPrRefN = 1;
+  /** @type {Map<string, string>} */
+  const rPrRefByKey = new Map();
+  let nextRPrRefN = 1;
+  /** @type {import("../../model/node.js").StyleTable} */
+  const styleTable = {};
+  // ADR-0028: the document's own docDefaults, under a sentinel ref no real
+  // interned pPrRef/rPrRef can ever collide with (those are always
+  // `p${n}`/`r${n}`, above). commands/size.js's effectiveSize falls back to
+  // this ONLY when a run carries neither a direct marks.sz override nor an
+  // rPrRef at all — a freshly typed paragraph, not an imported one (every
+  // real corpus run already carries an rPrRef whose OWN chain already
+  // resolves through docDefaults via `resolve()`, measured 81,973/81,973).
+  // BOTH halves under the one sentinel: `readRPr` never emits a pPr key and
+  // `readPPr` never emits an rPr key, so the two flat records cannot collide
+  // (`sz` comes only from rPr, `jc`/`ind.*`/`spacing.*` only from pPr).
+  // ADR-0029 EKLEME A — and this dal is NOT dead code: measured 46/46 real
+  // corpus documents declare an explicit docDefaults `jc` (all "left").
+  styleTable[DOC_DEFAULT_STYLE_REF] = { ...sx.docDefaults.rPr, ...sx.docDefaults.pPr };
+
+  /**
+   * @param {import("./xml-scan.js").XmlElement | undefined} el
+   * @returns {string}
+   */
+  function contentOf(el) {
+    return el ? decoder.decode(xmlBytes.subarray(el.start, el.end)) : "";
+  }
+
+  /**
+   * @param {Record<string, import("./styles-resolve.js").ResolvedValue>} eff
+   * @returns {Record<string, string>}
+   */
+  function flattenEffective(eff) {
+    /** @type {Record<string, string>} */
+    const out = {};
+    for (const [f, [v]] of Object.entries(eff)) out[f] = v;
+    return out;
+  }
+
+  /**
+   * @param {string | undefined} styleId
+   * @param {import("./xml-scan.js").XmlElement | undefined} pPrEl
+   * @returns {string}
+   */
+  function internPPrRef(styleId, pPrEl) {
+    const key = contentOf(pPrEl);
+    const cached = pPrRefByKey.get(key);
+    if (cached !== undefined) {
+      // A hit here is only ever a NON-numPr paragraph — see below, a numPr
+      // paragraph's ref is never written into this cache in the first place.
+      return cached;
+    }
+    // numId/ilvl computed AFTER the resolve() cascade (not straight off
+    // readPPr's direct output) so a numId inherited from a paragraph STYLE
+    // (not just the paragraph's own direct pPr) is honored too — same
+    // override rule jc/ind already follow.
+    const props = flattenEffective(resolve(sx.docDefaults.pPr, sx.styles, styleId, readPPr(pPrEl), "pPr"));
+    const ref = `p${nextPPrRefN++}`;
+    if (props["numPr.numId"] !== undefined) {
+      // NEVER interned, even though this exact pPrEl's bytes may recur:
+      // numberingCounter.next() must advance once per PARAGRAPH OCCURRENCE
+      // (numbering.js), but consecutive items in the same list commonly
+      // carry byte-identical pPr XML (same numId/ilvl/jc/ind) — caching by
+      // byte content, as the non-numPr path below still correctly does,
+      // would freeze every one of them onto whichever marker the FIRST
+      // occurrence computed (the exact bug this rebuild closes).
+      const resolved = numberingCounter.next(props["numPr.numId"], props["numPr.ilvl"] ?? "0");
+      // Not resolved (missing numbering.xml, orphan numId/ilvl, or a format
+      // numbering.js could not map) -> DEFAULT_BULLET, never guessed, same
+      // fallback numbering.js itself uses. Flagged as a capability gap in
+      // UNVERIFIED_ASSUMPTIONS below, not per-document.
+      props["numPr.marker"] = resolved?.marker ?? DEFAULT_BULLET;
+      styleTable[ref] = props;
+      return ref;
+    }
+    pPrRefByKey.set(key, ref);
+    styleTable[ref] = props;
+    return ref;
+  }
+
+  /**
+   * @param {string | undefined} styleId
+   * @param {import("./xml-scan.js").XmlElement | undefined} rPrEl
+   * @returns {string}
+   */
+  function internRPrRef(styleId, rPrEl) {
+    const key = `${styleId ?? ""}\u0000${contentOf(rPrEl)}`;
+    let ref = rPrRefByKey.get(key);
+    if (ref === undefined) {
+      ref = `r${nextRPrRefN++}`;
+      rPrRefByKey.set(key, ref);
+      styleTable[ref] = flattenEffective(resolve(sx.docDefaults.rPr, sx.styles, styleId, readRPr(rPrEl), "rPr"));
+    }
+    return ref;
+  }
+
+  let nextId = 2; // 1 is the document itself — IdFactory(2) parity
+  /** @type {import("../../model/node.js").Container[]} */
+  const containers = [];
+  /** @type {import("../../model/node.js").LayoutMap} */
+  const layout = {};
+  /** @type {import("../../model/node.js").Decoration[]} */
+  const decorations = [];
+  /** @type {import("../../model/node.js").DocImage[]} */
+  const images = [];
+  const anchorRanges = createAnchorRanges();
+  const propBlobs = createPropBlobs();
+  /** @type {Set<string>} */
+  const unsupportedCommands = new Set();
+  /** @type {ImportReport["lockedShapes"]} */
+  const lockedShapes = [];
+  /** @type {ImportReport["skippedImages"]} */
+  const skippedImages = [];
+  /** @type {ImportReport["emptyShapes"]} */
+  const emptyShapes = [];
+  /** @type {ImportReport["emptyContainers"]} */
+  const emptyContainers = [];
+
+  for (let anchorIndex = 0; anchorIndex < anchors.length; anchorIndex++) {
+    const anchor = anchors[anchorIndex];
+    const pageNumber = pageForAnchor(sectPrStarts, anchor.start, page.count);
+
+    const positionH = findChild(anchor, WP_NS, "positionH");
+    const posOffsetH = positionH && findChild(positionH, WP_NS, "posOffset");
+    const positionV = findChild(anchor, WP_NS, "positionV");
+    const posOffsetV = positionV && findChild(positionV, WP_NS, "posOffset");
+    const extent = findChild(anchor, WP_NS, "extent");
+    if (!posOffsetH || !posOffsetV || !extent) {
+      rejectAnchorPlacement(!posOffsetH, !posOffsetV, !extent, `anchor ${anchorIndex}`);
+    }
+
+    const anchorX = Number.parseInt(textOf(posOffsetH) || "0", 10);
+    const anchorY = Number.parseInt(textOf(posOffsetV) || "0", 10);
+    const z = Number.parseInt(getAttr(anchor, "", "relativeHeight") ?? "0", 10);
+
+    const graphic = findChild(anchor, A_NS, "graphic");
+    const graphicData = graphic && findChild(graphic, A_NS, "graphicData");
+    if (!graphicData) rejectMissingGraphicData(`anchor ${anchorIndex}`);
+
+    /** @type {{el: import("./xml-scan.js").XmlElement, x: number, y: number, cx: number, cy: number, ownXfrm: {rot: number, flipH: boolean, flipV: boolean}}[]} */
+    const shapes = [];
+    // Every container this SAME anchor produces, and every pic:pic this same
+    // anchor contains — collected during this anchor's own processing below,
+    // then reconciled once (after the shapes loop) so each image's fidelity
+    // bucket reflects ALL of this anchor's containers, not just whichever
+    // were created before the image happened to be encountered.
+    /** @type {number[]} */
+    const containerIdsThisAnchor = [];
+    /** @type {{context: string, name: string | null, embedId: string | null, geom: {x: number, y: number, cx: number, cy: number} | null}[]} */
+    const pendingImagesThisAnchor = [];
+
+    const group = findChild(graphicData, WPG_NS, "wgp");
+    if (group) {
+      const gXfrm = parseXfrm(findChild(group, WPG_NS, "grpSpPr"));
+      if (!gXfrm) rejectMissingGroupTransform(`anchor ${anchorIndex} group`);
+      const gCnvPr = findChild(group, WPG_NS, "cNvPr");
+      const gId = gCnvPr ? (getAttr(gCnvPr, "", "id") ?? "?") : "?";
+      const gName = gCnvPr ? (getAttr(gCnvPr, "", "name") ?? "?") : "?";
+      const { scaleX, scaleY } = checkGroupIdentity(
+        gXfrm,
+        group,
+        `anchor ${anchorIndex} group id=${gId} name=${JSON.stringify(gName)}`,
+      );
+
+      for (const pic of findChildren(group, PIC_NS, "pic")) {
+        // Group-child placement uses the SAME transform a wsp sibling does
+        // (the group is identity, checkGroupIdentity above). A pic with no
+        // xfrm has no computable placement -> geom null -> report-only skip.
+        const pXfrm = parseXfrm(findChild(pic, PIC_NS, "spPr"));
+        pendingImagesThisAnchor.push({
+          context: `group id=${gId} name=${JSON.stringify(gName)}`,
+          name: picName(pic),
+          embedId: picEmbedId(pic),
+          geom: pXfrm === null ? null : {
+            x: anchorX + (pXfrm.offX - gXfrm.chOffX) * scaleX,
+            y: anchorY + (pXfrm.offY - gXfrm.chOffY) * scaleY,
+            cx: pXfrm.extCx * scaleX,
+            cy: pXfrm.extCy * scaleY,
+          },
+        });
+      }
+      for (const child of findChildren(group, WPS_NS, "wsp")) {
+        const cXfrm = parseXfrm(findChild(child, WPS_NS, "spPr"));
+        if (!cXfrm) rejectMissingShapeTransform(`anchor ${anchorIndex} group id=${gId} name=${JSON.stringify(gName)}`);
+        shapes.push({
+          el: child,
+          x: anchorX + (cXfrm.offX - gXfrm.chOffX) * scaleX,
+          y: anchorY + (cXfrm.offY - gXfrm.chOffY) * scaleY,
+          cx: cXfrm.extCx * scaleX,
+          cy: cXfrm.extCy * scaleY,
+          ownXfrm: cXfrm,
+        });
+      }
+    } else {
+      const wsp = findChild(graphicData, WPS_NS, "wsp");
+      if (!wsp) {
+        const pic = findChild(graphicData, PIC_NS, "pic");
+        if (!pic) rejectUnsupportedGraphicDataKind(`anchor ${anchorIndex}`);
+        // A non-grouped anchor's graphicData holds EITHER wps:wsp OR pic:pic
+        // (this branch is only reached when wsp was absent) — it structurally
+        // cannot ALSO have produced a container from this same anchor, so it is
+        // always PRESERVED. Placement is the anchor's own posOffset + extent.
+        // Rendered (Doc.images) when its bytes resolve; otherwise report-only.
+        const mediaPartName = resolveMedia(picEmbedId(pic), relsMap);
+        if (mediaPartName !== null) {
+          images.push({
+            id: nextId++,
+            page: pageNumber,
+            x: emuToPt(anchorX),
+            y: emuToPt(anchorY),
+            cx: emuToPt(Number.parseInt(getAttr(extent, "", "cx") ?? "0", 10)),
+            cy: emuToPt(Number.parseInt(getAttr(extent, "", "cy") ?? "0", 10)),
+            z,
+            mediaPartName,
+          });
+        } else {
+          skippedImages.push({
+            anchorIndex,
+            context: "top-level (ungrouped)",
+            name: picName(pic),
+            fidelity: "PRESERVED",
+            sharedContainerIds: [],
+            anchorRange: { start: anchor.start, end: anchor.end },
+          });
+        }
+        continue;
+      }
+      const ownXfrm = parseXfrm(findChild(wsp, WPS_NS, "spPr")) ?? { rot: 0, flipH: false, flipV: false };
+      shapes.push({
+        el: wsp,
+        x: anchorX,
+        y: anchorY,
+        cx: Number.parseInt(getAttr(extent, "", "cx") ?? "0", 10),
+        cy: Number.parseInt(getAttr(extent, "", "cy") ?? "0", 10),
+        ownXfrm,
+      });
+    }
+
+    for (const { el: wsp, x, y, cx, cy, ownXfrm } of shapes) {
+      const spPr = findChild(wsp, WPS_NS, "spPr");
+      const txbxWrap = findChild(wsp, WPS_NS, "txbx");
+      const txbx = txbxWrap && findChild(txbxWrap, W_NS, "txbxContent");
+
+      const shapeRot = ownXfrm.rot ?? 0;
+      const shapeFlipH = ownXfrm.flipH ?? false;
+      const shapeFlipV = ownXfrm.flipV ?? false;
+      const locked = isShapeLocked({ rot: shapeRot, flipH: shapeFlipH, flipV: shapeFlipV });
+
+      if (txbx) {
+        const parsedParagraphs = paragraphsOf(txbx);
+        const paragraphIds = [];
+        // (ref, element) pairs for this container's pPr/rPr byte slices (ADR-0017
+        // opaque blobs). Collected here because the byte ranges are in hand at the
+        // intern sites, but recorded into `propBlobs` only after `containerId` is
+        // minted below — the map runs before that id exists.
+        /** @type {{ref: string, el: import("./xml-scan.js").XmlElement}[]} */
+        const propBlobEls = [];
+        const paragraphs = parsedParagraphs.map((p) => {
+          const id = nextId++;
+          paragraphIds.push(id);
+          const styleId = p.pStyleId ?? sx.defaultParagraphStyle ?? undefined;
+          const pPrRef = internPPrRef(styleId, p.pPrEl);
+          if (p.pPrEl) propBlobEls.push({ ref: pPrRef, el: p.pPrEl });
+          return createParagraph(
+            id,
+            p.runs.map((r) => {
+              const rPrRef = internRPrRef(styleId, r.rPrEl);
+              if (r.rPrEl) propBlobEls.push({ ref: rPrRef, el: r.rPrEl });
+              return createRun(r.text, { ...r.marks, rPrRef });
+            }),
+            { pPrRef },
+          );
+        });
+        // ADR-0021 (2026-08-27): a text box with zero non-empty runs is a
+        // RUN-LESS text box, not a separate class — M7 (commit 8bcc087)
+        // measured every supposed "empty box" signature on all 5,508 FILLED
+        // boxes too, so none of them distinguishes it. It becomes an editable
+        // Container like any other; normalize.js keeps an empty paragraph's
+        // single empty run and render/dom.js prints a <br> filler, so the
+        // model and renderer already accept this (a filled box with a blank
+        // paragraph produces the same zero-run Paragraph today). Its id is
+        // surfaced in emptyContainers so a consumer can still flag it as an
+        // unfilled form field — the very reason these documents are opened —
+        // but it is NOT skipped: it is clickable and editable now.
+        const hasAnyRuns = parsedParagraphs.some((p) => p.runs.length > 0);
+
+        const containerId = nextId++;
+        containers.push(createContainer(containerId, paragraphs));
+        recordAnchorRange(anchorRanges, containerId, anchor);
+        for (const { ref, el } of propBlobEls) recordPropBlob(propBlobs, containerId, ref, el);
+        containerIdsThisAnchor.push(containerId);
+        if (!hasAnyRuns) emptyContainers.push(containerId);
+
+        /** @type {import("../../model/node.js").BoxLayout} */
+        const layoutEntry = { page: pageNumber, x: emuToPt(x), y: emuToPt(y), cx: emuToPt(cx), cy: emuToPt(cy), z };
+        if (locked) {
+          layoutEntry.rot = shapeRot;
+          layoutEntry.flipH = shapeFlipH;
+          layoutEntry.flipV = shapeFlipV;
+          layoutEntry.locked = true;
+          const cnvpr = findChild(wsp, WPS_NS, "cNvPr");
+          lockedShapes.push({
+            containerId,
+            name: cnvpr ? (getAttr(cnvpr, "", "name") ?? null) : null,
+            rot: shapeRot,
+            flipH: shapeFlipH,
+            flipV: shapeFlipV,
+          });
+        }
+        layout[containerId] = layoutEntry;
+        continue;
+      }
+
+      const { paths, unsupported } = decorationPaths(spPr);
+      for (const u of unsupported) unsupportedCommands.add(u);
+      const fillHex = solidFillHex(spPr);
+      if (paths.length === 0 && fillHex === null) {
+        // Symmetric to the text-box case above — a decorative shape with
+        // neither a custGeom path nor a direct fill renders as nothing.
+        // Measured 2026-08-27: 0/2,697 real corpus decorative shapes
+        // trigger this (kural değil enstrüman until the corpus witnesses
+        // one — see OOXML mutation registry).
+        const cnvpr = findChild(wsp, WPS_NS, "cNvPr");
+        emptyShapes.push({ anchorIndex, kind: "decoration", name: cnvpr ? (getAttr(cnvpr, "", "name") ?? null) : null });
+        continue;
+      }
+
+      const decorationId = nextId++;
+      decorations.push({
+        id: decorationId,
+        page: pageNumber,
+        x: emuToPt(x),
+        y: emuToPt(y),
+        cx: emuToPt(cx),
+        cy: emuToPt(cy),
+        z,
+        fillHex,
+        paths,
+      });
+      recordAnchorRange(anchorRanges, decorationId, anchor);
+    }
+
+    // Reconciled once per anchor, after every shape (and so every container
+    // this anchor could produce) has been processed — ADR-0020 Karar 6: an
+    // image is DEGRADED exactly when its OWN anchor also produced at least
+    // one container (an editable text box); touching that container marks
+    // the whole anchor dirty for a future P6 export, which has no image
+    // render branch to re-emit this picture with. Measured 2026-08-27
+    // (46/46 real corpus documents): 0/466 images are DEGRADED under this
+    // rule — every wps:wsp sibling of every pic:pic in this corpus is a
+    // decorative shape (no txbx element at all), never a text box. The rule
+    // is still implemented for the general case (a corpus-external document,
+    // or this app someday allowing decorative-shape edits, could trigger it).
+    const anchorIsDegraded = containerIdsThisAnchor.length > 0;
+    for (const pending of pendingImagesThisAnchor) {
+      const mediaPartName = resolveMedia(pending.embedId, relsMap);
+      // Rendered (Doc.images) only when PRESERVED and BOTH bytes and placement
+      // resolve. DEGRADED (shares an anchor with an editable container — 0/466
+      // in the corpus) or an unresolvable embed/geometry stays a report-only
+      // skip, keeping ADR-0020 Karar 6's at-risk signal for a future export.
+      if (!anchorIsDegraded && mediaPartName !== null && pending.geom !== null) {
+        images.push({
+          id: nextId++,
+          page: pageNumber,
+          x: emuToPt(pending.geom.x),
+          y: emuToPt(pending.geom.y),
+          cx: emuToPt(pending.geom.cx),
+          cy: emuToPt(pending.geom.cy),
+          z,
+          mediaPartName,
+        });
+      } else {
+        skippedImages.push({
+          anchorIndex,
+          context: pending.context,
+          name: pending.name,
+          fidelity: anchorIsDegraded ? "DEGRADED" : "PRESERVED",
+          sharedContainerIds: [...containerIdsThisAnchor],
+          anchorRange: { start: anchor.start, end: anchor.end },
+        });
+      }
+    }
+  }
+
+  const doc = createDoc(1, containers, layout, { page, decorations, images, styles: styleTable });
+
+  return {
+    doc,
+    ids: createIdFactory(nextId),
+    anchorRanges,
+    report: {
+      unsupportedCommands: [...unsupportedCommands].sort(),
+      lockedShapes,
+      skippedImages,
+      emptyShapes,
+      emptyContainers,
+      unverifiedAssumptions: UNVERIFIED_ASSUMPTIONS,
+    },
+    // §3.5 retention (document-level half — `importDocx` adds packageBytes/entries).
+    // documentXmlBytes is the exact inflated word/document.xml piece 3 splices;
+    // dirty starts empty (pieces 4b/5 fill it).
+    provenance: { documentXmlBytes: xmlBytes, anchorRanges, propBlobs, dirty: new Set() },
+  };
+}
+
+/**
+ * The relationships (`Id -> resolved part name`) for the main document part.
+ * Its rels part is `<dir>/_rels/<name>.rels` beside the part; an absent one (a
+ * document with no relationships at all) yields an empty map. Targets resolve
+ * against the part's own directory (`<dir>`), the OPC rule.
+ * @param {Uint8Array} bytes
+ * @param {import("./zip-container.js").ZipEntry[]} entries
+ * @param {string} mainPartName  e.g. `"word/document.xml"`
+ * @returns {Promise<Map<string, string>>}
+ */
+async function loadRelationships(bytes, entries, mainPartName) {
+  const slash = mainPartName.lastIndexOf("/");
+  const dir = slash === -1 ? "" : mainPartName.slice(0, slash);
+  const name = slash === -1 ? mainPartName : mainPartName.slice(slash + 1);
+  const relsName = `${dir === "" ? "" : `${dir}/`}_rels/${name}.rels`;
+  const relsEntry = entries.find((e) => e.name === relsName);
+  if (relsEntry === undefined) return new Map();
+  const relsBytes = await inflateEntry(bytes, relsEntry);
+  const { root } = scanXml(relsBytes);
+  return parseRelationships(root, dir);
+}
+
+/**
+ * @param {Uint8Array} bytes  a whole .docx file's bytes
+ * @returns {Promise<ConvertResult>}
+ */
+export async function importDocx(bytes) {
+  const entries = parseZipContainer(bytes);
+  const mainPart = resolveMainDocumentPart(entries);
+  const stylesPart = resolveStylesPart(entries);
+  const xmlBytes = await inflateEntry(bytes, mainPart);
+  const stylesBytes = await inflateEntry(bytes, stylesPart);
+  const { root } = scanXml(xmlBytes);
+  const { root: stylesRoot } = scanXml(stylesBytes);
+  const relsMap = await loadRelationships(bytes, entries, mainPart.name);
+  // word/numbering.xml is OPTIONAL (30/46 real corpus documents carry it) —
+  // a fixed path lookup like resolveStylesPart's, but tolerant of absence
+  // rather than throwing: a numPr paragraph in a document with no
+  // numbering.xml still renders (numbering.js's default-bullet fallback).
+  const numberingPart = entries.find((e) => e.name === "word/numbering.xml");
+  const numberingRoot =
+    numberingPart !== undefined ? scanXml(await inflateEntry(bytes, numberingPart)).root : null;
+  const result = convertDocument(root, xmlBytes, stylesRoot, relsMap, numberingRoot);
+  // Retain the original OPC package (§3.5 step 1) so piece 2 (repack) can
+  // byte-copy every untouched part verbatim — convertDocument only had the
+  // inflated document.xml. `bytes` is the caller's array (a reference, not a
+  // copy); `entries` is re-derivable from it but kept to avoid a re-parse.
+  return { ...result, provenance: { ...result.provenance, packageBytes: bytes, entries } };
+}