@stll/folio-core 0.42.0 → 0.44.0

package/dist/docx/imageParser.js

@@ -1,9 +1,9 @@
 import { sanitizeImageSrc } from "../utils/sanitizeImageSrc.js";
 import { emuToPixels } from "../utils/units.js";
 import { sanitizeExternalUrl } from "../utils/urlSecurity.js";
-import { WRAP_ELEMENT_NAMES, parsePositionH, parsePositionV, parseWrapElement } from "./drawingUtils.js";
+import { WRAP_ELEMENT_NAMES, parseAnchorBehindDoc, parsePositionH, parsePositionV, parseWrapElement } from "./drawingUtils.js";
 import { parseGraphicFrameLocks } from "./graphicFrameLocks.js";
-import { resolveTarget } from "./relsParser.js";
+import { RELATIONSHIP_TYPES, resolveRelationshipIdOfType } from "./relsParser.js";
 import { isTextBoxDrawing } from "./textBoxParser.js";
 import { findByFullName, findChild, getAttribute, getChildElements, parseNumericAttribute, parseOnOffValue } from "./xmlParser.js";
 //#region src/docx/imageParser.ts
@@ -178,17 +178,20 @@ function parseImageOpacity(blip) {
 	return Math.max(0, amt / 1e5);
 }
 /**
-* Extract rId from a:blip element
+* Extract rId from a:blip element.
+*
+* Undefined when the drawing has no blip to read one from: a chart, a diagram
+* or an OLE frame carries an `a:graphic` that is not a picture, and a
+* `wp:inline` may carry no graphic at all.
 */
 function extractBlipRId(blip) {
-	if (!blip) return "";
+	if (!blip) return;
 	const rEmbed = getAttribute(blip, "r", "embed");
 	if (rEmbed) return rEmbed;
 	const embed = getAttribute(blip, null, "embed");
 	if (embed) return embed;
 	const rLink = getAttribute(blip, "r", "link");
 	if (rLink) return rLink;
-	return "";
 }
 /**
 * Find transform (a:xfrm) from picture shape properties
@@ -242,10 +245,9 @@ function getMimeType(path) {
 * @returns Object with src (data URL or blob), mimeType, and filename
 */
 function resolveImageData(rId, rels, media) {
-	if (!rId || !rels) return {};
-	const rel = rels.get(rId);
-	if (!rel) return {};
-	const targetPath = rel.target;
+	const resolved = resolveRelationshipIdOfType(rels, rId, RELATIONSHIP_TYPES.image);
+	if (resolved.status !== "resolved") return {};
+	const targetPath = resolved.relationship.target;
 	if (!targetPath) return {};
 	const normalizedPath = normalizeMediaPath(targetPath);
 	const filename = targetPath.split("/").pop();
@@ -319,7 +321,7 @@ function parseInline(inlineEl, rels, media) {
 	if (distR !== void 0) wrap.distR = distR;
 	const image = {
 		type: "image",
-		rId,
+		...rId === void 0 ? {} : { rId },
 		size,
 		wrap
 	};
@@ -337,11 +339,12 @@ function parseInline(inlineEl, rels, media) {
 	if (crop) image.crop = crop;
 	if (opacity !== void 0) image.opacity = opacity;
 	if (frameLocks) image.frameLocks = frameLocks;
-	if (props.hlinkRId && rels) {
-		const safeHref = sanitizeExternalUrl(resolveTarget(rels, props.hlinkRId));
+	const hlink = resolveRelationshipIdOfType(rels, props.hlinkRId, RELATIONSHIP_TYPES.hyperlink);
+	if (hlink.status === "resolved") {
+		const safeHref = sanitizeExternalUrl(hlink.relationship.target);
 		if (safeHref) {
 			image.hlinkHref = safeHref;
-			image.hlinkRId = props.hlinkRId;
+			image.hlinkRId = hlink.relationship.id;
 		}
 	}
 	return image;
@@ -359,7 +362,7 @@ function parseAnchor(anchorEl, rels, media) {
 	const padding = parseEffectExtent(findByFullName(anchorEl, "wp:effectExtent"));
 	const props = parseDocProps(findByFullName(anchorEl, "wp:docPr"));
 	const frameLocks = parseGraphicFrameLocks(anchorEl);
-	const behindDoc = parseOnOffValue(getAttribute(anchorEl, null, "behindDoc")) === true;
+	const behindDoc = parseAnchorBehindDoc(anchorEl);
 	const layoutInCell = parseOnOffAttr(anchorEl, "layoutInCell");
 	const allowOverlap = parseOnOffAttr(anchorEl, "allowOverlap");
 	const anchorDistT = parseNumericAttribute(anchorEl, null, "distT");
@@ -391,7 +394,7 @@ function parseAnchor(anchorEl, rels, media) {
 	const transform = parseTransform(findPictureTransform(anchorEl));
 	const image = {
 		type: "image",
-		rId,
+		...rId === void 0 ? {} : { rId },
 		size,
 		wrap
 	};
@@ -412,11 +415,12 @@ function parseAnchor(anchorEl, rels, media) {
 	if (frameLocks) image.frameLocks = frameLocks;
 	if (layoutInCell !== void 0) image.layoutInCell = layoutInCell;
 	if (allowOverlap !== void 0) image.allowOverlap = allowOverlap;
-	if (props.hlinkRId && rels) {
-		const safeHref = sanitizeExternalUrl(resolveTarget(rels, props.hlinkRId));
+	const hlink = resolveRelationshipIdOfType(rels, props.hlinkRId, RELATIONSHIP_TYPES.hyperlink);
+	if (hlink.status === "resolved") {
+		const safeHref = sanitizeExternalUrl(hlink.relationship.target);
 		if (safeHref) {
 			image.hlinkHref = safeHref;
-			image.hlinkRId = props.hlinkRId;
+			image.hlinkRId = hlink.relationship.id;
 		}
 	}
 	return image;

package/dist/docx/imageRawXml.js

@@ -46,12 +46,12 @@ const DRAWING_SAFETY_CLASSES = {
 	OPAQUE: "opaque"
 };
 /**
-* Regenerated DrawingML points at `image.rId`, and `serializePicGraphic` falls
-* back to `"rId1"` when that id is empty, which rebinds the picture to whichever
-* relationship happens to be first. A drawing with no relationship id therefore
-* has no faithful regeneration.
+* A drawing with no picture relationship has no picture to regenerate. The
+* serializer writes the anchor back without a graphic, which is faithful for an
+* anchor that never had one and lossy for a chart or an OLE frame, so the
+* drawing counts as opaque and an edit must block the save.
 */
-const canRegenerateDrawing = (drawing) => drawing.image.rId !== "";
+const canRegenerateDrawing = (drawing) => drawing.image.rId !== void 0;
 /**
 * Classify a drawing by what the run serializer will do with it.
 *

package/dist/docx/markupRangeMarker.d.ts

@@ -0,0 +1,15 @@
+import { document_d_exports } from "../types/document.js";
+import { XmlElement } from "./xmlParser.js";
+//#region src/docx/markupRangeMarker.d.ts
+declare const parseMarkupRangeMarker: (node: XmlElement) => document_d_exports.MarkupRangeMarker;
+declare const parseBookmarkRangeMarker: (node: XmlElement) => document_d_exports.BookmarkRangeMarker;
+/**
+ * `w:author` is required on `CT_MoveBookmark`, so an absent one takes the same
+ * `Unknown` fallback a tracked change takes rather than leaving the saved
+ * package short of an attribute the schema demands. `w:date` is required too,
+ * but inventing a timestamp would state a fact about the document that is not
+ * true, so an absent date stays absent.
+ */
+declare const parseMoveBookmarkMarker: (node: XmlElement) => document_d_exports.MoveBookmarkMarker;
+//#endregion
+export { parseBookmarkRangeMarker, parseMarkupRangeMarker, parseMoveBookmarkMarker };

package/dist/docx/markupRangeMarker.js

@@ -0,0 +1,44 @@
+import { getAttribute, parseNumericAttribute } from "./xmlParser.js";
+//#region src/docx/markupRangeMarker.ts
+/** ST_DisplacedByCustomXml. A value outside it is not a placement folio can honour. */
+const DISPLACED_BY_CUSTOM_XML = /* @__PURE__ */ new Set(["next", "prev"]);
+const parseDisplacedByCustomXml = (node) => {
+	const value = getAttribute(node, "w", "displacedByCustomXml") ?? "";
+	return DISPLACED_BY_CUSTOM_XML.has(value) ? value : void 0;
+};
+const parseMarkupRangeMarker = (node) => {
+	const marker = { id: parseNumericAttribute(node, "w", "id") ?? 0 };
+	const displacedByCustomXml = parseDisplacedByCustomXml(node);
+	if (displacedByCustomXml !== void 0) marker.displacedByCustomXml = displacedByCustomXml;
+	return marker;
+};
+const parseBookmarkRangeMarker = (node) => {
+	const marker = {
+		...parseMarkupRangeMarker(node),
+		name: getAttribute(node, "w", "name") ?? ""
+	};
+	const colFirst = parseNumericAttribute(node, "w", "colFirst");
+	if (colFirst !== void 0) marker.colFirst = colFirst;
+	const colLast = parseNumericAttribute(node, "w", "colLast");
+	if (colLast !== void 0) marker.colLast = colLast;
+	return marker;
+};
+/**
+* `w:author` is required on `CT_MoveBookmark`, so an absent one takes the same
+* `Unknown` fallback a tracked change takes rather than leaving the saved
+* package short of an attribute the schema demands. `w:date` is required too,
+* but inventing a timestamp would state a fact about the document that is not
+* true, so an absent date stays absent.
+*/
+const parseMoveBookmarkMarker = (node) => {
+	const author = (getAttribute(node, "w", "author") ?? "").trim();
+	const marker = {
+		...parseBookmarkRangeMarker(node),
+		author: author.length > 0 ? author : "Unknown"
+	};
+	const date = (getAttribute(node, "w", "date") ?? "").trim();
+	if (date.length > 0) marker.date = date;
+	return marker;
+};
+//#endregion
+export { parseBookmarkRangeMarker, parseMarkupRangeMarker, parseMoveBookmarkMarker };

package/dist/docx/noteReferenceStyles.d.ts

@@ -0,0 +1,29 @@
+import { document_d_exports } from "../types/document.js";
+//#region src/docx/noteReferenceStyles.d.ts
+/** The id `commentSerializer` and `paragraphSerializer` write. */
+declare const COMMENT_REFERENCE_STYLE_ID = "CommentReference";
+/** The ids `noteSerializer` writes for the two note kinds. */
+declare const FOOTNOTE_REFERENCE_STYLE_ID = "FootnoteReference";
+declare const ENDNOTE_REFERENCE_STYLE_ID = "EndnoteReference";
+/** Which reference marks a package actually contains. */
+type NoteReferenceNeeds = {
+  comments: boolean;
+  footnotes: boolean;
+  endnotes: boolean;
+};
+/** What a package's content requires, read off the model rather than guessed. */
+declare const noteReferenceNeeds: (pkg: {
+  comments?: unknown[] | undefined;
+  footnotes?: unknown[] | undefined;
+  endnotes?: unknown[] | undefined;
+}) => NoteReferenceNeeds;
+/**
+ * The reference styles a package needs and does not already define, by id.
+ *
+ * Returns the definitions to append rather than a mutated style table: the
+ * caller owns the document, and a document that already defines the style
+ * (under any id folio recognises) keeps its own.
+ */
+declare const missingNoteReferenceStyles: (styles: document_d_exports.StyleDefinitions | undefined, needs: NoteReferenceNeeds) => document_d_exports.Style[];
+//#endregion
+export { COMMENT_REFERENCE_STYLE_ID, ENDNOTE_REFERENCE_STYLE_ID, FOOTNOTE_REFERENCE_STYLE_ID, NoteReferenceNeeds, missingNoteReferenceStyles, noteReferenceNeeds };

package/dist/docx/noteReferenceStyles.js

@@ -0,0 +1,70 @@
+import { BUILT_IN_STYLE_NAME } from "./builtInStyles.js";
+//#region src/docx/noteReferenceStyles.ts
+/**
+* The character styles folio's serializers write into every document that
+* carries a comment or a note, and the definitions that keep those references
+* from dangling.
+*
+* `commentSerializer`, `paragraphSerializer` and `noteSerializer` each emit
+* `<w:rStyle w:val="…"/>` for the reference mark, because that is what Word
+* writes and what makes the mark superscript. Nothing guaranteed the document
+* *defined* those styles: a package folio assembled from the generic style set
+* referenced `FootnoteReference` while declaring only seven paragraph styles,
+* so the mark rendered as body text. One owner here, so a serializer and the
+* style table cannot disagree about the id.
+*/
+/** The id `commentSerializer` and `paragraphSerializer` write. */
+const COMMENT_REFERENCE_STYLE_ID = "CommentReference";
+/** The ids `noteSerializer` writes for the two note kinds. */
+const FOOTNOTE_REFERENCE_STYLE_ID = "FootnoteReference";
+const ENDNOTE_REFERENCE_STYLE_ID = "EndnoteReference";
+/** The default character style Word bases these on, when the package has one. */
+const DEFAULT_CHARACTER_STYLE_ID = "DefaultParagraphFont";
+const referenceStyle = (styleId, name, superscript) => ({
+	styleId,
+	type: "character",
+	name,
+	uiPriority: 99,
+	semiHidden: true,
+	unhideWhenUsed: true,
+	rPr: superscript ? { vertAlign: "superscript" } : { fontSize: 16 }
+});
+/**
+* The definition for each reference style, keyed by the need that requires it.
+* Word's comment reference is 8pt body text; the note references are
+* superscript.
+*/
+const REFERENCE_STYLES = {
+	comments: () => referenceStyle(COMMENT_REFERENCE_STYLE_ID, BUILT_IN_STYLE_NAME.commentReference, false),
+	footnotes: () => referenceStyle(FOOTNOTE_REFERENCE_STYLE_ID, BUILT_IN_STYLE_NAME.footnoteReference, true),
+	endnotes: () => referenceStyle(ENDNOTE_REFERENCE_STYLE_ID, BUILT_IN_STYLE_NAME.endnoteReference, true)
+};
+/** What a package's content requires, read off the model rather than guessed. */
+const noteReferenceNeeds = (pkg) => ({
+	comments: (pkg.comments?.length ?? 0) > 0,
+	footnotes: (pkg.footnotes?.length ?? 0) > 0,
+	endnotes: (pkg.endnotes?.length ?? 0) > 0
+});
+/**
+* The reference styles a package needs and does not already define, by id.
+*
+* Returns the definitions to append rather than a mutated style table: the
+* caller owns the document, and a document that already defines the style
+* (under any id folio recognises) keeps its own.
+*/
+const missingNoteReferenceStyles = (styles, needs) => {
+	const defined = new Set((styles?.styles ?? []).map((style) => style.styleId));
+	const basedOn = defined.has(DEFAULT_CHARACTER_STYLE_ID) ? DEFAULT_CHARACTER_STYLE_ID : void 0;
+	const missing = [];
+	for (const [need, create] of Object.entries(REFERENCE_STYLES)) {
+		if (!needs[need]) continue;
+		const style = create();
+		if (!defined.has(style.styleId)) missing.push(basedOn === void 0 ? style : {
+			...style,
+			basedOn
+		});
+	}
+	return missing;
+};
+//#endregion
+export { COMMENT_REFERENCE_STYLE_ID, ENDNOTE_REFERENCE_STYLE_ID, FOOTNOTE_REFERENCE_STYLE_ID, missingNoteReferenceStyles, noteReferenceNeeds };

package/dist/docx/numberingParser.js

@@ -1,3 +1,4 @@
+import { isNumberingReference } from "./numberingReference.js";
 import { formatOoxmlCounter, padDecimal } from "./ooxmlCounterFormatter.js";
 import { LevelSuffixSchema, narrowEnum } from "./parserEnums.js";
 import { parseRunProperties } from "./runParser.js";
@@ -529,7 +530,7 @@ function createNumberingMap(definitions) {
 */
 function computeListRendering(numPr, numbering) {
 	const { numId, ilvl = 0 } = numPr;
-	if (numId === void 0 || numId === 0) return null;
+	if (!isNumberingReference(numId)) return null;
 	const level = numbering.getLevel(numId, ilvl);
 	if (!level) return null;
 	const levelNumFmts = [];

package/dist/docx/numberingReference.d.ts

@@ -0,0 +1,21 @@
+//#region src/docx/numberingReference.d.ts
+/**
+ * The reserved `w:numId` value that means "no numbering".
+ *
+ * ECMA-376 (17.9.18 `numId`, 17.9.19 `numPr`) reserves 0: it names no `w:num`,
+ * it switches numbering off, and on a style it cancels the numbering the style
+ * would otherwise inherit through `w:basedOn` (Word writes it on, for example,
+ * a heading-based style that must not be numbered). It must therefore survive a
+ * round trip: dropping the `w:numPr` would hand the numbering back.
+ */
+declare const NO_NUMBERING_NUM_ID = 0;
+/**
+ * Whether a `w:numId` names a numbering definition to resolve.
+ *
+ * Every lookup or validation against `numbering.nums` goes through this: an
+ * absent id has nothing to resolve, and {@link NO_NUMBERING_NUM_ID} is the
+ * "none" sentinel, never a dangling reference.
+ */
+declare const isNumberingReference: (numId: number | undefined) => numId is number;
+//#endregion
+export { NO_NUMBERING_NUM_ID, isNumberingReference };

package/dist/docx/numberingReference.js

@@ -0,0 +1,21 @@
+//#region src/docx/numberingReference.ts
+/**
+* The reserved `w:numId` value that means "no numbering".
+*
+* ECMA-376 (17.9.18 `numId`, 17.9.19 `numPr`) reserves 0: it names no `w:num`,
+* it switches numbering off, and on a style it cancels the numbering the style
+* would otherwise inherit through `w:basedOn` (Word writes it on, for example,
+* a heading-based style that must not be numbered). It must therefore survive a
+* round trip: dropping the `w:numPr` would hand the numbering back.
+*/
+const NO_NUMBERING_NUM_ID = 0;
+/**
+* Whether a `w:numId` names a numbering definition to resolve.
+*
+* Every lookup or validation against `numbering.nums` goes through this: an
+* absent id has nothing to resolve, and {@link NO_NUMBERING_NUM_ID} is the
+* "none" sentinel, never a dangling reference.
+*/
+const isNumberingReference = (numId) => numId !== void 0 && numId !== 0;
+//#endregion
+export { NO_NUMBERING_NUM_ID, isNumberingReference };

package/dist/docx/numberingReferenceNormalization.d.ts

@@ -1,6 +1,9 @@
 import { document_d_exports } from "../types/document.js";
 import { NumberingMap } from "./numberingParser.js";
 //#region src/docx/numberingReferenceNormalization.d.ts
+/** The codes this normalisation is reported under, owned here, not at the caller. */
+declare const UNNUMBERED_PARAGRAPH_WARNING: "unnumbered-paragraph";
+declare const UNNUMBERED_STYLE_WARNING: "unnumbered-style";
 type NormalizeNumberingReferencesInput = {
   documentBody: document_d_exports.DocumentBody;
   numbering: NumberingMap;
@@ -10,8 +13,17 @@ type NormalizeNumberingReferencesInput = {
   endnotes?: readonly document_d_exports.Endnote[];
 };
 type NormalizeNumberingReferencesResult = {
-  removedMissingNumberingReferences: number;
+  unnumberedDanglingReferences: number;
 };
 declare const normalizeNumberingReferences: ({ documentBody, numbering, headers, footers, footnotes, endnotes }: NormalizeNumberingReferencesInput) => NormalizeNumberingReferencesResult;
+type NormalizeStyleNumberingReferencesInput = {
+  styles: readonly document_d_exports.Style[];
+  numbering: NumberingMap | undefined;
+};
+type NormalizeStyleNumberingReferencesResult = {
+  /** Style ids whose dangling reference became the "no numbering" sentinel. */
+  unnumberedStyleIds: string[];
+};
+declare const normalizeStyleNumberingReferences: ({ styles, numbering }: NormalizeStyleNumberingReferencesInput) => NormalizeStyleNumberingReferencesResult;
 //#endregion
-export { normalizeNumberingReferences };
+export { UNNUMBERED_PARAGRAPH_WARNING, UNNUMBERED_STYLE_WARNING, normalizeNumberingReferences, normalizeStyleNumberingReferences };

package/dist/docx/numberingReferenceNormalization.js

@@ -1,7 +1,37 @@
+import { isNumberingReference } from "./numberingReference.js";
 import { visitDocxParagraphs } from "./paragraphTraversal.js";
+import { PARSE_WARNING_CODES } from "@stll/docx-core/model";
 //#region src/docx/numberingReferenceNormalization.ts
+/**
+* Parse-boundary tolerance for `w:numPr` numbering references.
+*
+* A file Word opens must never reach a panic, so a reference that resolves to
+* nothing is repaired here, on both tiers that can carry one: the paragraph and
+* the paragraph style. Downstream code (and `assertStyleNumberingReferences` in
+* particular) can then treat a numbering reference as resolvable.
+*
+* The repair writes the sentinel rather than deleting the `w:numPr`. ECMA-376
+* 17.9.18 reserves `w:numId w:val="0"` for "the removal of numbering properties
+* at a particular level in the style hierarchy"; deleting the element instead
+* removes nothing, it only uncovers the tier below, handing the paragraph its
+* `w:pStyle` numbering or the style its `w:basedOn` numbering. A source that
+* shows no number would come back numbered.
+*/
+/**
+* Whether a `w:numId` still reaches a level definition: a `w:num` that names a
+* `w:abstractNum` the numbering part defines. Both hops can dangle, and a
+* `w:num` with no `w:abstractNum` numbers nothing just as a missing one does.
+*/
+const resolvesNumbering = (numId, numbering) => {
+	if (!numbering) return false;
+	const abstractNumId = numbering.getAbstractNumId(numId);
+	return abstractNumId !== null && numbering.getAbstract(abstractNumId) !== null;
+};
+/** The codes this normalisation is reported under, owned here, not at the caller. */
+const UNNUMBERED_PARAGRAPH_WARNING = PARSE_WARNING_CODES.unnumberedParagraph;
+const UNNUMBERED_STYLE_WARNING = PARSE_WARNING_CODES.unnumberedStyle;
 const normalizeNumberingReferences = ({ documentBody, numbering, headers, footers, footnotes, endnotes }) => {
-	let removedMissingNumberingReferences = 0;
+	let unnumberedDanglingReferences = 0;
 	visitDocxParagraphs({
 		documentBody,
 		headers,
@@ -9,14 +39,26 @@ const normalizeNumberingReferences = ({ documentBody, numbering, headers, footer
 		footnotes,
 		endnotes
 	}, (paragraph) => {
-		const numId = paragraph.formatting?.numPr?.numId;
-		if (numId !== void 0 && numId !== 0 && !numbering.hasNumbering(numId)) {
-			delete paragraph.formatting?.numPr;
-			delete paragraph.listRendering;
-			removedMissingNumberingReferences += 1;
-		}
+		const formatting = paragraph.formatting;
+		const numId = formatting?.numPr?.numId;
+		if (!formatting || !isNumberingReference(numId) || resolvesNumbering(numId, numbering)) return;
+		formatting.numPr = { numId: 0 };
+		delete formatting.numPrFromStyle;
+		delete paragraph.listRendering;
+		unnumberedDanglingReferences += 1;
 	});
-	return { removedMissingNumberingReferences };
+	return { unnumberedDanglingReferences };
+};
+const normalizeStyleNumberingReferences = ({ styles, numbering }) => {
+	const unnumberedStyleIds = [];
+	for (const style of styles) {
+		const pPr = style.pPr;
+		const numId = pPr?.numPr?.numId;
+		if (!pPr || !isNumberingReference(numId) || resolvesNumbering(numId, numbering)) continue;
+		pPr.numPr = { numId: 0 };
+		unnumberedStyleIds.push(style.styleId);
+	}
+	return { unnumberedStyleIds };
 };
 //#endregion
-export { normalizeNumberingReferences };
+export { UNNUMBERED_PARAGRAPH_WARNING, UNNUMBERED_STYLE_WARNING, normalizeNumberingReferences, normalizeStyleNumberingReferences };

package/dist/docx/paraIdRangeNormalization.d.ts

@@ -1,23 +1,4 @@
 //#region src/docx/paraIdRangeNormalization.d.ts
-/**
- * Keep every paragraph id a package carries inside the range the schema gives
- * it.
- *
- * `w14:paraId`, `w14:textId` and the comment-part ids that reference a
- * paragraph are `ST_LongHexNumber` with a maximum: the value has to be below
- * `0x80000000`, so the ids are 31-bit. Producers exist that write eight hex
- * digits without that bound, and folio preserves the ids a document arrives
- * with — so a package can carry an out-of-range id in, and a save that copies
- * it through hands a consumer a package it will refuse.
- *
- * {@link paraIdInRange} is the one mapping, and it is a pure function of the
- * value alone. That is what lets the parser and the save agree without
- * consulting each other: a paragraph's id in the model is the id the file gets,
- * so bringing an id into range does not make a document's own identity move
- * under it between reading and writing. The package pass below is the same
- * mapping applied to every attribute that carries such an id, so a paragraph
- * and every reference to it move together.
- */
 /**
  * `value` when it already fits, and a value derived from it when it does not.
  *