@stll/folio-core 0.54.2 → 0.55.0

package/dist/docx/foldedListNumberFields.js

@@ -0,0 +1,267 @@
+//#region src/docx/foldedListNumberFields.ts
+/** Zero-width markup that can stand between a field and its tab. */
+const RANGE_MARKER_TYPES = /* @__PURE__ */ new Set([
+	"bookmarkStart",
+	"bookmarkEnd",
+	"commentRangeStart",
+	"commentRangeEnd",
+	"commentReference"
+]);
+/** Markup that shows nothing and so does not end the start of a paragraph. */
+const ZERO_WIDTH_TYPES = /* @__PURE__ */ new Set([
+	...RANGE_MARKER_TYPES,
+	"moveFromRangeStart",
+	"moveFromRangeEnd",
+	"moveToRangeStart",
+	"moveToRangeEnd"
+]);
+/** Whether `content` is markup that may stand between a field and the tab that follows it. */
+const isListNumberGapMarker = (content) => RANGE_MARKER_TYPES.has(content.type);
+const isZeroWidth = (content) => ZERO_WIDTH_TYPES.has(content.type) || content.type === "preservedInline" && content.text === "";
+/** Whether `content` is a `LISTNUM` field, by its parsed type or its instruction. */
+const isListNumberField = (content) => content.type === "complexField" && (content.fieldType === "LISTNUM" || content.instruction.trim().toUpperCase().startsWith("LISTNUM"));
+/** A run that holds one tab and nothing else. */
+const isTabOnlyRun = (content) => content.type === "run" && content.content.length === 1 && content.content[0]?.type === "tab";
+/** The text a field's cached result puts in the marker. */
+const cachedListNumberText = (field) => {
+	let text = "";
+	for (const run of field.fieldResult) for (const piece of run.content) if (piece.type === "text") text += piece.text;
+	return text;
+};
+const isRecord = (value) => typeof value === "object" && value !== null;
+/** Whether `value` is what a capture stands for: a complex field, or a run. */
+const isFoldedListNumber = (value) => {
+	if (!isRecord(value)) return false;
+	if (value["kind"] === "field") {
+		const field = value["field"];
+		return isRecord(field) && field["type"] === "complexField" && typeof field["instruction"] === "string" && Array.isArray(field["fieldCode"]) && Array.isArray(field["fieldResult"]);
+	}
+	if (value["kind"] === "tab") {
+		const run = value["run"];
+		return isRecord(run) && run["type"] === "run" && Array.isArray(run["content"]);
+	}
+	return false;
+};
+/** What `content` stands for when it is a capture the fold left, else nothing. */
+const foldedListNumberOf = (content) => content.type === "preservedInline" ? content.foldedListNumber : void 0;
+/** Whether `content` is a capture the fold left in place of a field or its tab. */
+const isFoldedListNumberCapture = (content) => foldedListNumberOf(content) !== void 0;
+/**
+* Replace the `LISTNUM` fields that open a paragraph, and the tab after each,
+* by captures of the markup they were read from.
+*
+* Only what stands ahead of the first thing the line shows is folded: a field
+* after text is on the line where the text is. `sourceMarkupOf` answers the
+* markup; a field it has none for is left as the field it is, and ends the
+* fold. Bookmark and comment markers between a field and its tab stay where
+* they are, and the tab is still the field's when only they separate the two.
+*/
+const foldListNumberFields = (content, sourceMarkupOf) => {
+	const folded = [];
+	const cached = [];
+	let fieldCount = 0;
+	let leading = true;
+	let awaitingTab = false;
+	for (const item of content) {
+		if (isListNumberField(item)) fieldCount += 1;
+		if (!leading) {
+			folded.push(item);
+			continue;
+		}
+		if (awaitingTab && RANGE_MARKER_TYPES.has(item.type)) {
+			folded.push(item);
+			continue;
+		}
+		if (awaitingTab) {
+			awaitingTab = false;
+			const tabMarkup = isTabOnlyRun(item) ? sourceMarkupOf(item) : void 0;
+			if (isTabOnlyRun(item) && tabMarkup !== void 0) {
+				folded.push({
+					type: "preservedInline",
+					xml: tabMarkup,
+					text: "",
+					foldedListNumber: {
+						kind: "tab",
+						run: item
+					}
+				});
+				continue;
+			}
+		}
+		if (isListNumberField(item)) {
+			const markup = sourceMarkupOf(item);
+			if (markup !== void 0) {
+				folded.push({
+					type: "preservedInline",
+					xml: markup,
+					text: "",
+					foldedListNumber: {
+						kind: "field",
+						field: item
+					}
+				});
+				const text = cachedListNumberText(item);
+				if (text) cached.push(text);
+				awaitingTab = true;
+				continue;
+			}
+		}
+		folded.push(item);
+		leading = isZeroWidth(item);
+	}
+	return {
+		content: folded,
+		cached,
+		fieldCount
+	};
+};
+const isCapture = (item) => item?.kind === "field" || item?.kind === "tab";
+/**
+* Decide which captures of a paragraph stay hidden, and what its marker shows.
+*
+* `markerShowsFields` says whether the paragraph's marker shows folded fields
+* at all. When it does not, no capture is hidden.
+*
+* When it does, the captures it shows are the ones that open the paragraph:
+* those ahead of the first thing the line shows, each field followed at most
+* by its own tab. Text put in front of them was put in front of the body, not
+* of the marker, so if the first capture no longer opens the paragraph, it
+* and the captures that stand with it go back to the start. Every capture
+* further in is on the line.
+*/
+const planListNumberFold = (items, markerShowsFields) => {
+	const unmoved = items.map((_, index) => index);
+	const none = {
+		order: unmoved,
+		hidden: /* @__PURE__ */ new Set(),
+		suffix: void 0
+	};
+	const first = items.findIndex((item) => isCapture(item));
+	if (!markerShowsFields || first === -1) return none;
+	let order = unmoved;
+	if (items.slice(0, first).some((item) => item.kind === "shown")) {
+		let end = first + 1;
+		for (let index = first + 1; index < items.length; index += 1) {
+			const item = items[index];
+			if (item?.kind === "shown") break;
+			if (isCapture(item)) end = index + 1;
+		}
+		order = [
+			...unmoved.slice(first, end),
+			...unmoved.slice(0, first),
+			...unmoved.slice(end)
+		];
+	}
+	const hidden = /* @__PURE__ */ new Set();
+	const cached = [];
+	let fieldAwaitsTab = false;
+	for (const index of order) {
+		const item = items[index];
+		if (item?.kind === "hidden") continue;
+		if (item?.kind === "field") {
+			hidden.add(index);
+			if (item.cached) cached.push(item.cached);
+			fieldAwaitsTab = true;
+			continue;
+		}
+		if (item?.kind === "tab" && fieldAwaitsTab) {
+			hidden.add(index);
+			fieldAwaitsTab = false;
+			continue;
+		}
+		break;
+	}
+	return cached.length === 0 ? none : {
+		order,
+		hidden,
+		suffix: cached.join(" ")
+	};
+};
+/**
+* What a paragraph's marker says about folded fields. It shows them after a
+* tab its own level text does not have; a bullet shows only its glyph.
+*/
+const listMarkerFoldState = ({ marker, template, isBullet, numbered }) => {
+	const tab = marker?.indexOf("	") ?? -1;
+	if (!marker || !numbered || isBullet || !template || template.includes("	") || tab === -1) return {
+		showsFields: false,
+		base: marker ?? ""
+	};
+	return {
+		showsFields: true,
+		base: marker.slice(0, tab)
+	};
+};
+/** The marker text for `state` showing `suffix`. */
+const listMarkerWithFold = (state, suffix) => suffix === void 0 ? state.base : `${state.base}\t${suffix}`;
+const foldItemOf = (content) => {
+	const folded = foldedListNumberOf(content);
+	if (folded) return folded.kind === "field" ? {
+		kind: "field",
+		cached: cachedListNumberText(folded.field)
+	} : { kind: "tab" };
+	return isZeroWidth(content) ? { kind: "hidden" } : { kind: "shown" };
+};
+/** The item a capture stands for, which shows on the line; any other item is itself. */
+const unfoldedListNumberContent = (content) => {
+	const folded = foldedListNumberOf(content);
+	if (!folded) return content;
+	return folded.kind === "field" ? folded.field : folded.run;
+};
+/**
+* The one definition of a tracked change for the fold: content inserted,
+* deleted, or moved from or to a place under revision tracking.
+*/
+const isTrackedChange = (content) => content.type === "insertion" || content.type === "deletion" || content.type === "moveFrom" || content.type === "moveTo";
+/**
+* `content` with every capture inside a tracked change replaced by the item
+* it stands for. A tracked change is written with its own spellings (deleted
+* text is `w:delText`, a deleted instruction `w:delInstrText`), which markup
+* replayed as it was read does not have; the field and the run do.
+*/
+const withTrackedCapturesShown = (content) => {
+	let changed = false;
+	const next = content.map((item) => {
+		if (!isTrackedChange(item)) return item;
+		if (!item.content.some((child) => foldedListNumberOf(child) !== void 0)) return item;
+		changed = true;
+		return {
+			...item,
+			content: item.content.map((child) => {
+				const folded = foldedListNumberOf(child);
+				if (!folded) return child;
+				return structuredClone(folded.kind === "field" ? folded.field : folded.run);
+			})
+		};
+	});
+	return changed ? next : content;
+};
+/**
+* Bring `paragraph` to the one form the fold allows: the captures its marker
+* shows stand at its start, every other capture is the field or the tab it
+* stood for, and the marker shows exactly the fields still hidden behind it.
+* A capture under a tracked change is never hidden.
+*/
+const normalizeFoldedListNumbers = (paragraph) => {
+	paragraph.content = withTrackedCapturesShown(paragraph.content);
+	const rendering = paragraph.listRendering;
+	const state = listMarkerFoldState({
+		marker: rendering?.marker,
+		template: rendering?.markerTemplate,
+		isBullet: rendering?.isBullet === true,
+		numbered: rendering !== void 0
+	});
+	const content = paragraph.content;
+	if (!state.showsFields && !content.some(isFoldedListNumberCapture)) return;
+	const plan = planListNumberFold(content.map(foldItemOf), state.showsFields);
+	const next = [];
+	for (const index of plan.order) {
+		const item = content[index];
+		if (item === void 0) continue;
+		next.push(plan.hidden.has(index) || !isFoldedListNumberCapture(item) ? item : structuredClone(unfoldedListNumberContent(item)));
+	}
+	paragraph.content = next;
+	if (rendering && state.showsFields) rendering.marker = listMarkerWithFold(state, plan.suffix);
+};
+//#endregion
+export { foldListNumberFields, foldedListNumberOf, isFoldedListNumber, isFoldedListNumberCapture, isListNumberField, isListNumberGapMarker, isTabOnlyRun, normalizeFoldedListNumbers, planListNumberFold, unfoldedListNumberContent };

package/dist/docx/headerFooterVerbatim.d.ts

@@ -1,9 +1,22 @@
 import { document_d_exports } from "../types/document.js";
 //#region src/docx/headerFooterVerbatim.d.ts
+type HeaderFooterSourceBaseline = {
+  type: "missing";
+} | {
+  type: "mismatch";
+} | {
+  type: "captured";
+  content: readonly document_d_exports.BlockContent[];
+};
+declare const captureHeaderFooterPackageBaselines: (document: document_d_exports.Document) => void;
+/** Transfer the parsed package registry only across a trusted document graph clone. */
+declare const copyHeaderFooterPackageBaselines: (target: document_d_exports.Document, source: document_d_exports.Document) => void;
+declare const getHeaderFooterSourceBaseline: (hf: document_d_exports.HeaderFooter, originalBuffer?: ArrayBuffer) => HeaderFooterSourceBaseline;
+declare const canReplayHeaderFooterBlocks: (hf: document_d_exports.HeaderFooter, baselineContent: readonly document_d_exports.BlockContent[]) => boolean;
 declare const getHeaderFooterVerbatimXml: (hf: document_d_exports.HeaderFooter) => string | undefined;
 declare const canReplayHeaderFooterVerbatim: (hf: document_d_exports.HeaderFooter) => boolean;
 declare const assignHeaderFooterVerbatimXml: (hf: document_d_exports.HeaderFooter, xml: string) => void;
 declare const refreshHeaderFooterVerbatimFingerprint: (hf: document_d_exports.HeaderFooter) => void;
 declare const clearHeaderFooterVerbatimXml: (hf: document_d_exports.HeaderFooter) => void;
 //#endregion
-export { assignHeaderFooterVerbatimXml, canReplayHeaderFooterVerbatim, clearHeaderFooterVerbatimXml, getHeaderFooterVerbatimXml, refreshHeaderFooterVerbatimFingerprint };
+export { assignHeaderFooterVerbatimXml, canReplayHeaderFooterBlocks, canReplayHeaderFooterVerbatim, captureHeaderFooterPackageBaselines, clearHeaderFooterVerbatimXml, copyHeaderFooterPackageBaselines, getHeaderFooterSourceBaseline, getHeaderFooterVerbatimXml, refreshHeaderFooterVerbatimFingerprint };

package/dist/docx/headerFooterVerbatim.js

@@ -1,5 +1,89 @@
+import { canonicalJson } from "../utils/canonicalJson.js";
+import { Result } from "better-result";
 //#region src/docx/headerFooterVerbatim.ts
+const fingerprintBaselines = /* @__PURE__ */ new WeakMap();
+const readFingerprint = (hf) => {
+	const fingerprint = hf.verbatimFingerprint;
+	if (!fingerprint) return void 0;
+	const cached = fingerprintBaselines.get(hf);
+	if (cached?.fingerprint === fingerprint) return cached.value;
+	const parsed = Result.try(() => JSON.parse(fingerprint));
+	const value = parsed.isOk() ? parsed.value : void 0;
+	fingerprintBaselines.set(hf, {
+		fingerprint,
+		value
+	});
+	return value;
+};
+const BASELINE_HANDLE = Symbol("header-footer-source-baseline");
+const contentBaselines = /* @__PURE__ */ new WeakMap();
+const captureContentBaseline = (hf) => {
+	const fingerprint = hf.verbatimFingerprint;
+	if (fingerprint === void 0) return;
+	const handle = {};
+	const content = structuredClone(hf.content);
+	contentBaselines.set(handle, {
+		fingerprint,
+		xml: hf.verbatimXml,
+		contentFingerprint: canonicalJson(content),
+		content
+	});
+	Object.defineProperty(hf, BASELINE_HANDLE, {
+		value: handle,
+		enumerable: true,
+		configurable: true
+	});
+};
+const packageBaselines = /* @__PURE__ */ new WeakMap();
+const captureHeaderFooterPackageBaselines = (document) => {
+	if (!document.originalBuffer) return;
+	const handles = /* @__PURE__ */ new Map();
+	for (const parts of [document.package.headers, document.package.footers]) for (const hf of parts?.values() ?? []) {
+		if (!(BASELINE_HANDLE in hf) || typeof hf[BASELINE_HANDLE] !== "object" || hf[BASELINE_HANDLE] === null || hf.verbatimFingerprint === void 0 || hf.verbatimXml === void 0) continue;
+		const bySource = handles.get(hf.verbatimFingerprint) ?? /* @__PURE__ */ new Map();
+		bySource.set(hf.verbatimXml, hf[BASELINE_HANDLE]);
+		handles.set(hf.verbatimFingerprint, bySource);
+	}
+	packageBaselines.set(document.originalBuffer, handles);
+};
+/** Transfer the parsed package registry only across a trusted document graph clone. */
+const copyHeaderFooterPackageBaselines = (target, source) => {
+	if (!target.originalBuffer || !source.originalBuffer) return;
+	const baselines = packageBaselines.get(source.originalBuffer);
+	if (baselines) packageBaselines.set(target.originalBuffer, baselines);
+};
+const getHeaderFooterSourceBaseline = (hf, originalBuffer) => {
+	let handle;
+	if (BASELINE_HANDLE in hf) handle = hf[BASELINE_HANDLE];
+	else if (originalBuffer && hf.verbatimFingerprint !== void 0 && hf.verbatimXml !== void 0) handle = packageBaselines.get(originalBuffer)?.get(hf.verbatimFingerprint)?.get(hf.verbatimXml);
+	if (handle === void 0 && !(BASELINE_HANDLE in hf)) return { type: "missing" };
+	if (typeof handle !== "object" || handle === null) return { type: "mismatch" };
+	const baseline = contentBaselines.get(handle);
+	if (!baseline || baseline.fingerprint !== hf.verbatimFingerprint || baseline.xml !== hf.verbatimXml || baseline.contentFingerprint !== canonicalJson(baseline.content)) return { type: "mismatch" };
+	return {
+		type: "captured",
+		content: baseline.content
+	};
+};
+const canReplayHeaderFooterBlocks = (hf, baselineContent) => {
+	if (hf.rawWatermarkXml !== void 0) {
+		const index = hf.watermarkBlockIndex;
+		if (index === void 0 || !Number.isInteger(index) || index < 0 || index >= baselineContent.length || baselineContent.length !== hf.content.length || canonicalJson(baselineContent.at(index)) !== canonicalJson(hf.content.at(index))) return false;
+	}
+	const baseline = readFingerprint(hf);
+	if (baseline === null || typeof baseline !== "object" || !("type" in baseline) || baseline.type !== hf.type) return false;
+	return canonicalJson({
+		watermark: "watermark" in baseline ? baseline.watermark : void 0,
+		watermarkBlockIndex: "watermarkBlockIndex" in baseline ? baseline.watermarkBlockIndex : void 0,
+		rawWatermarkXml: "rawWatermarkXml" in baseline ? baseline.rawWatermarkXml : void 0
+	}) === canonicalJson({
+		watermark: hf.watermark,
+		watermarkBlockIndex: hf.watermarkBlockIndex,
+		rawWatermarkXml: hf.rawWatermarkXml
+	});
+};
 const headerFooterSerializationFingerprint = (hf) => JSON.stringify({
+	type: hf.type,
 	content: hf.content,
 	watermark: hf.watermark,
 	watermarkBlockIndex: hf.watermarkBlockIndex,
@@ -9,22 +93,31 @@ const getHeaderFooterVerbatimXml = (hf) => hf.verbatimXml;
 const canReplayHeaderFooterVerbatim = (hf) => {
 	const ext = hf;
 	if (!ext.verbatimXml || !ext.verbatimFingerprint) return false;
-	return ext.verbatimFingerprint === headerFooterSerializationFingerprint(hf);
+	return canonicalJson(readFingerprint(hf)) === canonicalJson({
+		type: hf.type,
+		content: hf.content,
+		watermark: hf.watermark,
+		watermarkBlockIndex: hf.watermarkBlockIndex,
+		rawWatermarkXml: hf.rawWatermarkXml
+	});
 };
 const assignHeaderFooterVerbatimXml = (hf, xml) => {
 	const ext = hf;
 	ext.verbatimXml = xml;
 	ext.verbatimFingerprint = headerFooterSerializationFingerprint(hf);
+	captureContentBaseline(hf);
 };
 const refreshHeaderFooterVerbatimFingerprint = (hf) => {
 	const ext = hf;
 	if (!ext.verbatimXml) return;
 	ext.verbatimFingerprint = headerFooterSerializationFingerprint(hf);
+	captureContentBaseline(hf);
 };
 const clearHeaderFooterVerbatimXml = (hf) => {
 	const ext = hf;
 	delete ext.verbatimXml;
 	delete ext.verbatimFingerprint;
+	Reflect.deleteProperty(hf, BASELINE_HANDLE);
 };
 //#endregion
-export { assignHeaderFooterVerbatimXml, canReplayHeaderFooterVerbatim, clearHeaderFooterVerbatimXml, getHeaderFooterVerbatimXml, refreshHeaderFooterVerbatimFingerprint };
+export { assignHeaderFooterVerbatimXml, canReplayHeaderFooterBlocks, canReplayHeaderFooterVerbatim, captureHeaderFooterPackageBaselines, clearHeaderFooterVerbatimXml, copyHeaderFooterPackageBaselines, getHeaderFooterSourceBaseline, getHeaderFooterVerbatimXml, refreshHeaderFooterVerbatimFingerprint };

package/dist/docx/noteIds.d.ts

@@ -1,4 +1,9 @@
 //#region src/docx/noteIds.d.ts
+/**
+ * The next free endnote id among `existingIds`, a document's endnotes. Ids are
+ * unique per document, so the allocator lives for one call: the result
+ * depends only on the document, never on what other documents minted.
+ */
 declare const mintEndnoteId: (existingIds: Iterable<number>) => number;
 //#endregion
 export { mintEndnoteId };

package/dist/docx/noteIds.js

@@ -1,8 +1,12 @@
 import { createNumericIdAllocator } from "./numericIdAllocator.js";
 //#region src/docx/noteIds.ts
-let endnoteIds;
+/**
+* The next free endnote id among `existingIds`, a document's endnotes. Ids are
+* unique per document, so the allocator lives for one call: the result
+* depends only on the document, never on what other documents minted.
+*/
 const mintEndnoteId = (existingIds) => {
-	const allocator = endnoteIds ??= createNumericIdAllocator({
+	const allocator = createNumericIdAllocator({
 		space: "endnote",
 		firstId: 1
 	});

package/dist/docx/noteReferenceMark.d.ts

@@ -3,6 +3,8 @@ import { document_d_exports } from "../types/document.js";
 type NoteKind = "footnote" | "endnote";
 /** The run carrying a note's in-note reference mark, in the note reference style. */
 declare const noteReferenceMarkRun: (kind: NoteKind) => document_d_exports.Run;
+/** Whether a note already owns its typed marker, including inside tracked content. */
+declare const hasNoteReferenceMark: (kind: NoteKind, content: readonly document_d_exports.BlockContent[]) => boolean;
 /**
  * A note's content with its reference mark run at the start of its first
  * paragraph, added when the note has none.
@@ -12,4 +14,4 @@ declare const withNoteReferenceMark: (kind: NoteKind, content: readonly document
 declare function createNote(kind: "footnote", id: number, content: readonly document_d_exports.BlockContent[]): document_d_exports.Footnote;
 declare function createNote(kind: "endnote", id: number, content: readonly document_d_exports.BlockContent[]): document_d_exports.Endnote;
 //#endregion
-export { createNote, noteReferenceMarkRun, withNoteReferenceMark };
+export { createNote, hasNoteReferenceMark, noteReferenceMarkRun, withNoteReferenceMark };

package/dist/docx/noteReferenceMark.js

@@ -1,37 +1,38 @@
 import { cloneParagraphWithPropertySource } from "./paragraphPropertySource.js";
+import { visitDocxParagraphs, visitParagraphRuns } from "./paragraphTraversal.js";
 //#region src/docx/noteReferenceMark.ts
-const MARK_ELEMENT = /<(?:[\w.-]+:)?(?:footnote|endnote)Ref[\s/>]/u;
 /** The run carrying a note's in-note reference mark, in the note reference style. */
 const noteReferenceMarkRun = (kind) => ({
 	type: "run",
 	formatting: { styleId: kind === "footnote" ? "FootnoteReference" : "EndnoteReference" },
 	content: [{
-		type: "preservedXml",
-		xml: `<w:${kind}Ref/>`,
-		text: ""
+		type: "noteMarker",
+		kind
 	}]
 });
-const holdsReferenceMark = (value) => {
-	if (Array.isArray(value)) return value.some(holdsReferenceMark);
-	if (typeof value !== "object" || value === null) return false;
-	const record = value;
-	if (record["type"] === "preservedXml" && typeof record["xml"] === "string") return MARK_ELEMENT.test(record["xml"]);
-	return Object.values(record).some(holdsReferenceMark);
+/** Whether a note already owns its typed marker, including inside tracked content. */
+const hasNoteReferenceMark = (kind, content) => {
+	let found = false;
+	visitDocxParagraphs({ documentBody: { content: [...content] } }, (paragraph) => {
+		visitParagraphRuns(paragraph, (run) => {
+			if (run.content.some((child) => child.type === "noteMarker" && child.kind === kind)) found = true;
+		});
+	});
+	return found;
 };
 /**
 * A note's content with its reference mark run at the start of its first
 * paragraph, added when the note has none.
 */
 const withNoteReferenceMark = (kind, content) => {
-	if (holdsReferenceMark(content)) return [...content];
+	if (hasNoteReferenceMark(kind, content)) return [...content];
 	const index = content.findIndex((block) => block.type === "paragraph");
 	const mark = noteReferenceMarkRun(kind);
 	if (index === -1) return [{
 		type: "paragraph",
 		content: [mark]
 	}, ...content];
-	const paragraph = content[index];
-	return content.map((block, position) => position === index ? cloneParagraphWithPropertySource(paragraph, { content: [mark, ...paragraph.content] }) : block);
+	return content.map((block, position) => position === index && block.type === "paragraph" ? cloneParagraphWithPropertySource(block, { content: [mark, ...block.content] }) : block);
 };
 function createNote(kind, id, content) {
 	return kind === "footnote" ? {
@@ -45,4 +46,4 @@ function createNote(kind, id, content) {
 	};
 }
 //#endregion
-export { createNote, noteReferenceMarkRun, withNoteReferenceMark };
+export { createNote, hasNoteReferenceMark, noteReferenceMarkRun, withNoteReferenceMark };

package/dist/docx/numberingParser.d.ts

@@ -81,7 +81,9 @@ declare function getBulletCharacter(level: document_d_exports.ListLevel): string
  * Check if a list level is a bullet (not numbered)
  */
 declare function isBulletLevel(level: document_d_exports.ListLevel): boolean;
+/** Whether a numbering definition uses a bullet marker rather than a numeric or hidden one. */
+declare const numberingLevelUsesBulletMarker: (level: Pick<document_d_exports.ListLevel, "numFmt"> | null | undefined) => boolean;
 /** Whether a numbering level reserves horizontal space for a visible marker. */
 declare const numberingLevelHasMarkerSlot: (level: Pick<document_d_exports.ListLevel, "numFmt">) => boolean;
 //#endregion
-export { NumberingMap, computeListRendering, counterFormatOf, createNumberingMap, customNumberFormatPadWidth, formatOoxmlCounter as formatNumber, getBulletCharacter, getCachedNumberingMap, isBulletLevel, markerAlignmentForLevel, markerFormattingFromLevel, numberingLevelHasMarkerSlot, padDecimal, parseNumbering, renderListMarker };
+export { NumberingMap, computeListRendering, counterFormatOf, createNumberingMap, customNumberFormatPadWidth, formatOoxmlCounter as formatNumber, getBulletCharacter, getCachedNumberingMap, isBulletLevel, markerAlignmentForLevel, markerFormattingFromLevel, numberingLevelHasMarkerSlot, numberingLevelUsesBulletMarker, padDecimal, parseNumbering, renderListMarker };

package/dist/docx/numberingParser.js

@@ -6,7 +6,20 @@ import { parseParagraphProperties } from "./paragraphProperties.js";
 import { LevelSuffixSchema, NumberFormatSchema, ParagraphAlignmentSchema, narrowEnum } from "./parserEnums.js";
 import { RUN_PROPERTY_OWNERS, parseRunProperties } from "./runParser.js";
 import { findChild, getAttribute, parseBooleanElement, parseNumericAttribute, parseOnOffAttribute, parseXmlDocument } from "./xmlParser.js";
+import { isNumberingLevel } from "@stll/docx-core/model";
 //#region src/docx/numberingParser.ts
+/**
+* Numbering/List Parser for DOCX
+*
+* Parses numbering.xml to extract:
+* - Abstract numbering definitions (templates with levels)
+* - Numbering instances (concrete references with optional overrides)
+*
+* OOXML Structure:
+* - w:abstractNum - Template definitions with 9 levels (0-8)
+* - w:num - Instances that reference abstractNum and can override levels
+* - w:lvl - Level definition with start, format, text pattern, etc.
+*/
 /** `w:abstractNum` reads its id; everything else it carries is the remainder's. */
 const MODELLED_ABSTRACT_NUM_ATTRIBUTES = /* @__PURE__ */ new Set(["abstractNumId"]);
 /** `w:lvl` reads the level it defines and Word's two template markers. */
@@ -117,7 +130,6 @@ function parseAbstractNumbering(element) {
 	return abstractNum;
 }
 /** ECMA-376 §17.9.1: a `w:abstractNum` defines levels 0 through 8 and no more. */
-const MAX_LIST_LEVEL = 8;
 const MULTI_LEVEL_TYPES = [
 	"hybridMultilevel",
 	"multilevel",
@@ -392,7 +404,7 @@ function createNumberingMap(definitions) {
 	return {
 		definitions,
 		getLevel(numId, ilvl) {
-			if (ilvl < 0 || ilvl > MAX_LIST_LEVEL) return null;
+			if (!isNumberingLevel(ilvl)) return null;
 			const num = numMap.get(numId);
 			if (!num) return null;
 			if (num.levelOverrides) {
@@ -524,7 +536,9 @@ function getBulletCharacter(level) {
 function isBulletLevel(level) {
 	return level.numFmt === "bullet" || level.numFmt === "none";
 }
+/** Whether a numbering definition uses a bullet marker rather than a numeric or hidden one. */
+const numberingLevelUsesBulletMarker = (level) => level?.numFmt === "bullet";
 /** Whether a numbering level reserves horizontal space for a visible marker. */
 const numberingLevelHasMarkerSlot = (level) => level.numFmt !== "none";
 //#endregion
-export { computeListRendering, counterFormatOf, createNumberingMap, customNumberFormatPadWidth, formatOoxmlCounter as formatNumber, getBulletCharacter, getCachedNumberingMap, isBulletLevel, markerAlignmentForLevel, markerFormattingFromLevel, numberingLevelHasMarkerSlot, padDecimal, parseNumbering, renderListMarker };
+export { computeListRendering, counterFormatOf, createNumberingMap, customNumberFormatPadWidth, formatOoxmlCounter as formatNumber, getBulletCharacter, getCachedNumberingMap, isBulletLevel, markerAlignmentForLevel, markerFormattingFromLevel, numberingLevelHasMarkerSlot, numberingLevelUsesBulletMarker, padDecimal, parseNumbering, renderListMarker };

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 };