@stll/folio-core 0.54.1 → 0.55.0

package/dist/docx/numericIdAllocator.d.ts

@@ -0,0 +1,12 @@
+//#region src/docx/numericIdAllocator.d.ts
+type NumericIdAllocatorOptions = {
+  space: string;
+  firstId: 0 | 1;
+};
+/** Each OOXML id space owns one instance, retaining loaded and minted ids through rollover. */
+declare const createNumericIdAllocator: ({ space, firstId }: NumericIdAllocatorOptions) => {
+  reserve: (ids: Iterable<number>) => void;
+  next: () => number;
+};
+//#endregion
+export { createNumericIdAllocator };

package/dist/docx/numericIdAllocator.js

@@ -0,0 +1,33 @@
+import { TaggedError } from "better-result";
+import { MAX_REVISION_ID } from "@stll/docx-core/model";
+//#region src/docx/numericIdAllocator.ts
+var OoxmlIdSpaceExhaustedError = class extends TaggedError("OoxmlIdSpaceExhaustedError") {};
+/** Each OOXML id space owns one instance, retaining loaded and minted ids through rollover. */
+const createNumericIdAllocator = ({ space, firstId }) => {
+	const reserved = /* @__PURE__ */ new Set();
+	let nextId = firstId;
+	return {
+		reserve: (ids) => {
+			let max = -1;
+			for (const id of ids) {
+				if (!Number.isInteger(id) || id < firstId || id > MAX_REVISION_ID) continue;
+				reserved.add(id);
+				max = Math.max(max, id);
+			}
+			if (max >= nextId) nextId = max === MAX_REVISION_ID ? firstId : max + 1;
+		},
+		next: () => {
+			if (reserved.size >= MAX_REVISION_ID - firstId + 1) throw new OoxmlIdSpaceExhaustedError({
+				message: `OOXML ${space} id space is exhausted`,
+				space
+			});
+			while (reserved.has(nextId)) nextId = nextId === MAX_REVISION_ID ? firstId : nextId + 1;
+			const id = nextId;
+			reserved.add(id);
+			nextId = id === MAX_REVISION_ID ? firstId : id + 1;
+			return id;
+		}
+	};
+};
+//#endregion
+export { createNumericIdAllocator };

package/dist/docx/numericIdNormalization.d.ts

@@ -0,0 +1,16 @@
+import { RawDocxContent } from "./unzip.js";
+import { XmlElement } from "./xmlParser.js";
+//#region src/docx/numericIdNormalization.d.ts
+type NumericIdNormalizationOptions = {
+  onParsedDocument?: (document: XmlElement) => void;
+};
+/**
+ * Repair out-of-range imported integers before any model or opaque XML is captured.
+ * Reserve the complete package first, then remap each old value once per space.
+ * Source splices preserve unrelated XML bytes; a valid package takes the fast path.
+ */
+declare const normalizeImportedNumericIds: (parts: ReadonlyMap<string, string>, options?: NumericIdNormalizationOptions) => ReadonlyMap<string, string>;
+/** Parser boundary: all captures and selective-save bytes see the same identities. */
+declare const normalizeRawDocxNumericIds: (raw: RawDocxContent) => Promise<XmlElement | undefined>;
+//#endregion
+export { normalizeImportedNumericIds, normalizeRawDocxNumericIds };

package/dist/docx/numericIdNormalization.js

@@ -0,0 +1,174 @@
+import { REVISION_ELEMENT_NAMES } from "./revisionIdNormalization.js";
+import { parseStreamingXmlWithIdentityVisitor, scanStreamingXmlNumericIdAttributes } from "./streamingXmlParser.js";
+import { replaceRawDocxXmlParts } from "./unzip.js";
+import { getLocalName, getNamespaceUri, resolveAttributeNamespaceUri } from "./xmlParser.js";
+import { XmlResourceLimitError } from "./xmlResourceLimits.js";
+import { panic } from "better-result";
+import { assertValidOoxmlNumericId, isOoxmlNumericIdAttributeName, isValidOoxmlNumericId, mayContainInvalidOoxmlNumericIds, mayContainOoxmlNumericIds, ooxmlNumericIdDomain } from "@stll/docx-core";
+//#region src/docx/numericIdNormalization.ts
+const identityKey = (value) => {
+	const spelling = String(value).trim();
+	if (!/^[+-]?\d+$/u.test(spelling)) return spelling;
+	const digits = spelling.replace(/^[+-]?0*/u, "");
+	return digits === "" ? "0" : `${spelling.startsWith("-") ? "-" : ""}${digits}`;
+};
+const identitySpace = ({ elementName, attributeName, domain }) => {
+	if (domain === "unsigned32") return "drawing";
+	const element = getLocalName(elementName);
+	const attribute = getLocalName(attributeName);
+	switch (attribute === "val" ? element : attribute) {
+		case "numId": return "numbering-instance";
+		case "abstractNumId": return "numbering-abstract";
+		case "numPicBulletId":
+		case "lvlPicBulletId": return "numbering-picture";
+		default: break;
+	}
+	switch (element) {
+		case "footnote":
+		case "footnoteReference": return "footnote";
+		case "endnote":
+		case "endnoteReference": return "endnote";
+		case "id": return "content-control";
+		default: return `annotation:${REVISION_ELEMENT_NAMES.has(element) ? "revision" : element.replace(/(?:Range)?(?:Start|End)$/u, "").replace(/^comment.*$/u, "comment")}`;
+	}
+};
+const identifiedAttributes = (element) => {
+	const attributes = [];
+	for (const [name, value] of Object.entries(element.attributes ?? {})) {
+		if (!isOoxmlNumericIdAttributeName({
+			elementName: element.name ?? "",
+			attributeName: name
+		})) continue;
+		if (value === void 0 || !/^[+-]?\d+$/u.test(String(value).trim())) continue;
+		const domain = ooxmlNumericIdDomain({
+			elementName: element.name ?? "",
+			elementNamespace: getNamespaceUri(element),
+			attributeName: name,
+			attributeNamespace: resolveAttributeNamespaceUri(element, name)
+		});
+		if (domain === void 0) continue;
+		attributes.push({
+			name,
+			value,
+			domain,
+			space: identitySpace({
+				elementName: element.name ?? "",
+				attributeName: name,
+				domain
+			})
+		});
+	}
+	return attributes;
+};
+/**
+* Repair out-of-range imported integers before any model or opaque XML is captured.
+* Reserve the complete package first, then remap each old value once per space.
+* Source splices preserve unrelated XML bytes; a valid package takes the fast path.
+*/
+const normalizeImportedNumericIds = (parts, options = {}) => {
+	if (![...parts.values()].some((xml) => mayContainInvalidOoxmlNumericIds(xml, "range"))) return parts;
+	const normalized = new Map(parts);
+	const candidates = [...parts].filter(([, xml]) => mayContainOoxmlNumericIds(xml)).toSorted(([left], [right]) => left.localeCompare(right));
+	const spaces = /* @__PURE__ */ new Map();
+	const reservedPools = /* @__PURE__ */ new Map();
+	const changedSpans = /* @__PURE__ */ new Map();
+	let parsedDocument;
+	const scan = ({ path, xml, visitor }) => {
+		const scanned = path.toLowerCase() === "word/document.xml" && options.onParsedDocument !== void 0 ? parseStreamingXmlWithIdentityVisitor(xml, visitor) : scanStreamingXmlNumericIdAttributes(xml, visitor);
+		if (scanned.status === "unsupported") throw new XmlResourceLimitError({
+			message: `Numeric-id normalization could not safely scan ${path}`,
+			limit: "syntax",
+			observed: 0,
+			allowed: 0
+		});
+		if (scanned.status === "parsed") parsedDocument = scanned.value;
+	};
+	for (const [path, xml] of candidates) scan({
+		path,
+		xml,
+		visitor: (element, attributeValueSpans) => {
+			for (const attribute of identifiedAttributes(element)) {
+				let space = spaces.get(attribute.space);
+				if (space === void 0) {
+					const poolName = attribute.space.startsWith("annotation:") ? "annotation" : attribute.space;
+					let reserved = reservedPools.get(poolName);
+					if (reserved === void 0) {
+						reserved = /* @__PURE__ */ new Set();
+						reservedPools.set(poolName, reserved);
+					}
+					space = {
+						reserved,
+						replacements: /* @__PURE__ */ new Map(),
+						next: 1
+					};
+					spaces.set(attribute.space, space);
+				}
+				if (isValidOoxmlNumericId(attribute.value, attribute.domain)) {
+					space.reserved.add(Number(attribute.value));
+					continue;
+				}
+				const key = identityKey(attribute.value);
+				space.replacements.set(key, "");
+				const span = attributeValueSpans.get(attribute.name);
+				if (span === void 0) panic("Missing imported numeric identity source span");
+				let spans = changedSpans.get(path);
+				if (spans === void 0) {
+					spans = [];
+					changedSpans.set(path, spans);
+				}
+				spans.push({
+					start: span.start,
+					end: span.end,
+					space: attribute.space,
+					key,
+					element,
+					attributeName: attribute.name
+				});
+			}
+			return null;
+		}
+	});
+	for (const space of spaces.values()) for (const key of space.replacements.keys()) {
+		while (space.reserved.has(space.next)) space.next += 1;
+		assertValidOoxmlNumericId({
+			value: space.next,
+			partPath: "import",
+			elementName: "allocated identity",
+			attributeName: "id"
+		});
+		const replacement = String(space.next);
+		space.replacements.set(key, replacement);
+		space.reserved.add(space.next);
+		space.next += 1;
+	}
+	for (const [path, spans] of changedSpans) {
+		const xml = parts.get(path);
+		if (xml === void 0) panic(`Missing imported numeric identity part: ${path}`);
+		const chunks = [];
+		let cursor = 0;
+		for (const span of spans.toSorted((left, right) => left.start - right.start)) {
+			const replacement = spaces.get(span.space)?.replacements.get(span.key);
+			if (replacement === void 0 || replacement === "") panic("Missing imported numeric identity replacement");
+			if (span.element.attributes === void 0) panic("Missing imported numeric identity attributes");
+			span.element.attributes[span.attributeName] = replacement;
+			chunks.push(xml.slice(cursor, span.start), replacement);
+			cursor = span.end;
+		}
+		chunks.push(xml.slice(cursor));
+		normalized.set(path, chunks.join(""));
+	}
+	if (parsedDocument !== void 0) options.onParsedDocument?.(parsedDocument);
+	return normalized;
+};
+/** Parser boundary: all captures and selective-save bytes see the same identities. */
+const normalizeRawDocxNumericIds = async (raw) => {
+	let documentTree;
+	const normalized = normalizeImportedNumericIds(raw.allXml, { onParsedDocument: (tree) => {
+		documentTree = tree;
+	} });
+	if (normalized === raw.allXml) return documentTree;
+	await replaceRawDocxXmlParts(raw, normalized);
+	return documentTree;
+};
+//#endregion
+export { normalizeImportedNumericIds, normalizeRawDocxNumericIds };

package/dist/docx/packageParts.d.ts

@@ -1,5 +1,7 @@
 import JSZip from "jszip";
 //#region src/docx/packageParts.d.ts
+/** Resolve an internal URI reference once, before comparing it with ZIP entries. */
+declare const resolvePackageRelationshipTarget: (target: string, relsPath: string) => string | undefined;
 /**
  * Whether an entry path would escape the package when a host writes the archive
  * to disk: absolute, backslash-separated, or climbing out through `..`. This is
@@ -76,4 +78,4 @@ type PackageIntegrityReport = {
  */
 declare const checkPackageIntegrity: (zip: JSZip) => Promise<PackageIntegrityReport>;
 //#endregion
-export { PackageIntegrityReport, PackageReferenceRepair, checkPackageIntegrity, isUnsafePackagePath, reconcilePackageReferences, removeUnsafeEntries };
+export { PackageIntegrityReport, PackageReferenceRepair, checkPackageIntegrity, isUnsafePackagePath, reconcilePackageReferences, removeUnsafeEntries, resolvePackageRelationshipTarget };

package/dist/docx/packageParts.js

@@ -1,5 +1,30 @@
-import { resolveRelativePath } from "./relsParser.js";
+import { Result } from "better-result";
 //#region src/docx/packageParts.ts
+/**
+* What a repack carries out of the source package, and the guarantee that
+* nothing in the output points at a part the output does not hold.
+*
+* A `.docx` is an OPC package: `[Content_Types].xml` declares every part in it
+* and the `.rels` parts wire them together. Folio models a handful of those
+* parts (the document body, headers, footers, notes, numbering, styles,
+* comments) and rewrites them on save. Everything else — embedded objects,
+* media, custom XML, fonts, charts, macro projects, parts folio has never heard
+* of — belongs to the author, and a repack hands it back byte for byte.
+*
+* Folio never executes document content and never removes it. The document is
+* the user's; the only thing a save refuses is a package path that would let
+* the archive escape its own directory when a host writes it out, which is a
+* property of the package structure rather than of the content. A macro-enabled
+* document therefore stays macro-enabled, main-part content type included:
+* silently handing back a `.docm` stripped of its project is data loss dressed
+* up as safety.
+*
+* A refused path loses its relationships and its content-type override with it.
+* That is the invariant this module exists for: Word and LibreOffice both
+* refuse a package whose `document.xml.rels` points at nothing, so a repack
+* that removes a part without removing its references produces a file that
+* does not open.
+*/
 const CONTENT_TYPE_ELEMENT = /<(?:Default|Override)\b[^>]*?\/?>/giu;
 const PART_NAME_ATTRIBUTE = /\bPartName\s*=\s*(?<quote>["'])(?<value>[^"']*)\k<quote>/u;
 const RELATIONSHIP_ELEMENT = /<Relationship\b[^>]*?(?:\/>|>\s*<\/Relationship>)/giu;
@@ -24,12 +49,38 @@ const owningPartPath = (relsPath) => {
 };
 /** Normalize a package path for comparison: lower case, no leading slash. */
 const normalizePartPath = (path) => (path.startsWith("/") ? path.slice(1) : path).toLowerCase();
-/**
-* Decode `%XX` escapes in a part name. `decodeURI` throws on a malformed
-* escape, and a malformed target is exactly the input this has to survive, so
-* the replacement is done by hand.
-*/
-const decodePartName = (name) => name.replaceAll(/%[0-9A-Fa-f]{2}/gu, (escape) => String.fromCharCode(Number.parseInt(escape.slice(1), 16)));
+/** Decode URI escapes as UTF-8; malformed references cannot name a part. */
+const decodePartName = (name) => {
+	const decoded = Result.try({
+		try: () => decodeURIComponent(name),
+		catch: () => void 0
+	});
+	return decoded.isOk() ? decoded.value : void 0;
+};
+/** Resolve an internal URI reference once, before comparing it with ZIP entries. */
+const resolvePackageRelationshipTarget = (target, relsPath) => {
+	const fragment = target.indexOf("#");
+	if (fragment === 0) {
+		const owner = owningPartPath(relsPath);
+		return owner === void 0 ? void 0 : normalizePartPath(owner);
+	}
+	const reference = fragment > 0 ? target.slice(0, fragment) : target;
+	if (!reference || reference.startsWith("//") || /[\\?:]/u.test(reference)) return void 0;
+	const owner = owningPartPath(relsPath);
+	const segments = reference.startsWith("/") || owner === void 0 ? [] : owner.split("/").slice(0, -1);
+	for (const encoded of reference.split("/")) {
+		const segment = decodePartName(encoded);
+		if (segment === void 0 || /[/\\]/u.test(segment) || segment.includes(String.fromCharCode(0))) return void 0;
+		if (segment === "" || segment === ".") continue;
+		if (segment === "..") {
+			if (segments.pop() === void 0) return void 0;
+			continue;
+		}
+		segments.push(segment);
+	}
+	const path = normalizePartPath(segments.join("/"));
+	return isUnsafePackagePath(path) ? void 0 : path;
+};
 /**
 * Whether an entry path would escape the package when a host writes the archive
 * to disk: absolute, backslash-separated, or climbing out through `..`. This is
@@ -53,15 +104,13 @@ const presentPartPaths = (zip) => {
 	for (const [path, file] of Object.entries(zip.files)) if (!file.dir) present.add(normalizePartPath(path));
 	return present;
 };
-const isPresent = (present, partPath) => present.has(normalizePartPath(partPath)) || present.has(normalizePartPath(decodePartName(partPath)));
+const isPresent = (present, partPath) => present.has(normalizePartPath(partPath)) || present.has(normalizePartPath(decodePartName(partPath) ?? ""));
 /** The part a relationship names, or null when it points outside the package. */
 const relationshipTarget = (element, relsPath) => {
 	if (TARGET_MODE_ATTRIBUTE.exec(element)?.groups?.["value"] === "External") return null;
 	const target = TARGET_ATTRIBUTE.exec(element)?.groups?.["value"];
 	if (target === void 0) return null;
-	const fragment = target.indexOf("#");
-	if (fragment === 0) return owningPartPath(relsPath) ?? "";
-	return resolveRelativePath(relsPath, fragment > 0 ? target.slice(0, fragment) : target);
+	return resolvePackageRelationshipTarget(target, relsPath) ?? "";
 };
 /**
 * Every `.rels` part with its text. Read one at a time rather than through
@@ -107,8 +156,8 @@ const reconcilePackageReferences = async (zip, compressionLevel) => {
 		let dropped = false;
 		const pruned = xml.replaceAll(RELATIONSHIP_ELEMENT, (element) => {
 			const target = relationshipTarget(element, path);
-			if (target === null || isPresent(present, target)) return element;
-			repair.danglingRelationships.push(target);
+			if (target === null || present.has(target)) return element;
+			repair.danglingRelationships.push(target || TARGET_ATTRIBUTE.exec(element)?.groups?.["value"] || "");
 			dropped = true;
 			const id = RELATIONSHIP_ID_ATTRIBUTE.exec(element)?.groups?.["value"];
 			const owningPart = owningPartPath(path);
@@ -154,7 +203,7 @@ const reconcilePackageReferences = async (zip, compressionLevel) => {
 	const prunedContentTypes = (await contentTypes.async("text")).replaceAll(CONTENT_TYPE_ELEMENT, (element) => {
 		const partName = PART_NAME_ATTRIBUTE.exec(element)?.groups?.["value"];
 		if (partName === void 0 || isPresent(present, partName)) return element;
-		repair.danglingOverrides.push(normalizePartPath(decodePartName(partName)));
+		repair.danglingOverrides.push(normalizePartPath(decodePartName(partName) ?? partName));
 		droppedOverride = true;
 		return "";
 	});
@@ -195,7 +244,7 @@ const checkPackageIntegrity = async (zip) => {
 			const id = RELATIONSHIP_ID_ATTRIBUTE.exec(element)?.groups?.["value"];
 			if (id !== void 0) ids.add(id);
 			const target = relationshipTarget(element, path);
-			if (target !== null && !isPresent(present, target)) report.danglingRelationshipTargets.push(`${path}|${target}`);
+			if (target !== null && !present.has(target)) report.danglingRelationshipTargets.push(`${path}|${target || TARGET_ATTRIBUTE.exec(element)?.groups?.["value"] || ""}`);
 		}
 		if (owningPart !== void 0) idsByOwningPart.set(owningPart, ids);
 	}
@@ -211,4 +260,4 @@ const checkPackageIntegrity = async (zip) => {
 	return report;
 };
 //#endregion
-export { checkPackageIntegrity, isUnsafePackagePath, reconcilePackageReferences, removeUnsafeEntries };
+export { checkPackageIntegrity, isUnsafePackagePath, reconcilePackageReferences, removeUnsafeEntries, resolvePackageRelationshipTarget };

package/dist/docx/paragraphMarkPropertyPresence.d.ts

@@ -0,0 +1,9 @@
+import { document_d_exports } from "../types/document.js";
+import { XmlElement } from "./xmlParser.js";
+//#region src/docx/paragraphMarkPropertyPresence.d.ts
+declare const EMPTY_MARK_PROPERTIES_ATTRIBUTE = "emptyMarkProperties";
+/** A paragraph-owned rPr carrier cannot distinguish absent and explicitly empty formatting. */
+declare const serializeEmptyMarkProperties: (paragraph: document_d_exports.Paragraph) => string | undefined;
+declare const restoreEmptyMarkProperties: (paragraph: document_d_exports.Paragraph, element: XmlElement) => void;
+//#endregion
+export { EMPTY_MARK_PROPERTIES_ATTRIBUTE, restoreEmptyMarkProperties, serializeEmptyMarkProperties };

package/dist/docx/paragraphMarkPropertyPresence.js

@@ -0,0 +1,21 @@
+import { OOXML_NAMESPACES } from "./serializer/partNamespaces.js";
+import { getAttributeByNamespaceUri } from "./xmlParser.js";
+import { EMPTY_PROPERTY_SETS } from "@stll/docx-core/ops";
+//#region src/docx/paragraphMarkPropertyPresence.ts
+const EMPTY_MARK_PROPERTIES_ATTRIBUTE = "emptyMarkProperties";
+const REVIEW_HISTORY_NAMESPACES = /* @__PURE__ */ new Set([OOXML_NAMESPACES.folio.uri]);
+/** A paragraph-owned rPr carrier cannot distinguish absent and explicitly empty formatting. */
+const serializeEmptyMarkProperties = (paragraph) => {
+	const properties = paragraph.formatting?.runProperties;
+	if (!(paragraph.pPrMark !== void 0 || paragraph.formatting?.runInWithNext !== void 0) || properties === void 0 || Object.keys(properties).length !== 0) return void 0;
+	return `folio:${EMPTY_MARK_PROPERTIES_ATTRIBUTE}="${EMPTY_PROPERTY_SETS.KEEP}"`;
+};
+const restoreEmptyMarkProperties = (paragraph, element) => {
+	if (paragraph.pPrMark === void 0 && paragraph.formatting?.runInWithNext === void 0 || getAttributeByNamespaceUri(element, REVIEW_HISTORY_NAMESPACES, "emptyMarkProperties") !== EMPTY_PROPERTY_SETS.KEEP || paragraph.formatting?.runProperties !== void 0) return;
+	paragraph.formatting = {
+		...paragraph.formatting,
+		runProperties: {}
+	};
+};
+//#endregion
+export { EMPTY_MARK_PROPERTIES_ATTRIBUTE, restoreEmptyMarkProperties, serializeEmptyMarkProperties };