@stll/folio-core 0.29.0 → 0.31.0

package/dist/controller/folioEditor.d.ts

@@ -1,3 +1,5 @@
+import { document_d_exports } from "../types/document.js";
+import { DocxInput } from "../utils/docxInput.js";
 import { Layout } from "../layout-engine/types.js";
 import { HiddenEditorApi } from "./hiddenEditorApi.js";
 import { FolioEditorEmitter } from "./folioEditorEvents.js";
@@ -8,9 +10,34 @@ type FolioEditorDeps = {
   getEditorApi: () => HiddenEditorApi | null;
   getLayout: () => Layout | null;
   runLayout: (state: EditorState, options: LayoutRunOptions) => void;
+  /** Required only when the document I/O methods are used. */
+  getDocumentIO?: () => FolioEditorDocumentIO;
   emitter: FolioEditorEmitter;
 };
+declare const FOLIO_DOCX_SERIALIZATION_MODE: Readonly<{
+  readonly full: "full";
+  readonly preferSelective: "prefer-selective";
+}>;
+type FolioDocxSerializationMode = (typeof FOLIO_DOCX_SERIALIZATION_MODE)[keyof typeof FOLIO_DOCX_SERIALIZATION_MODE];
+type FolioGetDocxOptions = {
+  mode?: FolioDocxSerializationMode;
+};
+/**
+ * Document lifecycle operations supplied by a host integration.
+ *
+ * The controller owns the stable contract while each adapter supplies its
+ * current persistence implementation. This lets document I/O migrate without
+ * coupling core to React, Vue, or host callbacks.
+ */
+type FolioEditorDocumentIO = {
+  getDocx: (options?: FolioGetDocxOptions) => Promise<ArrayBuffer | null>;
+  loadDocument: (document: document_d_exports.Document) => void;
+  loadDocx: (input: DocxInput) => Promise<void>;
+};
 type FolioEditor = HiddenEditorApi & {
+  getDocx: FolioEditorDocumentIO["getDocx"];
+  loadDocument: FolioEditorDocumentIO["loadDocument"];
+  loadDocx: FolioEditorDocumentIO["loadDocx"];
   getLayout: () => Layout | null;
   /** Re-run layout for the current editor state (no-op if there is no view). */
   relayout: () => void;
@@ -18,4 +45,4 @@ type FolioEditor = HiddenEditorApi & {
 };
 declare const createFolioEditor: (deps: FolioEditorDeps) => FolioEditor;
 //#endregion
-export { FolioEditor, FolioEditorDeps, createFolioEditor };
+export { FOLIO_DOCX_SERIALIZATION_MODE, FolioDocxSerializationMode, FolioEditor, FolioEditorDeps, FolioEditorDocumentIO, FolioGetDocxOptions, createFolioEditor };

package/dist/controller/folioEditor.js

@@ -1,29 +1,40 @@
+import { panic } from "better-result";
 //#region src/controller/folioEditor.ts
-const createFolioEditor = (deps) => ({
-	ensureView: () => deps.getEditorApi()?.ensureView(),
-	isViewRequested: () => deps.getEditorApi()?.isViewRequested() ?? false,
-	getState: () => deps.getEditorApi()?.getState() ?? null,
-	getView: () => deps.getEditorApi()?.getView() ?? null,
-	getDocument: () => deps.getEditorApi()?.getDocument() ?? null,
-	focus: () => deps.getEditorApi()?.focus(),
-	blur: () => deps.getEditorApi()?.blur(),
-	isFocused: () => deps.getEditorApi()?.isFocused() ?? false,
-	dispatch: (tr) => deps.getEditorApi()?.dispatch(tr),
-	executeCommand: (command) => deps.getEditorApi()?.executeCommand(command) ?? false,
-	undo: () => deps.getEditorApi()?.undo() ?? false,
-	redo: () => deps.getEditorApi()?.redo() ?? false,
-	canUndo: () => deps.getEditorApi()?.canUndo() ?? false,
-	canRedo: () => deps.getEditorApi()?.canRedo() ?? false,
-	setSelection: (anchor, head) => deps.getEditorApi()?.setSelection(anchor, head),
-	setNodeSelection: (pos) => deps.getEditorApi()?.setNodeSelection(pos),
-	setCellSelection: (anchorCellPos, headCellPos) => deps.getEditorApi()?.setCellSelection(anchorCellPos, headCellPos),
-	scrollToSelection: () => deps.getEditorApi()?.scrollToSelection(),
-	getLayout: () => deps.getLayout(),
-	relayout: () => {
-		const state = deps.getEditorApi()?.getState();
-		if (state) deps.runLayout(state, { reason: "manual" });
-	},
-	on: (event, listener) => deps.emitter.on(event, listener)
+const FOLIO_DOCX_SERIALIZATION_MODE = Object.freeze({
+	full: "full",
+	preferSelective: "prefer-selective"
 });
+const createFolioEditor = (deps) => {
+	const getDocumentIO = () => deps.getDocumentIO?.() ?? panic("FolioEditor document I/O requires a getDocumentIO dependency");
+	return {
+		getDocx: (options) => getDocumentIO().getDocx(options),
+		loadDocument: (document) => getDocumentIO().loadDocument(document),
+		loadDocx: (input) => getDocumentIO().loadDocx(input),
+		ensureView: () => deps.getEditorApi()?.ensureView(),
+		isViewRequested: () => deps.getEditorApi()?.isViewRequested() ?? false,
+		getState: () => deps.getEditorApi()?.getState() ?? null,
+		getView: () => deps.getEditorApi()?.getView() ?? null,
+		getDocument: () => deps.getEditorApi()?.getDocument() ?? null,
+		focus: () => deps.getEditorApi()?.focus(),
+		blur: () => deps.getEditorApi()?.blur(),
+		isFocused: () => deps.getEditorApi()?.isFocused() ?? false,
+		dispatch: (tr) => deps.getEditorApi()?.dispatch(tr),
+		executeCommand: (command) => deps.getEditorApi()?.executeCommand(command) ?? false,
+		undo: () => deps.getEditorApi()?.undo() ?? false,
+		redo: () => deps.getEditorApi()?.redo() ?? false,
+		canUndo: () => deps.getEditorApi()?.canUndo() ?? false,
+		canRedo: () => deps.getEditorApi()?.canRedo() ?? false,
+		setSelection: (anchor, head) => deps.getEditorApi()?.setSelection(anchor, head),
+		setNodeSelection: (pos) => deps.getEditorApi()?.setNodeSelection(pos),
+		setCellSelection: (anchorCellPos, headCellPos) => deps.getEditorApi()?.setCellSelection(anchorCellPos, headCellPos),
+		scrollToSelection: () => deps.getEditorApi()?.scrollToSelection(),
+		getLayout: () => deps.getLayout(),
+		relayout: () => {
+			const state = deps.getEditorApi()?.getState();
+			if (state) deps.runLayout(state, { reason: "manual" });
+		},
+		on: (event, listener) => deps.emitter.on(event, listener)
+	};
+};
 //#endregion
-export { createFolioEditor };
+export { FOLIO_DOCX_SERIALIZATION_MODE, createFolioEditor };

package/dist/controller/fontReadiness.js

@@ -1,3 +1,4 @@
+import { buildFontAlternates, getFontAlternate } from "../fonts/fontAlternates.js";
 import { expectFontFamilyMarkAttrs, expectParagraphAttrs } from "../prosemirror/attrs/index.js";
 import { parseFontFamilyList, resolveFontFamily } from "../utils/fontResolver.js";
 //#region src/controller/fontReadiness.ts
@@ -52,31 +53,32 @@ function collectInitialLayoutFontFamilies(documentModel, pmDoc) {
 }
 function collectInitialLayoutFontFaces(documentModel, pmDoc) {
 	const faces = /* @__PURE__ */ new Map();
-	addLayoutFontFamilyFace(faces, DEFAULT_LAYOUT_FONT_FAMILY, REGULAR_LAYOUT_FONT_DESCRIPTOR);
-	for (const family of documentModel?.requiredFonts ?? []) addLayoutFontFamilyFace(faces, family, REGULAR_LAYOUT_FONT_DESCRIPTOR);
-	addLayoutFontFamilyFace(faces, documentModel?.package.theme?.fontScheme?.majorFont?.latin, REGULAR_LAYOUT_FONT_DESCRIPTOR);
-	addLayoutFontFamilyFace(faces, documentModel?.package.theme?.fontScheme?.minorFont?.latin, REGULAR_LAYOUT_FONT_DESCRIPTOR);
-	addTextFormattingFontFaces(faces, documentModel?.package.styles?.docDefaults?.rPr);
-	for (const style of documentModel?.package.styles?.styles ?? []) addTextFormattingFontFaces(faces, style.rPr);
-	collectProseMirrorFontFaces(faces, pmDoc, void 0);
+	const fontAlternates = buildFontAlternates(documentModel?.package.fontTable);
+	addLayoutFontFamilyFace(faces, DEFAULT_LAYOUT_FONT_FAMILY, REGULAR_LAYOUT_FONT_DESCRIPTOR, fontAlternates);
+	for (const family of documentModel?.requiredFonts ?? []) addLayoutFontFamilyFace(faces, family, REGULAR_LAYOUT_FONT_DESCRIPTOR, fontAlternates);
+	addLayoutFontFamilyFace(faces, documentModel?.package.theme?.fontScheme?.majorFont?.latin, REGULAR_LAYOUT_FONT_DESCRIPTOR, fontAlternates);
+	addLayoutFontFamilyFace(faces, documentModel?.package.theme?.fontScheme?.minorFont?.latin, REGULAR_LAYOUT_FONT_DESCRIPTOR, fontAlternates);
+	addTextFormattingFontFaces(faces, documentModel?.package.styles?.docDefaults?.rPr, fontAlternates);
+	for (const style of documentModel?.package.styles?.styles ?? []) addTextFormattingFontFaces(faces, style.rPr, fontAlternates);
+	collectProseMirrorFontFaces(faces, pmDoc, void 0, fontAlternates);
 	return Array.from(faces.values());
 }
-function addTextFormattingFontFaces(faces, formatting) {
+function addTextFormattingFontFaces(faces, formatting, fontAlternates) {
 	const standardDescriptor = layoutDescriptorFromFormatting(formatting);
 	const complexScriptDescriptor = layoutDescriptorFromEmphasis(formatting?.boldCs ?? formatting?.bold, formatting?.italicCs ?? formatting?.italic);
-	addLayoutFontFamilyFace(faces, formatting?.fontFamily, standardDescriptor, complexScriptDescriptor);
+	addLayoutFontFamilyFace(faces, formatting?.fontFamily, standardDescriptor, fontAlternates, complexScriptDescriptor);
 }
-function collectProseMirrorFontFaces(faces, node, inheritedTextFormatting) {
+function collectProseMirrorFontFaces(faces, node, inheritedTextFormatting, fontAlternates) {
 	const paragraphDefaults = readParagraphDefaultTextFormatting(node);
 	const textFormatting = paragraphDefaults ?? inheritedTextFormatting;
-	if (paragraphDefaults) addTextFormattingFontFaces(faces, paragraphDefaults);
-	if (node.type.name === "paragraph") addTextFormattingFontFaces(faces, expectParagraphAttrs(node).listMarkerFormatting);
+	if (paragraphDefaults) addTextFormattingFontFaces(faces, paragraphDefaults, fontAlternates);
+	if (node.type.name === "paragraph") addTextFormattingFontFaces(faces, expectParagraphAttrs(node).listMarkerFormatting, fontAlternates);
 	if (node.isText) {
 		const descriptor = layoutDescriptorFromFormattingAndMarks(textFormatting, node.marks);
-		addLayoutFontFamilyFace(faces, readFontFamilyMarkAttrs(node.marks) ?? textFormatting?.fontFamily ?? DEFAULT_LAYOUT_FONT_FAMILY, descriptor);
+		addLayoutFontFamilyFace(faces, readFontFamilyMarkAttrs(node.marks) ?? textFormatting?.fontFamily ?? DEFAULT_LAYOUT_FONT_FAMILY, descriptor, fontAlternates);
 	}
 	node.forEach((child) => {
-		collectProseMirrorFontFaces(faces, child, textFormatting);
+		collectProseMirrorFontFaces(faces, child, textFormatting, fontAlternates);
 	});
 }
 function readParagraphDefaultTextFormatting(node) {
@@ -108,23 +110,25 @@ function layoutDescriptorFromFormattingAndMarks(formatting, marks) {
 		weight: bold ? 700 : 400
 	};
 }
-function addLayoutFontFamilyFace(faces, value, descriptor, complexScriptDescriptor = descriptor) {
+function addLayoutFontFamilyFace(faces, value, descriptor, fontAlternates, complexScriptDescriptor = descriptor) {
 	if (typeof value === "string") {
-		addLayoutFontFamilyNameFace(faces, value, descriptor);
+		addLayoutFontFamilyNameFace(faces, value, descriptor, fontAlternates);
 		return;
 	}
 	if (!value || typeof value !== "object") return;
 	const fontFamily = value;
-	addLayoutFontFamilyFace(faces, fontFamily.ascii, descriptor);
-	addLayoutFontFamilyFace(faces, fontFamily.hAnsi, descriptor);
-	addLayoutFontFamilyFace(faces, fontFamily.cs, complexScriptDescriptor);
-	addLayoutFontFamilyFace(faces, fontFamily.eastAsia, descriptor);
+	addLayoutFontFamilyFace(faces, fontFamily.ascii, descriptor, fontAlternates);
+	addLayoutFontFamilyFace(faces, fontFamily.hAnsi, descriptor, fontAlternates);
+	addLayoutFontFamilyFace(faces, fontFamily.cs, complexScriptDescriptor, fontAlternates);
+	addLayoutFontFamilyFace(faces, fontFamily.eastAsia, descriptor, fontAlternates);
 }
-function addLayoutFontFamilyNameFace(faces, family, descriptor) {
+function addLayoutFontFamilyNameFace(faces, family, descriptor, fontAlternates) {
 	const normalized = family.trim();
 	if (!normalized || CSS_GENERIC_FONT_FAMILIES.has(normalized)) return;
 	addLayoutFontFace(faces, normalized, descriptor);
-	for (const stackFamily of resolvedStackFamilies(normalized)) addLayoutFontFace(faces, stackFamily, descriptor);
+	const alternate = getFontAlternate(normalized, fontAlternates);
+	if (alternate) addLayoutFontFace(faces, alternate, descriptor);
+	for (const stackFamily of resolvedStackFamilies(normalized, alternate)) addLayoutFontFace(faces, stackFamily, descriptor);
 }
 /**
 * The concrete families in a resolved CSS font stack, generics dropped.
@@ -132,8 +136,8 @@ function addLayoutFontFamilyNameFace(faces, family, descriptor) {
 * Parsed from the stack rather than read from a map because the stack is what
 * the painter and the measurer put in `ctx.font` and `style.fontFamily`.
 */
-function resolvedStackFamilies(family) {
-	const { cssFallback } = resolveFontFamily(family);
+function resolvedStackFamilies(family, alternate) {
+	const { cssFallback } = resolveFontFamily(family, alternate);
 	return parseFontFamilyList(cssFallback).filter((name) => !CSS_GENERIC_FONT_FAMILIES.has(name));
 }
 function addLayoutFontFace(faces, family, descriptor) {

package/dist/controller/hiddenEditorManager.d.ts

@@ -1,6 +1,7 @@
 import { document_d_exports } from "../types/document.js";
 import { HiddenEditorStateReason } from "../layout-engine/layoutInstrumentation.js";
 import { ExtensionManager } from "../prosemirror/extensions/ExtensionManager.js";
+import { RemoteSelection } from "../types/remote-selection.js";
 import { HiddenEditorApi } from "./hiddenEditorApi.js";
 import { EditorState, Plugin, Transaction } from "prosemirror-state";
 import { EditorView } from "prosemirror-view";
@@ -26,13 +27,7 @@ type HiddenProseMirrorCollaboration = {
   shouldSeed?: boolean | undefined;
   yXmlFragment: XmlFragment;
 };
-type HiddenProseMirrorRemoteSelection = {
-  anchor: number;
-  clientId: number;
-  color: string;
-  head: number;
-  name: string;
-};
+type HiddenProseMirrorRemoteSelection = RemoteSelection;
 declare const collectRemoteSelections: (state: EditorState, awareness: CollaborationAwareness, collaborationModules: CollaborationModules) => HiddenProseMirrorRemoteSelection[];
 /**
  * Create ProseMirror state from document

package/dist/controller/layoutPipeline.js

@@ -4,6 +4,7 @@ import { buildBookmarkText } from "../fields/bookmarkText.js";
 import { buildHeaderFooterFieldValues, fieldValuesEqual, resolveFieldValues } from "../fields/resolveFieldValues.js";
 import { buildSectionPageCounts } from "../fields/sectionPageCounts.js";
 import { buildSeqValues } from "../fields/seqValues.js";
+import { buildFontAlternates } from "../fonts/fontAlternates.js";
 import { buildFootnoteContentMap, collectEndnoteRefs, collectFootnoteRefs, computeNoteDisplayNumbers, remapNoteMarkerText } from "../layout-bridge/convert/footnoteLayout.js";
 import { applyTemplatePreviewToBlocks } from "../layout-bridge/convert/templatePreviewFlow.js";
 import { toFlowBlocks } from "../layout-bridge/convert/toFlowBlocks.js";
@@ -97,7 +98,12 @@ function runLayoutPipeline(deps, state, options = {}) {
 	syncCoordinator.onLayoutStart();
 	try {
 		let phaseStartedAt = performance.now();
-		const flowOpts = { pageContentHeight: pageSize.h - margins.top - margins.bottom };
+		const pageContentHeight = pageSize.h - margins.top - margins.bottom;
+		const fontAlternates = buildFontAlternates(document?.package.fontTable);
+		const flowOpts = {
+			pageContentHeight,
+			fontAlternates
+		};
 		if (_theme !== void 0) flowOpts.theme = _theme;
 		if (defaultTabStop !== void 0) flowOpts.defaultTabStopTwips = defaultTabStop;
 		if (document?.package.settings?.lineBreakRules) flowOpts.lineBreakRules = document.package.settings.lineBreakRules;
@@ -155,6 +161,7 @@ function runLayoutPipeline(deps, state, options = {}) {
 			return {
 				...styles ? { styles } : {},
 				..._theme !== void 0 ? { theme: _theme } : {},
+				fontAlternates,
 				measureBlocks: hfMeasureBlocks,
 				...defaultTabStop !== void 0 ? { defaultTabStopTwips: defaultTabStop } : {},
 				...flowOpts.lineBreakRules ? { lineBreakRules: flowOpts.lineBreakRules } : {},
@@ -241,7 +248,18 @@ function runLayoutPipeline(deps, state, options = {}) {
 			pageHeight: blockMeasureInputs.pageHeights,
 			marginLeft: blockMeasureInputs.marginLefts,
 			marginRight: blockMeasureInputs.marginRights,
-			marginBottom: blockMeasureInputs.marginBottoms
+			marginBottom: blockMeasureInputs.marginBottoms,
+			contentLeft: blockMeasureInputs.contentLefts,
+			physicalPage: {
+				pageWidth: blockMeasureInputs.physicalPageGeometry.pageWidths,
+				pageHeight: blockMeasureInputs.physicalPageGeometry.pageHeights,
+				marginTop: blockMeasureInputs.physicalPageGeometry.marginTops,
+				marginLeft: blockMeasureInputs.physicalPageGeometry.marginLefts,
+				marginRight: blockMeasureInputs.physicalPageGeometry.marginRights,
+				marginBottom: blockMeasureInputs.physicalPageGeometry.marginBottoms
+			},
+			columnIndex: blockMeasureInputs.columnIndices,
+			columnCount: blockMeasureInputs.columnCounts
 		});
 		newBlocks = resolveEffectiveParagraphSpacingTree(newBlocks);
 		outcome.blocks = newBlocks;
@@ -290,6 +308,7 @@ function runLayoutPipeline(deps, state, options = {}) {
 				const footnoteOptions = { measureBlocks };
 				if (styles) footnoteOptions.styles = styles;
 				if (_theme !== void 0) footnoteOptions.theme = _theme;
+				footnoteOptions.fontAlternates = fontAlternates;
 				if (defaultTabStop !== void 0) footnoteOptions.defaultTabStopTwips = defaultTabStop;
 				if (flowOpts.lineBreakRules) footnoteOptions.lineBreakRules = flowOpts.lineBreakRules;
 				if (flowOpts.justificationCompatibility) footnoteOptions.justificationCompatibility = flowOpts.justificationCompatibility;
@@ -354,7 +373,18 @@ function runLayoutPipeline(deps, state, options = {}) {
 					pageHeight: blockMeasureInputs.pageHeights,
 					marginLeft: blockMeasureInputs.marginLefts,
 					marginRight: blockMeasureInputs.marginRights,
-					marginBottom: blockMeasureInputs.marginBottoms
+					marginBottom: blockMeasureInputs.marginBottoms,
+					contentLeft: blockMeasureInputs.contentLefts,
+					physicalPage: {
+						pageWidth: blockMeasureInputs.physicalPageGeometry.pageWidths,
+						pageHeight: blockMeasureInputs.physicalPageGeometry.pageHeights,
+						marginTop: blockMeasureInputs.physicalPageGeometry.marginTops,
+						marginLeft: blockMeasureInputs.physicalPageGeometry.marginLefts,
+						marginRight: blockMeasureInputs.physicalPageGeometry.marginRights,
+						marginBottom: blockMeasureInputs.physicalPageGeometry.marginBottoms
+					},
+					columnIndex: blockMeasureInputs.columnIndices,
+					columnCount: blockMeasureInputs.columnCounts
 				}, values);
 				relayoutWithCurrentMeasures(layoutOptsUsed);
 				pendingArtifacts = {

package/dist/controller/noteEditorManager.d.ts

@@ -1,12 +1,9 @@
 import { document_d_exports } from "../types/document.js";
+import { NoteStoryKey } from "../types/editor-story.js";
 import { Plugin } from "prosemirror-state";
 import { EditorView } from "prosemirror-view";
 //#region src/controller/noteEditorManager.d.ts
-type NoteStoryKind = "footnote" | "endnote";
-type NoteStoryKey = {
-  kind: NoteStoryKind;
-  noteId: number;
-};
+type NoteStoryKind = NoteStoryKey["kind"];
 type NoteEditorTransaction = NoteStoryKey & {
   docChanged: boolean;
   selectionChanged: boolean;
@@ -32,4 +29,4 @@ type NoteEditorManager = {
 declare const enumerateDocumentNoteStories: (document: document_d_exports.Document | null) => NoteStoryKey[];
 declare const createNoteEditorManager: (deps: NoteEditorManagerDeps) => NoteEditorManager;
 //#endregion
-export { NoteEditorManager, NoteEditorManagerDeps, NoteEditorTransaction, NoteStoryKey, NoteStoryKind, createNoteEditorManager, enumerateDocumentNoteStories };
+export { NoteEditorManager, NoteEditorManagerDeps, NoteEditorTransaction, type NoteStoryKey, NoteStoryKind, createNoteEditorManager, enumerateDocumentNoteStories };

package/dist/docx/metafileSvg.d.ts

@@ -0,0 +1,12 @@
+//#region src/docx/metafileSvg.d.ts
+/**
+ * Render a deliberately small, browser-safe EMF subset to generated SVG.
+ *
+ * This covers vector logos built from filled paths. Unsupported records fail
+ * closed: a partial metafile is more misleading than the existing placeholder.
+ * Original EMF bytes remain the source of truth for DOCX round-trip.
+ */
+/** Convert the supported filled-path EMF subset to inert generated SVG. */
+declare function renderEmfSvg(data: ArrayBuffer | Uint8Array): string | null;
+//#endregion
+export { renderEmfSvg };