@stll/folio-core 0.54.2 → 0.55.0

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,9 @@ 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 { 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 +32,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 +45,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 +90,16 @@ const createNoteEditorManager = (deps) => {
 	const sync = () => {
 		const host = deps.getHost();
 		if (!host) return;
-		const document = deps.getDocument();
+		if (deps.getExperimentalSession?.() === "canonical" && !deps.getCanonicalApi?.()?.getCanonicalStoryProjection(OP_STORIES.MAIN)) return;
+		const document = deps.getExperimentalSession?.() === "canonical" ? 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 +115,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 (deps.getExperimentalSession?.() === "canonical") {
+					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 +167,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: () => deps.getExperimentalSession?.() === "canonical",
+				onRefusal: deps.onSessionRefusal,
+				onSelectionChange: () => deps.onTransaction?.({
+					...storyKey,
+					view,
+					docChanged: false,
+					selectionChanged: true
+				})
+			});
+			const canonicalProjection = deps.getExperimentalSession?.() === "canonical" ? deps.getCanonicalApi?.()?.getCanonicalStoryProjection({
+				kind: storyKey.kind,
+				id: storyKey.noteId
+			}) : null;
+			if (deps.getExperimentalSession?.() === "canonical" && !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 +246,7 @@ const createNoteEditorManager = (deps) => {
 		getView: (story) => mounted.get(storyMapKey(story))?.view ?? null,
 		listStories: () => enumerateDocumentNoteStories(deps.getDocument()),
 		snapshotDocument: (document) => {
+			if (deps.getExperimentalSession?.() === "canonical") return deps.getCanonicalApi?.()?.getCanonicalDocument() ?? document;
 			let footnotes = document.package.footnotes;
 			let endnotes = document.package.endnotes;
 			let footnotesChanged = false;
@@ -169,6 +256,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 +271,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 +291,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/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/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 only references missing from the committed canonical snapshot, with exact multiplicity. */
+declare const repackWithCanonicalStoryRemovals: <T>({ document, repack }: CanonicalStoryRepackOptions<T>) => Promise<T>;
+//#endregion
+export { repackWithCanonicalStoryRemovals };

package/dist/docx/canonicalStoryRepack.js

@@ -0,0 +1,41 @@
+import { withSectionReferenceResolution } from "../internal/sectionReferenceResolution.js";
+import { readDocumentSectionFacts } from "./documentSectionFacts.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 repackWithCanonicalStoryRemovals = async ({ document, repack }) => {
+	if (!document.originalBuffer) return repack();
+	const xml = await (await JSZip.loadAsync(document.originalBuffer)).file("word/document.xml")?.async("text");
+	if (!xml) return repack();
+	const before = readDocumentSectionFacts(xml);
+	const after = readDocumentSectionFacts(serializeDocument(document));
+	const remaining = /* @__PURE__ */ new Map();
+	for (const reference of after.headerFooterReferences) {
+		const key = referenceKey(reference);
+		remaining.set(key, (remaining.get(key) ?? 0) + 1);
+	}
+	const removedReferences = [];
+	for (const reference of before.headerFooterReferences) {
+		const key = referenceKey(reference);
+		const count = remaining.get(key) ?? 0;
+		if (count > 0) {
+			remaining.set(key, count - 1);
+			continue;
+		}
+		removedReferences.push({
+			part: reference.element === "headerReference" ? "header" : "footer",
+			type: reference.type,
+			relationshipId: reference.rId
+		});
+	}
+	return withSectionReferenceResolution({
+		document,
+		removedReferences,
+		repack
+	});
+};
+//#endregion
+export { repackWithCanonicalStoryRemovals };

package/dist/docx/contentTypeRegistry.d.ts

@@ -0,0 +1,8 @@
+//#region src/docx/contentTypeRegistry.d.ts
+type ContentTypePart = {
+  partName: string;
+  contentType: string;
+};
+declare const registerContentTypeParts: (xml: string, parts: readonly ContentTypePart[]) => string;
+//#endregion
+export { registerContentTypeParts };

package/dist/docx/contentTypeRegistry.js

@@ -0,0 +1,64 @@
+import { resolvePackageRelationshipTarget } from "./packageParts.js";
+import { spliceXml } from "./selectiveXmlPatch.js";
+import { getAttribute, getLocalName, getNamespacePrefix, getNamespaceUri, parseXmlDocument } from "./xmlParser.js";
+import { panic } from "better-result";
+import { escapeXmlAttribute } from "@stll/docx-core";
+import { OOXML_NS } from "@stll/docx-utils";
+//#region src/docx/contentTypeRegistry.ts
+/** Register a package part without rewriting authored content-type entries. */
+const registerContentTypeParts = (xml, parts) => {
+	const root = parseXmlDocument(xml);
+	if (root?.name === void 0 || getLocalName(root.name) !== "Types" || getNamespaceUri(root) !== OOXML_NS.ct) return panic("The package content-type registry must have a valid Types root.");
+	const overrides = /* @__PURE__ */ new Map();
+	const defaults = /* @__PURE__ */ new Map();
+	for (const element of root.elements ?? []) {
+		if (getNamespaceUri(element) !== OOXML_NS.ct) continue;
+		const type = getAttribute(element, null, "ContentType");
+		if (type === null) continue;
+		if (getLocalName(element.name) === "Override") {
+			const name = getAttribute(element, null, "PartName");
+			const path = name === null ? void 0 : resolvePackageRelationshipTarget(name, "_rels/.rels");
+			if (path !== void 0) overrides.set(path, type);
+		}
+		if (getLocalName(element.name) === "Default") {
+			const extension = getAttribute(element, null, "Extension");
+			if (extension !== null) defaults.set(extension.toLowerCase(), type);
+		}
+	}
+	const prefix = getNamespacePrefix(root.name);
+	const name = prefix ? `${prefix}:Override` : "Override";
+	const additions = [];
+	for (const part of parts) {
+		const path = resolvePackageRelationshipTarget(part.partName, "_rels/.rels");
+		if (path === void 0) return panic("A registered part must have a safe package URI.");
+		const type = overrides.get(path);
+		if (type !== void 0) {
+			if (type !== part.contentType) return panic("A part's registered content type cannot change.");
+			continue;
+		}
+		const extension = path.slice(path.lastIndexOf(".") + 1);
+		if (defaults.get(extension) === part.contentType) continue;
+		additions.push(`<${name} PartName="${escapeXmlAttribute(part.partName)}" ContentType="${escapeXmlAttribute(part.contentType)}"/>`);
+		overrides.set(path, part.contentType);
+	}
+	if (additions.length === 0) return xml;
+	for (const token of xml.matchAll(/<!--[\s\S]*?-->|<\?[\s\S]*?\?>|<!\[CDATA\[[\s\S]*?\]\]>|<(?:"[^"]*"|'[^']*'|[^'">])*>/gu)) {
+		const markup = token[0];
+		if (markup.startsWith("</") && markup.slice(2, -1).trim() === root.name) return spliceXml(xml, [{
+			start: token.index,
+			end: token.index,
+			newXml: additions.join("")
+		}]) ?? panic("A registry insertion must preserve XML ranges.");
+		if (markup.startsWith(`<${root.name}`) && /[\s/>]/u.test(markup.charAt(root.name.length + 1)) && markup.endsWith("/>")) {
+			const end = token.index + markup.length - 2;
+			return spliceXml(xml, [{
+				start: end,
+				end: end + 2,
+				newXml: ">" + additions.join("") + `</${root.name}>`
+			}]) ?? panic("A registry insertion must preserve XML ranges.");
+		}
+	}
+	return panic("A content-type registry needs a closing root boundary.");
+};
+//#endregion
+export { registerContentTypeParts };

package/dist/docx/ensureParaIds.d.ts

@@ -1,8 +1,14 @@
 //#region src/docx/ensureParaIds.d.ts
+declare const ENSURE_PARA_IDS_REASONS: {
+  readonly NORMALIZATION_FAILED: "normalization-failed";
+  readonly NAMESPACE_INVALID: "namespace-invalid";
+  readonly SIGNED_PACKAGE: "signed-package";
+};
 declare const EnsureParaIdsError_base: import("better-result").TaggedErrorClass<"EnsureParaIdsError">;
 /** A malformed or unsupported package prevented paragraph-ID normalization. */
 declare class EnsureParaIdsError extends EnsureParaIdsError_base<{
   message: string;
+  reason: (typeof ENSURE_PARA_IDS_REASONS)[keyof typeof ENSURE_PARA_IDS_REASONS];
   cause?: unknown;
 }> {}
 /** Counts and normalized bytes returned by {@link ensureParaIds}. */
@@ -35,4 +41,4 @@ type EnsureParaIdsOptions = {
  */
 declare const ensureParaIds: (docx: Uint8Array | ArrayBuffer, options?: EnsureParaIdsOptions) => Promise<EnsureParaIdsResult>;
 //#endregion
-export { EnsureParaIdsError, EnsureParaIdsOptions, EnsureParaIdsResult, ensureParaIds };
+export { ENSURE_PARA_IDS_REASONS, EnsureParaIdsError, EnsureParaIdsOptions, EnsureParaIdsResult, ensureParaIds };