@stll/folio-core 0.54.2 → 0.56.0

package/dist/controller/layoutPipeline.d.ts

@@ -1,9 +1,9 @@
 import { document_d_exports } from "../types/document.js";
 import { TemplatePreviewEntry, TemplatePreviewHiddenRange } from "../prosemirror/plugins/templatePreviewValues.js";
 import { ColumnLayout, FlowBlock, FootnoteContent, HeaderFooterContent, Layout, Measure, PageHeaderFooterRefs, PageMargins } from "../layout-engine/types.js";
+import { LayoutRunOptions } from "./layoutRunOptions.js";
 import { DisplayMode } from "../managers/EditorModeManager.js";
 import { LayoutSession } from "./layoutSession.js";
-import { LayoutRunOptions } from "./layoutRunOptions.js";
 import { HyphenationReadiness } from "./hyphenationReadiness.js";
 import { ConvertHeaderFooterOptions, HeaderFooterMetrics } from "../layout-bridge/convert/headerFooterLayout.js";
 import "../layout-engine/index.js";

package/dist/controller/layoutPipeline.js

@@ -244,6 +244,7 @@ function runLayoutPipelineMeasured(deps, state, options) {
 			const hfMeasureBlocks = (hfBlocks, hfWidth) => measureBlocks(hfBlocks, hfWidth, void 0, void 0, buildHeaderFooterFieldValues(hfBlocks, pageCount, hfClock, fieldInputs), { allowEndTabOverflow: true });
 			return {
 				...flowOpts.styles ? { styles: flowOpts.styles } : {},
+				...document?.package.numbering === void 0 ? {} : { numbering: document.package.numbering },
 				...flowOpts.defaultSize === void 0 ? {} : { defaultSize: flowOpts.defaultSize },
 				..._theme !== void 0 ? { theme: _theme } : {},
 				fontAlternates,
@@ -377,6 +378,7 @@ function runLayoutPipelineMeasured(deps, state, options) {
 			if (flowOpts.styles) noteOptions.styles = flowOpts.styles;
 			if (flowOpts.defaultSize !== void 0) noteOptions.defaultSize = flowOpts.defaultSize;
 			if (_theme !== void 0) noteOptions.theme = _theme;
+			if (document?.package.numbering !== void 0) noteOptions.numbering = document.package.numbering;
 			noteOptions.fontAlternates = fontAlternates;
 			if (defaultTabStop !== void 0) noteOptions.defaultTabStopTwips = defaultTabStop;
 			if (flowOpts.lineBreakRules) noteOptions.lineBreakRules = flowOpts.lineBreakRules;

package/dist/controller/noteEditorManager.d.ts

@@ -1,4 +1,6 @@
 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";
 import { DirectEditorProps, EditorView } from "prosemirror-view";
@@ -12,6 +14,9 @@ type NoteEditorTransaction = NoteStoryKey & {
 type NoteEditorManagerDeps = {
   createView?: ((mountNode: HTMLElement, props: DirectEditorProps) => EditorView) | undefined;
   getDocument: () => document_d_exports.Document | null;
+  getCanonicalApi?: (() => HiddenEditorApi | null) | undefined;
+  getExperimentalSession?: (() => "canonical" | undefined) | undefined;
+  onSessionRefusal?: ((reason: string, gap: CanonicalGap) => void) | undefined;
   getHost: () => HTMLElement | null;
   getPlugins?: (() => Plugin[]) | undefined;
   getStyles: () => document_d_exports.StyleDefinitions | null | undefined;

package/dist/controller/noteEditorManager.js

@@ -1,4 +1,6 @@
 import { isSeparatorEndnote, isSeparatorFootnote } from "../docx/footnoteParser.js";
+import { cloneDocumentWithParagraphPropertySources } from "../docx/paragraphPropertySource.js";
+import { visitDocxParagraphs, visitParagraphRuns } from "../docx/paragraphTraversal.js";
 import { proseDocToBlocks } from "../prosemirror/conversion/fromProseDoc.js";
 import { footnoteToProseDoc } from "../prosemirror/conversion/toProseDoc.js";
 import { ExtensionManager } from "../prosemirror/extensions/ExtensionManager.js";
@@ -9,7 +11,10 @@ import { createDocumentNumberingPlugin } from "../prosemirror/plugins/documentNu
 import { createDocumentStylesPlugin } from "../prosemirror/plugins/documentStyles.js";
 import { schema } from "../prosemirror/schema/index.js";
 import { storyListNumbering } from "../prosemirror/storyListNumbering.js";
-import { EditorState } from "prosemirror-state";
+import { CANONICAL_GAP, usesCanonicalSession } from "../types/canonicalCapabilities.js";
+import { createCanonicalStoryEditor } from "./canonicalStoryEditor.js";
+import { OP_STORIES } from "@stll/docx-core/ops";
+import { EditorState, TextSelection } from "prosemirror-state";
 import { EditorView } from "prosemirror-view";
 //#region src/controller/noteEditorManager.ts
 /** Framework-neutral lifecycle owner for editable footnote and endnote stories. */
@@ -28,12 +33,7 @@ const enumerateDocumentNoteStories = (document) => [...(document?.package.footno
 const resolveNote = (document, story) => {
 	return (story.kind === "footnote" ? document?.package.footnotes : document?.package.endnotes)?.find(({ id }) => id === story.noteId) ?? null;
 };
-const noteToProseDocument = (note, styles, theme) => {
-	const options = {};
-	if (styles) options.styles = styles;
-	if (theme !== void 0) options.theme = theme;
-	return footnoteToProseDoc(note.content, options);
-};
+const noteToProseDocument = (note, options) => footnoteToProseDoc(note.content, options);
 const buildInitialState = (document, styles, numbering, manager, externalPlugins) => {
 	return ensureBaseDirectionInState(ensureParaIdsInState(EditorState.create({
 		doc: document,
@@ -46,6 +46,31 @@ const buildInitialState = (document, styles, numbering, manager, externalPlugins
 		]
 	})));
 };
+/** Automatic note marks have no PM width; retain their authored runs on default writeback. */
+const preserveNoteMarkers = ({ source, projected }) => {
+	const marks = [];
+	visitDocxParagraphs({ documentBody: { content: source } }, (paragraph) => visitParagraphRuns(paragraph, (run) => {
+		const content = run.content.filter((child) => child.type === "noteMarker");
+		if (content.length > 0) marks.push({
+			...run,
+			content
+		});
+	}));
+	if (marks.length === 0) return projected;
+	let hasMarker = false;
+	visitDocxParagraphs({ documentBody: { content: projected } }, (paragraph) => visitParagraphRuns(paragraph, (run) => {
+		if (run.content.some((child) => child.type === "noteMarker")) hasMarker = true;
+	}));
+	if (hasMarker) return projected;
+	const owned = cloneDocumentWithParagraphPropertySources({ package: { document: { content: projected } } }).package.document.content;
+	const paragraphs = [];
+	visitDocxParagraphs({ documentBody: { content: owned } }, (paragraph) => {
+		paragraphs.push(paragraph);
+	});
+	const first = paragraphs.at(0);
+	if (first) first.content.unshift(...marks);
+	return owned;
+};
 const createNoteEditorManager = (deps) => {
 	const mounted = /* @__PURE__ */ new Map();
 	let active = null;
@@ -66,10 +91,16 @@ const createNoteEditorManager = (deps) => {
 	const sync = () => {
 		const host = deps.getHost();
 		if (!host) return;
-		const document = deps.getDocument();
+		if (usesCanonicalSession(deps.getExperimentalSession?.(), CANONICAL_GAP.secondaryStories) && !deps.getCanonicalApi?.()?.getCanonicalStoryProjection(OP_STORIES.MAIN)) return;
+		const document = usesCanonicalSession(deps.getExperimentalSession?.(), CANONICAL_GAP.secondaryStories) ? deps.getCanonicalApi?.()?.getCanonicalDocument() ?? deps.getDocument() : deps.getDocument();
 		const styles = deps.getStyles();
 		const theme = deps.getTheme();
 		const numbering = document?.package.numbering;
+		const proseOptions = {
+			...styles ? { styles } : {},
+			...theme !== void 0 ? { theme } : {},
+			...numbering !== void 0 ? { numbering } : {}
+		};
 		const externalPlugins = deps.getPlugins?.() ?? EMPTY_PLUGINS;
 		const wanted = new Map(enumerateDocumentNoteStories(document).map((story) => [storyMapKey(story), story]));
 		const activeKey = active ? storyMapKey(active) : null;
@@ -85,7 +116,33 @@ const createNoteEditorManager = (deps) => {
 			const existing = mounted.get(key);
 			if (existing) {
 				if (existing.mountNode.parentElement !== host) host.append(existing.mountNode);
-				const nextProseDocument = noteToProseDocument(note, styles, theme);
+				if (usesCanonicalSession(deps.getExperimentalSession?.(), CANONICAL_GAP.secondaryStories)) {
+					const projected = deps.getCanonicalApi?.()?.getCanonicalStoryProjection({
+						kind: storyKey.kind,
+						id: storyKey.noteId
+					});
+					if (projected && !existing.view.state.doc.eq(projected)) {
+						const transaction = existing.view.state.tr.replaceWith(0, existing.view.state.doc.content.size, projected.content);
+						const restored = deps.getCanonicalApi?.()?.getCanonicalStorySelection({
+							kind: storyKey.kind,
+							id: storyKey.noteId
+						});
+						const anchor = Math.min(existing.view.state.selection.anchor, projected.content.size);
+						transaction.setSelection(restored ? TextSelection.create(transaction.doc, restored.anchor, restored.head) : TextSelection.near(transaction.doc.resolve(anchor)));
+						transaction.setMeta("addToHistory", false);
+						existing.view.updateState(existing.view.state.apply(transaction));
+					}
+					existing.appliedNote = note;
+					existing.appliedContent = note.content;
+					existing.appliedProseDocument = existing.view.state.doc;
+					existing.appliedStyles = styles;
+					existing.appliedTheme = theme;
+					existing.appliedNumbering = numbering;
+					existing.appliedPlugins = externalPlugins;
+					existing.dirty = false;
+					continue;
+				}
+				const nextProseDocument = noteToProseDocument(note, proseOptions);
 				const contextIsCurrent = existing.appliedStyles === styles && existing.appliedTheme === theme && existing.appliedNumbering === numbering && existing.appliedPlugins === externalPlugins;
 				if ((existing.appliedNote === note && existing.appliedContent === note.content || existing.appliedProseDocument.eq(nextProseDocument)) && contextIsCurrent) {
 					existing.appliedNote = note;
@@ -111,10 +168,40 @@ const createNoteEditorManager = (deps) => {
 			mountNode.dataset["noteKind"] = storyKey.kind;
 			mountNode.dataset["noteId"] = String(storyKey.noteId);
 			host.append(mountNode);
-			const proseDocument = noteToProseDocument(note, styles, theme);
+			const proseDocument = noteToProseDocument(note, proseOptions);
+			const canonical = createCanonicalStoryEditor({
+				story: {
+					kind: storyKey.kind,
+					id: storyKey.noteId
+				},
+				getView: () => view,
+				getApi: () => deps.getCanonicalApi?.() ?? null,
+				enabled: () => usesCanonicalSession(deps.getExperimentalSession?.(), CANONICAL_GAP.secondaryStories),
+				onRefusal: deps.onSessionRefusal,
+				onSelectionChange: () => deps.onTransaction?.({
+					...storyKey,
+					view,
+					docChanged: false,
+					selectionChanged: true
+				})
+			});
+			const canonicalProjection = usesCanonicalSession(deps.getExperimentalSession?.(), CANONICAL_GAP.secondaryStories) ? deps.getCanonicalApi?.()?.getCanonicalStoryProjection({
+				kind: storyKey.kind,
+				id: storyKey.noteId
+			}) : null;
+			if (usesCanonicalSession(deps.getExperimentalSession?.(), CANONICAL_GAP.secondaryStories) && !canonicalProjection) {
+				manager.destroy();
+				mountNode.remove();
+				continue;
+			}
 			const view = (deps.createView ?? createEditorView)(mountNode, {
-				state: buildInitialState(proseDocument, styles, numbering, manager, externalPlugins),
+				...canonical.props,
+				state: canonicalProjection ? EditorState.create({
+					doc: canonicalProjection,
+					plugins: [createDocumentStylesPlugin(styles), createDocumentNumberingPlugin(numbering)]
+				}) : buildInitialState(proseDocument, styles, numbering, manager, externalPlugins),
 				dispatchTransaction(transaction) {
+					if (canonical.dispatch(transaction)) return;
 					view.updateState(view.state.apply(transaction));
 					const mountedStory = mounted.get(key);
 					if (mountedStory && transaction.docChanged) mountedStory.dirty = true;
@@ -160,6 +247,7 @@ const createNoteEditorManager = (deps) => {
 		getView: (story) => mounted.get(storyMapKey(story))?.view ?? null,
 		listStories: () => enumerateDocumentNoteStories(deps.getDocument()),
 		snapshotDocument: (document) => {
+			if (usesCanonicalSession(deps.getExperimentalSession?.(), CANONICAL_GAP.secondaryStories)) return deps.getCanonicalApi?.()?.getCanonicalDocument() ?? document;
 			let footnotes = document.package.footnotes;
 			let endnotes = document.package.endnotes;
 			let footnotesChanged = false;
@@ -169,6 +257,11 @@ const createNoteEditorManager = (deps) => {
 				if (!story.dirty) continue;
 				const lists = storyListNumbering(story.view.state, numbering);
 				numbering = lists.numbering;
+				const proseOptions = {
+					...story.appliedStyles ? { styles: story.appliedStyles } : {},
+					...story.appliedTheme !== void 0 ? { theme: story.appliedTheme } : {},
+					...numbering !== void 0 ? { numbering } : {}
+				};
 				if (story.note.kind === "footnote") {
 					const index = footnotes?.findIndex(({ id }) => id === story.note.noteId) ?? -1;
 					const current = index === -1 ? null : footnotes?.at(index);
@@ -179,12 +272,15 @@ const createNoteEditorManager = (deps) => {
 					}
 					const updated = {
 						...current,
-						content: proseDocToBlocks(lists.doc, current.content, document.package.styles)
+						content: preserveNoteMarkers({
+							source: current.content,
+							projected: proseDocToBlocks(lists.doc, current.content, document.package.styles)
+						})
 					};
 					footnotes[index] = updated;
 					story.appliedNote = updated;
 					story.appliedContent = updated.content;
-					story.appliedProseDocument = noteToProseDocument(updated, story.appliedStyles, story.appliedTheme);
+					story.appliedProseDocument = noteToProseDocument(updated, proseOptions);
 					continue;
 				}
 				const index = endnotes?.findIndex(({ id }) => id === story.note.noteId) ?? -1;
@@ -196,12 +292,15 @@ const createNoteEditorManager = (deps) => {
 				}
 				const updated = {
 					...current,
-					content: proseDocToBlocks(lists.doc, current.content, document.package.styles)
+					content: preserveNoteMarkers({
+						source: current.content,
+						projected: proseDocToBlocks(lists.doc, current.content, document.package.styles)
+					})
 				};
 				endnotes[index] = updated;
 				story.appliedNote = updated;
 				story.appliedContent = updated.content;
-				story.appliedProseDocument = noteToProseDocument(updated, story.appliedStyles, story.appliedTheme);
+				story.appliedProseDocument = noteToProseDocument(updated, proseOptions);
 			}
 			if (!footnotesChanged && !endnotesChanged) return document;
 			return {

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/attributeRemainder.js

@@ -55,6 +55,7 @@ const attributeRemainder = ({ element, modelled }) => {
 		const name = getLocalName(spelling);
 		if (modelled.has(name)) continue;
 		const namespace = resolveAttributeNamespaceUri(element, spelling);
+		if (namespace === OOXML_NAMESPACES.mc.uri && name === "Ignorable") continue;
 		if (namespace !== void 0 && !CANONICAL_PREFIX.has(namespace)) continue;
 		remainder.push({
 			...namespace === void 0 ? {} : { namespace },

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/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/canonicalSessionInput.d.ts

@@ -0,0 +1,11 @@
+import { DocxInput } from "../utils/docxInput.js";
+//#region src/docx/canonicalSessionInput.d.ts
+declare const CanonicalDocxInputError_base: import("better-result").TaggedErrorClass<"CanonicalDocxInputError">;
+declare class CanonicalDocxInputError extends CanonicalDocxInputError_base<{
+  message: string;
+  cause?: unknown;
+}> {}
+/** Canonical seeding supports plaintext packages; refuse encryption before ZIP normalization. */
+declare const prepareCanonicalDocxInput: (input: DocxInput) => Promise<import("better-result").Err<ArrayBuffer, CanonicalDocxInputError> | import("better-result").Ok<Uint8Array<ArrayBufferLike>, CanonicalDocxInputError>>;
+//#endregion
+export { CanonicalDocxInputError, prepareCanonicalDocxInput };

package/dist/docx/canonicalSessionInput.js

@@ -0,0 +1,27 @@
+import { toArrayBuffer } from "../utils/docxInput.js";
+import { DOCX_CONTAINER_TYPES, detectDocxContainerType } from "./encryption/containerFormat.js";
+import { ensureParaIds } from "./ensureParaIds.js";
+import { Result, TaggedError } from "better-result";
+//#region src/docx/canonicalSessionInput.ts
+var CanonicalDocxInputError = class extends TaggedError("CanonicalDocxInputError") {};
+/** Canonical seeding supports plaintext packages; refuse encryption before ZIP normalization. */
+const prepareCanonicalDocxInput = async (input) => {
+	const bytes = await Result.tryPromise({
+		try: () => toArrayBuffer(input),
+		catch: (cause) => new CanonicalDocxInputError({
+			message: "Cannot read canonical document bytes.",
+			cause
+		})
+	});
+	if (bytes.isErr()) return bytes;
+	if (detectDocxContainerType(bytes.value) === DOCX_CONTAINER_TYPES.CFB) return Result.err(new CanonicalDocxInputError({ message: "Password-protected documents are unavailable in the experimental canonical session." }));
+	return Result.tryPromise({
+		try: async () => (await ensureParaIds(bytes.value)).docx,
+		catch: (cause) => new CanonicalDocxInputError({
+			message: cause instanceof Error ? cause.message : "Canonical document normalization failed.",
+			cause
+		})
+	});
+};
+//#endregion
+export { CanonicalDocxInputError, prepareCanonicalDocxInput };

package/dist/docx/canonicalStoryRepack.d.ts

@@ -0,0 +1,10 @@
+import { document_d_exports } from "../types/document.js";
+//#region src/docx/canonicalStoryRepack.d.ts
+type CanonicalStoryRepackOptions<T> = {
+  document: document_d_exports.Document;
+  repack: () => Promise<T>;
+};
+/** 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 };