@stll/folio-core 0.1.2 → 0.2.0

package/dist/i18n/messages/messages.gen.d.ts

@@ -0,0 +1,166 @@
+//#region src/i18n/messages/messages.gen.d.ts
+type Messages = {
+  "folio": {
+    "acceptChange": "Accept Change";
+    "accessDenied": "Access denied. You may not have permission to access this file.";
+    "alignCenter": "Center";
+    "alignLeft": "Align Left";
+    "alignRight": "Align Right";
+    "alignmentGroup": "Alignment";
+    "bold": "Bold";
+    "boldShortcut": "Bold (Ctrl+B)";
+    "bulletList": "Bullet List";
+    "checkingDocxEditDescription": "stella is still checking whether this DOCX can be edited safely. Try again when the document finishes loading.";
+    "checkingDocxEditTitle": "Checking document";
+    "clearDate": "Clear date";
+    "clipboardReadFailed": "Couldn't read the clipboard. Check clipboard permissions and try again.";
+    "comment": "Comment";
+    "comments": {
+      "addPlaceholder": "Add a comment...";
+      "cancel": "Cancel";
+      "hideAll": "Hide comments";
+      "moreReplies": "{count} more replies";
+      "noComments": "No comments yet.";
+      "reply": "Reply";
+      "replyPlaceholder": "Reply or add others with @";
+      "showAll": "All comments";
+      "unknownAuthor": "Unknown";
+      "visibility": "Comments";
+    };
+    "contentControlDateAriaLabel": "Pick a date";
+    "contentControlDropdownAriaLabel": "Dropdown options";
+    "contentControlDropdownNoOptions": "No options";
+    "copy": "Copy";
+    "copyLink": "Copy link";
+    "cut": "Cut";
+    "decreaseIndent": "Decrease Indent";
+    "delete": "Delete";
+    "deleteColumn": "Delete column";
+    "deleteRow": "Delete row";
+    "deleted": "Deleted";
+    "discardChanges": "Discard";
+    "dismiss": "Dismiss";
+    "displayText": "Display text";
+    "doneEditing": "Done editing";
+    "doubleClickFooter": "Double-click to add footer";
+    "doubleClickHeader": "Double-click to add header";
+    "editAuthRequired": "Refresh stella and sign in again before editing this document.";
+    "editDownloadFailed": "The document could not be downloaded for editing.";
+    "editLink": "Edit link";
+    "editOpenFailed": "The document could not be opened for editing.";
+    "editOpenFailedTitle": "Could not open DOCX";
+    "editPermissionDenied": "You do not have permission to edit this document.";
+    "editSaveFailedTitle": "Could not save DOCX";
+    "editSessionTakenOver": "Another tab, window, or device opened this document for editing, so this session was released. Unsaved local changes are preserved — reopen the doc to continue.";
+    "findReplace": {
+      "close": "Close search";
+      "find": "Find";
+      "findAndReplace": "Find and replace";
+      "findPlaceholder": "Search document...";
+      "findText": "Find text";
+      "matchCase": "Match case";
+      "matchCounter": "{current} / {total}";
+      "next": "Next match";
+      "nextShortcut": "Next match (Enter)";
+      "noResults": "No results";
+      "previous": "Previous match";
+      "previousShortcut": "Previous match (Shift+Enter)";
+      "replaceAll": "Replace all";
+      "replaceCurrent": "Replace current match";
+      "replacePlaceholder": "Replacement text...";
+      "replaceText": "Replacement text";
+      "wholeWords": "Whole words";
+    };
+    "finishEditing": "Finish editing";
+    "fontColor": "Font color";
+    "fontGroup": "Font";
+    "fontSize": "Font size";
+    "formatPainter": "Format Painter";
+    "formatPainterShortcut": "Format Painter (Ctrl+Shift+C)";
+    "formattingToolbar": "Formatting toolbar";
+    "hideDetails": "Hide details";
+    "historyGroup": "History";
+    "increaseIndent": "Increase Indent";
+    "insertColumnLeft": "Insert column left";
+    "insertColumnRight": "Insert column right";
+    "insertGroup": "Insert";
+    "insertImage": "Insert image";
+    "insertPageBreak": "Insert page break";
+    "insertRowAbove": "Insert row above";
+    "insertRowBelow": "Insert row below";
+    "insertTable": "Insert table";
+    "insertTableOfContents": "Insert table of contents";
+    "inserted": "Inserted";
+    "italic": "Italic";
+    "italicShortcut": "Italic (Ctrl+I)";
+    "justify": "Justify";
+    "listFormatting": "List formatting";
+    "listsGroup": "Lists";
+    "loadingDocument": "Loading document...";
+    "loadingEditor": "Loading editor...";
+    "lockFile": "Lock file";
+    "markupView": {
+      "allMarkup": "All Markup";
+      "noMarkup": "No Markup";
+      "original": "Original";
+      "simple": "Simple Markup";
+    };
+    "moreFormatting": "More formatting";
+    "networkError": "Network error. Please check your internet connection and try again.";
+    "nextChange": "Next Change";
+    "numberedList": "Numbered List";
+    "parseError": "The document could not be parsed. It may be corrupted or in an unsupported format.";
+    "paste": "Paste";
+    "pasteUnformatted": "Paste without formatting";
+    "previousChange": "Previous Change";
+    "printRedirect": "To print, download the document and open it in your word processor.";
+    "redo": "Redo";
+    "redoShortcut": "Redo (Ctrl+Y)";
+    "rejectChange": "Reject Change";
+    "removeLink": "Remove link";
+    "renderErrorDescription": "Something went wrong showing this part of the document. Reload the page — if it keeps happening, let us know.";
+    "ruler": {
+      "bottomMargin": "Bottom margin";
+      "firstLineIndent": "First line indent";
+      "horizontal": "Horizontal ruler";
+      "leftIndent": "Left indent";
+      "rightIndent": "Right indent";
+      "toggle": "Ruler";
+      "topMargin": "Top margin";
+      "vertical": "Vertical ruler";
+    };
+    "saveCheckpointFailedDescription": "The DOCX was created locally, but stella could not upload the checkpoint. Keep the editor open and try saving again.";
+    "saveCheckpointFailedTitle": "Could not upload save";
+    "saveEditorUnavailableDescription": "The editor is not ready yet. Wait for the document to finish loading, then try saving again.";
+    "saveEditorUnavailableTitle": "Editor not ready";
+    "saveSerializeFailedDescription": "Folio could not produce a safe DOCX file from the current edit. Your session is still open.";
+    "saveSerializeFailedTitle": "Could not create DOCX";
+    "savingDocument": "Saving...";
+    "selectAll": "Select all";
+    "showDetails": "Show details";
+    "somethingWentWrong": "Something went wrong";
+    "synced": "Synced";
+    "syncing": "Syncing";
+    "tableBordersAll": "All borders";
+    "tableBordersNone": "No borders";
+    "textDirection": "Text direction";
+    "textEditingMenu": "Text editing menu";
+    "textFormattingGroup": "Text formatting";
+    "toggleTrackChanges": "Toggle Track Changes";
+    "trackingOff": "Tracking: Off";
+    "trackingOn": "Tracking: On";
+    "tryAgain": "Try Again";
+    "underline": "Underline";
+    "underlineShortcut": "Underline (Ctrl+U)";
+    "undo": "Undo";
+    "undoShortcut": "Undo (Ctrl+Z)";
+    "unlockFile": "Unlock file";
+    "unlockForEditing": "Unlock to edit";
+    "unsupportedDocxEditDescription": "This DOCX contains structures Folio cannot safely rewrite. To avoid corrupting the file, download it and edit it in Word.";
+    "unsupportedDocxEditTitle": "Editing blocked";
+    "viewGroup": "View";
+    "zoomGroup": "Zoom";
+  };
+};
+//#endregion
+export type { Messages as default };

package/dist/i18n/messages.d.ts

@@ -0,0 +1,13 @@
+//#region src/i18n/messages.d.ts
+declare const FOLIO_LOCALES: readonly ["en", "de", "fr", "es", "cs", "ar", "et", "he", "hi", "hu", "lt", "lv", "pl", "pt-BR", "sk", "tr", "zh-CN"];
+type FolioLocale = (typeof FOLIO_LOCALES)[number];
+type FolioMessageTree = {
+  [key: string]: string | FolioMessageTree;
+};
+type FolioMessages = {
+  folio: FolioMessageTree;
+};
+declare const isFolioLocale: (locale: string) => locale is FolioLocale;
+declare const getFolioMessages: (locale: string) => FolioMessages;
+//#endregion
+export { FOLIO_LOCALES, FolioLocale, FolioMessages, getFolioMessages, isFolioLocale };

package/dist/i18n/messages.js

@@ -0,0 +1,39 @@
+import { CATALOGS as CATALOGS$1 } from "./messages/catalogs.gen.js";
+//#region src/i18n/messages.ts
+const FOLIO_LOCALES = [
+	"en",
+	"de",
+	"fr",
+	"es",
+	"cs",
+	"ar",
+	"et",
+	"he",
+	"hi",
+	"hu",
+	"lt",
+	"lv",
+	"pl",
+	"pt-BR",
+	"sk",
+	"tr",
+	"zh-CN"
+];
+const CATALOGS = CATALOGS$1;
+const FOLIO_LOCALE_SET = new Set(FOLIO_LOCALES);
+const isFolioLocale = (locale) => FOLIO_LOCALE_SET.has(locale);
+const baseLanguageOf = (locale) => {
+	try {
+		return new Intl.Locale(locale).language;
+	} catch {
+		return null;
+	}
+};
+const getFolioMessages = (locale) => {
+	if (isFolioLocale(locale)) return CATALOGS[locale];
+	const base = baseLanguageOf(locale);
+	if (base !== null && isFolioLocale(base)) return CATALOGS[base];
+	return CATALOGS.en;
+};
+//#endregion
+export { FOLIO_LOCALES, getFolioMessages, isFolioLocale };

package/dist/layout-bridge/cellSelectionHighlight.d.ts

@@ -0,0 +1,18 @@
+import { EditorState } from "prosemirror-state";
+
+//#region src/layout-bridge/cellSelectionHighlight.d.ts
+/**
+ * Apply the `.layout-table-cell-selected` class to painted layout cells
+ * matching a CellSelection in the PM state. Clears the class everywhere
+ * (within scope) first so toggling off (or moving to a TextSelection) erases
+ * prior highlights.
+ *
+ * Duck-types CellSelection via `$anchorCell` / `forEachCell` rather than
+ * `instanceof` to dodge bundling issues across `prosemirror-tables` copies
+ * (the same trick used inline in the selection-overlay update).
+ */
+declare function applyCellSelectionHighlight(pagesContainer: HTMLElement, state: EditorState, options?: {
+  scope?: "body" | "header" | "footer";
+}): void;
+//#endregion
+export { applyCellSelectionHighlight };

package/dist/layout-bridge/cellSelectionHighlight.js

@@ -0,0 +1,36 @@
+//#region src/layout-bridge/cellSelectionHighlight.ts
+/**
+* Apply the `.layout-table-cell-selected` class to painted layout cells
+* matching a CellSelection in the PM state. Clears the class everywhere
+* (within scope) first so toggling off (or moving to a TextSelection) erases
+* prior highlights.
+*
+* Duck-types CellSelection via `$anchorCell` / `forEachCell` rather than
+* `instanceof` to dodge bundling issues across `prosemirror-tables` copies
+* (the same trick used inline in the selection-overlay update).
+*/
+function applyCellSelectionHighlight(pagesContainer, state, options = {}) {
+	const scope = options.scope ?? "body";
+	const scopeClass = scope === "body" ? "layout-page-content" : `layout-page-${scope}`;
+	const scopeSelector = `.${scopeClass} .layout-table-cell`;
+	const prevSelected = pagesContainer.querySelectorAll(`.${scopeClass} .layout-table-cell-selected`);
+	for (const el of Array.from(prevSelected)) el.classList.remove("layout-table-cell-selected");
+	const sel = state.selection;
+	if (!("$anchorCell" in sel && typeof sel.forEachCell === "function") || !sel.forEachCell) return;
+	const selectedRanges = [];
+	sel.forEachCell((node, pos) => {
+		selectedRanges.push([pos, pos + node.nodeSize]);
+	});
+	const allCells = pagesContainer.querySelectorAll(scopeSelector);
+	for (const cellEl of Array.from(allCells)) {
+		const pmStartAttr = cellEl.dataset["pmStart"];
+		if (pmStartAttr === void 0) continue;
+		const pmPos = Number(pmStartAttr);
+		for (const [start, end] of selectedRanges) if (pmPos >= start && pmPos < end) {
+			cellEl.classList.add("layout-table-cell-selected");
+			break;
+		}
+	}
+}
+//#endregion
+export { applyCellSelectionHighlight };

package/dist/layout-bridge/convert/headerFooterLayout.d.ts

@@ -1,5 +1,5 @@
 import { document_d_exports } from "../../types/document.js";
-import { FlowBlock, HeaderFooterContent, ImageRun, Measure, PageMargins } from "../../layout-engine/types.js";
+import { FlowBlock, HeaderFooterContent, ImageRun, ImageRunPosition, Measure, PageMargins } from "../../layout-engine/types.js";
 import { MeasureBlocksFn } from "./footnoteLayout.js";
 import { Node } from "prosemirror-model";
 
@@ -13,6 +13,7 @@ type HeaderFooterMetrics = {
   margins: PageMargins;
 };
 declare function normalizeHeaderFooterMeasureBlocks(blocks: FlowBlock[]): FlowBlock[];
+declare function resolveHeaderFooterPositionedVisualTop(position: ImageRunPosition | undefined, elementHeight: number, sourceY: number, flowHeight: number, metrics: HeaderFooterMetrics): number;
 declare function resolveHeaderFooterVisualTop(run: ImageRun, paragraphY: number, flowHeight: number, metrics: HeaderFooterMetrics): number;
 declare function calculateHeaderFooterVisualBounds(blocks: FlowBlock[], measures: Measure[], flowHeight: number, metrics: HeaderFooterMetrics): {
   visualTop: number;
@@ -71,4 +72,4 @@ declare function convertHeaderFooterToContent(headerFooter: document_d_exports.H
  */
 declare function convertHeaderFooterPmDocToContent(pmDoc: Node | null | undefined, contentWidth: number, metrics: HeaderFooterMetrics, options: Omit<ConvertHeaderFooterOptions, "styles">): HeaderFooterContent | undefined;
 //#endregion
-export { ConvertHeaderFooterOptions, HeaderFooterMetrics, calculateHeaderFooterMarginPushBounds, calculateHeaderFooterVisualBounds, convertHeaderFooterPmDocToContent, convertHeaderFooterToContent, normalizeHeaderFooterMeasureBlocks, resolveHeaderFooterVisualTop };
+export { ConvertHeaderFooterOptions, HeaderFooterMetrics, calculateHeaderFooterMarginPushBounds, calculateHeaderFooterVisualBounds, convertHeaderFooterPmDocToContent, convertHeaderFooterToContent, normalizeHeaderFooterMeasureBlocks, resolveHeaderFooterPositionedVisualTop, resolveHeaderFooterVisualTop };

package/dist/layout-bridge/convert/headerFooterLayout.js

@@ -98,28 +98,43 @@ function normalizeTableBlock(block) {
 function getPositionAlignment(axis) {
 	return axis?.align ?? axis?.alignment;
 }
-function resolveHeaderFooterVisualTop(run, paragraphY, flowHeight, metrics) {
+function resolveHeaderFooterPositionedVisualTop(position, elementHeight, sourceY, flowHeight, metrics) {
 	const flowTop = metrics.section === "header" ? metrics.margins.header ?? 48 : metrics.pageSize.h - (metrics.margins.footer ?? 48) - flowHeight;
-	const vertical = run.position?.vertical;
-	if (!vertical) return paragraphY;
+	const vertical = position?.vertical;
+	if (!vertical) return sourceY;
 	const align = getPositionAlignment(vertical);
 	const offsetPx = vertical.posOffset !== void 0 ? emuToPixels(vertical.posOffset) : void 0;
 	if (vertical.relativeTo === "page") {
 		if (offsetPx !== void 0) return offsetPx - flowTop;
 		if (align === "top") return -flowTop;
-		if (align === "bottom") return metrics.pageSize.h - run.height - flowTop;
-		if (align === "center") return (metrics.pageSize.h - run.height) / 2 - flowTop;
+		if (align === "bottom") return metrics.pageSize.h - elementHeight - flowTop;
+		if (align === "center") return (metrics.pageSize.h - elementHeight) / 2 - flowTop;
 	}
 	if (vertical.relativeTo === "margin") {
 		const marginTop = metrics.margins.top;
 		const marginHeight = metrics.pageSize.h - metrics.margins.top - metrics.margins.bottom;
 		if (offsetPx !== void 0) return marginTop + offsetPx - flowTop;
 		if (align === "top") return marginTop - flowTop;
-		if (align === "bottom") return marginTop + marginHeight - run.height - flowTop;
-		if (align === "center") return marginTop + (marginHeight - run.height) / 2 - flowTop;
+		if (align === "bottom") return marginTop + marginHeight - elementHeight - flowTop;
+		if (align === "center") return marginTop + (marginHeight - elementHeight) / 2 - flowTop;
 	}
-	if (offsetPx !== void 0) return paragraphY + offsetPx;
-	return paragraphY;
+	if (offsetPx !== void 0) return sourceY + offsetPx;
+	return sourceY;
+}
+function resolveHeaderFooterVisualTop(run, paragraphY, flowHeight, metrics) {
+	return resolveHeaderFooterPositionedVisualTop(run.position, run.height, paragraphY, flowHeight, metrics);
+}
+function pageBandInHeaderFooterCoords(metrics, flowHeight) {
+	const flowTop = metrics.section === "header" ? metrics.margins.header ?? 48 : metrics.pageSize.h - (metrics.margins.footer ?? 48) - flowHeight;
+	return {
+		top: -flowTop,
+		bottom: metrics.pageSize.h - flowTop
+	};
+}
+/** True when a float's box overlaps the page band in header/footer coordinates. */
+function floatIntersectsPageBand(blockTop, blockBottom, metrics, flowHeight) {
+	const band = pageBandInHeaderFooterCoords(metrics, flowHeight);
+	return blockBottom > band.top && blockTop < band.bottom;
 }
 function resolveHeaderFooterFloatingTableVisualTop(floating, measure, sourceY, flowHeight, metrics) {
 	const flowTop = metrics.section === "header" ? metrics.margins.header ?? 48 : metrics.pageSize.h - (metrics.margins.footer ?? 48) - flowHeight;
@@ -156,8 +171,10 @@ function calculateHeaderFooterVisualBounds(blocks, measures, flowHeight, metrics
 				if (run.kind !== "image") continue;
 				if (!run.position && !isFloatingImageRun(run)) continue;
 				const runTop = resolveHeaderFooterVisualTop(run, paragraphStartY, flowHeight, metrics);
+				const runBottom = runTop + run.height;
+				if (!floatIntersectsPageBand(runTop, runBottom, metrics, flowHeight)) continue;
 				visualTop = Math.min(visualTop, runTop);
-				visualBottom = Math.max(visualBottom, runTop + run.height);
+				visualBottom = Math.max(visualBottom, runBottom);
 			}
 			cursorY = paragraphBottomY;
 		} else {
@@ -178,11 +195,18 @@ function calculateHeaderFooterVisualBounds(blocks, measures, flowHeight, metrics
 				cursorY = blockBottomY;
 			} else if (block.kind === "table" && block.floating && measure.kind === "table") {
 				const blockTop = resolveHeaderFooterFloatingTableVisualTop(block.floating, measure, cursorY, flowHeight, metrics);
-				visualTop = Math.min(visualTop, blockTop);
-				visualBottom = Math.max(visualBottom, blockTop + blockHeight);
+				const blockBottom = blockTop + blockHeight;
+				if (floatIntersectsPageBand(blockTop, blockBottom, metrics, flowHeight)) {
+					visualTop = Math.min(visualTop, blockTop);
+					visualBottom = Math.max(visualBottom, blockBottom);
+				}
 			} else if (block.kind === "textBox" && isPositionedHeaderFooterTextBoxBlock(block) && measure.kind === "textBox") {
-				visualTop = Math.min(visualTop, cursorY);
-				visualBottom = Math.max(visualBottom, cursorY + measure.height);
+				const blockTop = resolveHeaderFooterPositionedVisualTop(block.position, measure.height, cursorY, flowHeight, metrics);
+				const blockBottom = blockTop + measure.height;
+				if (floatIntersectsPageBand(blockTop, blockBottom, metrics, flowHeight)) {
+					visualTop = Math.min(visualTop, blockTop);
+					visualBottom = Math.max(visualBottom, blockBottom);
+				}
 			}
 		}
 	}
@@ -429,4 +453,4 @@ function serializeRunFmt(run) {
 	return JSON.stringify(out);
 }
 //#endregion
-export { calculateHeaderFooterMarginPushBounds, calculateHeaderFooterVisualBounds, convertHeaderFooterPmDocToContent, convertHeaderFooterToContent, normalizeHeaderFooterMeasureBlocks, resolveHeaderFooterVisualTop };
+export { calculateHeaderFooterMarginPushBounds, calculateHeaderFooterVisualBounds, convertHeaderFooterPmDocToContent, convertHeaderFooterToContent, normalizeHeaderFooterMeasureBlocks, resolveHeaderFooterPositionedVisualTop, resolveHeaderFooterVisualTop };

package/dist/layout-bridge/convert/toFlowBlocks.js

@@ -814,6 +814,7 @@ function convertParagraph(node, startPos, options) {
 		id: nextBlockId(),
 		runs,
 		attrs,
+		...pmAttrs.paraId ? { paraId: pmAttrs.paraId } : {},
 		...bookmarkNames && bookmarkNames.length > 0 ? { bookmarks: bookmarkNames } : {},
 		pmStart: startPos,
 		pmEnd: startPos + node.nodeSize

package/dist/layout-bridge/headerFooterLayout.d.ts

@@ -0,0 +1,50 @@
+import { EditorView } from "prosemirror-view";
+
+//#region src/layout-bridge/headerFooterLayout.d.ts
+/**
+ * Drop the cached HF host + span lists. Hosts/painters call this after
+ * a repaint (or HF mode toggle) so the next caret / selection compute
+ * re-walks the DOM. Public so adapters can call it from their painter
+ * commit signal.
+ *
+ * @public
+ */
+declare function invalidateHfDomCache(): void;
+/**
+ * Viewport-relative caret rect for a persistent HF EditorView's selection
+ * head. Resolves against the painter's `data-pm-start`/`data-pm-end` spans
+ * inside `.layout-page-header` / `.layout-page-footer`. The same HF doc is
+ * painted on every page (multi-page docs, titlePg), so this walks every
+ * candidate host and picks the one whose spans bracket the PM head; falls
+ * back to the first so empty paragraphs still resolve to a paragraph anchor.
+ *
+ * Public so the React + Vue adapters can share a single implementation
+ * (`packages/{react,vue}` adapters used to carry byte-identical copies).
+ *
+ * @public
+ */
+declare function computeHfCaretRectFromView(view: EditorView, section: "header" | "footer", doc?: globalThis.Document): {
+  top: number;
+  left: number;
+  height: number;
+} | null;
+/**
+ * Selection-rect set for a non-empty HF selection, projected against the
+ * painted HF spans. Mirror of `computeSelectionRectsFromDom` but scoped to
+ * `.layout-page-header` / `.layout-page-footer` instead of the body. Used
+ * so the painter draws a visible highlight when the user drag-selects
+ * inside a header/footer in edit mode.
+ *
+ * Returns viewport-relative `{top, left, width, height}` rects. Empty
+ * array when selection is collapsed or no painted spans overlap the range.
+ *
+ * @public
+ */
+declare function computeHfSelectionRectsFromView(view: EditorView, section: "header" | "footer", doc?: globalThis.Document): Array<{
+  top: number;
+  left: number;
+  width: number;
+  height: number;
+}>;
+//#endregion
+export { computeHfCaretRectFromView, computeHfSelectionRectsFromView, invalidateHfDomCache };

package/dist/layout-bridge/headerFooterLayout.js

@@ -0,0 +1,216 @@
+//#region src/layout-bridge/headerFooterLayout.ts
+const hfDomCache = {
+	header: null,
+	footer: null
+};
+/**
+* Drop the cached HF host + span lists. Hosts/painters call this after
+* a repaint (or HF mode toggle) so the next caret / selection compute
+* re-walks the DOM. Public so adapters can call it from their painter
+* commit signal.
+*
+* @public
+*/
+function invalidateHfDomCache() {
+	hfDomCache.header = null;
+	hfDomCache.footer = null;
+}
+function getHfDomSnapshot(section, doc) {
+	const hosts = doc.querySelectorAll(`.layout-page-${section}`);
+	if (hosts.length === 0) return null;
+	const win = doc.defaultView;
+	const vpCenter = win ? win.innerHeight / 2 : 0;
+	let host = hosts[0];
+	if (!host) return null;
+	let bestDist = Infinity;
+	for (const h of Array.from(hosts)) {
+		const r = h.getBoundingClientRect();
+		const dist = Math.abs((r.top + r.bottom) / 2 - vpCenter);
+		if (dist < bestDist) {
+			bestDist = dist;
+			host = h;
+		}
+	}
+	const cached = hfDomCache[section];
+	if (cached && cached.host === host && cached.host.isConnected) return cached;
+	const spans = Array.from(host.querySelectorAll("span[data-pm-start][data-pm-end]"));
+	const ranged = Array.from(host.querySelectorAll("[data-pm-start][data-pm-end]"));
+	const snapshot = {
+		host,
+		spans,
+		ranged
+	};
+	hfDomCache[section] = snapshot;
+	return snapshot;
+}
+/**
+* Viewport-relative caret rect for a persistent HF EditorView's selection
+* head. Resolves against the painter's `data-pm-start`/`data-pm-end` spans
+* inside `.layout-page-header` / `.layout-page-footer`. The same HF doc is
+* painted on every page (multi-page docs, titlePg), so this walks every
+* candidate host and picks the one whose spans bracket the PM head; falls
+* back to the first so empty paragraphs still resolve to a paragraph anchor.
+*
+* Public so the React + Vue adapters can share a single implementation
+* (`packages/{react,vue}` adapters used to carry byte-identical copies).
+*
+* @public
+*/
+function computeHfCaretRectFromView(view, section, doc = globalThis.document) {
+	const sel = view.state.selection;
+	if (!sel.empty) return null;
+	const pmPos = sel.head;
+	const snapshot = getHfDomSnapshot(section, doc);
+	if (!snapshot) return null;
+	const { host, spans } = snapshot;
+	for (const span of spans) {
+		const start = Number(span.dataset["pmStart"]);
+		const end = Number(span.dataset["pmEnd"]);
+		if (!Number.isFinite(start) || !Number.isFinite(end)) continue;
+		if (pmPos >= start && pmPos <= end) {
+			const range = host.ownerDocument.createRange();
+			const walker = host.ownerDocument.createTreeWalker(span, NodeFilter.SHOW_TEXT);
+			let remaining = pmPos - start;
+			let textNode = walker.nextNode();
+			while (textNode) {
+				const len = textNode.data.length;
+				if (remaining <= len) {
+					try {
+						range.setStart(textNode, remaining);
+						range.setEnd(textNode, remaining);
+						const rect = range.getClientRects()[0] ?? range.getBoundingClientRect();
+						if (rect && rect.height > 0) return {
+							top: rect.top,
+							left: rect.left,
+							height: rect.height
+						};
+					} catch {}
+					break;
+				}
+				remaining -= len;
+				textNode = walker.nextNode();
+			}
+			const spanRect = span.getBoundingClientRect();
+			const ratio = (pmPos - start) / Math.max(1, end - start);
+			return {
+				top: spanRect.top,
+				left: spanRect.left + spanRect.width * ratio,
+				height: spanRect.height
+			};
+		}
+	}
+	const anchor = host.querySelector(`[data-pm-start="${pmPos}"]`);
+	if (anchor) {
+		const rect = anchor.getBoundingClientRect();
+		return {
+			top: rect.top,
+			left: rect.left + 1,
+			height: rect.height || 16
+		};
+	}
+	const ranged = snapshot.ranged;
+	let bestEl = null;
+	let bestSpan = Infinity;
+	for (const el of ranged) {
+		const start = Number(el.dataset["pmStart"]);
+		const end = Number(el.dataset["pmEnd"]);
+		if (!Number.isFinite(start) || !Number.isFinite(end)) continue;
+		if (pmPos < start || pmPos > end) continue;
+		const span = end - start;
+		if (span < bestSpan) {
+			bestSpan = span;
+			bestEl = el;
+		}
+	}
+	if (bestEl) {
+		const rect = bestEl.getBoundingClientRect();
+		const atEnd = pmPos >= Number(bestEl.dataset["pmEnd"]);
+		return {
+			top: rect.top,
+			left: atEnd ? rect.right : rect.left + 1,
+			height: rect.height || 16
+		};
+	}
+	let trailingEl = null;
+	let trailingStart = -Infinity;
+	for (const el of ranged) {
+		const start = Number(el.dataset["pmStart"]);
+		if (!Number.isFinite(start)) continue;
+		if (start > pmPos) continue;
+		if (start > trailingStart) {
+			trailingStart = start;
+			trailingEl = el;
+		}
+	}
+	if (trailingEl) {
+		const rect = trailingEl.getBoundingClientRect();
+		return {
+			top: rect.top,
+			left: rect.right,
+			height: rect.height || 16
+		};
+	}
+	const hostRect = host.getBoundingClientRect();
+	return {
+		top: hostRect.top + 2,
+		left: hostRect.left + 2,
+		height: 16
+	};
+}
+/**
+* Selection-rect set for a non-empty HF selection, projected against the
+* painted HF spans. Mirror of `computeSelectionRectsFromDom` but scoped to
+* `.layout-page-header` / `.layout-page-footer` instead of the body. Used
+* so the painter draws a visible highlight when the user drag-selects
+* inside a header/footer in edit mode.
+*
+* Returns viewport-relative `{top, left, width, height}` rects. Empty
+* array when selection is collapsed or no painted spans overlap the range.
+*
+* @public
+*/
+function computeHfSelectionRectsFromView(view, section, doc = globalThis.document) {
+	const sel = view.state.selection;
+	if (sel.empty) return [];
+	const from = sel.from;
+	const to = sel.to;
+	const out = [];
+	const snapshot = getHfDomSnapshot(section, doc);
+	if (!snapshot) return out;
+	const { host, spans } = snapshot;
+	for (const spanEl of spans) {
+		const pmStart = Number(spanEl.dataset["pmStart"]);
+		const pmEnd = Number(spanEl.dataset["pmEnd"]);
+		if (!Number.isFinite(pmStart) || !Number.isFinite(pmEnd)) continue;
+		if (pmEnd <= from || pmStart >= to) continue;
+		if (spanEl.classList.contains("layout-run-tab")) {
+			const rect = spanEl.getBoundingClientRect();
+			out.push({
+				top: rect.top,
+				left: rect.left,
+				width: rect.width,
+				height: rect.height
+			});
+			continue;
+		}
+		let textNode = null;
+		if (spanEl.firstChild?.nodeType === Node.TEXT_NODE) textNode = spanEl.firstChild;
+		else if (spanEl.firstChild?.nodeType === Node.ELEMENT_NODE && spanEl.firstChild.tagName === "A" && spanEl.firstChild.firstChild?.nodeType === Node.TEXT_NODE) textNode = spanEl.firstChild.firstChild;
+		if (!textNode) continue;
+		const startChar = Math.max(0, from - pmStart);
+		const endChar = Math.min(textNode.length, to - pmStart);
+		if (startChar >= endChar) continue;
+		const range = host.ownerDocument.createRange();
+		range.setStart(textNode, startChar);
+		range.setEnd(textNode, endChar);
+		for (const rect of Array.from(range.getClientRects())) out.push({
+			top: rect.top,
+			left: rect.left,
+			width: rect.width,
+			height: rect.height
+		});
+	}
+	return out;
+}
+//#endregion
+export { computeHfCaretRectFromView, computeHfSelectionRectsFromView, invalidateHfDomCache };