@stll/folio-core 0.1.3 → 0.2.0

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/measureParagraph.js

@@ -1,8 +1,9 @@
 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";
@@ -47,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
@@ -537,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];
@@ -640,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;
@@ -664,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;
@@ -677,7 +712,7 @@ function measureParagraph(block, maxWidth, options) {
 						chunkStart = chunkEnd;
 						if (chunkStart < word.length) {
 							startNewLine(runIndex, charIndex + chunkStart);
-							updateMaxFont(style);
+							updateMaxFont(lineHeightStyle);
 						}
 					}
 					charIndex = nextBreak;
@@ -687,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-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 };

package/dist/layout-painter/imageLayout.js

@@ -0,0 +1,161 @@
+import { pixelsToEmu } from "../utils/units.js";
+//#region src/layout-painter/imageLayout.ts
+const LAYOUT_IMAGE_CLASSES = {
+	/** Inline image rendered inside `.layout-line`. */
+	runImage: "layout-run-image",
+	/** Block (centered, topAndBottom) image. */
+	blockImage: "layout-block-image",
+	/** Anchored image rendered in the page-level floating layer. */
+	pageFloatingImage: "layout-page-floating-image",
+	/** Anchored image rendered inside a table cell's floating layer. */
+	cellFloatingImage: "layout-cell-floating-image",
+	pageContent: "layout-page-content",
+	paragraph: "layout-paragraph"
+};
+const IMAGE_HIT_SELECTOR = [
+	`.${LAYOUT_IMAGE_CLASSES.pageFloatingImage}`,
+	`.${LAYOUT_IMAGE_CLASSES.cellFloatingImage}`,
+	`.${LAYOUT_IMAGE_CLASSES.blockImage}`,
+	`.${LAYOUT_IMAGE_CLASSES.runImage}`
+].join(", ");
+/**
+* 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`.
+*/
+function findImageElement(target) {
+	if (!(target instanceof HTMLElement)) return null;
+	if (target.tagName === "IMG" && target.classList.contains(LAYOUT_IMAGE_CLASSES.runImage)) return target;
+	const container = target.closest(IMAGE_HIT_SELECTOR);
+	if (container && container.dataset["pmStart"]) return container;
+	return 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.
+*/
+function captureInlinePositionEmu(imageEl, zoom = 1) {
+	if (!imageEl.classList.contains(LAYOUT_IMAGE_CLASSES.runImage)) return;
+	const pageContent = imageEl.closest(`.${LAYOUT_IMAGE_CLASSES.pageContent}`);
+	const paragraph = imageEl.closest(`.${LAYOUT_IMAGE_CLASSES.paragraph}`);
+	if (!pageContent || !paragraph) return;
+	const imgRect = imageEl.getBoundingClientRect();
+	const pageRect = pageContent.getBoundingClientRect();
+	const paraRect = paragraph.getBoundingClientRect();
+	const safeZoom = zoom > 0 ? zoom : 1;
+	return {
+		horizontalEmu: Math.round(pixelsToEmu((imgRect.left - pageRect.left) / safeZoom)),
+		verticalEmu: Math.round(pixelsToEmu((imgRect.top - paraRect.top) / safeZoom))
+	};
+}
+/**
+* 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.
+*/
+function deriveLayoutChoice(wrapType, cssFloat) {
+	if (wrapType === "inline") return "inline";
+	if (wrapType === "behind") return "behind";
+	if (wrapType === "inFront") return "inFront";
+	if (wrapType === "square" || wrapType === "tight" || wrapType === "through") return cssFloat === "right" ? "squareRight" : "squareLeft";
+	return null;
+}
+/** Mirrors Word's Wrap Text menu — five directional options. */
+const IMAGE_LAYOUT_OPTIONS = [
+	{
+		choice: "inline",
+		i18nLabelKey: "inLineWithText",
+		i18nDescKey: "inLineWithText",
+		iconHint: "inline"
+	},
+	{
+		choice: "squareLeft",
+		i18nLabelKey: "squareLeft",
+		i18nDescKey: "squareLeft",
+		iconHint: "squareLeft"
+	},
+	{
+		choice: "squareRight",
+		i18nLabelKey: "squareRight",
+		i18nDescKey: "squareRight",
+		iconHint: "squareRight"
+	},
+	{
+		choice: "behind",
+		i18nLabelKey: "behindText",
+		i18nDescKey: "behindText",
+		iconHint: "behind"
+	},
+	{
+		choice: "inFront",
+		i18nLabelKey: "inFrontOfText",
+		i18nDescKey: "inFrontOfText",
+		iconHint: "inFront"
+	}
+];
+/**
+* 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.
+*/
+function isImageLayoutOptionEnabled(_option, _currentWrapType) {
+	return true;
+}
+/**
+* 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".
+*/
+function toolbarValueToLayoutTarget(value) {
+	switch (value) {
+		case "inline": return "inline";
+		case "square":
+		case "tight":
+		case "through": return "squareLeft";
+		case "topAndBottom": return "topAndBottom";
+		case "behind": return "behind";
+		case "inFront": return "inFront";
+		case "wrapRight": return "squareLeft";
+		case "wrapLeft": return "squareRight";
+		default: return;
+	}
+}
+/**
+* Build the painter's `block.id → { block, measure }` lookup from the parallel
+* blocks/measures arrays. Shared by both adapters' paint step.
+*/
+function buildBlockLookup(blocks, measures) {
+	const lookup = /* @__PURE__ */ new Map();
+	for (let i = 0; i < blocks.length; i++) {
+		const block = blocks[i];
+		const measure = measures[i];
+		if (block && measure) lookup.set(String(block.id), {
+			block,
+			measure
+		});
+	}
+	return lookup;
+}
+//#endregion
+export { IMAGE_LAYOUT_OPTIONS, LAYOUT_IMAGE_CLASSES, buildBlockLookup, captureInlinePositionEmu, deriveLayoutChoice, findImageElement, isImageLayoutOptionEnabled, toolbarValueToLayoutTarget };

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

@@ -242,6 +242,21 @@ type PainterPaintedDetail = {
   container: HTMLElement;
   pageCount: number;
 };
+/**
+ * Force every virtualized page shell in `container` to be fully rendered.
+ *
+ * Virtualization keeps off-screen pages as empty shells, so cloning the pages
+ * container for print (or any DOM snapshot) yields blank pages past the visible
+ * band. Callers that need every page populated — print, export-to-HTML, pdf
+ * snapshot — should call this first.
+ *
+ * No-op for small documents (rendered eagerly) or containers that were never
+ * managed by `renderPages`. Returns the number of shells populated by this
+ * call (useful for tests).
+ *
+ * Ported from eigenpal/docx-editor `layout-painter/renderPage/virtualization.ts`.
+ */
+declare function renderAllPagesNow(container: HTMLElement): number;
 /**
  * Find the page shell whose layout fragments cover (or are nearest
  * before) a given ProseMirror position. Returns null if the
@@ -261,4 +276,4 @@ declare function findPageShellForPmPos(container: HTMLElement, pmPos: number): {
   isExact: boolean;
 } | null;
 //#endregion
-export { AnchoredImagePosition, FootnoteRenderItem, type HeaderFooterContent, HeaderFooterLayoutInfo, PAGE_CLASS_NAMES, PAINTER_PAINTED_EVENT, PageFloatingImage, PageGeometry, PainterPaintedDetail, type RenderContext, RenderPageOptions, applySectionHeaderFooterOptions, calculateFootnoteAreaRenderHeight, computePageFingerprint, emuToPixels, findPageShellForPmPos, getDefaultPageFontFamily, isFloatingImageRun, renderFloatingImagesLayer, renderFootnoteArea, renderPage, renderPages, resolveAnchoredImagePosition, resolveHeaderFooterFloatLeft };
+export { AnchoredImagePosition, FootnoteRenderItem, type HeaderFooterContent, HeaderFooterLayoutInfo, PAGE_CLASS_NAMES, PAINTER_PAINTED_EVENT, PageFloatingImage, PageGeometry, PainterPaintedDetail, type RenderContext, RenderPageOptions, applySectionHeaderFooterOptions, calculateFootnoteAreaRenderHeight, computePageFingerprint, emuToPixels, findPageShellForPmPos, getDefaultPageFontFamily, isFloatingImageRun, renderAllPagesNow, renderFloatingImagesLayer, renderFootnoteArea, renderPage, renderPages, resolveAnchoredImagePosition, resolveHeaderFooterFloatLeft };

package/dist/layout-painter/renderPage.js

@@ -1668,6 +1668,33 @@ function populatePageShell(shell, pageDataMap, totalPages, options) {
 	if (container instanceof HTMLElement) emitPainterPainted(container);
 }
 /**
+* Force every virtualized page shell in `container` to be fully rendered.
+*
+* Virtualization keeps off-screen pages as empty shells, so cloning the pages
+* container for print (or any DOM snapshot) yields blank pages past the visible
+* band. Callers that need every page populated — print, export-to-HTML, pdf
+* snapshot — should call this first.
+*
+* No-op for small documents (rendered eagerly) or containers that were never
+* managed by `renderPages`. Returns the number of shells populated by this
+* call (useful for tests).
+*
+* Ported from eigenpal/docx-editor `layout-painter/renderPage/virtualization.ts`.
+*/
+function renderAllPagesNow(container) {
+	const state = container.__pageRenderState;
+	if (!state) return 0;
+	const { pageStates, totalPages, currentOptions, pageDataMap } = state;
+	let populated = 0;
+	for (const { element } of pageStates) {
+		const data = pageDataMap.get(element);
+		if (!data || data.rendered) continue;
+		populatePageShell(element, pageDataMap, totalPages, currentOptions);
+		populated++;
+	}
+	return populated;
+}
+/**
 * Surgically replace only the content area of a rendered page shell.
 * Preserves header/footer elements to avoid blinking.
 */
@@ -1792,4 +1819,4 @@ function depopulatePageShell(shell, pageDataMap) {
 	}
 }
 //#endregion
-export { PAGE_CLASS_NAMES, PAINTER_PAINTED_EVENT, applySectionHeaderFooterOptions, calculateFootnoteAreaRenderHeight, computePageFingerprint, emuToPixels, findPageShellForPmPos, getDefaultPageFontFamily, isFloatingImageRun, renderFloatingImagesLayer, renderFootnoteArea, renderPage, renderPages, resolveAnchoredImagePosition, resolveHeaderFooterFloatLeft };
+export { PAGE_CLASS_NAMES, PAINTER_PAINTED_EVENT, applySectionHeaderFooterOptions, calculateFootnoteAreaRenderHeight, computePageFingerprint, emuToPixels, findPageShellForPmPos, getDefaultPageFontFamily, isFloatingImageRun, renderAllPagesNow, renderFloatingImagesLayer, renderFootnoteArea, renderPage, renderPages, resolveAnchoredImagePosition, resolveHeaderFooterFloatLeft };

package/dist/layout-painter/renderParagraph.js

@@ -3,9 +3,9 @@ import { resolveFontFamily } from "../utils/fontResolver.js";
 import "../utils/fontWeights.js";
 import { calculateTabWidth } from "../prosemirror/utils/tabCalculator.js";
 import { inlineImageBoundingBox, parseRotationDegrees, rotatedBoundingBox } from "../utils/rotationBoundingBox.js";
+import { hasCjk, segmentByScript } from "../utils/scriptSegments.js";
 import { isFloatingImageRun } from "../layout-engine/types.js";
 import { getListMarkerInlineWidth } from "../layout-engine/measure/listMarkerWidth.js";
-import { hasCjk, segmentByScript } from "../utils/scriptSegments.js";
 import { applySdtDataAttrs } from "./sdtBoundary.js";
 import { applyImageVisualAttrs, hasImageVisualAttrs, wrapImageWithCrop } from "./renderImage.js";
 import { ommlToMathml } from "../docx/mathToMathml.js";