@stll/folio-core 0.55.0 → 0.57.0

package/dist/controller/noteEditorManager.d.ts

@@ -1,4 +1,5 @@
 import { document_d_exports } from "../types/document.js";
+import { CanonicalGap } from "../types/canonicalCapabilities.js";
 import { HiddenEditorApi } from "./hiddenEditorApi.js";
 import { NoteStoryKey } from "../types/editor-story.js";
 import { Plugin } from "prosemirror-state";
@@ -15,7 +16,7 @@ type NoteEditorManagerDeps = {
   getDocument: () => document_d_exports.Document | null;
   getCanonicalApi?: (() => HiddenEditorApi | null) | undefined;
   getExperimentalSession?: (() => "canonical" | undefined) | undefined;
-  onSessionRefusal?: ((reason: string) => void) | undefined;
+  onSessionRefusal?: ((reason: string, gap: CanonicalGap, error?: Error) => void) | undefined;
   getHost: () => HTMLElement | null;
   getPlugins?: (() => Plugin[]) | undefined;
   getStyles: () => document_d_exports.StyleDefinitions | null | undefined;

package/dist/controller/noteEditorManager.js

@@ -7,10 +7,13 @@ import { ExtensionManager } from "../prosemirror/extensions/ExtensionManager.js"
 import { createStarterKit } from "../prosemirror/extensions/StarterKit.js";
 import { ensureBaseDirectionInState } from "../prosemirror/extensions/features/AutoBidiDetectionExtension.js";
 import { ensureParaIdsInState } from "../prosemirror/extensions/features/ParaIdAllocatorExtension.js";
+import { noteReferenceTransactionIssue } from "../prosemirror/noteReferenceOccurrences.js";
 import { createDocumentNumberingPlugin } from "../prosemirror/plugins/documentNumbering.js";
-import { createDocumentStylesPlugin } from "../prosemirror/plugins/documentStyles.js";
+import { createDocumentStyleContextPlugin, createDocumentStylesPlugin } from "../prosemirror/plugins/documentStyles.js";
 import { schema } from "../prosemirror/schema/index.js";
 import { storyListNumbering } from "../prosemirror/storyListNumbering.js";
+import { CANONICAL_GAP, usesCanonicalSession } from "../types/canonicalCapabilities.js";
+import { CanonicalSessionError } from "./canonicalSession.js";
 import { createCanonicalStoryEditor } from "./canonicalStoryEditor.js";
 import { OP_STORIES } from "@stll/docx-core/ops";
 import { EditorState, TextSelection } from "prosemirror-state";
@@ -87,11 +90,12 @@ const createNoteEditorManager = (deps) => {
 		mounted.clear();
 		active = null;
 	};
+	const getOwnedDocument = () => usesCanonicalSession(deps.getExperimentalSession?.(), CANONICAL_GAP.authorityRouting) ? deps.getCanonicalApi?.()?.getCanonicalDocument() ?? null : deps.getDocument();
 	const sync = () => {
 		const host = deps.getHost();
 		if (!host) return;
-		if (deps.getExperimentalSession?.() === "canonical" && !deps.getCanonicalApi?.()?.getCanonicalStoryProjection(OP_STORIES.MAIN)) return;
-		const document = deps.getExperimentalSession?.() === "canonical" ? deps.getCanonicalApi?.()?.getCanonicalDocument() ?? deps.getDocument() : deps.getDocument();
+		if (usesCanonicalSession(deps.getExperimentalSession?.(), CANONICAL_GAP.authorityRouting) && !deps.getCanonicalApi?.()?.getCanonicalStoryProjection(OP_STORIES.MAIN)) return;
+		const document = getOwnedDocument();
 		const styles = deps.getStyles();
 		const theme = deps.getTheme();
 		const numbering = document?.package.numbering;
@@ -115,7 +119,7 @@ const createNoteEditorManager = (deps) => {
 			const existing = mounted.get(key);
 			if (existing) {
 				if (existing.mountNode.parentElement !== host) host.append(existing.mountNode);
-				if (deps.getExperimentalSession?.() === "canonical") {
+				if (usesCanonicalSession(deps.getExperimentalSession?.(), CANONICAL_GAP.authorityRouting)) {
 					const projected = deps.getCanonicalApi?.()?.getCanonicalStoryProjection({
 						kind: storyKey.kind,
 						id: storyKey.noteId
@@ -175,7 +179,7 @@ const createNoteEditorManager = (deps) => {
 				},
 				getView: () => view,
 				getApi: () => deps.getCanonicalApi?.() ?? null,
-				enabled: () => deps.getExperimentalSession?.() === "canonical",
+				enabled: () => usesCanonicalSession(deps.getExperimentalSession?.(), CANONICAL_GAP.authorityRouting),
 				onRefusal: deps.onSessionRefusal,
 				onSelectionChange: () => deps.onTransaction?.({
 					...storyKey,
@@ -184,11 +188,11 @@ const createNoteEditorManager = (deps) => {
 					selectionChanged: true
 				})
 			});
-			const canonicalProjection = deps.getExperimentalSession?.() === "canonical" ? deps.getCanonicalApi?.()?.getCanonicalStoryProjection({
+			const canonicalProjection = usesCanonicalSession(deps.getExperimentalSession?.(), CANONICAL_GAP.authorityRouting) ? deps.getCanonicalApi?.()?.getCanonicalStoryProjection({
 				kind: storyKey.kind,
 				id: storyKey.noteId
 			}) : null;
-			if (deps.getExperimentalSession?.() === "canonical" && !canonicalProjection) {
+			if (usesCanonicalSession(deps.getExperimentalSession?.(), CANONICAL_GAP.authorityRouting) && !canonicalProjection) {
 				manager.destroy();
 				mountNode.remove();
 				continue;
@@ -197,16 +201,20 @@ const createNoteEditorManager = (deps) => {
 				...canonical.props,
 				state: canonicalProjection ? EditorState.create({
 					doc: canonicalProjection,
-					plugins: [createDocumentStylesPlugin(styles), createDocumentNumberingPlugin(numbering)]
+					plugins: [createDocumentStyleContextPlugin(styles), createDocumentNumberingPlugin(numbering)]
 				}) : buildInitialState(proseDocument, styles, numbering, manager, externalPlugins),
 				dispatchTransaction(transaction) {
 					if (canonical.dispatch(transaction)) return;
-					view.updateState(view.state.apply(transaction));
+					const nextState = view.state.apply(transaction);
+					const docChanged = !nextState.doc.eq(view.state.doc);
+					view.updateState(nextState);
+					const noteIssue = noteReferenceTransactionIssue(transaction);
+					if (noteIssue) deps.onSessionRefusal?.(noteIssue.message, CANONICAL_GAP.dispatch, noteIssue);
 					const mountedStory = mounted.get(key);
-					if (mountedStory && transaction.docChanged) mountedStory.dirty = true;
+					if (mountedStory && docChanged) mountedStory.dirty = true;
 					deps.onTransaction?.({
 						...storyKey,
-						docChanged: transaction.docChanged,
+						docChanged,
 						selectionChanged: transaction.selectionSet,
 						view
 					});
@@ -244,9 +252,17 @@ const createNoteEditorManager = (deps) => {
 		destroy,
 		getActive: () => active,
 		getView: (story) => mounted.get(storyMapKey(story))?.view ?? null,
-		listStories: () => enumerateDocumentNoteStories(deps.getDocument()),
+		listStories: () => enumerateDocumentNoteStories(getOwnedDocument()),
 		snapshotDocument: (document) => {
-			if (deps.getExperimentalSession?.() === "canonical") return deps.getCanonicalApi?.()?.getCanonicalDocument() ?? document;
+			if (usesCanonicalSession(deps.getExperimentalSession?.(), CANONICAL_GAP.authorityRouting)) {
+				const canonical = deps.getCanonicalApi?.()?.getCanonicalDocument();
+				if (canonical) return canonical;
+				throw new CanonicalSessionError({
+					gap: CANONICAL_GAP.authorityRouting,
+					reason: "refused",
+					message: "Canonical story snapshot is unavailable."
+				});
+			}
 			let footnotes = document.package.footnotes;
 			let endnotes = document.package.endnotes;
 			let footnotesChanged = false;

package/dist/document-operations.d.ts

@@ -132,6 +132,7 @@ type FolioDocumentOperationIssue = {
   code: FolioAIEditSkippedOperation["reason"];
   retryable: boolean;
   recovery: FolioDocumentOperationRecovery;
+  canonicalRefusal?: FolioAIEditSkippedOperation["canonicalRefusal"];
   /** The skip's detail, when it has one; see {@link FolioAIEditSkippedOperation.message}. */
   message?: string;
 };
@@ -264,6 +265,12 @@ type FolioDocumentOperationResult = (FolioDocumentOperationResultBase & {
 declare const getFolioDocumentOperationIssues: (operations: readonly FolioDocumentOperation[], skipped: readonly FolioAIEditSkippedOperation[]) => FolioDocumentOperationIssue[];
 /** Build deterministic affected-target receipts from operations and their applied entries. */
 declare const getFolioDocumentOperationReceipts: (operations: readonly FolioDocumentOperation[], applied: readonly FolioAIEditAppliedOperation[]) => FolioDocumentOperationReceipt[];
+type GetFolioDocumentOperationReceiptsForStoryOptions = {
+  operations: readonly FolioDocumentOperation[];
+  applied: readonly FolioAIEditAppliedOperation[];
+  story: FolioDocumentOperationStory;
+};
+declare const getFolioDocumentOperationReceiptsForStory: ({ operations, applied, story }: GetFolioDocumentOperationReceiptsForStoryOptions) => FolioDocumentOperationReceipt[];
 type ApplyFolioDocumentOperationsOptions = {
   view: FolioAIEditView;
   snapshot: FolioAIEditSnapshot;
@@ -301,4 +308,4 @@ type ApplyFolioDocumentOperationsOptions = {
 };
 declare const applyFolioDocumentOperations: ({ view, snapshot, batch, story, author, createCommentId, createUndoHandle, revisionStamp, wordDiff, tableTemplates, replacementBackground, undefinedStyles }: ApplyFolioDocumentOperationsOptions) => FolioDocumentOperationResult;
 //#endregion
-export { ApplyFolioDocumentOperationsOptions, FOLIO_DOCUMENT_OPERATION_BATCH_MODES, FOLIO_DOCUMENT_OPERATION_BATCH_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION, FOLIO_DOCUMENT_OPERATION_KEYS_BY_TYPE, FOLIO_DOCUMENT_OPERATION_MODES, FOLIO_DOCUMENT_OPERATION_MODES_BY_TYPE, FOLIO_DOCUMENT_OPERATION_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_STORIES, FOLIO_DOCUMENT_OPERATION_TYPES, FOLIO_LINE_SPACING_RULE_VALUES, FOLIO_PAGE_BREAK_CLEAR_VALUES, FOLIO_PARAGRAPH_ALIGNMENT_VALUES, FolioDocumentOperation, FolioDocumentOperationAffectedTarget, FolioDocumentOperationBatch, FolioDocumentOperationBatchPrecondition, FolioDocumentOperationCapabilities, FolioDocumentOperationIssue, FolioDocumentOperationMode, FolioDocumentOperationPrecondition, FolioDocumentOperationQueuedOperation, FolioDocumentOperationReceipt, FolioDocumentOperationRecovery, FolioDocumentOperationResult, FolioDocumentOperationResultBase, FolioDocumentOperationStatus, FolioDocumentOperationStory, FolioDocumentOperationType, FolioDocumentOperationUndoFailureReason, FolioDocumentOperationUndoHandle, FolioDocumentOperationUndoResult, InvalidFolioDocumentOperationBatchError, UnsupportedFolioDocumentOperationVersionError, applyFolioDocumentOperations, assertSupportedFolioDocumentOperationVersion, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, isFolioDocumentOperationModeSupported, isSupportedFolioDocumentOperationVersion, parseFolioDocumentOperationBatch };
+export { ApplyFolioDocumentOperationsOptions, FOLIO_DOCUMENT_OPERATION_BATCH_MODES, FOLIO_DOCUMENT_OPERATION_BATCH_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION, FOLIO_DOCUMENT_OPERATION_KEYS_BY_TYPE, FOLIO_DOCUMENT_OPERATION_MODES, FOLIO_DOCUMENT_OPERATION_MODES_BY_TYPE, FOLIO_DOCUMENT_OPERATION_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_STORIES, FOLIO_DOCUMENT_OPERATION_TYPES, FOLIO_LINE_SPACING_RULE_VALUES, FOLIO_PAGE_BREAK_CLEAR_VALUES, FOLIO_PARAGRAPH_ALIGNMENT_VALUES, FolioDocumentOperation, FolioDocumentOperationAffectedTarget, FolioDocumentOperationBatch, FolioDocumentOperationBatchPrecondition, FolioDocumentOperationCapabilities, FolioDocumentOperationIssue, FolioDocumentOperationMode, FolioDocumentOperationPrecondition, FolioDocumentOperationQueuedOperation, FolioDocumentOperationReceipt, FolioDocumentOperationRecovery, FolioDocumentOperationResult, FolioDocumentOperationResultBase, FolioDocumentOperationStatus, FolioDocumentOperationStory, FolioDocumentOperationType, FolioDocumentOperationUndoFailureReason, FolioDocumentOperationUndoHandle, FolioDocumentOperationUndoResult, InvalidFolioDocumentOperationBatchError, UnsupportedFolioDocumentOperationVersionError, applyFolioDocumentOperations, assertSupportedFolioDocumentOperationVersion, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, getFolioDocumentOperationReceiptsForStory, isFolioDocumentOperationModeSupported, isSupportedFolioDocumentOperationVersion, parseFolioDocumentOperationBatch };

package/dist/document-operations.js

@@ -1072,22 +1072,24 @@ const recoveryByReason = {
 	missingStyle: "refreshDocument",
 	missingNumbering: "refreshDocument",
 	invalidResult: "refreshDocument",
-	pendingDeletion: "resolveTrackedChange"
+	pendingDeletion: "resolveTrackedChange",
+	pendingParagraphMarkDeletion: "resolveTrackedChange"
 };
 const getFolioDocumentOperationIssues = (operations, skipped) => {
 	const indexById = /* @__PURE__ */ new Map();
 	operations.forEach(({ id }, index) => {
 		indexById.set(id, index);
 	});
-	return skipped.map(({ id, reason, message }) => {
+	return skipped.map(({ id, reason, message, canonicalRefusal }) => {
 		const operationIndex = indexById.get(id) ?? -1;
 		return {
 			operationId: id,
 			operationIndex,
 			path: `$.operations[${operationIndex}]`,
 			code: reason,
-			retryable: reason !== "emptyOperation" && reason !== "noopOperation" && reason !== "pendingParagraphPropertyChange" && reason !== "pendingRunPropertyChange" && reason !== "pendingDeletion" && reason !== "payloadDoesNotFit" && reason !== "protectedReference" && reason !== "invalidResult",
+			retryable: reason !== "emptyOperation" && reason !== "noopOperation" && reason !== "pendingParagraphPropertyChange" && reason !== "pendingRunPropertyChange" && reason !== "pendingDeletion" && reason !== "pendingParagraphMarkDeletion" && reason !== "payloadDoesNotFit" && reason !== "protectedReference" && reason !== "invalidResult",
 			recovery: recoveryByReason[reason],
+			...canonicalRefusal === void 0 ? {} : { canonicalRefusal },
 			...message !== void 0 && { message }
 		};
 	});
@@ -1468,4 +1470,4 @@ const applyFolioDocumentOperations = ({ view, snapshot, batch, story = "main", a
 	};
 };
 //#endregion
-export { FOLIO_DOCUMENT_OPERATION_BATCH_MODES, FOLIO_DOCUMENT_OPERATION_BATCH_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION, FOLIO_DOCUMENT_OPERATION_KEYS_BY_TYPE, FOLIO_DOCUMENT_OPERATION_MODES, FOLIO_DOCUMENT_OPERATION_MODES_BY_TYPE, FOLIO_DOCUMENT_OPERATION_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_STORIES, FOLIO_DOCUMENT_OPERATION_TYPES, FOLIO_LINE_SPACING_RULE_VALUES, FOLIO_PAGE_BREAK_CLEAR_VALUES, FOLIO_PARAGRAPH_ALIGNMENT_VALUES, InvalidFolioDocumentOperationBatchError, UnsupportedFolioDocumentOperationVersionError, applyFolioDocumentOperations, assertSupportedFolioDocumentOperationVersion, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, isFolioDocumentOperationModeSupported, isSupportedFolioDocumentOperationVersion, parseFolioDocumentOperationBatch };
+export { FOLIO_DOCUMENT_OPERATION_BATCH_MODES, FOLIO_DOCUMENT_OPERATION_BATCH_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_CONTRACT_VERSION, FOLIO_DOCUMENT_OPERATION_KEYS_BY_TYPE, FOLIO_DOCUMENT_OPERATION_MODES, FOLIO_DOCUMENT_OPERATION_MODES_BY_TYPE, FOLIO_DOCUMENT_OPERATION_PRECONDITIONS, FOLIO_DOCUMENT_OPERATION_STORIES, FOLIO_DOCUMENT_OPERATION_TYPES, FOLIO_LINE_SPACING_RULE_VALUES, FOLIO_PAGE_BREAK_CLEAR_VALUES, FOLIO_PARAGRAPH_ALIGNMENT_VALUES, InvalidFolioDocumentOperationBatchError, UnsupportedFolioDocumentOperationVersionError, applyFolioDocumentOperations, assertSupportedFolioDocumentOperationVersion, getFolioDocumentOperationCapabilities, getFolioDocumentOperationIssues, getFolioDocumentOperationReceipts, getFolioDocumentOperationReceiptsForStory, isFolioDocumentOperationModeSupported, isSupportedFolioDocumentOperationVersion, parseFolioDocumentOperationBatch };

package/dist/docx/blockPlainText.d.ts

@@ -1,6 +1,6 @@
 import { document_d_exports } from "../types/document.js";
 //#region src/docx/blockPlainText.d.ts
-/** One entry per block, so callers can join or count lines as they need. */
+/** One entry per accepted block; deleted breaks and table structure resolve together. */
 declare const collectBlockTexts: (blocks: readonly document_d_exports.BlockContent[]) => string[];
 declare const blockPlainText: (blocks: readonly document_d_exports.BlockContent[]) => string;
 //#endregion

package/dist/docx/blockPlainText.js

@@ -1,3 +1,4 @@
+import { projectAcceptedBlocks } from "../internal/acceptedBlockProjection.js";
 import { ALT_CHUNK_READER_DIAGNOSTIC, isAltChunkMarkup } from "./altChunk.js";
 import { OPAQUE_REVISION_CARRIER_READER_DIAGNOSTIC, isOpaqueNestedRowMarkup, opaqueRevisionCarrierName } from "./opaqueCarrier.js";
 import { getParagraphText } from "./paragraphParser.js";
@@ -18,7 +19,7 @@ import { panic } from "better-result";
 * everything below block level and reads the accepted tracked-change view.
 */
 /** One entry per block, so callers can join or count lines as they need. */
-const collectBlockTexts = (blocks) => {
+const collectResolvedBlockTexts = (blocks) => {
 	const texts = [];
 	for (const block of blocks) switch (block.type) {
 		case "paragraph":
@@ -27,12 +28,12 @@ const collectBlockTexts = (blocks) => {
 		case "table":
 			for (const row of block.rows) {
 				if (row.formatting?.hidden === true) continue;
-				texts.push(row.cells.map((cell) => collectBlockTexts(cell.content).join("\n")).join("	"));
+				texts.push(row.cells.map((cell) => collectResolvedBlockTexts(cell.content).join("\n")).join("	"));
 			}
 			break;
 		case "blockSdt":
 		case "blockCustomXml":
-			texts.push(...collectBlockTexts(block.content));
+			texts.push(...collectResolvedBlockTexts(block.content));
 			break;
 		case "preservedBlock":
 			if (isAltChunkMarkup(block.xml)) texts.push(block.readerText === void 0 ? ALT_CHUNK_READER_DIAGNOSTIC : `${ALT_CHUNK_READER_DIAGNOSTIC}\n${block.readerText}`);
@@ -45,6 +46,13 @@ const collectBlockTexts = (blocks) => {
 	}
 	return texts;
 };
+/** One entry per accepted block; deleted breaks and table structure resolve together. */
+const collectBlockTexts = (blocks) => {
+	const projection = projectAcceptedBlocks(blocks, void 0);
+	const texts = collectResolvedBlockTexts(projection?.blocks ?? blocks);
+	if (projection?.completeness === "partial") texts.push("[Unresolved tracked structural changes]");
+	return texts;
+};
 const blockPlainText = (blocks) => collectBlockTexts(blocks).join("\n");
 //#endregion
 export { blockPlainText, collectBlockTexts };

package/dist/docx/builtInStyles.js

@@ -1,5 +1,5 @@
 import { BUILT_IN_DEFAULT_PARAGRAPH_STYLE_NAME, resolveDefaultParagraphStyle } from "./defaultParagraphStyle.js";
-import { headingLevelOf } from "@stll/docx-core/model";
+import { headingLevelOf, headingOutlineLevel } from "@stll/docx-core/model";
 //#region src/docx/builtInStyles.ts
 /**
 * Whether a paragraph is a heading, and of which level, without reading the
@@ -134,20 +134,27 @@ const headingOutlineLevelFromStyleName = (name) => {
 const CANONICAL_BY_NORMALIZED = new Map(Object.values(BUILT_IN_STYLE_NAME).map((name) => [normalizeStyleName(name), name]));
 const asBuiltInName = (normalized) => CANONICAL_BY_NORMALIZED.get(normalized);
 /**
-* The outline level a style chain sets: the style's own `w:outlineLvl`, else
-* the nearest ancestor's (17.7.1). `styleParser` already flattens `w:basedOn`
-* for a parsed package, but a style set built in memory carries the raw chain,
-* so the walk keeps both kinds of input on the same answer. `seen` guards the
-* circular `basedOn` a malformed package can contain.
+* The effective outline contribution of a style chain: the nearest explicit
+* `w:outlineLvl` wins across the chain; only when none exists does the nearest
+* built-in heading name supply its implicit level. `styleParser` already flattens
+* `w:basedOn` for a parsed package, but a style set built in memory carries the
+* raw chain, so the walk keeps both kinds of input on the same answer. `seen`
+* guards the circular `basedOn` a malformed package can contain.
 */
 const inheritedOutlineLevel = (style, styleById) => {
 	const seen = /* @__PURE__ */ new Set();
 	let current = style;
+	let nearestImplicitHeadingLevel;
 	while (current && !seen.has(current.styleId)) {
 		seen.add(current.styleId);
 		if (current.pPr?.outlineLevel !== void 0) return current.pPr.outlineLevel;
+		if (nearestImplicitHeadingLevel === void 0) {
+			const namedLevel = headingOutlineLevelFromStyleName(current.name);
+			if (namedLevel !== void 0) nearestImplicitHeadingLevel = headingOutlineLevel(namedLevel);
+		}
 		current = current.basedOn === void 0 ? void 0 : styleById.get(current.basedOn);
 	}
+	return nearestImplicitHeadingLevel;
 };
 /** The level a heading style is indexed under, or undefined if it is not one. */
 const headingLevelForIndex = (namedLevel, statedLevel) => {

package/dist/docx/canonicalResourceSave.d.ts

@@ -0,0 +1,16 @@
+import { document_d_exports } from "../types/document.js";
+import { CANONICAL_GAP } from "../types/canonicalCapabilities.js";
+import { SaveDiagnostic } from "./saveDiagnostics.js";
+//#region src/docx/canonicalResourceSave.d.ts
+declare const CanonicalResourceSaveRefusalError_base: import("better-result").TaggedErrorClass<"CanonicalResourceSaveRefusalError">;
+declare class CanonicalResourceSaveRefusalError extends CanonicalResourceSaveRefusalError_base<{
+  message: string;
+  gap: typeof CANONICAL_GAP.resourceReplacement;
+  diagnostic: Extract<SaveDiagnostic, {
+    type: "canonicalResourceReplacement";
+  }>;
+}> {}
+/** Full and selective package writers preserve existing style/media source entries. */
+declare const canonicalResourceReplacementOf: (document: document_d_exports.Document) => string | undefined;
+//#endregion
+export { CanonicalResourceSaveRefusalError, canonicalResourceReplacementOf };

package/dist/docx/canonicalResourceSave.js

@@ -0,0 +1,27 @@
+import { canonicalJson } from "../utils/canonicalJson.js";
+import { getDocumentSourceBaseline } from "./headerFooterVerbatim.js";
+import { TaggedError } from "better-result";
+//#region src/docx/canonicalResourceSave.ts
+var CanonicalResourceSaveRefusalError = class extends TaggedError("CanonicalResourceSaveRefusalError") {};
+/** Full and selective package writers preserve existing style/media source entries. */
+const canonicalResourceReplacementOf = (document) => {
+	const source = getDocumentSourceBaseline(document);
+	if (source.type !== "captured" || !document.originalBuffer) return void 0;
+	const baseline = source.resourceStyles;
+	const current = document.package.styles;
+	if (baseline) {
+		const { styles: sourceStyles, ...sourceDefaults } = baseline;
+		const { styles: currentStyles, ...currentDefaults } = current ?? { styles: [] };
+		const currentById = new Map(currentStyles.map((style) => [style.styleId, style]));
+		if (canonicalJson(sourceDefaults) !== canonicalJson(currentDefaults) || sourceStyles.some((style) => canonicalJson(style) !== canonicalJson(currentById.get(style.styleId)))) return "word/styles.xml";
+	}
+	for (const [path, media] of source.resourceMedia) {
+		const currentMedia = document.package.media?.get(path);
+		if (!currentMedia || media.mimeType !== currentMedia.mimeType) return path;
+		const sourceBytes = new Uint8Array(media.data);
+		const currentBytes = new Uint8Array(currentMedia.data);
+		if (sourceBytes.length !== currentBytes.length || sourceBytes.some((byte, index) => byte !== currentBytes[index])) return path;
+	}
+};
+//#endregion
+export { CanonicalResourceSaveRefusalError, canonicalResourceReplacementOf };

package/dist/docx/canonicalSave.d.ts

@@ -0,0 +1,29 @@
+import { CANONICAL_GAP } from "../types/canonicalCapabilities.js";
+import { SaveDiagnostic } from "./saveDiagnostics.js";
+import { CanonicalSaveSnapshot } from "../types/canonicalSave.js";
+import { FolioGetDocxOptions } from "../types/docxSerialization.js";
+import { TripwireResult } from "./selectiveSaveTripwire.js";
+import { FolioSelectiveSaveFlags } from "./selectiveSaveFlags.js";
+//#region src/docx/canonicalSave.d.ts
+declare const CanonicalSaveDiagnosticError_base: import("better-result").TaggedErrorClass<"CanonicalSaveDiagnosticError">;
+/** Forward a fidelity fallback through the adapters' existing error channel. */
+declare class CanonicalSaveDiagnosticError extends CanonicalSaveDiagnosticError_base<{
+  message: string;
+  gap: typeof CANONICAL_GAP.save;
+  diagnostic: SaveDiagnostic;
+}> {}
+type SerializeCanonicalSaveOptions = {
+  snapshot: CanonicalSaveSnapshot;
+  options?: FolioGetDocxOptions | undefined;
+  featureFlags?: FolioSelectiveSaveFlags | undefined;
+};
+/** Model and change signals come from one committed snapshot, never from PM. */
+declare const serializeCanonicalSave: ({ snapshot, options, featureFlags }: SerializeCanonicalSaveOptions) => Promise<{
+  buffer: ArrayBuffer;
+  document: import("@stll/docx-core").Document;
+  version: number;
+  diagnostics: SaveDiagnostic[];
+  tripwireResult: TripwireResult | null;
+}>;
+//#endregion
+export { CanonicalSaveDiagnosticError, serializeCanonicalSave };

package/dist/docx/canonicalSave.js

@@ -0,0 +1,101 @@
+import { withoutUnreferencedNotes } from "../prosemirror/noteReferenceReview.js";
+import { CANONICAL_GAP } from "../types/canonicalCapabilities.js";
+import { FOLIO_DOCX_SERIALIZATION_MODE } from "../types/docxSerialization.js";
+import { CanonicalResourceSaveRefusalError, canonicalResourceReplacementOf } from "./canonicalResourceSave.js";
+import { repackWithCanonicalStoryRemovals } from "./canonicalStoryRepack.js";
+import { getDocumentSourceBaseline } from "./headerFooterVerbatim.js";
+import { resolveSelectiveSaveFlags } from "./selectiveSaveFlags.js";
+import { Result, TaggedError } from "better-result";
+//#region src/docx/canonicalSave.ts
+/** Forward a fidelity fallback through the adapters' existing error channel. */
+var CanonicalSaveDiagnosticError = class extends TaggedError("CanonicalSaveDiagnosticError") {};
+/** Model and change signals come from one committed snapshot, never from PM. */
+const serializeCanonicalSave = async ({ snapshot, options, featureFlags }) => {
+	const document = withoutUnreferencedNotes(snapshot.document);
+	const replacementPart = snapshot.structure === "changed" ? canonicalResourceReplacementOf(document) : void 0;
+	if (replacementPart) {
+		const diagnostic = {
+			type: "canonicalResourceReplacement",
+			gap: CANONICAL_GAP.resourceReplacement,
+			part: replacementPart
+		};
+		options?.onDiagnostic?.(diagnostic);
+		throw new CanonicalResourceSaveRefusalError({
+			message: "Canonical save cannot preserve this package resource replacement.",
+			gap: CANONICAL_GAP.resourceReplacement,
+			diagnostic
+		});
+	}
+	const baseline = document.originalBuffer;
+	const flags = resolveSelectiveSaveFlags(featureFlags);
+	const diagnostics = [];
+	const onDiagnostic = (diagnostic) => {
+		if (!diagnostics.some((existing) => existing.type === diagnostic.type && existing.part === diagnostic.part)) diagnostics.push(diagnostic);
+	};
+	const { repackDocx, createDocx } = await import("./rezip.js");
+	const useSelective = flags.selectiveSave && options?.mode !== FOLIO_DOCX_SERIALIZATION_MODE.full;
+	let selectiveBuffer = null;
+	if (baseline && (useSelective || flags.selectiveSaveTripwire)) {
+		const { attemptSelectiveSave } = await import("./selectiveSave.js");
+		selectiveBuffer = await attemptSelectiveSave(document, baseline, {
+			bodyAuthority: "canonical",
+			changedParaIds: new Set(snapshot.changedBlockIds),
+			structuralChange: snapshot.structure === "changed",
+			hasUntrackedChanges: false,
+			maxBytes: flags.selectiveSaveMaxBytes,
+			onDiagnostic
+		});
+		if (useSelective && !selectiveBuffer) onDiagnostic({
+			type: "selectiveSaveRefused",
+			part: "word/document.xml"
+		});
+	}
+	const repack = () => {
+		if (baseline && getDocumentSourceBaseline(document).type === "missing") onDiagnostic({
+			type: "sourceReplayUnavailable",
+			part: "word/document.xml"
+		});
+		return baseline ? repackWithCanonicalStoryRemovals({
+			document,
+			repack: () => repackDocx(document, {
+				onDiagnostic,
+				bodyAuthority: "canonical"
+			})
+		}) : createDocx(document, {
+			onDiagnostic,
+			bodyAuthority: "canonical"
+		});
+	};
+	let buffer = useSelective ? selectiveBuffer : null;
+	let fullBuffer = null;
+	if (!buffer) {
+		fullBuffer = await repack();
+		buffer = fullBuffer;
+	} else if (flags.selectiveSaveTripwire) {
+		const full = await Result.tryPromise({
+			try: repack,
+			catch: (error) => error
+		});
+		if (full.isOk()) fullBuffer = full.value;
+	}
+	let tripwireResult = null;
+	if (flags.selectiveSaveTripwire && fullBuffer) {
+		const { compareSelectiveVsFull } = await import("./selectiveSaveTripwire.js");
+		const capturedFullBuffer = fullBuffer;
+		const compared = await Result.tryPromise({
+			try: () => compareSelectiveVsFull(selectiveBuffer, capturedFullBuffer),
+			catch: (error) => error
+		});
+		if (compared.isOk()) tripwireResult = compared.value;
+	}
+	for (const diagnostic of diagnostics) options?.onDiagnostic?.(diagnostic);
+	return {
+		buffer,
+		document,
+		version: snapshot.version,
+		diagnostics,
+		tripwireResult
+	};
+};
+//#endregion
+export { CanonicalSaveDiagnosticError, serializeCanonicalSave };

package/dist/docx/canonicalStoryRepack.d.ts

@@ -4,7 +4,7 @@ type CanonicalStoryRepackOptions<T> = {
   document: document_d_exports.Document;
   repack: () => Promise<T>;
 };
-/** Authorize only references missing from the committed canonical snapshot, with exact multiplicity. */
+/** Authorize exact canonical section removals and references missing from the committed snapshot. */
 declare const repackWithCanonicalStoryRemovals: <T>({ document, repack }: CanonicalStoryRepackOptions<T>) => Promise<T>;
 //#endregion
 export { repackWithCanonicalStoryRemovals };

package/dist/docx/canonicalStoryRepack.js

@@ -1,17 +1,28 @@
+import { withTrackedSectionEndpointRemoval } from "../internal/sectionEndpointResolution.js";
 import { withSectionReferenceResolution } from "../internal/sectionReferenceResolution.js";
 import { readDocumentSectionFacts } from "./documentSectionFacts.js";
+import { parseDocx } from "./parser.js";
+import { assertSectionCarriersMatchModel } from "./rezip.js";
 import { serializeDocument } from "./serializer/documentSerializer.js";
 import JSZip from "jszip";
 //#region src/docx/canonicalStoryRepack.ts
 /** Canonical snapshots own explicit section references; the PM projection does not. */
 const referenceKey = ({ element, type, rId }) => `${element}:${type}:${rId}`;
-/** Authorize only references missing from the committed canonical snapshot, with exact multiplicity. */
+const xmlFingerprint = async (xml) => {
+	const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(xml));
+	let fingerprint = "";
+	for (const byte of new Uint8Array(digest)) fingerprint += byte.toString(16).padStart(2, "0");
+	return fingerprint;
+};
+/** Authorize exact canonical section removals and references missing from the committed snapshot. */
 const repackWithCanonicalStoryRemovals = async ({ document, repack }) => {
-	if (!document.originalBuffer) return repack();
-	const xml = await (await JSZip.loadAsync(document.originalBuffer)).file("word/document.xml")?.async("text");
+	const originalBuffer = document.originalBuffer;
+	if (!originalBuffer) return repack();
+	const xml = await (await JSZip.loadAsync(originalBuffer)).file("word/document.xml")?.async("text");
 	if (!xml) return repack();
 	const before = readDocumentSectionFacts(xml);
-	const after = readDocumentSectionFacts(serializeDocument(document));
+	const serializedXml = serializeDocument(document);
+	const after = readDocumentSectionFacts(serializedXml);
 	const remaining = /* @__PURE__ */ new Map();
 	for (const reference of after.headerFooterReferences) {
 		const key = referenceKey(reference);
@@ -34,7 +45,29 @@ const repackWithCanonicalStoryRemovals = async ({ document, repack }) => {
 	return withSectionReferenceResolution({
 		document,
 		removedReferences,
-		repack
+		repack: async () => {
+			if (after.sectionCount >= before.sectionCount) return repack();
+			const baseline = await parseDocx(originalBuffer, { preloadFonts: false });
+			const baselineXml = serializeDocument(baseline);
+			const baselineFacts = readDocumentSectionFacts(baselineXml);
+			if (baselineFacts.sectionCount !== before.sectionCount) return repack();
+			assertSectionCarriersMatchModel({
+				doc: baseline,
+				serializedSectionCount: baselineFacts.sectionCount
+			});
+			return withTrackedSectionEndpointRemoval({
+				document,
+				resolution: {
+					type: "tracked-section-endpoint-removal",
+					sourceParagraphEndpointCount: before.sectionCount,
+					expectedParagraphEndpointCount: after.sectionCount,
+					sourceEndpointFingerprint: await xmlFingerprint(baselineXml),
+					expectedEndpointFingerprint: await xmlFingerprint(serializedXml),
+					removedReferences
+				},
+				repack
+			});
+		}
 	});
 };
 //#endregion

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

@@ -35,9 +35,11 @@ declare const CONTAINER_CHILDREN: {
   readonly "w:fldSimple": readonly ["bdo", "bookmarkEnd", "bookmarkStart", "commentRangeEnd", "commentRangeStart", "customXml", "customXmlDelRangeEnd", "customXmlDelRangeStart", "customXmlInsRangeEnd", "customXmlInsRangeStart", "customXmlMoveFromRangeEnd", "customXmlMoveFromRangeStart", "customXmlMoveToRangeEnd", "customXmlMoveToRangeStart", "del", "dir", "fldData", "fldSimple", "hyperlink", "ins", "moveFrom", "moveFromRangeEnd", "moveFromRangeStart", "moveTo", "moveToRangeEnd", "moveToRangeStart", "permEnd", "permStart", "proofErr", "r", "sdt", "smartTag", "subDoc"];
   readonly "block-content": readonly ["altChunk", "bookmarkEnd", "bookmarkStart", "commentRangeEnd", "commentRangeStart", "customXml", "customXmlDelRangeEnd", "customXmlDelRangeStart", "customXmlInsRangeEnd", "customXmlInsRangeStart", "customXmlMoveFromRangeEnd", "customXmlMoveFromRangeStart", "customXmlMoveToRangeEnd", "customXmlMoveToRangeStart", "del", "ins", "moveFrom", "moveFromRangeEnd", "moveFromRangeStart", "moveTo", "moveToRangeEnd", "moveToRangeStart", "p", "permEnd", "permStart", "proofErr", "sdt", "sectPr", "tbl", "tcPr"];
 };
+/** WordprocessingML children permitted directly inside CT_RunTrackChange. */
+declare const TRACKED_RUN_WORDPROCESSING_CHILDREN: readonly ["bdo", "bookmarkEnd", "bookmarkStart", "commentRangeEnd", "commentRangeStart", "customXml", "customXmlDelRangeEnd", "customXmlDelRangeStart", "customXmlInsRangeEnd", "customXmlInsRangeStart", "customXmlMoveFromRangeEnd", "customXmlMoveFromRangeStart", "customXmlMoveToRangeEnd", "customXmlMoveToRangeStart", "del", "dir", "ins", "moveFrom", "moveFromRangeEnd", "moveFromRangeStart", "moveTo", "moveToRangeEnd", "moveToRangeStart", "permEnd", "permStart", "proofErr", "r", "sdt", "smartTag"];
 /** A container the shared child dispatcher covers. */
 type DispatchedContainer = keyof typeof CONTAINER_CHILDREN;
 /** Every child name the schema declares for `Container`. */
 type DeclaredChild<Container extends DispatchedContainer> = (typeof CONTAINER_CHILDREN)[Container][number];
 //#endregion
-export { CONTAINER_CHILDREN, DeclaredChild, DispatchedContainer };
+export { CONTAINER_CHILDREN, DeclaredChild, DispatchedContainer, TRACKED_RUN_WORDPROCESSING_CHILDREN };

package/dist/docx/containerChildren.gen.js

@@ -260,5 +260,37 @@ const CONTAINER_CHILDREN = {
 	],
 	...SEQUENCE_CHILDREN
 };
+/** WordprocessingML children permitted directly inside CT_RunTrackChange. */
+const TRACKED_RUN_WORDPROCESSING_CHILDREN = [
+	"bdo",
+	"bookmarkEnd",
+	"bookmarkStart",
+	"commentRangeEnd",
+	"commentRangeStart",
+	"customXml",
+	"customXmlDelRangeEnd",
+	"customXmlDelRangeStart",
+	"customXmlInsRangeEnd",
+	"customXmlInsRangeStart",
+	"customXmlMoveFromRangeEnd",
+	"customXmlMoveFromRangeStart",
+	"customXmlMoveToRangeEnd",
+	"customXmlMoveToRangeStart",
+	"del",
+	"dir",
+	"ins",
+	"moveFrom",
+	"moveFromRangeEnd",
+	"moveFromRangeStart",
+	"moveTo",
+	"moveToRangeEnd",
+	"moveToRangeStart",
+	"permEnd",
+	"permStart",
+	"proofErr",
+	"r",
+	"sdt",
+	"smartTag"
+];
 //#endregion
-export { CONTAINER_CHILDREN };
+export { CONTAINER_CHILDREN, TRACKED_RUN_WORDPROCESSING_CHILDREN };

package/dist/docx/documentParser.d.ts

@@ -54,22 +54,10 @@ declare function getAllParagraphs(body: document_d_exports.DocumentBody): docume
  * Get all tables from document body
  */
 declare function getAllTables(body: document_d_exports.DocumentBody): document_d_exports.Table[];
-/**
- * Get plain text from entire document body
- */
-declare function getDocumentText(body: document_d_exports.DocumentBody): string;
 /**
  * Count total paragraphs in document
  */
 declare function getParagraphCount(body: document_d_exports.DocumentBody): number;
-/**
- * Count total words in document (approximate)
- */
-declare function getWordCount(body: document_d_exports.DocumentBody): number;
-/**
- * Count total characters in document
- */
-declare function getCharacterCount(body: document_d_exports.DocumentBody): number;
 /**
  * Get section count
  */
@@ -79,4 +67,4 @@ declare function getSectionCount(body: document_d_exports.DocumentBody): number;
  */
 declare function hasTemplateVariables(body: document_d_exports.DocumentBody): boolean;
 //#endregion
-export { extractAllTemplateVariables, extractTemplateVariables, getAllParagraphs, getAllTables, getCharacterCount, getDocumentText, getParagraphCount, getSectionCount, getWordCount, hasTemplateVariables, parseDocumentBody, parseDocumentBodyTree };
+export { extractAllTemplateVariables, extractTemplateVariables, getAllParagraphs, getAllTables, getParagraphCount, getSectionCount, hasTemplateVariables, parseDocumentBody, parseDocumentBodyTree };