@stll/folio-core 0.61.0 → 0.63.0

package/dist/markdown/renderParagraph.js

@@ -1,8 +1,8 @@
 import { isQuoteStyle, resolveHeadingLevel } from "../docx/builtInStyles.js";
-import { resolveCachedListRendering, resolveListRenderingDefinition } from "../docx/listRendering.js";
 import { getCachedNumberingMap } from "../docx/numberingParser.js";
-import { mergeParagraphNumbering } from "../docx/numberingReference.js";
 import { listLabelAttrsFromRendering } from "../prosemirror/listLabels.js";
+import { effectiveParagraphNumberingReference, paragraphNumberingAttr } from "../prosemirror/numberingAttr.js";
+import { resolveParagraphList } from "../prosemirror/paragraphList.js";
 import { inlineBreaksToHtml } from "./escape.js";
 import { renderParagraphInline } from "./renderRuns.js";
 //#region src/markdown/renderParagraph.ts
@@ -21,6 +21,8 @@ import { renderParagraphInline } from "./renderRuns.js";
 */
 /** Markdown has six heading levels; Word has nine. */
 const MAX_MARKDOWN_HEADING_LEVEL = 6;
+/** Explicit projection carried by canonical models that are not attached to a package. */
+const standaloneListRendering = (para) => para.listRendering;
 /**
 * Render a paragraph and return the block text. No surrounding blank line: the
 * caller joins blocks.
@@ -35,26 +37,48 @@ function renderParagraph(ctx, pkg, para) {
 * does not define as prose, as every other reader reads them.
 */
 function renderParagraphBlock(ctx, pkg, para) {
-	const numPrFromStyle = ctx.paragraphNumbering(para.formatting?.styleId) ?? para.formatting?.numPrFromStyle;
-	const numPr = mergeParagraphNumbering(numPrFromStyle, para.formatting?.numPr);
-	let list = para.listRendering;
-	if (numPr?.kind === "none" || pkg?.numbering !== void 0 && numPr === void 0) list = void 0;
-	else if (pkg?.numbering !== void 0 && numPr?.kind === "reference") list = resolveCachedListRendering(para.listRendering, resolveListRenderingDefinition(numPr, getCachedNumberingMap(pkg.numbering))) ?? void 0;
-	const counterAttrs = listLabelAttrsFromRendering(list, {
+	const inherited = ctx.paragraphNumbering(para.formatting?.styleId);
+	const inheritedReference = effectiveParagraphNumberingReference({
+		numPr: void 0,
+		numPrFromStyle: inherited
+	});
+	const sources = {
 		numPr: para.formatting?.numPr,
-		numPrFromStyle
+		numPrFromStyle: para.formatting?.numPrFromStyle
+	};
+	const numbering = pkg?.numbering ? getCachedNumberingMap(pkg.numbering) : null;
+	const resolvedList = resolveParagraphList({
+		...sources,
+		inheritedReference: inheritedReference ?? null
+	}, numbering, standaloneListRendering(para));
+	const resolvedRendering = resolvedList.kind === "marker" ? resolvedList.rendering : void 0;
+	const counterAttrs = listLabelAttrsFromRendering(resolvedRendering, {
+		...sources,
+		numPrFromStyle: resolvedList.kind === "none" ? void 0 : inherited ?? sources.numPrFromStyle
 	});
+	if (sources.numPr === void 0 && sources.numPrFromStyle !== void 0 && inheritedReference === void 0 && para.propertyChanges !== void 0 && para.propertyChanges.length > 0) counterAttrs.numPr = paragraphNumberingAttr({ kind: "none" });
 	if (para.pPrMark) counterAttrs.pPrMark = para.pPrMark;
 	let originalList;
-	if (para.propertyChanges) counterAttrs._propertyChanges = para.propertyChanges.map(({ previousFormatting, ...change }) => {
+	if (para.propertyChanges && ctx.opts.trackedChanges !== "clean") counterAttrs._propertyChanges = para.propertyChanges.map(({ previousFormatting, ...change }) => {
 		if (!previousFormatting) return change;
-		const previousInherited = ctx.paragraphNumbering(previousFormatting.styleId) ?? previousFormatting.numPrFromStyle;
-		const previousNumbering = mergeParagraphNumbering(previousInherited, previousFormatting.numPr);
-		const previousRendering = pkg?.numbering !== void 0 && previousNumbering?.kind === "reference" ? resolveListRenderingDefinition(previousNumbering, getCachedNumberingMap(pkg.numbering)).rendering ?? void 0 : void 0;
+		const previousInherited = ctx.paragraphNumbering(previousFormatting.styleId);
+		const previousInheritedReference = effectiveParagraphNumberingReference({
+			numPr: void 0,
+			numPrFromStyle: previousInherited
+		});
+		const previousSources = {
+			numPr: previousFormatting.numPr,
+			numPrFromStyle: previousFormatting.numPrFromStyle
+		};
+		const previousList = resolveParagraphList({
+			...previousSources,
+			inheritedReference: previousInheritedReference ?? null
+		}, numbering);
+		const previousRendering = previousList.kind === "marker" ? previousList.rendering : void 0;
 		originalList ??= previousRendering;
 		const previousAttrs = listLabelAttrsFromRendering(previousRendering, {
-			numPr: previousFormatting.numPr,
-			numPrFromStyle: previousInherited
+			...previousSources,
+			numPrFromStyle: previousList.kind === "none" ? void 0 : previousInherited ?? previousSources.numPrFromStyle
 		});
 		return {
 			...change,
@@ -66,7 +90,8 @@ function renderParagraphBlock(ctx, pkg, para) {
 			}
 		};
 	});
-	const label = ctx.nextListLabel(counterAttrs);
+	const countedList = ctx.nextListLabel(counterAttrs, resolvedRendering);
+	const label = countedList.kind === "marker" ? countedList.label : void 0;
 	const inline = renderParagraphInline(ctx, pkg, para.content, para.paraId);
 	const styleId = para.formatting?.styleId;
 	const headingLevel = markdownHeadingLevel(ctx, para);
@@ -83,7 +108,7 @@ function renderParagraphBlock(ctx, pkg, para) {
 			type: "paragraph"
 		};
 	}
-	const visibleList = list ?? originalList;
+	const visibleList = resolvedRendering ?? (sources.numPr?.kind === "levelOnly" ? void 0 : originalList);
 	if (visibleList && label !== void 0) return renderListItem(ctx, visibleList, label, inline);
 	ctx.listIndentWidths = [];
 	if (isQuoteStyle(styleId, ctx.builtInStyles)) return {

package/dist/markdown/renderRuns.d.ts

@@ -6,7 +6,7 @@ import { RenderContext } from "./types.js";
  * so the output reads cleanly (`***bold italic***`), not the reverse.
  */
 type MarkKey = "bold" | "italic" | "code" | "strike";
-declare function applyMarks(text: string, marks: readonly MarkKey[]): string;
+export declare function applyMarks(text: string, marks: readonly MarkKey[]): string;
 /**
  * The character beside a run's delimiters: `""` at the paragraph's edge,
  * `undefined` when it cannot be told (read as a letter, the strictest case).
@@ -20,6 +20,6 @@ type RunNeighbors = {
  * Render the full inline content of a paragraph, tracking comment-range
  * boundaries to apply the configured wrapper.
  */
-declare function renderParagraphInline(ctx: RenderContext, pkg: document_d_exports.DocxPackage | undefined, content: readonly document_d_exports.ParagraphContent[], paraId: string | undefined, edges?: RunNeighbors): string;
+export declare function renderParagraphInline(ctx: RenderContext, pkg: document_d_exports.DocxPackage | undefined, content: readonly document_d_exports.ParagraphContent[], paraId: string | undefined, edges?: RunNeighbors): string;
 //#endregion
-export { applyMarks, renderParagraphInline };
+export {};

package/dist/markdown/renderRuns.js

@@ -7,6 +7,16 @@ import { registerImage } from "./images.js";
 import { numberNoteReference, pushWarning } from "./internals.js";
 import { compileMarkdownToContent } from "@stll/docx-core";
 //#region src/markdown/renderRuns.ts
+/**
+* Render inline content (runs, hyperlinks, comment-range markers, tracked
+* changes) to markdown. Operates on the `ParagraphContent[]` of a paragraph, or
+* the equivalent inline lists inside hyperlinks and tracked-change wrappers.
+*
+* Inline marks are rendered as character-precise wrappers around the affected
+* runs. Comments and tracked changes become configurable annotation tags via
+* `./annotations`. Ported from eigenpal/docx-editor PR #595 (folio adds the
+* `footnotes: "strip"` gate).
+*/
 const MARK_DELIMS = {
 	bold: "**",
 	italic: "*",
@@ -241,12 +251,7 @@ function renderRunContent(ctx, pkg, content, paraId) {
 			pushWarning(ctx, `image rId=${item.image.rId ?? "(absent)"} not resolvable`);
 			break;
 		}
-		case "shape":
-			pushWarning(ctx, "shape not representable in markdown");
-			break;
-		case "fieldChar":
-		case "instrText": break;
-		default: break;
+		case "shape": pushWarning(ctx, "shape not representable in markdown");
 	}
 	return out;
 }
@@ -386,6 +391,9 @@ function renderTrackedWrapper(ctx, pkg, wrapper, paraId) {
 			case "complexField": return renderParagraphInline(ctx, pkg, [child], paraId, UNKNOWN_NEIGHBORS);
 			case "bookmarkStart":
 			case "bookmarkEnd":
+			case "commentRangeStart":
+			case "commentRangeEnd":
+			case "commentReference":
 			case "moveFromRangeStart":
 			case "moveFromRangeEnd":
 			case "moveToRangeStart":
@@ -497,10 +505,7 @@ function renderParagraphInline(ctx, pkg, content, paraId, edges = {
 			case "inlineWrapper":
 				out += renderParagraphInline(ctx, pkg, item.content, paraId, around(index));
 				break;
-			case "mathEquation":
-				if (item.plainText) out += escapeInline(item.plainText);
-				break;
-			default: break;
+			case "mathEquation": if (item.plainText) out += escapeInline(item.plainText);
 		}
 	}
 	while (openComments.length) {

package/dist/markdown/renderTable.d.ts

@@ -2,6 +2,5 @@ import { document_d_exports } from "../types/document.js";
 import { RenderContext } from "./types.js";
 //#region src/markdown/renderTable.d.ts
 /** Render a `Table` as markdown. Picks GFM vs HTML based on cell features. */
-declare function renderTable(ctx: RenderContext, pkg: document_d_exports.DocxPackage | undefined, table: document_d_exports.Table): string;
-//#endregion
-export { renderTable };
+export declare function renderTable(ctx: RenderContext, pkg: document_d_exports.DocxPackage | undefined, table: document_d_exports.Table): string;
+//#endregion

package/dist/markdown/renderTable.js

@@ -8,6 +8,13 @@ import { registerImage } from "./images.js";
 import { numberNoteReference, pushWarning } from "./internals.js";
 import { renderParagraph } from "./renderParagraph.js";
 //#region src/markdown/renderTable.ts
+/**
+* Render a Word table as markdown. Two output modes, picked automatically per
+* table: GFM for simple tables (no merged cells, no nested tables); inline HTML
+* `<table>` with `colspan`/`rowspan` when the table has `gridSpan`, `vMerge`, or
+* a nested table. Multi-paragraph cells join their paragraphs with `<br>` in
+* both modes. Ported from eigenpal/docx-editor PR #595.
+*/
 /** Render a `Table` as markdown. Picks GFM vs HTML based on cell features. */
 function renderTable(ctx, pkg, table) {
 	const { rows } = table;
@@ -82,7 +89,11 @@ function renderGfmCell(ctx, pkg, cell) {
 				else if (isOpaqueNestedRowMarkup(item.xml)) blocks.push("[Unsupported nested w:tr content]");
 				break;
 			case "bookmarkStart":
-			case "bookmarkEnd": break;
+			case "bookmarkEnd":
+			case "moveFromRangeStart":
+			case "moveFromRangeEnd":
+			case "moveToRangeStart":
+			case "moveToRangeEnd": break;
 			default: return item;
 		}
 	};
@@ -161,7 +172,11 @@ function renderHtmlCell(ctx, pkg, cell) {
 				else if (isOpaqueNestedRowMarkup(item.xml)) parts.push("[Unsupported nested w:tr content]");
 				break;
 			case "bookmarkStart":
-			case "bookmarkEnd": break;
+			case "bookmarkEnd":
+			case "moveFromRangeStart":
+			case "moveFromRangeEnd":
+			case "moveToRangeStart":
+			case "moveToRangeEnd": break;
 			default: return item;
 		}
 	};
@@ -200,10 +215,7 @@ function renderHtmlInline(ctx, pkg, content, paraId) {
 		case "inlineWrapper":
 			out += renderHtmlInline(ctx, pkg, item.content, paraId);
 			break;
-		case "mathEquation":
-			if (item.plainText) out += escapeHtml(item.plainText);
-			break;
-		default: break;
+		case "mathEquation": if (item.plainText) out += escapeHtml(item.plainText);
 	}
 	return out;
 }
@@ -223,6 +235,9 @@ function renderHtmlChildren(ctx, pkg, children, paraId) {
 			case "moveTo": return renderHtmlInline(ctx, pkg, [child], paraId);
 			case "bookmarkStart":
 			case "bookmarkEnd":
+			case "commentRangeStart":
+			case "commentRangeEnd":
+			case "commentReference":
 			case "moveFromRangeStart":
 			case "moveFromRangeEnd":
 			case "moveToRangeStart":
@@ -279,8 +294,6 @@ function renderHtmlRun(ctx, pkg, run, paraId) {
 			text += `<sup>[${token}]</sup>`;
 			break;
 		}
-		case "noteMarker": break;
-		default: break;
 	}
 	if (!text) return "";
 	const f = run.formatting;

package/dist/markdown/trailers.d.ts

@@ -7,6 +7,5 @@ import { RenderContext } from "./types.js";
  * `comments: "sidecar"`). Each section is emitted only when its corresponding
  * refs accumulator has entries.
  */
-declare function appendTrailers(ctx: RenderContext, doc: document_d_exports.Document, body: string): string;
-//#endregion
-export { appendTrailers };
+export declare function appendTrailers(ctx: RenderContext, doc: document_d_exports.Document, body: string): string;
+//#endregion

package/dist/markdown/types.d.ts

@@ -8,7 +8,7 @@ import { ListLabelCounter } from "../prosemirror/listLabels.js";
  * module so its public surface is independent of the docx model's drawing
  * types.
  */
-type ImageMeta = {
+export type ImageMeta = {
   /** `paraId` of the containing paragraph, when the source paragraph has one. */
   paraId?: string | undefined;
   /** 1-based ordinal in registration order. Unique per render call. */
@@ -21,7 +21,7 @@ type ImageMeta = {
   alt?: string | undefined;
 };
 /** Full registration record for an image, keyed by `virtualPath`. */
-type ImageRef = {
+export type ImageRef = {
   /** Raw bytes as exposed by the DOCX parser. */
   data: Uint8Array;
   /** Base64-encoded contents, without the `data:` prefix. */
@@ -36,7 +36,7 @@ type ImageRef = {
  * `{ annotations: "strip", trackedChanges: "clean", comments: "strip",
  * hyperlinks: "inline", footnotes: "strip" }`.
  */
-type MarkdownOptions = {
+export type MarkdownOptions = {
   /**
    * How to encode constructs markdown can't express natively (comments,
    * tracked changes).
@@ -79,7 +79,7 @@ type MarkdownOptions = {
   imagePath?: (info: ImageMeta) => string;
 };
 /** Result of a render, when the caller needs images/warnings as well as text. */
-type MarkdownResult = {
+export type MarkdownResult = {
   /** The full rendered markdown string. */
   markdown: string;
   /** Every image referenced in `markdown`, keyed by its virtual path. */
@@ -88,7 +88,7 @@ type MarkdownResult = {
   warnings: string[];
 };
 /** Resolved option values with defaults applied. Used internally. */
-type ResolvedOptions = {
+export type ResolvedOptions = {
   annotations: "html" | "pandoc" | "strip";
   trackedChanges: "clean" | "annotate";
   comments: "strip" | "inline" | "sidecar";
@@ -101,7 +101,7 @@ type ResolvedOptions = {
  * side-channel output: image map, warnings, and footnote/comment/hyperlink
  * reference lists. Exported only so the split renderer files share the shape.
  */
-type RenderContext = {
+export type RenderContext = {
   opts: ResolvedOptions;
   /** Accumulated images keyed by virtual path. */
   images: Map<string, ImageRef>;
@@ -150,5 +150,4 @@ type RenderContext = {
    */
   listIndentWidths: number[];
 };
-//#endregion
-export { ImageMeta, ImageRef, MarkdownOptions, MarkdownResult, RenderContext, ResolvedOptions };
+//#endregion

package/dist/model.d.ts

@@ -1,8 +1,8 @@
 import { document_d_exports } from "./types/document.js";
 import { CONDITIONAL_STYLE_TYPE_VALUES, COUNTER_FORMAT_VALUES, EMPHASIS_MARK_VALUES, FIELD_TYPE_VALUES, FLOATING_TABLE_X_SPEC_VALUES, FLOATING_TABLE_Y_SPEC_VALUES, FONT_HINT_VALUES, FONT_THEME_VALUES, FRAME_WRAP_VALUES, FRAME_X_ALIGN_VALUES, FRAME_Y_ALIGN_VALUES, HIGHLIGHT_COLOR_VALUES, IMAGE_HORIZONTAL_ALIGNMENT_VALUES, IMAGE_HORIZONTAL_RELATIVE_TO_VALUES, IMAGE_VERTICAL_ALIGNMENT_VALUES, IMAGE_VERTICAL_RELATIVE_TO_VALUES, IMAGE_WRAP_TEXT_VALUES, IMAGE_WRAP_TYPE_VALUES, LEVEL_SUFFIX_VALUES, LINE_SPACING_RULE_VALUES, NUMBER_FORMAT_VALUES, OUTLINE_STYLE_ATTR_VALUES, OUTLINE_STYLE_CSS_ALIAS_VALUES, OutlineStyleAttr, OutlineStyleCssAlias, PARAGRAPH_ALIGNMENT_VALUES, POSITIONAL_TAB_ALIGNMENT_VALUES, POSITIONAL_TAB_LEADER_VALUES, POSITIONAL_TAB_RELATIVE_TO_VALUES, SDT_LOCK_VALUES, SDT_TYPE_VALUES, SHADING_PATTERN_VALUES, SHAPE_TEXT_ANCHOR_VALUES, SHAPE_TYPE_VALUES, STYLE_TYPE_VALUES, TABLE_CELL_VERTICAL_ALIGNMENT_VALUES, TABLE_JUSTIFICATION_VALUES, TABLE_ROW_HEIGHT_RULE_VALUES, TABLE_WIDTH_TYPE_VALUES, TAB_LEADER_VALUES, TAB_STOP_ALIGNMENT_VALUES, TEXT_DIRECTION_VALUES, TEXT_EFFECT_VALUES, UNDERLINE_STYLE_VALUES, normalizeShapeTextAnchor, outlineAttrForDash, presetDashForOutlineAttr } from "./types/documentEnumValues.js";
 import { DeriveBlockIdInput, FolioBlockId, currentFolioBlockId, deriveBlankBlockId, deriveBlockId, getFolioParaIdFromBlockId, getSequentialFolioBlockIdIndex, isBlankFolioBlockId, isFolioBlockId, isSequentialFolioBlockId } from "./types/block-id.js";
-import { types_d_exports } from "./layout-engine/types.js";
 import { measureTypes_d_exports } from "./layout-engine/measure/measureTypes.js";
+import { types_d_exports } from "./layout-engine/types.js";
 export * from "@stll/docx-core/model";
 declare namespace model_d_exports {
   export { CONDITIONAL_STYLE_TYPE_VALUES, COUNTER_FORMAT_VALUES, DeriveBlockIdInput, EMPHASIS_MARK_VALUES, FIELD_TYPE_VALUES, FLOATING_TABLE_X_SPEC_VALUES, FLOATING_TABLE_Y_SPEC_VALUES, FONT_HINT_VALUES, FONT_THEME_VALUES, FRAME_WRAP_VALUES, FRAME_X_ALIGN_VALUES, FRAME_Y_ALIGN_VALUES, FolioBlockId, HIGHLIGHT_COLOR_VALUES, IMAGE_HORIZONTAL_ALIGNMENT_VALUES, IMAGE_HORIZONTAL_RELATIVE_TO_VALUES, IMAGE_VERTICAL_ALIGNMENT_VALUES, IMAGE_VERTICAL_RELATIVE_TO_VALUES, IMAGE_WRAP_TEXT_VALUES, IMAGE_WRAP_TYPE_VALUES, LEVEL_SUFFIX_VALUES, LINE_SPACING_RULE_VALUES, types_d_exports as Layout, measureTypes_d_exports as Measure, NUMBER_FORMAT_VALUES, OUTLINE_STYLE_ATTR_VALUES, OUTLINE_STYLE_CSS_ALIAS_VALUES, OutlineStyleAttr, OutlineStyleCssAlias, PARAGRAPH_ALIGNMENT_VALUES, POSITIONAL_TAB_ALIGNMENT_VALUES, POSITIONAL_TAB_LEADER_VALUES, POSITIONAL_TAB_RELATIVE_TO_VALUES, SDT_LOCK_VALUES, SDT_TYPE_VALUES, SHADING_PATTERN_VALUES, SHAPE_TEXT_ANCHOR_VALUES, SHAPE_TYPE_VALUES, STYLE_TYPE_VALUES, TABLE_CELL_VERTICAL_ALIGNMENT_VALUES, TABLE_JUSTIFICATION_VALUES, TABLE_ROW_HEIGHT_RULE_VALUES, TABLE_WIDTH_TYPE_VALUES, TAB_LEADER_VALUES, TAB_STOP_ALIGNMENT_VALUES, TEXT_DIRECTION_VALUES, TEXT_EFFECT_VALUES, UNDERLINE_STYLE_VALUES, currentFolioBlockId, deriveBlankBlockId, deriveBlockId, getFolioParaIdFromBlockId, getSequentialFolioBlockIdIndex, isBlankFolioBlockId, isFolioBlockId, isSequentialFolioBlockId, normalizeShapeTextAnchor, outlineAttrForDash, presetDashForOutlineAttr };

package/dist/paged-layout/LayoutSelectionGate.d.ts

@@ -18,7 +18,7 @@ type RenderCallback = () => void;
  * 4. Selection update requested → requestRender()
  * 5. If safe → callback is called
  */
-declare class LayoutSelectionGate {
+export declare class LayoutSelectionGate {
   #private;
   /**
    * Set the document state sequence (call when document changes).
@@ -77,4 +77,4 @@ declare class LayoutSelectionGate {
   };
 }
 //#endregion
-export { LayoutSelectionGate };
+export {};

package/dist/paged-layout/blockGeometry.d.ts

@@ -1,7 +1,7 @@
 import { FolioAIEditSnapshot } from "../ai-edits/types.js";
 //#region src/paged-layout/blockGeometry.d.ts
 /** Painted geometry for one AI-snapshot block in scroll-content coordinates. */
-type BlockRect = {
+export type BlockRect = {
   blockId: string;
   /** One-based painted page number. */
   page: number;
@@ -12,7 +12,7 @@ type BlockRect = {
   width: number;
   height: number;
 };
-type ReadBlockRectsOptions = {
+export type ReadBlockRectsOptions = {
   blockIds: readonly string[];
   snapshot: FolioAIEditSnapshot;
   pagesContainer: HTMLElement;
@@ -25,8 +25,7 @@ type ReadBlockRectsOptions = {
  * requested block is measured at most once; painted elements are collected in
  * one DOM query per relevant page.
  */
-declare const readBlockRects: ({ blockIds, snapshot, pagesContainer, scrollRoot }: ReadBlockRectsOptions) => ReadonlyMap<string, BlockRect>;
+export declare const readBlockRects: ({ blockIds, snapshot, pagesContainer, scrollRoot }: ReadBlockRectsOptions) => ReadonlyMap<string, BlockRect>;
 /** Subscribe to instance-scoped painted-page changes. */
-declare const onPaintedLayoutChange: (pagesContainer: HTMLElement, listener: () => void) => (() => void);
-//#endregion
-export { BlockRect, ReadBlockRectsOptions, onPaintedLayoutChange, readBlockRects };
+export declare const onPaintedLayoutChange: (pagesContainer: HTMLElement, listener: () => void) => (() => void);
+//#endregion

package/dist/paged-layout/editorScrollRoot.d.ts

@@ -1,15 +1,17 @@
 //#region src/paged-layout/editorScrollRoot.d.ts
-declare const getEditorScrollRoot: (element: HTMLElement | null) => HTMLElement | null;
+export declare const getEditorScrollRoot: (element: HTMLElement | null) => HTMLElement | null;
 /** Resolve the root even when a caller holds a painted descendant or viewport. */
-declare const scrollEditorTo: (element: HTMLElement | null, options: ScrollToOptions) => void;
-declare const scrollEditorBy: (element: HTMLElement | null, delta: number) => void;
+export declare const scrollEditorTo: (element: HTMLElement | null, options: ScrollToOptions) => void;
+export declare const scrollEditorBy: (element: HTMLElement | null, delta: number) => void;
 type ScrollEditorElementOptions = {
   block?: "start" | "center" | "end" | "nearest";
   behavior?: ScrollBehavior;
   /** Space to leave between the target and the visible root edge. */
   margin?: number;
+  /** Measured target range when only part of the element should be revealed. */
+  rect?: DOMRectReadOnly;
 };
 /** Scroll only the marked root, including when the target is inside a scaled viewport. */
-declare const scrollEditorElementIntoView: (element: HTMLElement | null, { block, behavior, margin }?: ScrollEditorElementOptions) => void;
+export declare const scrollEditorElementIntoView: (element: HTMLElement | null, { block, behavior, margin, rect }?: ScrollEditorElementOptions) => void;
 //#endregion
-export { getEditorScrollRoot, scrollEditorBy, scrollEditorElementIntoView, scrollEditorTo };
+export {};

package/dist/paged-layout/editorScrollRoot.js

@@ -25,10 +25,10 @@ const nearestScrollOffset = ({ targetStart, targetEnd, viewportStart, viewportEn
 	return 0;
 };
 /** Scroll only the marked root, including when the target is inside a scaled viewport. */
-const scrollEditorElementIntoView = (element, { block = "center", behavior = prefersReducedMotionBehavior(), margin = 0 } = {}) => {
+const scrollEditorElementIntoView = (element, { block = "center", behavior = prefersReducedMotionBehavior(), margin = 0, rect } = {}) => {
 	const root = getEditorScrollRoot(element);
 	if (!root || !element) return;
-	const targetRect = element.getBoundingClientRect();
+	const targetRect = rect ?? element.getBoundingClientRect();
 	const rootRect = root.getBoundingClientRect();
 	const visibleTop = rootRect.top + root.clientTop;
 	const targetTop = targetRect.top - visibleTop + root.scrollTop;

package/dist/paged-layout/fitWidthZoom.d.ts

@@ -0,0 +1,36 @@
+//#region src/paged-layout/fitWidthZoom.d.ts
+/**
+ * fitWidthZoom
+ *
+ * Framework-agnostic fit-width math for the React `useZoomAndPageInfo` hook.
+ *
+ * The fit reads the container's border-box width minus the widest
+ * non-content edge (borders plus a classic vertical scrollbar) seen so far,
+ * never `clientWidth` alone. Whether a classic scrollbar shows depends on the
+ * fitted zoom, so a fit that follows `clientWidth` can toggle the scrollbar
+ * and with it its own input. Reserving the widest edge makes the basis
+ * independent of the scrollbar: a container re-fits once when its gutter first
+ * appears and then holds.
+ */
+export declare const FIT_TO_WIDTH_PADDING_PX = 16;
+export declare const FIT_TO_WIDTH_MIN_ZOOM = 0.1;
+export declare const FIT_TO_WIDTH_MAX_ZOOM = 1;
+type FitWidthZoomParams = {
+  /** Border-box width of the scroll container (`offsetWidth`). */
+  offsetWidth: number;
+  /** Content-box width of the scroll container (`clientWidth`). */
+  clientWidth: number;
+  /** Natural width of the laid-out page at zoom 1. */
+  pageWidth: number;
+  /** The widest edge returned by earlier fits of the same container, or 0. */
+  reservedEdge: number;
+};
+type FitWidthZoomResult = {
+  /** The fitted zoom, or `null` when the container has no width to fit. */
+  zoom: number | null;
+  /** Pass back as `reservedEdge` on the next fit of the same container. */
+  reservedEdge: number;
+};
+export declare const fitWidthZoom: ({ offsetWidth, clientWidth, pageWidth, reservedEdge }: FitWidthZoomParams) => FitWidthZoomResult;
+//#endregion
+export {};

package/dist/paged-layout/fitWidthZoom.js

@@ -0,0 +1,31 @@
+//#region src/paged-layout/fitWidthZoom.ts
+/**
+* fitWidthZoom
+*
+* Framework-agnostic fit-width math for the React `useZoomAndPageInfo` hook.
+*
+* The fit reads the container's border-box width minus the widest
+* non-content edge (borders plus a classic vertical scrollbar) seen so far,
+* never `clientWidth` alone. Whether a classic scrollbar shows depends on the
+* fitted zoom, so a fit that follows `clientWidth` can toggle the scrollbar
+* and with it its own input. Reserving the widest edge makes the basis
+* independent of the scrollbar: a container re-fits once when its gutter first
+* appears and then holds.
+*/
+const FIT_TO_WIDTH_PADDING_PX = 16;
+const FIT_TO_WIDTH_MIN_ZOOM = .1;
+const FIT_TO_WIDTH_MAX_ZOOM = 1;
+const fitWidthZoom = ({ offsetWidth, clientWidth, pageWidth, reservedEdge }) => {
+	const edge = Math.max(reservedEdge, offsetWidth - clientWidth);
+	const available = offsetWidth - edge - 16;
+	if (available <= 0 || pageWidth <= 0) return {
+		zoom: null,
+		reservedEdge: edge
+	};
+	return {
+		zoom: Math.min(1, Math.max(FIT_TO_WIDTH_MIN_ZOOM, Math.round(available / pageWidth * 100) / 100)),
+		reservedEdge: edge
+	};
+};
+//#endregion
+export { FIT_TO_WIDTH_MAX_ZOOM, FIT_TO_WIDTH_MIN_ZOOM, FIT_TO_WIDTH_PADDING_PX, fitWidthZoom };

package/dist/paged-layout/hiddenEditorScroll.d.ts

@@ -1,4 +1,3 @@
 //#region src/paged-layout/hiddenEditorScroll.d.ts
-declare const suppressHiddenEditorScrollToSelection: () => true;
-//#endregion
-export { suppressHiddenEditorScrollToSelection };
+export declare const suppressHiddenEditorScrollToSelection: () => true;
+//#endregion

package/dist/paged-layout/incrementalMeasure.d.ts

@@ -1,10 +1,10 @@
 import { FlowBlock, Measure } from "../layout-engine/types.js";
 //#region src/paged-layout/incrementalMeasure.d.ts
-type DirtyRange = {
+export type DirtyRange = {
   from: number;
   to: number;
 };
-type IncrementalMeasureInput = {
+export type IncrementalMeasureInput = {
   previousBlocks: FlowBlock[];
   previousMeasures: Measure[];
   previousBlockWidths: number[];
@@ -13,11 +13,10 @@ type IncrementalMeasureInput = {
   dirtyRange: DirtyRange;
   measureBlock: (block: FlowBlock, blockWidth: number, blockIndex: number) => Measure;
 };
-type IncrementalMeasureResult = {
+export type IncrementalMeasureResult = {
   measures: Measure[];
   measuredBlockIndexes: number[];
 };
-declare function findDirtyBlockIndexes(blocks: FlowBlock[], dirtyRange: DirtyRange): number[];
-declare function tryBuildIncrementalMeasures({ previousBlocks, previousMeasures, previousBlockWidths, nextBlocks, nextBlockWidths, dirtyRange, measureBlock }: IncrementalMeasureInput): IncrementalMeasureResult | null;
-//#endregion
-export { DirtyRange, IncrementalMeasureInput, IncrementalMeasureResult, findDirtyBlockIndexes, tryBuildIncrementalMeasures };
+export declare function findDirtyBlockIndexes(blocks: FlowBlock[], dirtyRange: DirtyRange): number[];
+export declare function tryBuildIncrementalMeasures({ previousBlocks, previousMeasures, previousBlockWidths, nextBlocks, nextBlockWidths, dirtyRange, measureBlock }: IncrementalMeasureInput): IncrementalMeasureResult | null;
+//#endregion

package/dist/paged-layout/pageText.d.ts

@@ -18,6 +18,6 @@ type PageTextOptions = {
  * are skipped. Returns `null` when the layout hasn't been computed yet or the
  * page number is out of range.
  */
-declare const getPageTextFromLayout: ({ layout, doc, page, projection }: PageTextOptions) => string | null;
+export declare const getPageTextFromLayout: ({ layout, doc, page, projection }: PageTextOptions) => string | null;
 //#endregion
-export { getPageTextFromLayout };
+export {};

package/dist/paged-layout/paragraphFlash.d.ts

@@ -1,16 +1,16 @@
 import { ParagraphHighlightOptions, ScrollToParaIdOptions } from "./paragraphFlashTypes.js";
 //#region src/paged-layout/paragraphFlash.d.ts
 /** Default color used by paragraph flashes. */
-declare const DEFAULT_PARAGRAPH_FLASH_COLOR = "rgba(255, 235, 59, 0.55)";
+export declare const DEFAULT_PARAGRAPH_FLASH_COLOR = "rgba(255, 235, 59, 0.55)";
 /** Default duration for paragraph flashes. */
-declare const DEFAULT_PARAGRAPH_FLASH_DURATION_MS = 1200;
+export declare const DEFAULT_PARAGRAPH_FLASH_DURATION_MS = 1200;
 /** CSS class applied to paragraph fragments during a transient flash. */
-declare const PARAGRAPH_FLASH_CLASS_NAME = "folio-paragraph-flash";
+export declare const PARAGRAPH_FLASH_CLASS_NAME = "folio-paragraph-flash";
 /** Find all painted paragraph fragments with a stable `data-para-id`. */
-declare const findParagraphFragmentsByParaId: (root: ParentNode, paraId: string) => HTMLElement[];
+export declare const findParagraphFragmentsByParaId: (root: ParentNode, paraId: string) => HTMLElement[];
 /** Apply a transient flash to a collection of paragraph elements. */
-declare const flashParagraphElements: (elements: Iterable<HTMLElement>, options?: ParagraphHighlightOptions) => number;
+export declare const flashParagraphElements: (elements: Iterable<HTMLElement>, options?: ParagraphHighlightOptions) => number;
 /** Find paragraph fragments by `paraId` and flash them. */
-declare const flashParagraphFragmentsByParaId: (root: ParentNode, paraId: string, options?: ParagraphHighlightOptions) => boolean;
+export declare const flashParagraphFragmentsByParaId: (root: ParentNode, paraId: string, options?: ParagraphHighlightOptions) => boolean;
 //#endregion
-export { DEFAULT_PARAGRAPH_FLASH_COLOR, DEFAULT_PARAGRAPH_FLASH_DURATION_MS, PARAGRAPH_FLASH_CLASS_NAME, type ParagraphHighlightOptions, type ScrollToParaIdOptions, findParagraphFragmentsByParaId, flashParagraphElements, flashParagraphFragmentsByParaId };
+export type { ParagraphHighlightOptions, ScrollToParaIdOptions };

package/dist/paged-layout/paragraphFlashTypes.d.ts

@@ -6,16 +6,15 @@
  * paragraph-flash DOM helpers.
  */
 /** Customization for the transient paragraph flash applied by `scrollToParaId`. */
-type ParagraphHighlightOptions = {
+export type ParagraphHighlightOptions = {
   /** CSS color used for the transient paragraph flash. Defaults to yellow. */
   color?: string;
   /** How long the flash remains visible before it is removed. Defaults to 1200ms. */
   durationMs?: number;
 };
 /** Optional reveal behavior for `scrollToParaId`. */
-type ScrollToParaIdOptions = {
+export type ScrollToParaIdOptions = {
   /** Flash rendered paragraph fragments after scrolling to the paragraph. */
   highlight?: ParagraphHighlightOptions;
 };
-//#endregion
-export { ParagraphHighlightOptions, ScrollToParaIdOptions };
+//#endregion