@stll/folio-core 0.46.0 → 0.47.1

package/dist/docx/commentAnchorIndex.js

@@ -19,7 +19,7 @@ const visitCommentMarkers = (blocks, visit) => {
 			for (const row of block.rows) for (const cell of row.cells) visitBlocks(cell.content);
 			return;
 		}
-		if (block.type === "preservedBlock") return;
+		if (block.type !== "blockSdt") return;
 		visitBlocks(block.content);
 	};
 	const visitBlocks = (nested) => {

package/dist/docx/commentParser.js

@@ -3,7 +3,7 @@ import { CAPTURE, dispatchChildren } from "./containerChildren.js";
 import { PARA_ID_NAMESPACE_URIS, paraIdAttribute, paraIdParentAttribute } from "./paraIdAttribute.js";
 import { parseParagraph } from "./paragraphParser.js";
 import { cloneParagraphWithPropertySource } from "./paragraphPropertySource.js";
-import { parseRunProperties } from "./runParser.js";
+import { RUN_PROPERTY_OWNERS, parseRunProperties } from "./runParser.js";
 import { findChild, getAttribute, getAttributeByNamespaceUri, getChildElements, getLocalName, parseOnOffValue, parseXml } from "./xmlParser.js";
 import { PARSE_WARNING_CODES } from "@stll/docx-core/model";
 //#region src/docx/commentParser.ts
@@ -36,7 +36,7 @@ const normalizeFirstCommentParagraph = (paragraphElement, paragraph, theme) => {
 	const firstContentElement = getChildElements(paragraphElement).find((element) => getLocalName(element.name) !== "pPr");
 	if (!firstContentElement || getLocalName(firstContentElement.name) !== "r" || !findChild(firstContentElement, "w", "annotationRef")) return { paragraph };
 	const runProperties = findChild(firstContentElement, "w", "rPr");
-	const annotationReferenceFormatting = normalizeAnnotationReferenceFormatting(runProperties ? parseRunProperties(runProperties, theme) : void 0);
+	const annotationReferenceFormatting = normalizeAnnotationReferenceFormatting(runProperties ? parseRunProperties(runProperties, theme, RUN_PROPERTY_OWNERS.standalone) : void 0);
 	const firstParsedContent = paragraph.content.at(0);
 	return {
 		paragraph: firstParsedContent?.type === "run" && firstParsedContent.content.every((item) => item.type === "preservedXml" && item.text === "") ? cloneParagraphWithPropertySource(paragraph, { content: paragraph.content.slice(1) }) : paragraph,
@@ -140,7 +140,7 @@ function parseComments(commentsXml, styles, theme, rels, media, commentsExtensib
 		const preserved = dispatchChildren({
 			element: child,
 			container: "w:comment",
-			modelledCount: () => paragraphs.length,
+			capturePosition: () => paragraphs.length,
 			handlers: {
 				p: (contentChild) => {
 					const paragraph = parseParagraph(contentChild, styles, theme, null, rels, media);

package/dist/docx/commentRangeIntegrity.js

@@ -147,7 +147,7 @@ const withoutOrphanBlockMarkers = (blocks, validCommentIds) => {
 const withoutOrphanBlockMarker = (block, validCommentIds) => {
 	if (block.type === "paragraph") return withoutOrphanParagraphMarkers(block, validCommentIds);
 	if (block.type === "table") return withoutOrphanTableMarkers(block, validCommentIds);
-	if (block.type === "preservedBlock") return block;
+	if (block.type !== "blockSdt") return block;
 	const content = withoutOrphanBlockMarkers(block.content, validCommentIds);
 	if (!content) return block;
 	return {

package/dist/docx/commentRangeJoin.js

@@ -1,5 +1,5 @@
 import { visitCommentMarkers } from "./commentAnchorIndex.js";
-import { InlineContentRemovals } from "./paragraphTraversal.js";
+import { InlineContentRemovals } from "./inlineContentRemovals.js";
 //#region src/docx/commentRangeJoin.ts
 /**
 * Collapse each comment's range markers to its first start and its last end.

package/dist/docx/commentReferenceNormalization.js

@@ -1,4 +1,5 @@
-import { InlineContentRemovals, visitInlineContentSlots } from "./paragraphTraversal.js";
+import { InlineContentRemovals } from "./inlineContentRemovals.js";
+import { visitInlineContentSlots } from "./paragraphTraversal.js";
 import { PARSE_WARNING_CODES } from "@stll/docx-core/model";
 //#region src/docx/commentReferenceNormalization.ts
 /** The codes this normalisation is reported under, owned here, not at the caller. */
@@ -39,7 +40,7 @@ const normalizeCommentReferences = ({ documentBody, comments, headers, footers,
 			normalizeTable(block);
 			return;
 		}
-		if (block.type === "preservedBlock") return;
+		if (block.type !== "blockSdt") return;
 		normalizeBlocks(block.content);
 	};
 	const normalizeBlocks = (blocks) => {

package/dist/docx/commentReplyMarkers.js

@@ -25,7 +25,7 @@ const eachParagraph = (blocks, visit) => {
 			for (const row of block.rows ?? []) for (const cell of row.cells ?? []) eachParagraph(cell.content ?? [], visit);
 			continue;
 		}
-		if (block.type === "preservedBlock") continue;
+		if (block.type !== "blockSdt") continue;
 		eachParagraph(block.content ?? [], visit);
 	}
 };

package/dist/docx/compatibility.js

@@ -1,4 +1,5 @@
 import { DRAWING_SAFETY_CLASSES, classifyDrawingSafety } from "./imageRawXml.js";
+import { panic } from "better-result";
 import { DOCX_CONFORMANCE_CLASSES } from "@stll/docx-core/model";
 //#region src/docx/compatibility.ts
 /**
@@ -97,7 +98,7 @@ function inspectBlocks(blocks, context) {
 			});
 			continue;
 		}
-		if (block.type === "preservedBlock") continue;
+		if (block.type !== "blockSdt") continue;
 		inspectBlocks(block.content, {
 			part: context.part,
 			path: `${blockPath}.content`,
@@ -114,53 +115,66 @@ function inspectParagraphContent(content, context) {
 			...context,
 			path: `${context.path}[${itemIndex}]`
 		};
-		if (item.type === "run") {
-			inspectRun(item, itemContext);
-			continue;
-		}
-		if (item.type === "hyperlink") {
-			inspectHyperlink(item, itemContext);
-			continue;
-		}
-		if (item.type === "inlineSdt") {
-			inspectParagraphContent(item.content, {
-				...itemContext,
-				path: `${itemContext.path}.content`
-			});
-			continue;
+		switch (item.type) {
+			case "run":
+				inspectRun(item, itemContext);
+				continue;
+			case "hyperlink":
+				inspectHyperlink(item, itemContext);
+				continue;
+			case "inlineSdt":
+			case "inlineWrapper":
+			case "insertion":
+			case "deletion":
+			case "moveFrom":
+			case "moveTo":
+			case "simpleField":
+				inspectParagraphContent(item.content, {
+					...itemContext,
+					path: `${itemContext.path}.content`
+				});
+				continue;
+			case "complexField":
+				for (const [runIndex, run] of item.fieldCode.entries()) inspectRun(run, {
+					...itemContext,
+					path: `${itemContext.path}.fieldCode[${runIndex}]`
+				});
+				for (const [runIndex, run] of item.fieldResult.entries()) inspectRun(run, {
+					...itemContext,
+					path: `${itemContext.path}.fieldResult[${runIndex}]`
+				});
+				continue;
+			case "bookmarkStart":
+			case "bookmarkEnd":
+			case "commentRangeStart":
+			case "commentRangeEnd":
+			case "commentReference":
+			case "moveFromRangeStart":
+			case "moveFromRangeEnd":
+			case "moveToRangeStart":
+			case "moveToRangeEnd":
+			case "mathEquation":
+			case "preservedInline": continue;
+			default: panic(`Unsupported paragraph content: ${JSON.stringify(item)}`);
 		}
-		if (item.type === "insertion" || item.type === "deletion" || item.type === "moveFrom" || item.type === "moveTo") {
-			inspectParagraphContent(item.content, {
-				...itemContext,
-				path: `${itemContext.path}.content`
-			});
-			continue;
-		}
-		if (item.type === "simpleField") {
-			inspectParagraphContent(item.content, {
-				...itemContext,
-				path: `${itemContext.path}.content`
+	}
+}
+function inspectHyperlink(hyperlink, context) {
+	for (const [childIndex, child] of hyperlink.children.entries()) {
+		const path = `${context.path}.children[${childIndex}]`;
+		if (child.type === "run") {
+			inspectRun(child, {
+				...context,
+				path
 			});
 			continue;
 		}
-		if (item.type === "complexField") {
-			for (const [runIndex, run] of item.fieldCode.entries()) inspectRun(run, {
-				...itemContext,
-				path: `${itemContext.path}.fieldCode[${runIndex}]`
-			});
-			for (const [runIndex, run] of item.fieldResult.entries()) inspectRun(run, {
-				...itemContext,
-				path: `${itemContext.path}.fieldResult[${runIndex}]`
-			});
-		}
+		if (child.type === "inlineWrapper") inspectParagraphContent(child.content, {
+			...context,
+			path: `${path}.content`
+		});
 	}
 }
-function inspectHyperlink(hyperlink, context) {
-	for (const [childIndex, child] of hyperlink.children.entries()) if (child.type === "run") inspectRun(child, {
-		...context,
-		path: `${context.path}.children[${childIndex}]`
-	});
-}
 function inspectRun(run, context) {
 	for (const [contentIndex, content] of run.content.entries()) {
 		if (content.type !== "drawing") continue;

package/dist/docx/containerChildren.d.ts

@@ -1,9 +1,30 @@
 import { XmlElement } from "./xmlParser.js";
 import { DeclaredChild, DispatchedContainer } from "./containerChildren.gen.js";
-import { PreservedMarkup } from "@stll/docx-core/model";
+import { PreservedChild, PreservedMarkup } from "@stll/docx-core/model";
+import { SequenceContainer } from "@stll/docx-core/schema";
 //#region src/docx/containerChildren.d.ts
 /** Keep this child's markup verbatim, in place. */
 declare const CAPTURE = "capture";
+/**
+ * What a handler answers with: nothing when it took a typed value, and
+ * {@link CAPTURE} when it took none, so the child's bytes are kept instead.
+ *
+ * `<w:tblLayout/>` states no layout and `<w:jc w:val="end"/>` states a value a
+ * reader's enumeration does not admit. Both used to fall off the end of the
+ * walk, and neither can be decided by name: a map keyed by name cannot list
+ * the values a reader will refuse, only the names it has never heard of.
+ */
+declare const keptUnless: (taken: boolean) => typeof CAPTURE | undefined;
+declare const OWNED_ELSEWHERE = "owned-elsewhere";
+/**
+ * Who reads a child this walk skips: `<module>#<export>`.
+ *
+ * The module is a file under `packages/core/src/docx/` without its extension,
+ * and the export is the function that reads the child off the container
+ * element. Both halves are resolved by `scripts/container-ownership.test.ts`,
+ * which imports every one of them.
+ */
+type ChildOwnerRef = `${string}#${string}`;
 /**
  * Another reader owns this child, and re-emits it.
  *
@@ -11,8 +32,46 @@ declare const CAPTURE = "capture";
  * under a run, lifted out by the paragraph parser. Capturing one of these as
  * well would write it twice, so the disposition has to be stated rather than
  * left to a bare `break`.
+ *
+ * A capture and a handler are verified by running them: the survival law
+ * exercises the pair and reports what came back. This one is a claim about a
+ * *different module*, and nothing ran it. `w:tr/w:tblPrEx` carried it while
+ * the container contract recorded the same pair as never parsed, and the two
+ * statements sat side by side without contradicting each other. So the claim
+ * names its owner, `ownedElsewhere` registers it where a check can read it,
+ * and `scripts/lib/container-survival/ownership.ts` refuses a contract that
+ * records an owned pair as never parsed or lost with its container.
+ *
+ * The container and the child are on the value rather than inferred from the
+ * key, and {@link ChildHandlers} binds them to it: an entry that names a child
+ * other than the one it is filed under does not compile.
  */
-declare const OWNED_ELSEWHERE = "owned-elsewhere";
+type OwnedElsewhere<Container extends DispatchedContainer = DispatchedContainer, Child extends string = string> = {
+  readonly disposition: typeof OWNED_ELSEWHERE;
+  readonly container: Container;
+  readonly child: Child;
+  readonly reader: ChildOwnerRef;
+};
+/** One handler map's claim that another reader owns one of its children. */
+type ChildOwnerClaim = {
+  readonly container: DispatchedContainer;
+  readonly child: string;
+  readonly reader: ChildOwnerRef;
+};
+/**
+ * Every owner a handler map has claimed so far.
+ *
+ * A claim is registered when `ownedElsewhere` is called, so a module that is
+ * never imported contributes none. The checks that read this therefore load
+ * the claiming modules first, by scanning the sources for the call rather than
+ * by keeping a list beside them.
+ */
+declare const ownedElsewhereClaims: () => readonly ChildOwnerClaim[];
+/** State that another reader takes this child, and who. */
+declare const ownedElsewhere: <Container extends DispatchedContainer, Child extends DeclaredChild<Container>>(claim: ChildOwnerClaim & {
+  container: Container;
+  child: Child;
+}) => OwnedElsewhere<Container, Child>;
 /**
  * This child goes with the wrapper folio does not keep.
  *
@@ -24,15 +83,27 @@ declare const OWNED_ELSEWHERE = "owned-elsewhere";
  * difference between this and a `default` that says nothing.
  */
 declare const DROPPED_WITH_ITS_WRAPPER = "dropped-with-its-wrapper";
-/** What a container does with one declared child. */
-type ChildDisposition = ((child: XmlElement) => void) | typeof CAPTURE | typeof DROPPED_WITH_ITS_WRAPPER | typeof OWNED_ELSEWHERE;
+/**
+ * What a container does with one declared child.
+ *
+ * A handler that reads the child may hand it back by returning {@link CAPTURE}
+ * — "I looked and took nothing from this, so keep the bytes". A property set
+ * needs it: `<w:cols/>` states no column count, `<w:jc w:val="end"/>` states a
+ * value the reader's enumeration does not admit, and a handler that turns
+ * neither into a typed value leaves the element with nowhere to go. Deciding
+ * it by the outcome rather than by the name is what makes the decision total:
+ * the map cannot list the values a reader will refuse.
+ */
+type ChildDisposition<Container extends DispatchedContainer = DispatchedContainer, Child extends string = string> = ((child: XmlElement) => typeof CAPTURE | void) | typeof CAPTURE | typeof DROPPED_WITH_ITS_WRAPPER | OwnedElsewhere<Container, Child>;
 /**
  * A total decision per declared child.
  *
- * `Record`, never `Partial<Record>`: a partial map lets a new declared child
- * land without a decision, which is the drop this module exists to prevent.
+ * Total, never `Partial`: a partial map lets a new declared child land without
+ * a decision, which is the drop this module exists to prevent. The value's
+ * type is keyed by the child it is filed under, so an {@link ownedElsewhere}
+ * entry cannot name a different child than the one it decides.
  */
-type ChildHandlers<Container extends DispatchedContainer> = Readonly<Record<DeclaredChild<Container>, ChildDisposition>>;
+type ChildHandlers<Container extends DispatchedContainer> = Readonly<{ [Child in DeclaredChild<Container>]: ChildDisposition<Container, Child>; }>;
 type DispatchChildrenOptions<Container extends DispatchedContainer> = {
   /** The container element, as the source wrote it. */
   element: XmlElement;
@@ -40,10 +111,17 @@ type DispatchChildrenOptions<Container extends DispatchedContainer> = {
   container: Container;
   handlers: ChildHandlers<Container>;
   /**
-   * How many modelled children the caller holds right now. Called once per
-   * captured child, so the capture lands after the siblings already read.
+   * Where a capture belongs among the caller's children, called once per
+   * captured child.
+   *
+   * A container that models one kind of child answers with how many it holds
+   * right now, so the capture lands after the siblings already read. A
+   * container whose content model is a fixed sequence answers with the child's
+   * own ordinal in that sequence, because there the position is decided by the
+   * name rather than by what happened to be read first; see
+   * {@link sequencePositions}.
    */
-  modelledCount: () => number;
+  capturePosition: (child: XmlElement) => number;
   /**
    * Dispositions for names the container's content model does not declare.
    *
@@ -93,7 +171,7 @@ declare const transitionalNamespaceOf: (namespace: string) => string;
  *   none — an empty record is never written, so a fully modelled container
  *   stays byte-identical in the model.
  */
-declare const dispatchChildren: <Container extends DispatchedContainer>({ element, handlers, modelledCount, undeclared, undeclaredNamespaces }: DispatchChildrenOptions<Container>) => PreservedMarkup | undefined;
+declare const dispatchChildren: <Container extends DispatchedContainer>({ element, handlers, capturePosition, undeclared, undeclaredNamespaces }: DispatchChildrenOptions<Container>) => PreservedMarkup | undefined;
 /**
  * Put a container's modelled children back with its preserved ones between
  * them, in source position.
@@ -104,8 +182,27 @@ declare const dispatchChildren: <Container extends DispatchedContainer>({ elemen
  *
  * @param wrap turns one capture's markup into whatever the caller's list holds
  */
-declare const withPreservedChildren: <Item>(modelled: readonly Item[], preserved: PreservedMarkup | undefined, wrap: (xml: string) => Item) => Item[];
+declare const withPreservedChildren: <Item, Child extends PreservedChild = PreservedChild>(modelled: readonly Item[], preserved: {
+  children?: Child[];
+} | undefined, wrap: (xml: string, child: Child) => Item) => Item[];
 /** {@link withPreservedChildren} for a caller that already holds markup. */
 declare const serializeWithPreservedChildren: (modelled: readonly string[], preserved: PreservedMarkup | undefined) => string;
+/**
+ * Where each child sits in a container whose content model is one flat sequence.
+ *
+ * A property set is that container: `CT_TblPr` and `CT_SectPr` are sequences
+ * of optional singletons, so a child's position is a property of its name and
+ * the generated list is the order. That is what the sink records for them,
+ * rather than a count of modelled siblings: the count is a mirror of whichever
+ * properties folio models today, and it moves under the capture the moment one
+ * more of them is modelled.
+ *
+ * An undeclared child — a foreign namespace, an `mc:` construct, a name a
+ * later revision of the format adds — has no place in the sequence, so it
+ * takes the place of the last declared child before it and comes back beside
+ * the same neighbour. One before every declared child takes position `-1`,
+ * ahead of the sequence's first slot.
+ */
+declare const sequencePositions: <Container extends SequenceContainer>(container: Container, element: XmlElement) => ((child: XmlElement) => number);
 //#endregion
-export { CAPTURE, ChildDisposition, ChildHandlers, DROPPED_WITH_ITS_WRAPPER, OWNED_ELSEWHERE, dispatchChildren, serializeWithPreservedChildren, transitionalNamespaceOf, withPreservedChildren };
+export { CAPTURE, ChildDisposition, ChildHandlers, ChildOwnerClaim, ChildOwnerRef, DROPPED_WITH_ITS_WRAPPER, OwnedElsewhere, dispatchChildren, keptUnless, ownedElsewhere, ownedElsewhereClaims, sequencePositions, serializeWithPreservedChildren, transitionalNamespaceOf, withPreservedChildren };

package/dist/docx/containerChildren.gen.d.ts

@@ -12,10 +12,25 @@
  *   bun run generate:container-children
  */
 declare const CONTAINER_CHILDREN: {
+  readonly "w:numbering": readonly ["numPicBullet", "abstractNum", "num", "numIdMacAtCleanup"];
+  readonly "w:abstractNum": readonly ["nsid", "multiLevelType", "tmpl", "name", "styleLink", "numStyleLink", "lvl"];
+  readonly "w:lvl": readonly ["start", "numFmt", "lvlRestart", "pStyle", "isLgl", "suff", "lvlText", "lvlPicBulletId", "legacy", "lvlJc", "pPr", "rPr"];
+  readonly "w:num": readonly ["abstractNumId", "lvlOverride"];
+  readonly "w:lvlOverride": readonly ["startOverride", "lvl"];
+  readonly "paragraph-properties": readonly ["pStyle", "keepNext", "keepLines", "pageBreakBefore", "framePr", "widowControl", "numPr", "suppressLineNumbers", "pBdr", "shd", "tabs", "suppressAutoHyphens", "kinsoku", "wordWrap", "overflowPunct", "topLinePunct", "autoSpaceDE", "autoSpaceDN", "bidi", "adjustRightInd", "snapToGrid", "spacing", "ind", "contextualSpacing", "mirrorIndents", "suppressOverlap", "jc", "textDirection", "textAlignment", "textboxTightWrap", "outlineLvl", "divId", "cnfStyle", "rPr", "sectPr", "pPrChange"];
+  readonly "table-properties": readonly ["tblStyle", "tblpPr", "tblOverlap", "bidiVisual", "tblStyleRowBandSize", "tblStyleColBandSize", "tblW", "jc", "tblCellSpacing", "tblInd", "tblBorders", "shd", "tblLayout", "tblCellMar", "tblLook", "tblCaption", "tblDescription", "tblPrChange"];
+  readonly "table-property-exceptions": readonly ["tblW", "jc", "tblCellSpacing", "tblInd", "tblBorders", "shd", "tblLayout", "tblCellMar", "tblLook", "tblPrExChange"];
+  readonly "row-properties": readonly ["cnfStyle", "divId", "gridBefore", "gridAfter", "wBefore", "wAfter", "cantSplit", "trHeight", "tblHeader", "tblCellSpacing", "jc", "hidden", "ins", "del", "trPrChange"];
+  readonly "cell-properties": readonly ["cnfStyle", "tcW", "gridSpan", "hMerge", "vMerge", "tcBorders", "shd", "noWrap", "tcMar", "textDirection", "tcFitText", "vAlign", "hideMark", "headers", "cellIns", "cellDel", "cellMerge", "tcPrChange"];
+  readonly "run-properties": readonly ["ins", "del", "moveFrom", "moveTo", "rStyle", "rFonts", "b", "bCs", "i", "iCs", "caps", "smallCaps", "strike", "dstrike", "outline", "shadow", "emboss", "imprint", "noProof", "snapToGrid", "vanish", "webHidden", "color", "spacing", "w", "kern", "position", "sz", "szCs", "highlight", "u", "effect", "bdr", "shd", "fitText", "vertAlign", "rtl", "cs", "em", "lang", "eastAsianLayout", "specVanish", "oMath", "rPrChange"];
+  readonly "content-control-properties": readonly ["rPr", "alias", "tag", "id", "lock", "placeholder", "temporary", "showingPlcHdr", "dataBinding", "label", "tabIndex", "equation", "comboBox", "date", "docPartObj", "docPartList", "dropDownList", "picture", "richText", "text", "citation", "group", "bibliography"];
+  readonly "section-properties": readonly ["headerReference", "footerReference", "footnotePr", "endnotePr", "type", "pgSz", "pgMar", "paperSrc", "pgBorders", "lnNumType", "pgNumType", "cols", "formProt", "vAlign", "noEndnote", "titlePg", "textDirection", "bidi", "rtlGutter", "docGrid", "printerSettings", "sectPrChange"];
   readonly "w:comment": readonly ["altChunk", "bookmarkEnd", "bookmarkStart", "commentRangeEnd", "commentRangeStart", "customXml", "customXmlDelRangeEnd", "customXmlDelRangeStart", "customXmlInsRangeEnd", "customXmlInsRangeStart", "customXmlMoveFromRangeEnd", "customXmlMoveFromRangeStart", "customXmlMoveToRangeEnd", "customXmlMoveToRangeStart", "del", "ins", "moveFrom", "moveFromRangeEnd", "moveFromRangeStart", "moveTo", "moveToRangeEnd", "moveToRangeStart", "p", "permEnd", "permStart", "proofErr", "sdt", "tbl"];
-  readonly "run-level-content": readonly ["bdo", "bookmarkEnd", "bookmarkStart", "commentRangeEnd", "commentRangeStart", "customXml", "customXmlDelRangeEnd", "customXmlDelRangeStart", "customXmlInsRangeEnd", "customXmlInsRangeStart", "customXmlMoveFromRangeEnd", "customXmlMoveFromRangeStart", "customXmlMoveToRangeEnd", "customXmlMoveToRangeStart", "del", "dir", "fldSimple", "hyperlink", "ins", "moveFrom", "moveFromRangeEnd", "moveFromRangeStart", "moveTo", "moveToRangeEnd", "moveToRangeStart", "pPr", "permEnd", "permStart", "proofErr", "r", "sdt", "smartTag", "smartTagPr", "subDoc"];
+  readonly "run-level-content": readonly ["bdo", "bookmarkEnd", "bookmarkStart", "commentRangeEnd", "commentRangeStart", "customXml", "customXmlDelRangeEnd", "customXmlDelRangeStart", "customXmlInsRangeEnd", "customXmlInsRangeStart", "customXmlMoveFromRangeEnd", "customXmlMoveFromRangeStart", "customXmlMoveToRangeEnd", "customXmlMoveToRangeStart", "customXmlPr", "del", "dir", "fldSimple", "hyperlink", "ins", "moveFrom", "moveFromRangeEnd", "moveFromRangeStart", "moveTo", "moveToRangeEnd", "moveToRangeStart", "pPr", "permEnd", "permStart", "proofErr", "r", "sdt", "smartTag", "smartTagPr", "subDoc"];
   readonly "table-content": readonly ["bookmarkEnd", "bookmarkStart", "commentRangeEnd", "commentRangeStart", "customXml", "customXmlDelRangeEnd", "customXmlDelRangeStart", "customXmlInsRangeEnd", "customXmlInsRangeStart", "customXmlMoveFromRangeEnd", "customXmlMoveFromRangeStart", "customXmlMoveToRangeEnd", "customXmlMoveToRangeStart", "customXmlPr", "del", "ins", "moveFrom", "moveFromRangeEnd", "moveFromRangeStart", "moveTo", "moveToRangeEnd", "moveToRangeStart", "permEnd", "permStart", "proofErr", "sdt", "tblGrid", "tblPr", "tr"];
   readonly "row-content": readonly ["bookmarkEnd", "bookmarkStart", "commentRangeEnd", "commentRangeStart", "customXml", "customXmlDelRangeEnd", "customXmlDelRangeStart", "customXmlInsRangeEnd", "customXmlInsRangeStart", "customXmlMoveFromRangeEnd", "customXmlMoveFromRangeStart", "customXmlMoveToRangeEnd", "customXmlMoveToRangeStart", "del", "ins", "moveFrom", "moveFromRangeEnd", "moveFromRangeStart", "moveTo", "moveToRangeEnd", "moveToRangeStart", "permEnd", "permStart", "proofErr", "sdt", "tblPrEx", "tc", "tr", "trPr"];
+  readonly "w:fonts": readonly ["font"];
+  readonly "w:font": readonly ["altName", "charset", "embedBold", "embedBoldItalic", "embedItalic", "embedRegular", "family", "notTrueType", "panose1", "pitch", "sig"];
   readonly "w:hyperlink": readonly ["bdo", "bookmarkEnd", "bookmarkStart", "commentRangeEnd", "commentRangeStart", "customXml", "customXmlDelRangeEnd", "customXmlDelRangeStart", "customXmlInsRangeEnd", "customXmlInsRangeStart", "customXmlMoveFromRangeEnd", "customXmlMoveFromRangeStart", "customXmlMoveToRangeEnd", "customXmlMoveToRangeStart", "del", "dir", "fldSimple", "hyperlink", "ins", "moveFrom", "moveFromRangeEnd", "moveFromRangeStart", "moveTo", "moveToRangeEnd", "moveToRangeStart", "permEnd", "permStart", "proofErr", "r", "sdt", "smartTag", "subDoc"];
   readonly "w:fldSimple": readonly ["bdo", "bookmarkEnd", "bookmarkStart", "commentRangeEnd", "commentRangeStart", "customXml", "customXmlDelRangeEnd", "customXmlDelRangeStart", "customXmlInsRangeEnd", "customXmlInsRangeStart", "customXmlMoveFromRangeEnd", "customXmlMoveFromRangeStart", "customXmlMoveToRangeEnd", "customXmlMoveToRangeStart", "del", "dir", "fldData", "fldSimple", "hyperlink", "ins", "moveFrom", "moveFromRangeEnd", "moveFromRangeStart", "moveTo", "moveToRangeEnd", "moveToRangeStart", "permEnd", "permStart", "proofErr", "r", "sdt", "smartTag", "subDoc"];
   readonly "block-content": readonly ["altChunk", "bookmarkEnd", "bookmarkStart", "commentRangeEnd", "commentRangeStart", "customXml", "customXmlDelRangeEnd", "customXmlDelRangeStart", "customXmlInsRangeEnd", "customXmlInsRangeStart", "customXmlMoveFromRangeEnd", "customXmlMoveFromRangeStart", "customXmlMoveToRangeEnd", "customXmlMoveToRangeStart", "del", "ins", "moveFrom", "moveFromRangeEnd", "moveFromRangeStart", "moveTo", "moveToRangeEnd", "moveToRangeStart", "p", "permEnd", "permStart", "proofErr", "sdt", "sectPr", "tbl", "tcPr"];

package/dist/docx/containerChildren.gen.js

@@ -1,3 +1,4 @@
+import { SEQUENCE_CHILDREN } from "@stll/docx-core/schema";
 //#region src/docx/containerChildren.gen.ts
 /**
 * GENERATED FILE — do not edit.
@@ -57,6 +58,7 @@ const CONTAINER_CHILDREN = {
 		"customXmlMoveFromRangeStart",
 		"customXmlMoveToRangeEnd",
 		"customXmlMoveToRangeStart",
+		"customXmlPr",
 		"del",
 		"dir",
 		"fldSimple",
@@ -140,6 +142,20 @@ const CONTAINER_CHILDREN = {
 		"tr",
 		"trPr"
 	],
+	"w:fonts": ["font"],
+	"w:font": [
+		"altName",
+		"charset",
+		"embedBold",
+		"embedBoldItalic",
+		"embedItalic",
+		"embedRegular",
+		"family",
+		"notTrueType",
+		"panose1",
+		"pitch",
+		"sig"
+	],
 	"w:hyperlink": [
 		"bdo",
 		"bookmarkEnd",
@@ -240,7 +256,8 @@ const CONTAINER_CHILDREN = {
 		"sectPr",
 		"tbl",
 		"tcPr"
-	]
+	],
+	...SEQUENCE_CHILDREN
 };
 //#endregion
 export { CONTAINER_CHILDREN };

package/dist/docx/containerChildren.js

@@ -1,18 +1,39 @@
 import { TRANSITIONAL_NAMESPACE_BY_STRICT_URI } from "./strictValueEncodings.gen.js";
 import { captureVerbatimXml } from "./verbatimCapture.js";
 import { WORDPROCESSINGML_NAMESPACE_URIS, getChildElements, getLocalName, getNamespaceUri } from "./xmlParser.js";
+import { SEQUENCE_CHILDREN } from "@stll/docx-core/schema";
 //#region src/docx/containerChildren.ts
 /** Keep this child's markup verbatim, in place. */
 const CAPTURE = "capture";
 /**
-* Another reader owns this child, and re-emits it.
+* What a handler answers with: nothing when it took a typed value, and
+* {@link CAPTURE} when it took none, so the child's bytes are kept instead.
 *
-* `w:rPr` under a run, read by `parseRunProperties`; `w:commentReference`
-* under a run, lifted out by the paragraph parser. Capturing one of these as
-* well would write it twice, so the disposition has to be stated rather than
-* left to a bare `break`.
+* `<w:tblLayout/>` states no layout and `<w:jc w:val="end"/>` states a value a
+* reader's enumeration does not admit. Both used to fall off the end of the
+* walk, and neither can be decided by name: a map keyed by name cannot list
+* the values a reader will refuse, only the names it has never heard of.
 */
+const keptUnless = (taken) => taken ? void 0 : CAPTURE;
 const OWNED_ELSEWHERE = "owned-elsewhere";
+const CLAIMS = /* @__PURE__ */ new Map();
+/**
+* Every owner a handler map has claimed so far.
+*
+* A claim is registered when `ownedElsewhere` is called, so a module that is
+* never imported contributes none. The checks that read this therefore load
+* the claiming modules first, by scanning the sources for the call rather than
+* by keeping a list beside them.
+*/
+const ownedElsewhereClaims = () => [...CLAIMS.values()];
+/** State that another reader takes this child, and who. */
+const ownedElsewhere = (claim) => {
+	CLAIMS.set(`${claim.container}/${claim.child}#${claim.reader}`, claim);
+	return {
+		disposition: OWNED_ELSEWHERE,
+		...claim
+	};
+};
 /**
 * This child goes with the wrapper folio does not keep.
 *
@@ -45,11 +66,11 @@ const transitionalNamespaceOf = (namespace) => TRANSITIONAL_NAMESPACE_BY_STRICT_
 *   none — an empty record is never written, so a fully modelled container
 *   stays byte-identical in the model.
 */
-const dispatchChildren = ({ element, handlers, modelledCount, undeclared, undeclaredNamespaces }) => {
+const dispatchChildren = ({ element, handlers, capturePosition, undeclared, undeclaredNamespaces }) => {
 	const children = [];
 	const capture = (child) => {
 		children.push({
-			index: modelledCount(),
+			index: capturePosition(child),
 			xml: captureVerbatimXml(child)
 		});
 	};
@@ -64,8 +85,8 @@ const dispatchChildren = ({ element, handlers, modelledCount, undeclared, undecl
 			capture(child);
 			continue;
 		}
-		if (disposition === "dropped-with-its-wrapper" || disposition === "owned-elsewhere") continue;
-		disposition(child);
+		if (typeof disposition !== "function") continue;
+		if (disposition(child) === "capture") capture(child);
 	}
 	return children.length === 0 ? void 0 : { children };
 };
@@ -83,14 +104,15 @@ const withPreservedChildren = (modelled, preserved, wrap) => {
 	const captures = preserved?.children;
 	if (captures === void 0 || captures.length === 0) return [...modelled];
 	const byIndex = /* @__PURE__ */ new Map();
-	for (const { index, xml } of captures) {
+	for (const child of captures) {
+		const { index, xml } = child;
 		const slot = Math.min(Math.max(index, 0), modelled.length);
 		const bucket = byIndex.get(slot);
 		if (bucket) {
-			bucket.push(wrap(xml));
+			bucket.push(wrap(xml, child));
 			continue;
 		}
-		byIndex.set(slot, [wrap(xml)]);
+		byIndex.set(slot, [wrap(xml, child)]);
 	}
 	const items = [];
 	for (const [index, item] of modelled.entries()) items.push(...byIndex.get(index) ?? [], item);
@@ -99,5 +121,33 @@ const withPreservedChildren = (modelled, preserved, wrap) => {
 };
 /** {@link withPreservedChildren} for a caller that already holds markup. */
 const serializeWithPreservedChildren = (modelled, preserved) => withPreservedChildren(modelled, preserved, (xml) => xml).join("");
+/**
+* Where each child sits in a container whose content model is one flat sequence.
+*
+* A property set is that container: `CT_TblPr` and `CT_SectPr` are sequences
+* of optional singletons, so a child's position is a property of its name and
+* the generated list is the order. That is what the sink records for them,
+* rather than a count of modelled siblings: the count is a mirror of whichever
+* properties folio models today, and it moves under the capture the moment one
+* more of them is modelled.
+*
+* An undeclared child — a foreign namespace, an `mc:` construct, a name a
+* later revision of the format adds — has no place in the sequence, so it
+* takes the place of the last declared child before it and comes back beside
+* the same neighbour. One before every declared child takes position `-1`,
+* ahead of the sequence's first slot.
+*/
+const sequencePositions = (container, element) => {
+	const declared = SEQUENCE_CHILDREN[container];
+	const positions = /* @__PURE__ */ new Map();
+	let previous = -1;
+	for (const child of getChildElements(element)) {
+		const namespace = getNamespaceUri(child);
+		const at = namespace === void 0 || WORDPROCESSINGML_NAMESPACE_URIS.has(namespace) ? declared.indexOf(getLocalName(child.name)) : -1;
+		if (at !== -1) previous = at;
+		positions.set(child, at === -1 ? previous : at);
+	}
+	return (child) => positions.get(child) ?? -1;
+};
 //#endregion
-export { CAPTURE, DROPPED_WITH_ITS_WRAPPER, OWNED_ELSEWHERE, dispatchChildren, serializeWithPreservedChildren, transitionalNamespaceOf, withPreservedChildren };
+export { CAPTURE, DROPPED_WITH_ITS_WRAPPER, dispatchChildren, keptUnless, ownedElsewhere, ownedElsewhereClaims, sequencePositions, serializeWithPreservedChildren, transitionalNamespaceOf, withPreservedChildren };

package/dist/docx/diagramPreview.d.ts

@@ -1,7 +1,19 @@
 import { document_d_exports } from "../types/document.js";
 import { XmlElement } from "./xmlParser.js";
 //#region src/docx/diagramPreview.d.ts
-/** Create a deliberately simple, bounded preview; it is never an editable diagram projection. */
+/**
+ * How many `dsp:sp` a preview describes at most.
+ *
+ * The bound is on the description rather than on any picture built from it:
+ * the shapes are what a backend draws, and a drawing with ten thousand of them
+ * is a drawing folio summarises rather than reproduces.
+ */
+declare const MAX_PREVIEW_SHAPES = 128;
+/**
+ * Describe a diagram drawing, without drawing it.
+ *
+ * Deliberately simple and bounded; it is never an editable diagram projection.
+ */
 declare const parseDiagramPreview: (drawing: XmlElement, rels: document_d_exports.RelationshipMap | undefined, media: Map<string, document_d_exports.MediaFile> | undefined) => document_d_exports.Image | null;
 //#endregion
-export { parseDiagramPreview };
+export { MAX_PREVIEW_SHAPES, parseDiagramPreview };