@stll/folio-core 0.0.1-placeholder.0 → 0.1.0

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

@@ -0,0 +1,17 @@
+import { EditorState, Transaction } from "prosemirror-state";
+import { EditorView } from "prosemirror-view";
+
+//#region src/layout-bridge/convert/wrapEditorViewAsSurface.d.ts
+type Surface = {
+  /** Identity tag — `"body"` for the body PM, `"hf"` for any HF PM. */kind: "body" | "hf"; /** rId of the source HF part; `null` for the body surface. */
+  rId: string | null;
+  getState: () => EditorState | null;
+  getView: () => EditorView | null;
+  focus: () => void;
+  isFocused: () => boolean;
+  dispatch: (tr: Transaction) => void;
+  setSelection: (anchor: number, head?: number) => void;
+};
+declare function wrapEditorViewAsSurface(view: EditorView | null, rId: string): Surface;
+//#endregion
+export { Surface, wrapEditorViewAsSurface };

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

@@ -0,0 +1,36 @@
+import { Selection, TextSelection } from "prosemirror-state";
+//#region src/layout-bridge/convert/wrapEditorViewAsSurface.ts
+/**
+* Surface adapter — gives the pointer pipeline a uniform shape for the body
+* PM and any HF PM, so a single resolved `activeSurface()` can drive click
+* routing / drag-select / focus from one code path.
+*
+* The body PM ref (`HiddenProseMirrorRef`) and the persistent HF PMs (raw
+* `EditorView` from `HiddenHeaderFooterPMs.getView()`) carry different APIs;
+* this adapter projects both onto a small intersection: focus, set selection,
+* get state, dispatch.
+*/
+function wrapEditorViewAsSurface(view, rId) {
+	return {
+		kind: "hf",
+		rId,
+		getState: () => view?.state ?? null,
+		getView: () => view,
+		focus: () => view?.focus(),
+		isFocused: () => view?.hasFocus() ?? false,
+		dispatch: (tr) => view?.dispatch(tr),
+		setSelection(anchor, head) {
+			if (!view) return;
+			const { state, dispatch } = view;
+			const docEnd = state.doc.content.size;
+			const clampedAnchor = Math.max(0, Math.min(anchor, docEnd));
+			const clampedHead = head === void 0 ? clampedAnchor : Math.max(0, Math.min(head, docEnd));
+			const $anchor = state.doc.resolve(clampedAnchor);
+			const $head = state.doc.resolve(clampedHead);
+			const selection = head === void 0 ? Selection.near($anchor) : TextSelection.between($anchor, $head);
+			dispatch(state.tr.setSelection(selection));
+		}
+	};
+}
+//#endregion
+export { wrapEditorViewAsSurface };

package/dist/layout-bridge/dom/clickToPositionDom.d.ts

@@ -0,0 +1,66 @@
+//#region src/layout-bridge/dom/clickToPositionDom.d.ts
+/**
+ * DOM-based Click-to-Position Mapping
+ *
+ * Uses the browser's actual rendered DOM to find ProseMirror positions.
+ * This is more accurate than geometry-based calculation because it uses
+ * the browser's own text rendering with document.elementsFromPoint().
+ *
+ * DOM elements are tagged with data-pm-start and data-pm-end attributes,
+ * enabling binary search to find exact character positions.
+ */
+/**
+ * Find ProseMirror position from a click using DOM-based detection.
+ *
+ * @param container - The pages container element
+ * @param clientX - Client X coordinate from mouse event
+ * @param clientY - Client Y coordinate from mouse event
+ * @param zoom - Current zoom level (default 1)
+ * @returns ProseMirror position, or null if not found
+ */
+declare function clickToPositionDom(container: HTMLElement, clientX: number, clientY: number, zoom?: number): number | null;
+/**
+ * Find exact position within a text span. Defers to the
+ * browser's own hit-tester (`caretPositionFromPoint` /
+ * `caretRangeFromPoint`) — that's what every native text
+ * editor uses, and it correctly handles bidi runs, kerning,
+ * variable fonts, sub-pixel rendering, and line wrap. Falls
+ * back to a per-glyph rect scan when the browser API is
+ * unavailable or returns a point outside this span (e.g. the
+ * caret API resolved to a sibling text node at the same y).
+ */
+declare function findPositionInSpan(spanEl: HTMLElement, clientX: number, clientY: number): number | null;
+/**
+ * Get selection rectangles for a PM range using DOM-based detection.
+ *
+ * @param container - The pages container element
+ * @param from - Start PM position
+ * @param to - End PM position
+ * @param overlayRect - Bounding rect of the selection overlay
+ * @returns Array of selection rectangles in overlay coordinates
+ */
+type DomSelectionRect = {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  pageIndex: number;
+};
+declare function getSelectionRectsFromDom(container: HTMLElement, from: number, to: number, overlayRect: DOMRect): DomSelectionRect[];
+/**
+ * Get caret position from DOM for a PM position.
+ *
+ * @param container - The pages container element
+ * @param pmPos - ProseMirror position
+ * @param overlayRect - Bounding rect of the selection overlay
+ * @returns Caret position in overlay coordinates, or null
+ */
+type DomCaretPosition = {
+  x: number;
+  y: number;
+  height: number;
+  pageIndex: number;
+};
+declare function getCaretPositionFromDom(container: HTMLElement, pmPos: number, overlayRect: DOMRect): DomCaretPosition | null;
+//#endregion
+export { DomCaretPosition, DomSelectionRect, clickToPositionDom, findPositionInSpan, getCaretPositionFromDom, getSelectionRectsFromDom };

package/dist/layout-bridge/dom/clickToPositionDom.js

@@ -0,0 +1,304 @@
+import { closestHtmlElement, findHtmlElement, htmlQueryAll, queryHtmlElement } from "../../utils/domGuards.js";
+//#region src/layout-bridge/dom/clickToPositionDom.ts
+/**
+* DOM-based Click-to-Position Mapping
+*
+* Uses the browser's actual rendered DOM to find ProseMirror positions.
+* This is more accurate than geometry-based calculation because it uses
+* the browser's own text rendering with document.elementsFromPoint().
+*
+* DOM elements are tagged with data-pm-start and data-pm-end attributes,
+* enabling binary search to find exact character positions.
+*/
+/**
+* Find ProseMirror position from a click using DOM-based detection.
+*
+* @param container - The pages container element
+* @param clientX - Client X coordinate from mouse event
+* @param clientY - Client Y coordinate from mouse event
+* @param zoom - Current zoom level (default 1)
+* @returns ProseMirror position, or null if not found
+*/
+function clickToPositionDom(container, clientX, clientY, zoom = 1) {
+	const elements = document.elementsFromPoint(clientX, clientY);
+	const pageEl = findHtmlElement(elements, (el) => el.classList.contains("layout-page"));
+	if (!pageEl) return null;
+	const spanEl = findHtmlElement(elements, (el) => el.tagName === "SPAN" && el.dataset["pmStart"] !== void 0 && el.dataset["pmEnd"] !== void 0);
+	if (spanEl) return findPositionInSpan(spanEl, clientX, clientY);
+	const emptyRun = findHtmlElement(elements, (el) => el.classList.contains("layout-empty-run"));
+	if (emptyRun) {
+		const paragraph = closestHtmlElement(emptyRun, ".layout-paragraph");
+		if (paragraph && paragraph.dataset["pmStart"]) return Number(paragraph.dataset["pmStart"]);
+	}
+	const paragraphEl = findHtmlElement(elements, (el) => el.classList.contains("layout-paragraph") && el.dataset["pmStart"] !== void 0);
+	if (paragraphEl && paragraphEl.dataset["pmStart"]) {
+		const nearestPos = findNearestSpanInElement(paragraphEl, clientX, clientY);
+		if (nearestPos !== null) return nearestPos;
+		return Number(paragraphEl.dataset["pmStart"]);
+	}
+	const cellEl = findHtmlElement(elements, (el) => el.classList.contains("layout-table-cell"));
+	if (cellEl) return findNearestSpanInElement(cellEl, clientX, clientY);
+	return findNearestSpan(container, pageEl, clientX, clientY, zoom);
+}
+/**
+* Find exact position within a text span. Defers to the
+* browser's own hit-tester (`caretPositionFromPoint` /
+* `caretRangeFromPoint`) — that's what every native text
+* editor uses, and it correctly handles bidi runs, kerning,
+* variable fonts, sub-pixel rendering, and line wrap. Falls
+* back to a per-glyph rect scan when the browser API is
+* unavailable or returns a point outside this span (e.g. the
+* caret API resolved to a sibling text node at the same y).
+*/
+function findPositionInSpan(spanEl, clientX, clientY) {
+	const pmStart = Number(spanEl.dataset["pmStart"]);
+	const pmEnd = Number(spanEl.dataset["pmEnd"]);
+	if (spanEl.classList.contains("layout-run-tab")) {
+		const rect = spanEl.getBoundingClientRect();
+		return clientX < (rect.left + rect.right) / 2 ? pmStart : pmEnd;
+	}
+	const textNode = spanEl.firstChild;
+	if (!textNode || textNode.nodeType !== Node.TEXT_NODE) return pmStart;
+	const text = textNode;
+	const textLength = text.length;
+	if (textLength === 0) return pmStart;
+	const ownerDoc = spanEl.ownerDocument;
+	const native = caretOffsetFromPoint(ownerDoc, text, clientX, clientY);
+	if (native !== null) return pmStart + Math.min(native, pmEnd - pmStart);
+	const range = ownerDoc.createRange();
+	let bestOffset = 0;
+	let bestDistance = Number.POSITIVE_INFINITY;
+	for (let i = 0; i < textLength; i++) {
+		range.setStart(text, i);
+		range.setEnd(text, i + 1);
+		const rect = range.getBoundingClientRect();
+		if (rect.width === 0 && rect.height === 0) continue;
+		const midpoint = rect.left + rect.width / 2;
+		const distance = Math.abs(clientX - midpoint);
+		if (distance < bestDistance) {
+			bestDistance = distance;
+			bestOffset = clientX < midpoint ? i : i + 1;
+		}
+	}
+	return pmStart + Math.min(bestOffset, pmEnd - pmStart);
+}
+/**
+* Resolve `(clientX, clientY)` to a character offset
+* inside `text` using the browser's caret hit-tester.
+* Returns `null` if the API is unavailable or resolved to
+* a different node — callers fall back to a glyph-by-glyph
+* scan in that case.
+*/
+function caretOffsetFromPoint(ownerDoc, text, clientX, clientY) {
+	const doc = ownerDoc;
+	if (typeof doc.caretPositionFromPoint === "function") {
+		const pos = doc.caretPositionFromPoint(clientX, clientY);
+		if (pos && pos.offsetNode === text) return pos.offset;
+	}
+	if (typeof doc.caretRangeFromPoint === "function") {
+		const range = doc.caretRangeFromPoint(clientX, clientY);
+		if (range && range.startContainer === text) return range.startOffset;
+	}
+	return null;
+}
+/**
+* Find the nearest text span within a specific element (e.g. a table cell).
+* Used when a click lands in empty space within a cell to keep the cursor
+* inside that cell rather than jumping to a different one.
+*/
+function findNearestSpanInElement(element, clientX, clientY) {
+	const emptyRun = queryHtmlElement(element, ".layout-empty-run");
+	if (emptyRun) {
+		if (emptyRun.dataset["pmStart"]) return Number(emptyRun.dataset["pmStart"]);
+		const paragraph = closestHtmlElement(emptyRun, ".layout-paragraph");
+		if (paragraph && paragraph.dataset["pmStart"]) return Number(paragraph.dataset["pmStart"]);
+	}
+	const lines = htmlQueryAll(element, ".layout-line");
+	let closestLine = null;
+	let closestLineDistance = Infinity;
+	for (const line of lines) {
+		const rect = line.getBoundingClientRect();
+		const centerY = (rect.top + rect.bottom) / 2;
+		const distance = Math.abs(clientY - centerY);
+		if (distance < closestLineDistance) {
+			closestLineDistance = distance;
+			closestLine = line;
+		}
+	}
+	if (!closestLine) {
+		const paragraph = queryHtmlElement(element, ".layout-paragraph[data-pm-start]");
+		if (paragraph?.dataset["pmStart"]) return Number(paragraph.dataset["pmStart"]);
+		if (element.dataset["pmStart"]) return Number(element.dataset["pmStart"]);
+		return null;
+	}
+	const lineSpans = htmlQueryAll(closestLine, "span[data-pm-start][data-pm-end]");
+	if (lineSpans.length === 0) {
+		const paragraph = closestHtmlElement(closestLine, ".layout-paragraph");
+		if (paragraph?.dataset["pmStart"]) return Number(paragraph.dataset["pmStart"]);
+		return null;
+	}
+	let closestSpan = null;
+	let closestSpanDistance = Infinity;
+	for (const spanEl of lineSpans) {
+		const rect = spanEl.getBoundingClientRect();
+		if (clientX >= rect.left && clientX <= rect.right) return findPositionInSpan(spanEl, clientX, clientY);
+		const distance = clientX < rect.left ? rect.left - clientX : clientX - rect.right;
+		if (distance < closestSpanDistance) {
+			closestSpanDistance = distance;
+			closestSpan = spanEl;
+		}
+	}
+	if (!closestSpan) return null;
+	if (clientX < closestSpan.getBoundingClientRect().left) return Number(closestSpan.dataset["pmStart"]);
+	return Number(closestSpan.dataset["pmEnd"]);
+}
+/**
+* Find the nearest text span when click is not directly on text.
+* This handles clicks in margins, between lines, etc.
+*/
+function findNearestSpan(_container, pageEl, clientX, clientY, _zoom) {
+	if (htmlQueryAll(pageEl, ".layout-page-content span[data-pm-start][data-pm-end]").length === 0) {
+		const firstP = htmlQueryAll(pageEl, ".layout-page-content .layout-paragraph").at(0);
+		if (firstP) return Number(firstP.dataset["pmStart"]) || 0;
+		return null;
+	}
+	const lines = htmlQueryAll(pageEl, ".layout-page-content .layout-line");
+	let closestLine = null;
+	let closestLineDistance = Infinity;
+	for (const line of lines) {
+		const rect = line.getBoundingClientRect();
+		const centerY = (rect.top + rect.bottom) / 2;
+		const distance = Math.abs(clientY - centerY);
+		if (distance < closestLineDistance) {
+			closestLineDistance = distance;
+			closestLine = line;
+		}
+	}
+	if (!closestLine) return null;
+	const lineSpans = htmlQueryAll(closestLine, "span[data-pm-start][data-pm-end]");
+	if (lineSpans.length === 0) {
+		const paragraph = closestHtmlElement(closestLine, ".layout-paragraph");
+		if (paragraph?.dataset["pmStart"]) return Number(paragraph.dataset["pmStart"]);
+		return null;
+	}
+	let closestSpan = null;
+	let closestSpanDistance = Infinity;
+	for (const spanEl of lineSpans) {
+		const rect = spanEl.getBoundingClientRect();
+		if (clientX >= rect.left && clientX <= rect.right) return findPositionInSpan(spanEl, clientX, clientY);
+		const distance = clientX < rect.left ? rect.left - clientX : clientX - rect.right;
+		if (distance < closestSpanDistance) {
+			closestSpanDistance = distance;
+			closestSpan = spanEl;
+		}
+	}
+	if (!closestSpan) return null;
+	if (clientX < closestSpan.getBoundingClientRect().left) return Number(closestSpan.dataset["pmStart"]);
+	return Number(closestSpan.dataset["pmEnd"]);
+}
+function getSelectionRectsFromDom(container, from, to, overlayRect) {
+	const rects = [];
+	const spans = htmlQueryAll(container, ".layout-page-content span[data-pm-start][data-pm-end]");
+	for (const spanEl of spans) {
+		const pmStart = Number(spanEl.dataset["pmStart"]);
+		if (Number(spanEl.dataset["pmEnd"]) <= from || pmStart >= to) continue;
+		const textNode = spanEl.firstChild;
+		if (!textNode || textNode.nodeType !== Node.TEXT_NODE) continue;
+		const text = textNode;
+		const ownerDoc = spanEl.ownerDocument;
+		const startChar = Math.max(0, from - pmStart);
+		const endChar = Math.min(text.length, to - pmStart);
+		if (startChar >= endChar) continue;
+		const range = ownerDoc.createRange();
+		range.setStart(text, startChar);
+		range.setEnd(text, endChar);
+		const clientRects = range.getClientRects();
+		const pageEl = closestHtmlElement(spanEl, ".layout-page");
+		const pageIndex = pageEl ? Number(pageEl.dataset["pageNumber"] || 1) - 1 : 0;
+		for (const clientRect of Array.from(clientRects)) rects.push({
+			x: clientRect.left - overlayRect.left,
+			y: clientRect.top - overlayRect.top,
+			width: clientRect.width,
+			height: clientRect.height,
+			pageIndex
+		});
+	}
+	return rects;
+}
+function getCaretPositionFromDom(container, pmPos, overlayRect) {
+	const spans = htmlQueryAll(container, ".layout-page-content span[data-pm-start][data-pm-end]");
+	for (const spanEl of spans) {
+		const pmStart = Number(spanEl.dataset["pmStart"]);
+		const pmEnd = Number(spanEl.dataset["pmEnd"]);
+		if (spanEl.classList.contains("layout-run-tab")) {
+			if (pmPos >= pmStart && pmPos < pmEnd) {
+				const spanRect = spanEl.getBoundingClientRect();
+				const pageEl = closestHtmlElement(spanEl, ".layout-page");
+				const pageIndex = pageEl ? Number(pageEl.dataset["pageNumber"] || 1) - 1 : 0;
+				const lineEl = closestHtmlElement(spanEl, ".layout-line");
+				const lineHeight = lineEl ? lineEl.offsetHeight : 16;
+				return {
+					x: spanRect.left - overlayRect.left,
+					y: spanRect.top - overlayRect.top,
+					height: lineHeight,
+					pageIndex
+				};
+			}
+			continue;
+		}
+		if (pmPos >= pmStart && pmPos <= pmEnd) {
+			const textNode = spanEl.firstChild;
+			if (!textNode || textNode.nodeType !== Node.TEXT_NODE) {
+				const spanRect = spanEl.getBoundingClientRect();
+				const pageEl = closestHtmlElement(spanEl, ".layout-page");
+				const pageIndex = pageEl ? Number(pageEl.dataset["pageNumber"] || 1) - 1 : 0;
+				const lineEl = closestHtmlElement(spanEl, ".layout-line");
+				const lineHeight = lineEl ? lineEl.offsetHeight : 16;
+				return {
+					x: spanRect.left - overlayRect.left,
+					y: spanRect.top - overlayRect.top,
+					height: lineHeight,
+					pageIndex
+				};
+			}
+			const text = textNode;
+			const charIndex = Math.min(pmPos - pmStart, text.length);
+			const range = spanEl.ownerDocument.createRange();
+			range.setStart(text, charIndex);
+			range.setEnd(text, charIndex);
+			const rangeRect = range.getBoundingClientRect();
+			const pageEl = closestHtmlElement(spanEl, ".layout-page");
+			const pageIndex = pageEl ? Number(pageEl.dataset["pageNumber"] || 1) - 1 : 0;
+			const lineEl = closestHtmlElement(spanEl, ".layout-line");
+			const lineHeight = lineEl ? lineEl.offsetHeight : 16;
+			return {
+				x: rangeRect.left - overlayRect.left,
+				y: rangeRect.top - overlayRect.top,
+				height: rangeRect.height || lineHeight,
+				pageIndex
+			};
+		}
+	}
+	const paragraphs = htmlQueryAll(container, ".layout-paragraph");
+	for (const pEl of paragraphs) {
+		const pStart = Number(pEl.dataset["pmStart"]);
+		const pEnd = Number(pEl.dataset["pmEnd"]);
+		if (pmPos >= pStart && pmPos <= pEnd) {
+			const targetEl = pEl.querySelector(".layout-empty-run") || pEl;
+			const rect = targetEl.getBoundingClientRect();
+			const pageEl = closestHtmlElement(pEl, ".layout-page");
+			const pageIndex = pageEl ? Number(pageEl.dataset["pageNumber"] || 1) - 1 : 0;
+			const lineCandidate = targetEl.closest(".layout-line") ?? targetEl;
+			const lineHeight = lineCandidate instanceof HTMLElement ? lineCandidate.offsetHeight : 16;
+			return {
+				x: rect.left - overlayRect.left,
+				y: rect.top - overlayRect.top,
+				height: lineHeight,
+				pageIndex
+			};
+		}
+	}
+	return null;
+}
+//#endregion
+export { clickToPositionDom, findPositionInSpan, getCaretPositionFromDom, getSelectionRectsFromDom };

package/dist/layout-bridge/dom/findBodyPmSpans.d.ts

@@ -0,0 +1,7 @@
+//#region src/layout-bridge/dom/findBodyPmSpans.d.ts
+declare function findBodyPmSpans(container: ParentNode): HTMLElement[];
+declare function findBodyEmptyRuns(container: ParentNode): HTMLElement[];
+declare function findBodyPmAnchors(container: ParentNode): HTMLElement[];
+declare function findBodyPmAnchor(container: ParentNode, pmStart: number): HTMLElement | null;
+//#endregion
+export { findBodyEmptyRuns, findBodyPmAnchor, findBodyPmAnchors, findBodyPmSpans };

package/dist/layout-bridge/dom/findBodyPmSpans.js

@@ -0,0 +1,17 @@
+//#region src/layout-bridge/dom/findBodyPmSpans.ts
+const BODY_SCOPE = ".layout-page-content";
+function findBodyPmSpans(container) {
+	return Array.from(container.querySelectorAll(`${BODY_SCOPE} span[data-pm-start][data-pm-end]`));
+}
+function findBodyEmptyRuns(container) {
+	return Array.from(container.querySelectorAll(`${BODY_SCOPE} .layout-empty-run`));
+}
+function findBodyPmAnchors(container) {
+	return Array.from(container.querySelectorAll(`${BODY_SCOPE} [data-pm-start]`));
+}
+function findBodyPmAnchor(container, pmStart) {
+	if (!Number.isFinite(pmStart)) return null;
+	return container.querySelector(`${BODY_SCOPE} [data-pm-start="${String(pmStart)}"]`);
+}
+//#endregion
+export { findBodyEmptyRuns, findBodyPmAnchor, findBodyPmAnchors, findBodyPmSpans };

package/dist/layout-bridge/dom/findHfPmSpans.d.ts

@@ -0,0 +1,62 @@
+//#region src/layout-bridge/dom/findHfPmSpans.d.ts
+/**
+ * Slot-scoped sibling of `findBodyPmSpans` — locates `data-pm-start` markers
+ * inside a single painted header/footer slot. The pointer pipeline uses these
+ * to translate a click coordinate inside `.layout-page-header[data-rid="…"]`
+ * (or footer) to a PM position on the matching hidden HF EditorView.
+ *
+ * Slot identity is the part-relationship id (`rId`) emitted by the painter on
+ * the HF DOM node — never the `(hdrFtrType, kind)` tuple (two sections that
+ * share a header by rId share both the painted spans and the EditorView).
+ */
+type HfSlotKind = "header" | "footer";
+declare function findHfPmSpans(container: ParentNode, kind: HfSlotKind, rId: string): HTMLElement[];
+declare function findHfPmAnchors(container: ParentNode, kind: HfSlotKind, rId: string): HTMLElement[];
+declare function findHfPmAnchor(container: ParentNode, kind: HfSlotKind, rId: string, pmStart: number): HTMLElement | null;
+/**
+ * Locate the span that covers a PM position for caret rendering, including
+ * `pmEnd` boundaries. `findHfPmAnchor` only matches `data-pm-start="${pos}"`
+ * exactly; when the caret sits at the end of a run / paragraph,
+ * `selection.from` equals that span's `data-pm-end` and the exact lookup
+ * returns null. This helper falls back to a range scan over the slot's
+ * `[data-pm-start][data-pm-end]` spans and reports the edge the caret
+ * should hug so the renderer can pick `left` vs `right`.
+ */
+type HfCaretSpanHit = {
+  element: HTMLElement; /** Which edge of the span's getBoundingClientRect to anchor the caret to. */
+  edge: "left" | "right";
+};
+declare function findHfCaretSpan(container: ParentNode, kind: HfSlotKind, rId: string, pos: number): HfCaretSpanHit | null;
+/**
+ * Slot-scoped click-to-position mapper. `clickToPositionDom`'s fallback
+ * (`findNearestSpan`) is hardcoded to `.layout-page-content` — body — so when
+ * the user clicks HF whitespace (right of the text, between lines, etc.),
+ * the body fallback can return a body PM position that the HF dispatch then
+ * applies to the HF EditorView (clamped) and the caret leaps to an
+ * unrelated HF doc position (Codex #487 P2: 21:02 review).
+ *
+ * Scope everything to the slot element: try the exact-span lookup via
+ * `document.elementsFromPoint` filtered to descendants of `slot`; fall back
+ * to nearest-span-in-line + start/end edge math within the same slot.
+ */
+declare function clickToPositionInHfSlot(container: ParentNode, kind: HfSlotKind, rId: string, clientX: number, clientY: number): number | null;
+declare function findHfSlotForTarget(target: Node | null): {
+  kind: HfSlotKind;
+  rId: string;
+  element: HTMLElement;
+} | null;
+/**
+ * Resolve only the header/footer KIND of the slot under `target`, whether or
+ * not it has an assigned rId yet. `findHfSlotForTarget` matches only a slot
+ * that already carries a `data-rid` (an existing HF part); but the painter also
+ * renders an EMPTY `.layout-page-header` / `.layout-page-footer` box — the
+ * hover-hint and double-click-to-add target — that has no rId. Entering edit
+ * mode to *create* a header needs only the kind (the handler mints the part),
+ * so this looser resolver matches that empty box too.
+ */
+declare function findHfSlotKindForTarget(target: Node | null): {
+  kind: HfSlotKind;
+  element: HTMLElement;
+} | null;
+//#endregion
+export { HfCaretSpanHit, HfSlotKind, clickToPositionInHfSlot, findHfCaretSpan, findHfPmAnchor, findHfPmAnchors, findHfPmSpans, findHfSlotForTarget, findHfSlotKindForTarget };