@stll/folio-core 0.43.0 → 0.45.0

package/dist/docx/vmlImageParser.js

@@ -1,6 +1,7 @@
 import { sanitizeImageSrc } from "../utils/sanitizeImageSrc.js";
 import { pixelsToEmu } from "../utils/units.js";
 import { resolveImageData } from "./imageParser.js";
+import { PREVIEW_KINDS } from "./previewBudget.js";
 import { captureVerbatimXml } from "./verbatimCapture.js";
 import { isValidVmlPreviewDimension, parseVmlNumber, parseVmlStyle, renderStandaloneVmlPreview, renderVmlGroupPreview, vmlCssLengthToPx, vmlSvgDataUrl } from "./vmlPreview.js";
 import { isWatermarkShape } from "./watermarkParser.js";
@@ -73,8 +74,8 @@ const previewImage = (pictElement, svg, widthPx, heightPx, style, rootXmlns) =>
 			type: "image",
 			rId: "",
 			src,
-			mimeType: "image/svg+xml",
-			filename: "vml-shape-preview.svg",
+			mimeType: PREVIEW_KINDS.vmlShape.mimeType,
+			filename: PREVIEW_KINDS.vmlShape.filename,
 			size: {
 				width: pixelsToEmu(widthPx),
 				height: pixelsToEmu(heightPx)
@@ -135,7 +136,7 @@ function shouldPreserveRawVmlPict(pictElement) {
 * `o:relid` instead, so fall back through those before the bare `id`.
 */
 function readImageDataRId(imagedata) {
-	return getAttribute(imagedata, "r", "id") ?? getAttribute(imagedata, "r", "embed") ?? getAttribute(imagedata, "o", "relid") ?? getAttribute(imagedata, null, "id") ?? "";
+	return getAttribute(imagedata, "r", "id") ?? getAttribute(imagedata, "r", "embed") ?? getAttribute(imagedata, "o", "relid") ?? getAttribute(imagedata, null, "id") ?? void 0;
 }
 /**
 * Parse a `w:pict` element into an inline image, or null when it carries no
@@ -157,7 +158,7 @@ function parseVmlImageContent(pictElement, rels, media, rootXmlns = {}) {
 		const imagedata = findChild(shape, "v", "imagedata");
 		if (!imagedata) continue;
 		const rId = readImageDataRId(imagedata);
-		if (!rId) continue;
+		if (rId === void 0 || rId.length === 0) continue;
 		if (isWatermarkShape(shape)) continue;
 		const { src, mimeType, filename } = resolveImageData(rId, rels ?? void 0, media ?? void 0);
 		const shapeStyle = parseVmlStyle(getAttribute(shape, null, "style"));

package/dist/docx/vmlPreview.d.ts

@@ -25,7 +25,5 @@ declare const vmlSvgDataUrl: (svg: string) => string | undefined;
 declare const renderStandaloneVmlPreview: (shape: XmlElement) => VmlPreviewResult;
 /** Render a VML group through bounded, non-clipping local-coordinate transforms. */
 declare const renderVmlGroupPreview: (group: XmlElement) => VmlPreviewResult;
-/** Bound retained synthetic VML previews while preserving their raw replay nodes. */
-declare const enforcePackageVmlPreviewBudget: (root: unknown, maxCharacters?: number) => void;
 //#endregion
-export { VmlPreviewResult, enforcePackageVmlPreviewBudget, isValidVmlPreviewDimension, parseVmlNumber, parseVmlStyle, renderStandaloneVmlPreview, renderVmlGroupPreview, vmlCssLengthToPx, vmlSvgDataUrl };
+export { VmlPreviewResult, isValidVmlPreviewDimension, parseVmlNumber, parseVmlStyle, renderStandaloneVmlPreview, renderVmlGroupPreview, vmlCssLengthToPx, vmlSvgDataUrl };

package/dist/docx/vmlPreview.js

@@ -1,3 +1,4 @@
+import { VML_PREVIEW_DATA_URL_PREFIX } from "./previewBudget.js";
 import { findChild, findDeep, getAttribute, getChildElements, getLocalName } from "./xmlParser.js";
 //#region src/docx/vmlPreview.ts
 const MAX_VML_PREVIEW_DEPTH = 16;
@@ -6,10 +7,6 @@ const MAX_VML_PREVIEW_PATH_POINTS = 2e4;
 const MAX_VML_PREVIEW_COORDINATE = 1e6;
 const MAX_VML_PREVIEW_DIMENSION_PX = 2e4;
 const MAX_VML_SVG_CHARACTERS = 1e6;
-const MAX_PACKAGE_VML_PREVIEW_CHARACTERS = 8 * 1024 * 1024;
-const VML_PREVIEW_DATA_URL_PREFIX = "data:image/svg+xml;charset=utf-8,";
-const VML_PREVIEW_FILENAME = "vml-shape-preview.svg";
-const VML_PREVIEW_MIME_TYPE = "image/svg+xml";
 const SAFE_VML_COLORS = /* @__PURE__ */ new Set([
 	"black",
 	"white",
@@ -506,30 +503,5 @@ const renderVmlGroupPreview = (group) => {
 		style
 	};
 };
-/** Bound retained synthetic VML previews while preserving their raw replay nodes. */
-const enforcePackageVmlPreviewBudget = (root, maxCharacters = MAX_PACKAGE_VML_PREVIEW_CHARACTERS) => {
-	let remainingCharacters = Math.max(0, maxCharacters);
-	const visited = /* @__PURE__ */ new WeakSet();
-	const visit = (value) => {
-		if (value === null || typeof value !== "object" || visited.has(value)) return;
-		visited.add(value);
-		if (value instanceof ArrayBuffer || ArrayBuffer.isView(value)) return;
-		if (value instanceof Map) {
-			for (const child of value.values()) visit(child);
-			return;
-		}
-		if (Array.isArray(value)) {
-			for (const child of value) visit(child);
-			return;
-		}
-		if ("type" in value && value.type === "image" && "rId" in value && value.rId === "" && "mimeType" in value && value.mimeType === VML_PREVIEW_MIME_TYPE && "filename" in value && value.filename === VML_PREVIEW_FILENAME && "src" in value && typeof value.src === "string" && value.src.startsWith(VML_PREVIEW_DATA_URL_PREFIX)) if (value.src.length <= remainingCharacters) remainingCharacters -= value.src.length;
-		else {
-			remainingCharacters = 0;
-			delete value.src;
-		}
-		for (const child of Object.values(value)) visit(child);
-	};
-	visit(root);
-};
 //#endregion
-export { enforcePackageVmlPreviewBudget, isValidVmlPreviewDimension, parseVmlNumber, parseVmlStyle, renderStandaloneVmlPreview, renderVmlGroupPreview, vmlCssLengthToPx, vmlSvgDataUrl };
+export { isValidVmlPreviewDimension, parseVmlNumber, parseVmlStyle, renderStandaloneVmlPreview, renderVmlGroupPreview, vmlCssLengthToPx, vmlSvgDataUrl };

package/dist/docx/watermarkParser.js

@@ -1,3 +1,4 @@
+import { parseAnchorBehindDoc } from "./drawingUtils.js";
 import { captureVerbatimXml } from "./verbatimCapture.js";
 import { cloneWithXmlnsDeclarations, collectXmlnsDeclarations, findChild, findChildren, findDeep, getAttribute, getLocalName, getTextContent } from "./xmlParser.js";
 //#region src/docx/watermarkParser.ts
@@ -258,8 +259,7 @@ function collectDrawingMlBehindContentAnchors(header) {
 	for (const drawing of collectByLocalName(header, "drawing")) {
 		const anchor = findDeep(drawing, "wp", "anchor");
 		if (!anchor) continue;
-		const behindDoc = getAttribute(anchor, null, "behindDoc");
-		if (behindDoc === "1" || behindDoc === "true") out.push(anchor);
+		if (parseAnchorBehindDoc(anchor)) out.push(anchor);
 	}
 	return out;
 }

package/dist/docx/xmlParser.d.ts

@@ -1,24 +1,5 @@
+import { ParseContext } from "./parseContext.js";
 //#region src/docx/xmlParser.d.ts
-/**
- * XML Parser Utilities for OOXML
- *
- * Provides helper functions for parsing Office Open XML (OOXML) content
- * with proper namespace handling.
- *
- * OOXML uses many namespaces:
- * - w:  WordprocessingML (main document content)
- * - a:  DrawingML (graphics)
- * - r:  Relationships
- * - wp: Word Drawing positioning
- * - wps: Word Drawing shapes
- * - wpc: Word Drawing canvas
- * - wpg: Word Drawing group
- * - m:  Math
- * - mc: Markup Compatibility
- * - v:  VML (legacy vector graphics)
- * - o:  Office (extensions)
- * - pic: Pictures
- */
 /**
  * XML element tree node — drop-in replacement for the `Element` type
  * previously imported from `xml-js`. Every consumer imports this from
@@ -90,7 +71,22 @@ declare const NAMESPACES: {
 declare const OOXML_NAMESPACE_SCOPE: XmlNamespaceScope;
 declare function parseXml(xml: string, inheritedNamespaceScope?: XmlNamespaceScope): XmlElement;
 /**
- * Serialize an XmlElement back to an XML string
+ * Serialize an XmlElement back to an XML string.
+ *
+ * Written here rather than handed to `fast-xml-parser`'s builder for two
+ * reasons. The builder writes a tab or a newline inside an attribute value
+ * literally, and XML 1.0 §3.3.3 has every conformant reader normalise those to
+ * a space: a `descr="two lines
"` a source file wrote came back as
+ * `descr="two lines "`. `escapeXmlAttribute` writes the character references
+ * that survive that step. And the builder returned a string per node, so a
+ * subtree's bytes were copied into its parent's answer, its grandparent's and
+ * so on, which `writeElement` below replaces with one buffer.
+ *
+ * Those two are the whole difference from the builder: the attribute
+ * character references, an attribute the model dropped written as absent
+ * rather than as the word "undefined", and the characters XML 1.0 §2.2 admits
+ * no spelling for dropped. Every other rule reproduces its output byte for
+ * byte, so replaying a capture is unchanged wherever it was already correct.
  */
 declare function elementToXml(element: XmlElement): string;
 /**
@@ -249,14 +245,18 @@ declare function getAttributes(element: XmlElement | null | undefined): Record<s
  */
 declare function getTextContent(element: XmlElement | null | undefined): string;
 /**
- * Check if an element has a specific attribute with value "true" or "1"
+ * Read an `ST_OnOff` attribute.
  *
- * @param element - Element to check
- * @param namespace - Attribute namespace
- * @param name - Attribute name
- * @returns true if attribute exists and is truthy
+ * The type has three spellings per polarity — `1`/`true`/`on` and
+ * `0`/`false`/`off` — and producers use all of them. `undefined` means the
+ * author said nothing (absent, or a value outside the type), so the caller
+ * still owns what absence means for its own slot.
+ *
+ * Every on/off attribute goes through here: a hand-rolled `=== "1"` reads
+ * `w:beforeAutospacing="on"` as false, and the save path then writes `"0"`,
+ * inverting what the document said.
  */
-declare function hasFlag(element: XmlElement | null | undefined, namespace: string | null, name: string): boolean;
+declare function parseOnOffAttribute(element: XmlElement | null | undefined, namespace: string | null, name: string, context?: ParseContext): boolean | undefined;
 /**
  * Check if a child element exists (used for boolean flags in OOXML)
  *
@@ -297,15 +297,20 @@ declare function parseNumericAttribute(element: XmlElement | null | undefined, n
  */
 declare function parseNumberingLevelAttribute(element: XmlElement | null | undefined): number | undefined;
 /**
- * Parse `w:w` on a table width/height element. For `w:type="pct"`, producers
- * sometimes emit human-readable percentages (`100%`) instead of 50ths-of-percent
- * (`5000`); normalize those to the ECMA-376 unit the layout engine expects.
+ * Parse `w:w` on a table width/height element. A percentage may be spelled the
+ * way it reads (`100%`) or as the number its slot counts in
+ * (50ths-of-percent, `5000`); the generated slot table says which unit that
+ * is, so the two spellings are not decided here.
  */
 declare function parseTableMeasurementValue(element: XmlElement | null | undefined, widthType: string): number | undefined;
 /**
  * Parse an OOXML `ST_OnOff` lexical value.
+ *
+ * `context` is optional and trailing on purpose: every call site that has one
+ * reports the value folio declined to read, and the hundred that do not yet
+ * thread one keep compiling and keep their behaviour.
  */
-declare function parseOnOffValue(value: string | null | undefined): boolean | undefined;
+declare function parseOnOffValue(value: string | null | undefined, context?: ParseContext, element?: string): boolean | undefined;
 /**
  * Parse a boolean value from an attribute or element presence
  *
@@ -318,7 +323,7 @@ declare function parseOnOffValue(value: string | null | undefined): boolean | un
  * @param namespace - Namespace for val attribute
  * @returns boolean value
  */
-declare function parseBooleanElement(element: XmlElement | null | undefined, namespace?: string): boolean;
+declare function parseBooleanElement(element: XmlElement | null | undefined, namespace?: string, context?: ParseContext): boolean;
 /**
  * Deep find - search recursively for an element
  *
@@ -378,4 +383,4 @@ declare function cloneWithXmlnsDeclarations(element: XmlElement, xmlnsDecls: Rec
  */
 declare function cloneElement(element: XmlElement, overrides: Partial<XmlElement>): XmlElement;
 //#endregion
-export { NAMESPACES, OFFICE_RELATIONSHIP_NAMESPACE_URIS, OOXML_NAMESPACE_SCOPE, WORDPROCESSINGML_NAMESPACE_URIS, XmlAttributeMatch, XmlElement, XmlNamespaceScope, attachXmlNamespaceContext, cloneElement, cloneWithXmlnsDeclarations, collectXmlnsDeclarations, elementToXml, findAllDeep, findAttributeByNamespaceUri, findByFullName, findChild, findChildByLocalName, findChildByNamespaceUri, findChildren, findChildrenByLocalName, findChildrenByNamespaceUri, findDeep, getAttribute, getAttributeAny, getAttributeAnyPrefix, getAttributeByNamespaceUri, getAttributes, getChildElements, getLocalName, getNamespacePrefix, getNamespaceUri, getTextContent, hasChild, hasFlag, matchesName, mergeXmlnsDeclarations, parseBooleanElement, parseColorElement, parseNumberingLevelAttribute, parseNumericAttribute, parseOnOffValue, parseTableMeasurementValue, parseXml, parseXmlDocument, selectAlternateContentBranch };
+export { NAMESPACES, OFFICE_RELATIONSHIP_NAMESPACE_URIS, OOXML_NAMESPACE_SCOPE, WORDPROCESSINGML_NAMESPACE_URIS, XmlAttributeMatch, XmlElement, XmlNamespaceScope, attachXmlNamespaceContext, cloneElement, cloneWithXmlnsDeclarations, collectXmlnsDeclarations, elementToXml, findAllDeep, findAttributeByNamespaceUri, findByFullName, findChild, findChildByLocalName, findChildByNamespaceUri, findChildren, findChildrenByLocalName, findChildrenByNamespaceUri, findDeep, getAttribute, getAttributeAny, getAttributeAnyPrefix, getAttributeByNamespaceUri, getAttributes, getChildElements, getLocalName, getNamespacePrefix, getNamespaceUri, getTextContent, hasChild, matchesName, mergeXmlnsDeclarations, parseBooleanElement, parseColorElement, parseNumberingLevelAttribute, parseNumericAttribute, parseOnOffAttribute, parseOnOffValue, parseTableMeasurementValue, parseXml, parseXmlDocument, selectAlternateContentBranch };

package/dist/docx/xmlParser.js

@@ -1,7 +1,9 @@
-import { transitionalSlotEncoding } from "./transitionalSpelling.js";
+import { NUMBERS_PER_PERCENT, percentageSpelling, transitionalSlotEncoding } from "./transitionalSpelling.js";
 import { universalMeasureAs } from "./universalMeasure.js";
-import { XMLBuilder, XMLParser } from "fast-xml-parser";
+import { escapeXmlAttribute, escapeXmlText } from "@stll/docx-core";
+import { XMLParser } from "fast-xml-parser";
 import { OOXML_NS } from "@stll/docx-utils";
+import { PARSE_WARNING_CODES } from "@stll/docx-core/model";
 //#region src/docx/xmlParser.ts
 /**
 * XML Parser Utilities for OOXML
@@ -41,22 +43,12 @@ const fxpParserOptionsWithStopNodes = {
 	...fxpParserOptions,
 	stopNodes: ["*.w:binData"]
 };
-const fxpBuilderOptions = {
-	preserveOrder: true,
-	ignoreAttributes: false,
-	attributeNamePrefix: "",
-	textNodeName: "#text",
-	suppressEmptyNode: true
-};
 const fxpParser = new XMLParser(fxpParserOptions);
 const fxpParserWithStopNodes = new XMLParser(fxpParserOptionsWithStopNodes);
-const fxpBuilder = new XMLBuilder(fxpBuilderOptions);
 /** Text node key used by fast-xml-parser in preserveOrder mode. */
 const TEXT_KEY = "#text";
 /** Attribute group key used by fast-xml-parser in preserveOrder mode. */
 const ATTR_KEY = ":@";
-/** Character reference required to keep carriage returns through XML end-of-line normalization. */
-const XML_CARRIAGE_RETURN_REFERENCE = "
";
 const EMPTY_NAMESPACE_SCOPE = { bindings: /* @__PURE__ */ new Map() };
 const resolveNamespaceUri = (scope, prefix) => {
 	let current = scope;
@@ -137,18 +129,6 @@ function fxpToRootElement(nodes, inheritedNamespaceScope = EMPTY_NAMESPACE_SCOPE
 	return { elements: nodes };
 }
 /**
-* Convert an XmlElement back into the fast-xml-parser preserveOrder format
-* so we can feed it to XMLBuilder.
-*/
-function elementToFxpNode(el) {
-	if (el.type === "text") return { [TEXT_KEY]: el.text ?? "" };
-	const name = el.name ?? "";
-	const children = el.elements ? el.elements.map(elementToFxpNode) : [];
-	const node = { [name]: children };
-	if (el.attributes && Object.keys(el.attributes).length > 0) node[ATTR_KEY] = el.attributes;
-	return node;
-}
-/**
 * Common OOXML namespace URIs — re-exported from @stll/docx-utils.
 */
 const NAMESPACES = OOXML_NS;
@@ -173,13 +153,64 @@ function parseXml(xml, inheritedNamespaceScope = EMPTY_NAMESPACE_SCOPE) {
 	return fxpToRootElement((xml.includes("binData") ? fxpParserWithStopNodes : fxpParser).parse(xml), inheritedNamespaceScope);
 }
 /**
-* Serialize an XmlElement back to an XML string
+* Serialize an XmlElement back to an XML string.
+*
+* Written here rather than handed to `fast-xml-parser`'s builder for two
+* reasons. The builder writes a tab or a newline inside an attribute value
+* literally, and XML 1.0 §3.3.3 has every conformant reader normalise those to
+* a space: a `descr="two lines
"` a source file wrote came back as
+* `descr="two lines "`. `escapeXmlAttribute` writes the character references
+* that survive that step. And the builder returned a string per node, so a
+* subtree's bytes were copied into its parent's answer, its grandparent's and
+* so on, which `writeElement` below replaces with one buffer.
+*
+* Those two are the whole difference from the builder: the attribute
+* character references, an attribute the model dropped written as absent
+* rather than as the word "undefined", and the characters XML 1.0 §2.2 admits
+* no spelling for dropped. Every other rule reproduces its output byte for
+* byte, so replaying a capture is unchanged wherever it was already correct.
 */
 function elementToXml(element) {
-	const fxpNode = elementToFxpNode(element);
-	return fxpBuilder.build([fxpNode]).replaceAll("\r", XML_CARRIAGE_RETURN_REFERENCE);
+	const out = [];
+	writeElement(element, out);
+	return out.join("");
 }
 /**
+* Serialize into one shared buffer rather than a string per node.
+*
+* Returning a string per element makes a subtree's bytes a substring of its
+* parent's, its grandparent's and so on, so a table pays for its rows, its
+* rows pay for their cells, and a part that nests four levels deep is copied
+* four times before anything is written. Appending into one array of chunks
+* and joining once costs each node its own text and nothing for its ancestors.
+*
+* Whether an element self-closes is not known until its children are written,
+* so the opening tag reserves a slot in the buffer and fills it afterwards:
+* `>` when something was appended, `/>` when nothing was.
+*/
+const writeElement = (element, out) => {
+	if (element.type === "text") {
+		const text = String(element.text ?? "");
+		if (text !== "") out.push(escapeXmlText(text));
+		return;
+	}
+	const name = element.name ?? "";
+	out.push(`<${name}`);
+	if (element.attributes) for (const [attribute, value] of Object.entries(element.attributes)) {
+		if (value === void 0) continue;
+		out.push(` ${attribute}="${escapeXmlAttribute(String(value))}"`);
+	}
+	const openingSlot = out.push("") - 1;
+	const contentStart = out.length;
+	for (const child of element.elements ?? []) writeElement(child, out);
+	if (out.length === contentStart) {
+		out[openingSlot] = "/>";
+		return;
+	}
+	out[openingSlot] = ">";
+	out.push(`</${name}>`);
+};
+/**
 * Parse XML string to a more convenient format
 */
 function parseXmlDocument(xml) {
@@ -481,17 +512,19 @@ function getTextContent(element) {
 	return text;
 }
 /**
-* Check if an element has a specific attribute with value "true" or "1"
+* Read an `ST_OnOff` attribute.
 *
-* @param element - Element to check
-* @param namespace - Attribute namespace
-* @param name - Attribute name
-* @returns true if attribute exists and is truthy
+* The type has three spellings per polarity — `1`/`true`/`on` and
+* `0`/`false`/`off` — and producers use all of them. `undefined` means the
+* author said nothing (absent, or a value outside the type), so the caller
+* still owns what absence means for its own slot.
+*
+* Every on/off attribute goes through here: a hand-rolled `=== "1"` reads
+* `w:beforeAutospacing="on"` as false, and the save path then writes `"0"`,
+* inverting what the document said.
 */
-function hasFlag(element, namespace, name) {
-	const value = getAttribute(element, namespace, name);
-	if (value === null) return false;
-	return parseOnOffValue(value) ?? true;
+function parseOnOffAttribute(element, namespace, name, context) {
+	return parseOnOffValue(getAttribute(element, namespace, name), context, element?.name ?? name);
 }
 /**
 * Check if a child element exists (used for boolean flags in OOXML)
@@ -554,17 +587,19 @@ function parseNumberingLevelAttribute(element) {
 	return level !== void 0 && level >= 0 ? level : void 0;
 }
 /**
-* Parse `w:w` on a table width/height element. For `w:type="pct"`, producers
-* sometimes emit human-readable percentages (`100%`) instead of 50ths-of-percent
-* (`5000`); normalize those to the ECMA-376 unit the layout engine expects.
+* Parse `w:w` on a table width/height element. A percentage may be spelled the
+* way it reads (`100%`) or as the number its slot counts in
+* (50ths-of-percent, `5000`); the generated slot table says which unit that
+* is, so the two spellings are not decided here.
 */
 function parseTableMeasurementValue(element, widthType) {
 	const raw = getAttribute(element, "w", "w");
 	if (raw === null) return;
 	const trimmed = raw.trim();
-	if (widthType === "pct" && trimmed.endsWith("%")) {
-		const pct = Number.parseFloat(trimmed.slice(0, -1));
-		if (!Number.isNaN(pct)) return Math.round(pct * 50);
+	if (widthType === "pct") {
+		const percent = percentageSpelling(trimmed);
+		const unit = element === null || element === void 0 ? void 0 : transitionalSlotEncoding(element.namespaceUri, getLocalName(element.name), "w")?.percent;
+		if (percent !== void 0 && unit !== void 0) return Math.round(percent * NUMBERS_PER_PERCENT[unit]);
 	}
 	const measure = universalMeasureAs(trimmed, "twips");
 	if (measure !== void 0) return measure;
@@ -573,8 +608,12 @@ function parseTableMeasurementValue(element, widthType) {
 }
 /**
 * Parse an OOXML `ST_OnOff` lexical value.
+*
+* `context` is optional and trailing on purpose: every call site that has one
+* reports the value folio declined to read, and the hundred that do not yet
+* thread one keep compiling and keep their behaviour.
 */
-function parseOnOffValue(value) {
+function parseOnOffValue(value, context, element) {
 	if (value === null || value === void 0) return;
 	switch (value) {
 		case "1":
@@ -583,7 +622,13 @@ function parseOnOffValue(value) {
 		case "0":
 		case "false":
 		case "off": return false;
-		default: return;
+		default:
+			context?.warn({
+				code: PARSE_WARNING_CODES.unrecognisedOnOffValue,
+				value,
+				...element === void 0 ? {} : { element }
+			});
+			return;
 	}
 }
 /**
@@ -598,7 +643,7 @@ function parseOnOffValue(value) {
 * @param namespace - Namespace for val attribute
 * @returns boolean value
 */
-function parseBooleanElement(element, namespace = "w") {
+function parseBooleanElement(element, namespace = "w", context) {
 	if (!element) return false;
 	let val = null;
 	const elementName = element.name ?? "";
@@ -613,7 +658,7 @@ function parseBooleanElement(element, namespace = "w") {
 		}
 	}
 	if (val === null) return true;
-	return parseOnOffValue(val) ?? true;
+	return parseOnOffValue(val, context, elementName) ?? false;
 }
 /**
 * Deep find - search recursively for an element
@@ -810,4 +855,4 @@ function cloneElement(element, overrides) {
 	return clone;
 }
 //#endregion
-export { NAMESPACES, OFFICE_RELATIONSHIP_NAMESPACE_URIS, OOXML_NAMESPACE_SCOPE, WORDPROCESSINGML_NAMESPACE_URIS, attachXmlNamespaceContext, cloneElement, cloneWithXmlnsDeclarations, collectXmlnsDeclarations, elementToXml, findAllDeep, findAttributeByNamespaceUri, findByFullName, findChild, findChildByLocalName, findChildByNamespaceUri, findChildren, findChildrenByLocalName, findChildrenByNamespaceUri, findDeep, getAttribute, getAttributeAny, getAttributeAnyPrefix, getAttributeByNamespaceUri, getAttributes, getChildElements, getLocalName, getNamespacePrefix, getNamespaceUri, getTextContent, hasChild, hasFlag, matchesName, mergeXmlnsDeclarations, parseBooleanElement, parseColorElement, parseNumberingLevelAttribute, parseNumericAttribute, parseOnOffValue, parseTableMeasurementValue, parseXml, parseXmlDocument, selectAlternateContentBranch };
+export { NAMESPACES, OFFICE_RELATIONSHIP_NAMESPACE_URIS, OOXML_NAMESPACE_SCOPE, WORDPROCESSINGML_NAMESPACE_URIS, attachXmlNamespaceContext, cloneElement, cloneWithXmlnsDeclarations, collectXmlnsDeclarations, elementToXml, findAllDeep, findAttributeByNamespaceUri, findByFullName, findChild, findChildByLocalName, findChildByNamespaceUri, findChildren, findChildrenByLocalName, findChildrenByNamespaceUri, findDeep, getAttribute, getAttributeAny, getAttributeAnyPrefix, getAttributeByNamespaceUri, getAttributes, getChildElements, getLocalName, getNamespacePrefix, getNamespaceUri, getTextContent, hasChild, matchesName, mergeXmlnsDeclarations, parseBooleanElement, parseColorElement, parseNumberingLevelAttribute, parseNumericAttribute, parseOnOffAttribute, parseOnOffValue, parseTableMeasurementValue, parseXml, parseXmlDocument, selectAlternateContentBranch };

package/dist/docx/xmlResourceLimits.d.ts

@@ -1,27 +1,107 @@
 //#region src/docx/xmlResourceLimits.d.ts
-/** Shared bounds for XML parts parsed by Folio. */
+/**
+ * Shared bounds for XML parts parsed by Folio.
+ *
+ * `maxBytes` and the package expansion ceiling bound the *markup*; they do not
+ * bound what parsing that markup allocates. A parsed element retains far more
+ * than the bytes it was written as, so a part that satisfies a byte bound can
+ * still cost multiples of it in tree. Measured on this repository's corpus
+ * generators (Bun 1.4, arm64, heap retained after a forced GC):
+ *
+ *   shape                       bytes/element   tree heap / part bytes
+ *   `<w:r/>`                          49.5 B            8.3x
+ *   `<w:r a=".." x4/>`               105-124 B          2.8-3.3x
+ *   `<w:r><w:t>x</w:t></w:r>`        162-171 B         14.1-14.8x
+ *
+ * An element is therefore the unit a memory bound has to count, because the
+ * adversarial shape is the cheap one: `<w:r/>` is 7 bytes of markup and 49.5
+ * bytes of tree, so 128 MiB of markup buys ~19M elements and ~950 MB of tree
+ * inside a byte budget that never trips.
+ *
+ * Corpus distribution (5,314 readable packages, every XML and .rels part):
+ *
+ *   metric                     p50      p90      p99    p99.9        max
+ *   elements / part             16      227    1,590   24,719    596,668
+ *   elements / package         917    3,230   29,106   71,975    602,212
+ *   attributes / part           27      577    1,993   21,037    630,374
+ *   attributes / package     1,783    4,711   25,896   91,946    639,110
+ *   depth / part                 3        9       15       22     15,005
+ *   elements per byte        0.012    0.027    0.036    0.043      0.111
+ *
+ * The defaults below reject no corpus package that today's bounds accept. The
+ * package budget is the one that matters: it caps a whole package at ~2.5M
+ * elements and ~3M attributes, which is at most ~425 MB of tree at the densest
+ * measured shape and ~124 MB at the cheapest. Before it existed, only
+ * `word/document.xml`, `word/styles.xml` and `word/numbering.xml` were counted
+ * at all, so a package of many merely-large parts could reach the expansion
+ * ceiling of 250 MiB, ~37M elements and well past 1.8 GB of tree while passing
+ * every bound. Lower these to trade format reach for a smaller ceiling.
+ */
 declare const FOLIO_XML_RESOURCE_LIMITS: {
   readonly maxBytes: number;
   readonly maxDepth: 100;
-  readonly maxNodes: 1000000;
+  /** 1.68x the corpus maximum (596,668). Unchanged; a shipped bound is not loosened. */
+  readonly maxElementsPerPart: 1000000;
+  /** 3.97x the corpus maximum (630,374). */
+  readonly maxAttributesPerPart: 2500000;
+  /** 4.15x the corpus maximum (602,212). */
+  readonly maxElementsPerPackage: 2500000;
+  /** 4.69x the corpus maximum (639,110). */
+  readonly maxAttributesPerPackage: 3000000;
 };
 type XmlResourceLimits = {
   maxBytes: number;
   maxDepth: number;
-  maxNodes: number;
+  maxElementsPerPart: number;
+  maxAttributesPerPart: number;
+  maxElementsPerPackage: number;
+  maxAttributesPerPackage: number;
 };
-type XmlResourceLimitKind = "bytes" | "depth" | "nodes" | "syntax";
+type XmlResourceLimitKind = "bytes" | "depth" | "elements" | "attributes" | "package-elements" | "package-attributes" | "syntax";
 declare const XmlResourceLimitError_base: import("better-result").TaggedErrorClass<"XmlResourceLimitError">;
 /** XML input exceeded a parser resource bound or could not be scanned safely. */
 declare class XmlResourceLimitError extends XmlResourceLimitError_base<{
   message: string;
   limit: XmlResourceLimitKind;
+  /** The package part being scanned, when the caller named one. */
+  partPath?: string;
+  /** The count reached at the point of refusal, not the count of the whole input. */
+  observed: number;
+  allowed: number;
 }> {}
 /**
- * Bound XML bytes, element count, and nesting before building an object tree.
- * The lexical scan is iterative, so deeply nested input cannot consume the JS
- * call stack before the depth limit is enforced.
+ * What a package has spent so far, shared by every part in one package.
+ *
+ * Per-part bounds alone do not bound a package: a package may hold hundreds of
+ * parts, each individually modest. The budget is the accumulator the readers
+ * carry across parts so the ceiling is the package's, not each part's.
+ */
+type XmlPackageBudget = {
+  elements: number;
+  attributes: number;
+};
+declare const createXmlPackageBudget: () => XmlPackageBudget;
+type XmlResourceScanOptions = {
+  xml: string;
+  limits?: XmlResourceLimits;
+  /** The package path scanned, carried on any refusal so a host can name it. */
+  partPath?: string;
+  /** Charged as the scan proceeds; omit for a part with no package context. */
+  budget?: XmlPackageBudget;
+};
+/** What the preflight counted, for callers that reconcile it against the tree. */
+type XmlResourceScanResult = {
+  elements: number;
+  attributes: number;
+  maxDepth: number;
+};
+/**
+ * Bound XML bytes, element count, attribute count and nesting before building
+ * an object tree. The lexical scan is iterative, so deeply nested input cannot
+ * consume the JS call stack before the depth limit is enforced, and every
+ * bound is checked at the point it is crossed, so the work done before a
+ * refusal is proportional to the limit rather than to the input.
  */
-declare const assertXmlResourceLimits: (xml: string, limits?: XmlResourceLimits) => void;
+declare const assertXmlResourceLimits: ({ xml, limits, partPath, budget }: XmlResourceScanOptions) => XmlResourceScanResult;
 //#endregion
-export { FOLIO_XML_RESOURCE_LIMITS, XmlResourceLimitError, assertXmlResourceLimits };
+export { FOLIO_XML_RESOURCE_LIMITS, XmlPackageBudget, XmlResourceLimitError, XmlResourceLimits, XmlResourceScanOptions, XmlResourceScanResult, assertXmlResourceLimits, createXmlPackageBudget };