@stll/folio-core 0.1.2 → 0.2.0

package/dist/layout-bridge/measuring/measureBlocksPipeline.d.ts

@@ -0,0 +1,33 @@
+//#region src/layout-bridge/measuring/measureBlocksPipeline.d.ts
+/**
+ * Floating-aware block measurement pipeline (adapter-facing surface).
+ *
+ * Upstream exposes a generic `measureBlocksWithFloats(blocks, contentWidth,
+ * measureBlock, pageGeometry)` orchestrator: it pre-scans blocks for floating
+ * exclusion zones, groups co-located floats, then walks the blocks calling a
+ * caller-supplied `measureBlock` with the active zones + cumulative Y.
+ *
+ * @packageDocumentation
+ * @public
+ */
+/**
+ * Page geometry (CSS px) used to resolve page/margin-relative anchored objects
+ * into content-area coordinates — currently the vertical anchor of a top-pinned
+ * `topAndBottom` band. Structurally identical to the painter's `PageGeometry`,
+ * declared here rather than imported because layout-bridge must not import from
+ * layout-painter (arch boundary); both paths resolve to identical positions.
+ *
+ * @public
+ */
+type FloatPageGeometry = {
+  pageWidth: number;
+  pageHeight: number;
+  marginLeft: number;
+  marginTop: number;
+  marginRight: number;
+  marginBottom: number;
+  contentWidth: number;
+  contentHeight: number;
+};
+//#endregion
+export { FloatPageGeometry };

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

@@ -0,0 +1,11 @@
+import { document_d_exports } from "../types/document.js";
+import { ColumnLayout } from "../layout-engine/types.js";
+
+//#region src/layout-bridge/sectionColumns.d.ts
+/**
+ * Extract column layout from section properties.
+ * Returns undefined for single-column (default) to avoid unnecessary paginator overhead.
+ */
+declare function getColumns(sectionProps: document_d_exports.SectionProperties | null | undefined): ColumnLayout | undefined;
+//#endregion
+export { getColumns };

package/dist/layout-bridge/sectionColumns.js

@@ -0,0 +1,21 @@
+import { twipsToPixels } from "../paged-layout/sectionGeometry.js";
+//#region src/layout-bridge/sectionColumns.ts
+/** Default column spacing per OOXML spec: 720 twips (0.5 inch). */
+const DEFAULT_COLUMN_SPACE_TWIPS = 720;
+/**
+* Extract column layout from section properties.
+* Returns undefined for single-column (default) to avoid unnecessary paginator overhead.
+*/
+function getColumns(sectionProps) {
+	const count = sectionProps?.columnCount ?? 1;
+	if (count <= 1) return void 0;
+	const columns = {
+		count,
+		gap: twipsToPixels(sectionProps?.columnSpace ?? DEFAULT_COLUMN_SPACE_TWIPS),
+		equalWidth: sectionProps?.equalWidth ?? true
+	};
+	if (sectionProps?.separator !== void 0) columns.separator = sectionProps.separator;
+	return columns;
+}
+//#endregion
+export { getColumns };

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

@@ -0,0 +1,42 @@
+//#region src/layout-bridge/tableInsertHover.d.ts
+/**
+ * Table-insert "+" hover hit-test.
+ *
+ * Pure DOM logic for the floating row/column insert button that shows
+ * when the mouse is near the left or top edge of a layout table. Lives
+ * in core so React + Vue + any future adapter can share the hit-test
+ * and just wire up their own UI rendering of the button.
+ *
+ * The function is gated by `hfEditMode`: tables in inactive HF/body
+ * regions don't surface the affordance. A header table only matches
+ * when the user is editing the header; a body table only matches when
+ * not in any HF edit mode.
+ * @packageDocumentation
+ * @public
+ */
+declare const TABLE_INSERT_EDGE_PROXIMITY = 30;
+declare const TABLE_INSERT_HIDE_DELAY_MS = 200;
+type TableInsertHoverHit = {
+  type: "row" | "column"; /** Client-coordinate anchor for the button. Caller converts to its UI frame. */
+  clientX: number;
+  clientY: number; /** PM position of the cell the button targets. */
+  cellPmPos: number;
+};
+type TableInsertHoverInput = {
+  mouseX: number;
+  mouseY: number;
+  pagesContainer: HTMLElement; /** Element under the cursor at the time of the event (e.target). */
+  target: HTMLElement;
+  hfEditMode: "header" | "footer" | null; /** Override edge proximity in pixels (defaults to TABLE_INSERT_EDGE_PROXIMITY). */
+  edgeProximity?: number;
+};
+/**
+ * Detect whether a mousemove should surface a row/column insert "+" button.
+ *
+ * Returns the button anchor + target cell PM position, or `null` if the
+ * mouse isn't near a row's left edge or a column's top edge — or if the
+ * relevant table belongs to an inactive HF/body region.
+ */
+declare function detectTableInsertHover(input: TableInsertHoverInput): TableInsertHoverHit | null;
+//#endregion
+export { TABLE_INSERT_EDGE_PROXIMITY, TABLE_INSERT_HIDE_DELAY_MS, TableInsertHoverHit, TableInsertHoverInput, detectTableInsertHover };

package/dist/layout-bridge/tableInsertHover.js

@@ -0,0 +1,102 @@
+//#region src/layout-bridge/tableInsertHover.ts
+/**
+* Table-insert "+" hover hit-test.
+*
+* Pure DOM logic for the floating row/column insert button that shows
+* when the mouse is near the left or top edge of a layout table. Lives
+* in core so React + Vue + any future adapter can share the hit-test
+* and just wire up their own UI rendering of the button.
+*
+* The function is gated by `hfEditMode`: tables in inactive HF/body
+* regions don't surface the affordance. A header table only matches
+* when the user is editing the header; a body table only matches when
+* not in any HF edit mode.
+* @packageDocumentation
+* @public
+*/
+const TABLE_INSERT_EDGE_PROXIMITY = 30;
+const TABLE_INSERT_HIDE_DELAY_MS = 200;
+const ROW_BUTTON_OFFSET_X = 24;
+const ROW_BUTTON_OFFSET_Y = 10;
+const COL_BUTTON_OFFSET_X = 10;
+const COL_BUTTON_OFFSET_Y = 24;
+/**
+* Detect whether a mousemove should surface a row/column insert "+" button.
+*
+* Returns the button anchor + target cell PM position, or `null` if the
+* mouse isn't near a row's left edge or a column's top edge — or if the
+* relevant table belongs to an inactive HF/body region.
+*/
+function detectTableInsertHover(input) {
+	const { mouseX, mouseY, pagesContainer, target, hfEditMode, edgeProximity = 30 } = input;
+	const tableSelector = ".layout-table";
+	const rowSelector = ".layout-table-row";
+	const cellSelector = ".layout-table-cell";
+	const headerSelector = ".layout-page-header";
+	const footerSelector = ".layout-page-footer";
+	const tableIsActive = (t) => {
+		const inHeader = !!t.closest(headerSelector);
+		const inFooter = !!t.closest(footerSelector);
+		if (!inHeader && !inFooter) return !hfEditMode;
+		if (inHeader) return hfEditMode === "header";
+		return hfEditMode === "footer";
+	};
+	let tableEl = target.closest(tableSelector);
+	if (tableEl && !tableIsActive(tableEl)) tableEl = null;
+	if (!tableEl) {
+		const tables = pagesContainer.querySelectorAll(tableSelector);
+		for (const t of Array.from(tables)) {
+			if (!tableIsActive(t)) continue;
+			const r = t.getBoundingClientRect();
+			const nearLeft = mouseX >= r.left - edgeProximity && mouseX < r.left;
+			const nearTop = mouseY >= r.top - edgeProximity && mouseY < r.top;
+			const withinX = mouseX >= r.left - edgeProximity && mouseX <= r.right;
+			const withinY = mouseY >= r.top - edgeProximity && mouseY <= r.bottom;
+			if (nearLeft && withinY || nearTop && withinX) {
+				tableEl = t;
+				break;
+			}
+		}
+	}
+	if (!tableEl) return null;
+	const tableRect = tableEl.getBoundingClientRect();
+	const nearLeftEdge = mouseX < tableRect.left + edgeProximity && mouseX >= tableRect.left - edgeProximity;
+	const nearTopEdge = mouseY < tableRect.top + edgeProximity && mouseY >= tableRect.top - edgeProximity;
+	if (!nearLeftEdge && !nearTopEdge) return null;
+	const rows = tableEl.querySelectorAll(`:scope > ${rowSelector}`);
+	if (rows.length === 0) return null;
+	const getCellPmPos = (el) => el ? Number(el.dataset["pmStart"]) || 0 : 0;
+	if (nearLeftEdge) for (const row of Array.from(rows)) {
+		const rowRect = row.getBoundingClientRect();
+		if (mouseY >= rowRect.top && mouseY <= rowRect.bottom) {
+			const pmPos = getCellPmPos(row.querySelector(cellSelector));
+			if (!pmPos) break;
+			return {
+				type: "row",
+				clientX: tableRect.left - ROW_BUTTON_OFFSET_X,
+				clientY: rowRect.top + rowRect.height / 2 - ROW_BUTTON_OFFSET_Y,
+				cellPmPos: pmPos
+			};
+		}
+	}
+	const firstRow = rows[0];
+	if (nearTopEdge && firstRow) {
+		const cells = firstRow.querySelectorAll(`:scope > ${cellSelector}`);
+		for (const cell of Array.from(cells)) {
+			const cellRect = cell.getBoundingClientRect();
+			if (mouseX >= cellRect.left && mouseX <= cellRect.right) {
+				const pmPos = getCellPmPos(cell);
+				if (!pmPos) break;
+				return {
+					type: "column",
+					clientX: cellRect.left + cellRect.width / 2 - COL_BUTTON_OFFSET_X,
+					clientY: tableRect.top - COL_BUTTON_OFFSET_Y,
+					cellPmPos: pmPos
+				};
+			}
+		}
+	}
+	return null;
+}
+//#endregion
+export { TABLE_INSERT_EDGE_PROXIMITY, TABLE_INSERT_HIDE_DELAY_MS, detectTableInsertHover };

package/dist/layout-engine/index.d.ts

@@ -2,6 +2,7 @@ import { BlockId, BorderStyle, CellBorderSpec, CellBorders, ColumnBreakBlock, Co
 import { PageState, Paginator, PaginatorOptions, createPaginator } from "./paginator.js";
 import { KeepNextChain, calculateChainHeight, computeKeepNextChains, getMidChainIndices, hasKeepLines, hasPageBreakBefore } from "./keep-together.js";
 import { BreakDecision, SectionState, applyPendingToActive, createInitialSectionState, getEffectiveColumns, getEffectiveMargins, getEffectivePageSize, scheduleSectionBreak } from "./section-breaks.js";
+import { assertExhaustiveFlowBlock, findPageIndexContainingPmPos } from "./pmPageIndex.js";
 
 //#region src/layout-engine/index.d.ts
 type SectionLayoutConfig = {
@@ -41,4 +42,4 @@ declare function layoutDocument(blocks: FlowBlock[], measures: Measure[], option
  */
 declare function getHeaderRowsHeight(measure: TableMeasure, headerRowCount: number): number;
 //#endregion
-export { BlockId, BorderStyle, type BreakDecision, CellBorderSpec, CellBorders, ColumnBreakBlock, ColumnBreakMeasure, ColumnLayout, DEFAULT_TEXTBOX_MARGINS, DEFAULT_TEXTBOX_WIDTH, DocumentPosition, FOOTNOTE_ENTRY_MARGIN_BOTTOM, FOOTNOTE_FALLBACK_LINE_HEIGHT, FOOTNOTE_SEPARATOR_HEIGHT, FieldRun, FloatingTablePosition, FlowBlock, FootnoteContent, Fragment, FragmentBase, HeaderFooterContent, HeaderFooterContentHeights, HeaderFooterLayout, HitTestResult, HyperlinkInfo, ImageBlock, ImageFragment, ImageMeasure, ImageRun, ImageRunPosition, type KeepNextChain, Layout, LayoutOptions, LineBreakRun, ListNumPr, MathRun, Measure, MeasuredLine, Page, PageBreakBlock, PageBreakMeasure, PageHeaderFooterRefs, PageMargins, type PageState, type Paginator, type PaginatorOptions, ParagraphAttrs, ParagraphBlock, ParagraphBorders, ParagraphFragment, ParagraphIndent, ParagraphMeasure, ParagraphSpacing, Run, RunFormatting, SdtGroup, SectionBreakBlock, SectionBreakMeasure, SectionLayoutConfig, type SectionState, TabAlignment, TabRun, TabStop, TableBlock, TableCell, TableCellMeasure, TableFragment, TableMeasure, TableRow, TableRowMeasure, TextBoxBlock, TextBoxFlowAttrs, TextBoxFragment, TextBoxMeasure, TextRun, applyContextualSpacing, applyPendingToActive, calculateChainHeight, collectSectionConfigs, computeKeepNextChains, createInitialSectionState, createPaginator, floatingTextBoxReservesBand, floatingTextBoxWrapsText, getEffectiveColumns, getEffectiveMargins, getEffectivePageSize, getHeaderRowsHeight, getMidChainIndices, hasKeepLines, hasPageBreakBefore, isFloatingImageRun, isFloatingTextBoxBlock, isTextWrappingFloatingImageRun, layoutDocument, scheduleSectionBreak };
+export { BlockId, BorderStyle, type BreakDecision, CellBorderSpec, CellBorders, ColumnBreakBlock, ColumnBreakMeasure, ColumnLayout, DEFAULT_TEXTBOX_MARGINS, DEFAULT_TEXTBOX_WIDTH, DocumentPosition, FOOTNOTE_ENTRY_MARGIN_BOTTOM, FOOTNOTE_FALLBACK_LINE_HEIGHT, FOOTNOTE_SEPARATOR_HEIGHT, FieldRun, FloatingTablePosition, FlowBlock, FootnoteContent, Fragment, FragmentBase, HeaderFooterContent, HeaderFooterContentHeights, HeaderFooterLayout, HitTestResult, HyperlinkInfo, ImageBlock, ImageFragment, ImageMeasure, ImageRun, ImageRunPosition, type KeepNextChain, Layout, LayoutOptions, LineBreakRun, ListNumPr, MathRun, Measure, MeasuredLine, Page, PageBreakBlock, PageBreakMeasure, PageHeaderFooterRefs, PageMargins, type PageState, type Paginator, type PaginatorOptions, ParagraphAttrs, ParagraphBlock, ParagraphBorders, ParagraphFragment, ParagraphIndent, ParagraphMeasure, ParagraphSpacing, Run, RunFormatting, SdtGroup, SectionBreakBlock, SectionBreakMeasure, SectionLayoutConfig, type SectionState, TabAlignment, TabRun, TabStop, TableBlock, TableCell, TableCellMeasure, TableFragment, TableMeasure, TableRow, TableRowMeasure, TextBoxBlock, TextBoxFlowAttrs, TextBoxFragment, TextBoxMeasure, TextRun, applyContextualSpacing, applyPendingToActive, assertExhaustiveFlowBlock, calculateChainHeight, collectSectionConfigs, computeKeepNextChains, createInitialSectionState, createPaginator, findPageIndexContainingPmPos, floatingTextBoxReservesBand, floatingTextBoxWrapsText, getEffectiveColumns, getEffectiveMargins, getEffectivePageSize, getHeaderRowsHeight, getMidChainIndices, hasKeepLines, hasPageBreakBefore, isFloatingImageRun, isFloatingTextBoxBlock, isTextWrappingFloatingImageRun, layoutDocument, scheduleSectionBreak };

package/dist/layout-engine/index.js

@@ -6,6 +6,7 @@ import { getParagraphFragmentPmRange } from "./paragraphFragmentRange.js";
 import { buildTableRowBreakInfo, snapRowBreak } from "./tableRowBreak.js";
 import { bandFragmentX, bandTopContentY, isPageFrameRelativeAnchor } from "./textBoxFlow.js";
 import { applyPendingToActive, createInitialSectionState, getEffectiveColumns, getEffectiveMargins, getEffectivePageSize, scheduleSectionBreak } from "./section-breaks.js";
+import { assertExhaustiveFlowBlock, findPageIndexContainingPmPos } from "./pmPageIndex.js";
 import { panic } from "better-result";
 //#region src/layout-engine/index.ts
 /**
@@ -688,4 +689,4 @@ function handleSectionBreak(_block, paginator, nextSectionConfig, nextSectionTyp
 	paginator.updateColumns(nextSectionConfig.columns ?? DEFAULT_COLUMNS);
 }
 //#endregion
-export { DEFAULT_TEXTBOX_MARGINS, DEFAULT_TEXTBOX_WIDTH, FOOTNOTE_ENTRY_MARGIN_BOTTOM, FOOTNOTE_FALLBACK_LINE_HEIGHT, FOOTNOTE_SEPARATOR_HEIGHT, applyContextualSpacing, applyPendingToActive, calculateChainHeight, collectSectionConfigs, computeKeepNextChains, createInitialSectionState, createPaginator, floatingTextBoxReservesBand, floatingTextBoxWrapsText, getEffectiveColumns, getEffectiveMargins, getEffectivePageSize, getHeaderRowsHeight, getMidChainIndices, hasKeepLines, hasPageBreakBefore, isFloatingImageRun, isFloatingTextBoxBlock, isTextWrappingFloatingImageRun, layoutDocument, scheduleSectionBreak };
+export { DEFAULT_TEXTBOX_MARGINS, DEFAULT_TEXTBOX_WIDTH, FOOTNOTE_ENTRY_MARGIN_BOTTOM, FOOTNOTE_FALLBACK_LINE_HEIGHT, FOOTNOTE_SEPARATOR_HEIGHT, applyContextualSpacing, applyPendingToActive, assertExhaustiveFlowBlock, calculateChainHeight, collectSectionConfigs, computeKeepNextChains, createInitialSectionState, createPaginator, findPageIndexContainingPmPos, floatingTextBoxReservesBand, floatingTextBoxWrapsText, getEffectiveColumns, getEffectiveMargins, getEffectivePageSize, getHeaderRowsHeight, getMidChainIndices, hasKeepLines, hasPageBreakBefore, isFloatingImageRun, isFloatingTextBoxBlock, isTextWrappingFloatingImageRun, layoutDocument, scheduleSectionBreak };

package/dist/layout-engine/measure/lineBreaks.d.ts

@@ -0,0 +1,10 @@
+//#region src/layout-engine/measure/lineBreaks.d.ts
+/**
+ * Indices in `text` where a line may end. Latin text breaks after
+ * whitespace or hyphen; CJK text can break after every ideograph so a
+ * partial line is filled instead of pushing the whole run to the next line.
+ */
+declare function findWordBreaks(text: string): number[];
+declare function isBreakChar(char: string | undefined): boolean;
+//#endregion
+export { findWordBreaks, isBreakChar };

package/dist/layout-engine/measure/lineBreaks.js

@@ -0,0 +1,30 @@
+import { isCjkCodePoint } from "../../utils/scriptSegments.js";
+//#region src/layout-engine/measure/lineBreaks.ts
+/**
+* Indices in `text` where a line may end. Latin text breaks after
+* whitespace or hyphen; CJK text can break after every ideograph so a
+* partial line is filled instead of pushing the whole run to the next line.
+*/
+function findWordBreaks(text) {
+	const breaks = [];
+	for (let index = 0; index < text.length;) {
+		const codePoint = text.codePointAt(index);
+		if (codePoint === void 0) break;
+		const charLength = codePoint > 65535 ? 2 : 1;
+		const char = text[index];
+		if (char === " " || char === "-" || char === "	") breaks.push(index + charLength);
+		else if (isCjkCodePoint(codePoint)) breaks.push(index + charLength);
+		index += charLength;
+	}
+	return breaks;
+}
+function isBreakChar(char) {
+	if (char === void 0) return false;
+	if (char === " " || char === "-" || char === "	") return true;
+	const codePoint = char.codePointAt(0);
+	if (codePoint === void 0) return false;
+	if (char >= "\udc00" && char <= "\udfff") return true;
+	return isCjkCodePoint(codePoint);
+}
+//#endregion
+export { findWordBreaks, isBreakChar };

package/dist/layout-engine/measure/measureContainer.js

@@ -1,7 +1,7 @@
 import { setMeasureProvider } from "./measureProvider.js";
 import { buildFontString, getResolvedData, ptToPx } from "./measureHelpers.js";
-import { getCachedFontMetrics, getCachedTextWidth, getTextWidthCacheGeneration, setCachedFontMetrics, setCachedTextWidth } from "./cache.js";
 import { hasCjk, isCjkCodePoint, segmentByScript } from "../../utils/scriptSegments.js";
+import { getCachedFontMetrics, getCachedTextWidth, getTextWidthCacheGeneration, setCachedFontMetrics, setCachedTextWidth } from "./cache.js";
 import { canPrefetchMeasurement, prefetchMeasurement } from "./measureWorker.js";
 import { WORKER_FONT_FINGERPRINT_TEXT, countCodePoints } from "./measureWorkerProtocol.js";
 import { panic } from "better-result";

package/dist/layout-engine/measure/measureParagraph.js

@@ -1,13 +1,15 @@
 import { getFontMetrics, measureRun, measureTextWidth } from "./measureProvider.js";
-import "../../utils/fontResolver.js";
+import { CJK_FALLBACK_FONT_FAMILY, isCjkFont } from "../../utils/fontResolver.js";
 import { buildRunFontStyle, ptToPx } from "./measureHelpers.js";
 import { calculateTabWidth, pixelsToTwips } from "../../prosemirror/utils/tabCalculator.js";
 import { inlineImageBoundingBox } from "../../utils/rotationBoundingBox.js";
+import { hasCjk } from "../../utils/scriptSegments.js";
 import { measuredLineAdvance } from "../lineFlow.js";
 import { isFloatingImageRun } from "../types.js";
 import { clampFloatingWrapMargins } from "./clampFloatingWrapMargins.js";
 import { getFloatingAvailableWidth, getFloatingMargins } from "./floatingZones.js";
 import { getListMarkerInlineWidth } from "./listMarkerWidth.js";
+import { findWordBreaks, isBreakChar } from "./lineBreaks.js";
 //#region src/layout-engine/measure/measureParagraph.ts
 /**
 * Paragraph measurement module
@@ -46,6 +48,35 @@ function runToFontStyle(run) {
 	return buildRunFontStyle(run, DEFAULT_FONT_FAMILY, DEFAULT_FONT_SIZE);
 }
 /**
+* Line-HEIGHT style for a text run. Word derives a CJK line's height from an
+* East-Asian face, not the run's ascii font: real documents routinely put CJK
+* glyphs in runs whose ascii/eastAsia fonts are Latin (e.g. `w:eastAsia`
+* "Century"), and Word font-links those glyphs to the default East-Asian face
+* and uses its taller single-line height (≈1.303 vs the ≈1.15 Latin default).
+*
+* When the run holds CJK text, swap `fontFamily` to the face whose
+* `singleLineRatio` Word would actually use: the run's `w:eastAsia` font when
+* it is a real CJK face, the run's own ascii font when THAT is a CJK face, or
+* `CJK_FALLBACK_FONT_FAMILY` otherwise. Non-CJK runs return `baseStyle`
+* unchanged, so Latin-only documents are unaffected by construction.
+*
+* The result feeds `updateMaxFont` (line height) ONLY — width measurement
+* keeps the base style so wrapping is untouched.
+*/
+function cjkLineHeightStyle(run, baseStyle) {
+	if (!run.text || !hasCjk(run.text)) return baseStyle;
+	const eastAsia = baseStyle.eastAsiaFontFamily;
+	if (eastAsia !== void 0 && isCjkFont(eastAsia)) return {
+		...baseStyle,
+		fontFamily: eastAsia
+	};
+	if (isCjkFont(baseStyle.fontFamily ?? DEFAULT_FONT_FAMILY)) return baseStyle;
+	return {
+		...baseStyle,
+		fontFamily: CJK_FALLBACK_FONT_FAMILY
+	};
+}
+/**
 * Calculate typography metrics from font size and spacing settings
 *
 * @param fontSize - Font size in points
@@ -207,18 +238,34 @@ function isEmptyTextRun(run) {
 * desync measurer and painter on tab advance for paragraphs with a tab
 * preceding a floating image.
 */
+function isBlockLayoutImageRun(run) {
+	return run.wrapType === "topAndBottom" || run.displayMode === "block";
+}
 function measureInlineWidthAfterTab(runs, tabIndex, fieldValues) {
 	let width = 0;
 	for (let i = tabIndex + 1; i < runs.length; i++) {
 		const next = runs[i];
 		if (!next || isTabRun(next) || isLineBreakRun(next)) break;
+		if (isImageRun(next)) {
+			if (isBlockLayoutImageRun(next)) break;
+			if (!isFloatingImageRun(next)) width += inlineImageBoundingBox(next).width || 0;
+			continue;
+		}
 		if (isTextRun(next)) width += measureTextWidth(next.text || "", runToFontStyle(next));
 		else if (isFieldRun(next)) width += measureTextWidth(fieldMeasureText(next, fieldValues), runToFontStyle(next));
-		else if (isImageRun(next) && !isFloatingImageRun(next)) width += next.width || 0;
 		else if (isMathRun(next)) width += measureTextWidth(next.plainText || "[equation]", runToFontStyle(next));
 	}
 	return width;
 }
+function hasFollowingTabOnLine(runs, tabIndex) {
+	for (let i = tabIndex + 1; i < runs.length; i++) {
+		const next = runs[i];
+		if (!next || isLineBreakRun(next)) break;
+		if (isImageRun(next) && isBlockLayoutImageRun(next)) break;
+		if (isTabRun(next)) return true;
+	}
+	return false;
+}
 /**
 * Width of the inline content preceding the first `.` in the runs that follow
 * a tab, used to anchor `decimal` tab stops. Mirrors `getTextAfterTab` +
@@ -249,21 +296,6 @@ function measureDecimalPrefixWidthAfterTab(runs, tabIndex, fieldValues) {
 	if (decimalIndex === -1 || !firstRun) return 0;
 	return measureTextWidth(text.slice(0, decimalIndex), runToFontStyle(firstRun));
 }
-/**
-* Find word break points in text
-* Returns array of indices where words end (after space/punctuation)
-*/
-function findWordBreaks(text) {
-	const breaks = [];
-	for (let i = 0; i < text.length; i++) {
-		const char = text[i];
-		if (char === " " || char === "-" || char === "	") breaks.push(i + 1);
-	}
-	return breaks;
-}
-function isBreakChar(char) {
-	return char === " " || char === "-" || char === "	";
-}
 function isSpaceOrTab(char) {
 	return char === " " || char === "	";
 }
@@ -535,7 +567,11 @@ function measureParagraph(block, maxWidth, options) {
 		if (!currentLine.maxFontMetrics || fontSize > currentLine.maxFontSize) {
 			currentLine.maxFontSize = fontSize;
 			currentLine.maxFontMetrics = getFontMetrics(style);
+			return;
 		}
+		if (fontSize !== currentLine.maxFontSize || !isCjkFont(style.fontFamily ?? "")) return;
+		const metrics = getFontMetrics(style);
+		if (metrics.singleLineRatio > currentLine.maxFontMetrics.singleLineRatio) currentLine.maxFontMetrics = metrics;
 	};
 	for (let runIndex = 0; runIndex < runs.length; runIndex++) {
 		const run = runs[runIndex];
@@ -551,13 +587,17 @@ function measureParagraph(block, maxWidth, options) {
 			const followingWidth = measureInlineWidthAfterTab(runs, runIndex, options?.fieldValues);
 			const decimalPrefixWidth = measureDecimalPrefixWidthAfterTab(runs, runIndex, options?.fieldValues);
 			const lineX = currentLine.width + currentLine.leftOffset;
-			const tabWidth = calculateTabWidth(indentLeft + (lines.length === 0 ? firstLineOffset + markerInlineWidth : 0) + lineX, {
+			const isFirstLine = lines.length === 0;
+			const contentX = indentLeft + (isFirstLine ? firstLineOffset + markerInlineWidth : 0) + lineX;
+			let tabWidth = calculateTabWidth(contentX, {
 				...attrs?.tabs !== void 0 ? { explicitStops: attrs.tabs } : {},
 				leftIndent: pixelsToTwips(indentLeft)
 			}, {
 				followingWidth,
 				decimalPrefixWidth
 			}).width;
+			const lineRightEdgeX = indentLeft + (isFirstLine ? firstLineOffset + markerInlineWidth : 0) + currentLine.availableWidth + currentLine.leftOffset;
+			if (!hasFollowingTabOnLine(runs, runIndex) && (tabWidth > 0 || followingWidth > 0) && contentX + tabWidth + followingWidth > lineRightEdgeX + WIDTH_TOLERANCE) tabWidth = Math.max(1, lineRightEdgeX - contentX - followingWidth);
 			if (currentLine.width + tabWidth > currentLine.availableWidth + WIDTH_TOLERANCE) {
 				startNewLine(runIndex, 0);
 				updateMaxFont(style);
@@ -634,7 +674,8 @@ function measureParagraph(block, maxWidth, options) {
 			const textRun = run;
 			const text = textRun.text;
 			const style = runToFontStyle(textRun);
-			updateMaxFont(style);
+			const lineHeightStyle = cjkLineHeightStyle(textRun, style);
+			updateMaxFont(lineHeightStyle);
 			if (!text || text.length === 0) {
 				currentLine.toRun = runIndex;
 				currentLine.toChar = 0;
@@ -658,7 +699,7 @@ function measureParagraph(block, maxWidth, options) {
 						if (bestEnd === 0) {
 							if (currentLine.width > 0) {
 								startNewLine(runIndex, charIndex + chunkStart);
-								updateMaxFont(style);
+								updateMaxFont(lineHeightStyle);
 								continue;
 							}
 							bestEnd = 1;
@@ -671,7 +712,7 @@ function measureParagraph(block, maxWidth, options) {
 						chunkStart = chunkEnd;
 						if (chunkStart < word.length) {
 							startNewLine(runIndex, charIndex + chunkStart);
-							updateMaxFont(style);
+							updateMaxFont(lineHeightStyle);
 						}
 					}
 					charIndex = nextBreak;
@@ -681,7 +722,7 @@ function measureParagraph(block, maxWidth, options) {
 				const glueWidth = rawGlueWidth > 0 && wordWidth + rawGlueWidth <= getPostWrapAvailableWidth() + WIDTH_TOLERANCE ? rawGlueWidth : 0;
 				if (currentLine.width > 0 && currentLine.width + wordWidth + glueWidth > currentLine.availableWidth + WIDTH_TOLERANCE) {
 					startNewLine(runIndex, charIndex);
-					updateMaxFont(style);
+					updateMaxFont(lineHeightStyle);
 				}
 				currentLine.width += wordWidth;
 				currentLine.toRun = runIndex;

package/dist/layout-engine/pmPageIndex.d.ts

@@ -0,0 +1,24 @@
+import { Layout } from "./types.js";
+
+//#region src/layout-engine/pmPageIndex.d.ts
+/**
+ * Exhaustiveness guard for `FlowBlock`-shaped switches. Call from the
+ * `default` arm with the still-typed value; TypeScript will refuse to
+ * compile if any variant of `FlowBlock` was missed. The thrown error
+ * names the calling site so runtime failures (e.g. an old adapter
+ * compiled against a newer core) point future debuggers at the contract.
+ */
+declare function assertExhaustiveFlowBlock(block: never, site: string): never;
+/**
+ * Page index (0-based) whose layout fragments cover `pmPos`, or null if none.
+ * Used when the painted DOM may not yet have `[data-pm-start]` for this position (virtualization).
+ *
+ * Range semantics: `[pmStart, pmEnd)` — half-open, matching ProseMirror's
+ * `pos + nodeSize` convention. Boundary positions belong to the next fragment,
+ * so when a fragment ends at the same position the next one starts, the next
+ * fragment wins (avoids returning the previous page for the start of the
+ * next paragraph).
+ */
+declare function findPageIndexContainingPmPos(layout: Layout, pmPos: number): number | null;
+//#endregion
+export { assertExhaustiveFlowBlock, findPageIndexContainingPmPos };

package/dist/layout-engine/pmPageIndex.js

@@ -0,0 +1,37 @@
+//#region src/layout-engine/pmPageIndex.ts
+/**
+* Exhaustiveness guard for `FlowBlock`-shaped switches. Call from the
+* `default` arm with the still-typed value; TypeScript will refuse to
+* compile if any variant of `FlowBlock` was missed. The thrown error
+* names the calling site so runtime failures (e.g. an old adapter
+* compiled against a newer core) point future debuggers at the contract.
+*/
+function assertExhaustiveFlowBlock(block, site) {
+	const kind = block.kind ?? "<unknown>";
+	throw new Error(`${site}: unhandled FlowBlock kind "${kind}". Add the case alongside the other FlowBlock switches (see types.ts).`);
+}
+/**
+* Page index (0-based) whose layout fragments cover `pmPos`, or null if none.
+* Used when the painted DOM may not yet have `[data-pm-start]` for this position (virtualization).
+*
+* Range semantics: `[pmStart, pmEnd)` — half-open, matching ProseMirror's
+* `pos + nodeSize` convention. Boundary positions belong to the next fragment,
+* so when a fragment ends at the same position the next one starts, the next
+* fragment wins (avoids returning the previous page for the start of the
+* next paragraph).
+*/
+function findPageIndexContainingPmPos(layout, pmPos) {
+	for (let pi = 0; pi < layout.pages.length; pi++) {
+		const page = layout.pages[pi];
+		if (!page) continue;
+		for (const frag of page.fragments) {
+			if (frag.pmStart == null) continue;
+			const start = frag.pmStart;
+			const end = frag.pmEnd ?? start + 1;
+			if (pmPos >= start && pmPos < end) return pi;
+		}
+	}
+	return null;
+}
+//#endregion
+export { assertExhaustiveFlowBlock, findPageIndexContainingPmPos };

package/dist/layout-engine/types.d.ts

@@ -365,7 +365,8 @@ type ParagraphAttrs = {
  */
 type ParagraphBlock = {
   kind: "paragraph";
-  id: BlockId;
+  id: BlockId; /** Stable Word `w14:paraId` / PM `paraId`, when available. */
+  paraId?: string;
   runs: Run[];
   attrs?: ParagraphAttrs;
   /** Names of bookmarks anchored to this paragraph; used to map a bookmark to

package/dist/layout-painter/imageLayout.d.ts

@@ -0,0 +1,101 @@
+import { FlowBlock, Measure } from "../layout-engine/types.js";
+import { BlockLookup } from "./index.js";
+import { WrapType } from "../docx/wrapTypes.js";
+import { ImageAttrs } from "../prosemirror/schema/nodes.js";
+
+//#region src/layout-painter/imageLayout.d.ts
+/**
+ * Anchored wrap-type targets — the OOXML wrap types except `inline`.
+ * Defined locally because the fork's `ImageExtension` does not export the
+ * layout-target vocabulary the way upstream does.
+ */
+type AnchorWrapType = Exclude<WrapType, "inline">;
+/**
+ * User-facing layout choices that mirror Word's Wrap Text menu. `squareLeft`
+ * floats the image left (text wraps on the right); `squareRight` floats it
+ * right; `inline` flows it as a glyph; the remaining targets are 1:1 with
+ * their OOXML wrap types.
+ */
+type ImageLayoutTarget = AnchorWrapType | "squareLeft" | "squareRight" | "inline";
+declare const LAYOUT_IMAGE_CLASSES: {
+  /** Inline image rendered inside `.layout-line`. */readonly runImage: "layout-run-image"; /** Block (centered, topAndBottom) image. */
+  readonly blockImage: "layout-block-image"; /** Anchored image rendered in the page-level floating layer. */
+  readonly pageFloatingImage: "layout-page-floating-image"; /** Anchored image rendered inside a table cell's floating layer. */
+  readonly cellFloatingImage: "layout-cell-floating-image";
+  readonly pageContent: "layout-page-content";
+  readonly paragraph: "layout-paragraph";
+};
+/**
+ * Walk up from a click target to the nearest rendered image element, returning
+ * just the element (no PM position parsing). Used by the left-click selection
+ * path in both adapters — `data-pm-start` is read separately by callers that
+ * need the position. Returns the element when the click was directly on an
+ * inline `<img.layout-run-image>` OR inside one of the container classes
+ * registered in `LAYOUT_IMAGE_CLASSES`.
+ */
+declare function findImageElement(target: EventTarget | null): HTMLElement | null;
+/**
+ * Capture the rendered position of an inline image as EMUs, normalised to
+ * unzoomed coordinates. Returns horizontal offset relative to the page
+ * content area (column origin) and vertical offset relative to the
+ * containing paragraph — matches the OOXML attrs the resolver writes
+ * (`relativeFrom: 'column'` / `relativeFrom: 'paragraph'`).
+ *
+ * `zoom` defaults to 1; pass the editor's current zoom factor when the
+ * pages container has a CSS scale applied so `getBoundingClientRect` deltas
+ * are converted back to authored-pixel space before going to EMU.
+ *
+ * Returns undefined for non-inline images or detached DOM.
+ */
+declare function captureInlinePositionEmu(imageEl: HTMLElement, zoom?: number): {
+  horizontalEmu: number;
+  verticalEmu: number;
+} | undefined;
+/**
+ * Map an image's current OOXML attrs onto the menu's choice vocabulary so the
+ * menu can highlight the active option. Returns null for `topAndBottom` and
+ * any unknown wrap type — those don't have a directional menu entry.
+ *
+ * `cssFloat` accepts both `null` and `undefined` so framework adapters can
+ * use either as their "unset" sentinel without an extra normalisation step.
+ */
+declare function deriveLayoutChoice(wrapType: WrapType, cssFloat?: ImageAttrs["cssFloat"] | null): ImageLayoutTarget | null;
+/**
+ * Hint to the framework's icon registry for which Material Symbol — or
+ * equivalent — to render alongside each option. Bindings own the icon
+ * component itself.
+ */
+type ImageLayoutIconHint = "inline" | "squareLeft" | "squareRight" | "behind" | "inFront";
+type ImageLayoutOptionDef = {
+  /** Choice value — what gets dispatched on click. */choice: ImageLayoutTarget; /** i18n key under `imageWrap.menu.*`. */
+  i18nLabelKey: string; /** i18n key under `imageWrap.menuDesc.*`. */
+  i18nDescKey: string; /** Hint for the framework's icon registry. */
+  iconHint: ImageLayoutIconHint;
+};
+/** Mirrors Word's Wrap Text menu — five directional options. */
+declare const IMAGE_LAYOUT_OPTIONS: readonly ImageLayoutOptionDef[];
+/**
+ * Whether a given option is enabled for an image with the given current wrap
+ * type. Every option stays clickable — picking the option that matches the
+ * current state is a no-op (the PM command early-returns), which matches
+ * Word's behavior. Kept around for forward-compatibility (e.g. future
+ * read-only mode), but currently always returns true.
+ */
+declare function isImageLayoutOptionEnabled(_option: ImageLayoutOptionDef, _currentWrapType: WrapType): boolean;
+/**
+ * Translate the legacy toolbar wrap-type vocabulary (`wrapLeft` / `wrapRight`
+ * / `square` / `tight` / `through` / `topAndBottom` / `behind` / `inFront` /
+ * `inline`) into an `ImageLayoutTarget` so toolbar dispatch shares the same PM
+ * command path as the right-click menu.
+ *
+ * Returns `undefined` for unknown values; callers should treat that as
+ * "no-op".
+ */
+declare function toolbarValueToLayoutTarget(value: string): ImageLayoutTarget | undefined;
+/**
+ * Build the painter's `block.id → { block, measure }` lookup from the parallel
+ * blocks/measures arrays. Shared by both adapters' paint step.
+ */
+declare function buildBlockLookup(blocks: FlowBlock[], measures: Measure[]): BlockLookup;
+//#endregion
+export { AnchorWrapType, IMAGE_LAYOUT_OPTIONS, ImageLayoutIconHint, ImageLayoutOptionDef, ImageLayoutTarget, LAYOUT_IMAGE_CLASSES, buildBlockLookup, captureInlinePositionEmu, deriveLayoutChoice, findImageElement, isImageLayoutOptionEnabled, toolbarValueToLayoutTarget };