@stll/folio-core 0.32.1 → 0.33.0

package/dist/display-list/dom/renderDisplayListToDom.js

@@ -0,0 +1,620 @@
+import { STROKE_DASH_FACTORS, walkRegions } from "../primitives.js";
+import { panic } from "better-result";
+//#region src/display-list/dom/renderDisplayListToDom.ts
+/**
+* The DOM backend for the display list.
+*
+* Every mark is positioned absolutely from the coordinates the producer
+* already decided. Nothing here re-derives a position from inline flow
+* (`text-align`, `text-indent`, floats, line boxes): a second opinion about
+* where a glyph goes is the divergence the display list exists to remove.
+*
+* A glyph run is one element, and the display list places its origin. Where
+* each glyph lands inside the run is the browser's, because shaping is the
+* only thing that forms a ligature, applies a kern, or picks a cursive
+* letter's initial, medial or final form, and none of those can be recovered
+* from advances alone. The painted extent of a run can therefore differ from
+* its declared extent by the shaper's rounding.
+*
+* That residue is measured rather than assumed. It is small when the list was
+* built by the same engine that paints it, which is the editor's own path, and
+* larger when a list built from font-table advances is painted by a shaper
+* that kerns; the harness reports both and gates only on the first.
+*
+* This module takes a type-only edge to the paint IR and a runtime edge to its
+* companions in `../primitives`, which carry no layout fact. It has no access
+* to the layout engine, so a fact it needs and the display list does not carry
+* has to be added to the contract, where the PDF backend sees it too.
+*
+* `DisplayList.unsupported` is not paint and is not consumed here: the caller
+* surfaces it, because a page missing marks must say so.
+*
+* Object URLs minted for images and embedded fonts outlive this call, one per
+* image and one per embedded face for the whole render. A caller that discards
+* the returned elements should revoke them (`img[src^="blob:"]` and the `src`
+* of each `@font-face` rule).
+*/
+const PAGE_CLASS_NAME = "layout-page";
+/**
+* Anchor ids are the display list's own page indices, not `pageNumber`, which
+* the engine may restart or skip. One numbering, so a link target and the id
+* it addresses cannot drift apart.
+*/
+const PAGE_ELEMENT_ID_PREFIX = "page-";
+const DEGREES_PER_RADIAN = 180 / Math.PI;
+const BASE64_CHUNK_SIZE = 32768;
+const IMAGE_MIME_TYPES = {
+	png: "image/png",
+	jpeg: "image/jpeg"
+};
+/**
+* The display list does not say whether an embedded face is sfnt or WOFF, so a
+* data URL declares neither and the browser sniffs; an `@font-face` `src` needs
+* no `format()` hint to load.
+*/
+const FONT_MIME_TYPE = "application/octet-stream";
+/**
+* Which implementation draws a rect's stroke. Every pattern with a period or a
+* second line goes through the `line` renderer, so a dashed cell border and a
+* dashed underline cannot come out as two different dashes. `solid` has no
+* pattern to get wrong, so a CSS border expresses it exactly and cheaply.
+*/
+const RECT_STROKE_PAINTERS = {
+	solid: "border",
+	dashed: "edges",
+	dotted: "edges",
+	double: "edges",
+	wavy: "edges"
+};
+const px = (value) => `${value}px`;
+/**
+* `rgb()` when opaque so serialized styles stay stable and diffable against
+* the PDF backend's colour dump.
+*/
+const cssColor = ({ r, g, b, a }) => a === 1 ? `rgb(${r}, ${g}, ${b})` : `rgba(${r}, ${g}, ${b}, ${a})`;
+const quoteFontFamily = (family) => `"${family.replaceAll("\"", "\\\"")}"`;
+/**
+* An embedded face wins over any installed face of the same name by being
+* named first, under the id its `@font-face` rule was registered with.
+*/
+/**
+* The stack the measurer resolved, rebuilt in CSS.
+*
+* Every entry, not just the first: the browser picks the first family it has,
+* and so did the measurement. A shorter stack here paints a different face on
+* any host missing the first one.
+*/
+const fontFamilyStack = ({ family, fallbacks, generic, embedded }) => {
+	const resolved = `${[family, ...fallbacks].map(quoteFontFamily).join(", ")}, ${generic}`;
+	return embedded === void 0 ? resolved : `${quoteFontFamily(embedded.id)}, ${resolved}`;
+};
+const resolveFont = (ref, fonts) => {
+	const face = ref < 0 ? void 0 : fonts.at(ref);
+	if (face === void 0) panic(`renderDisplayListToDom: font ref ${ref} is out of range (${fonts.length} faces)`);
+	return face;
+};
+const resolveImage = (ref, images) => {
+	const source = ref < 0 ? void 0 : images.at(ref);
+	if (source === void 0) panic(`renderDisplayListToDom: image ref ${ref} is out of range (${images.length} images)`);
+	return source;
+};
+const toBase64 = (bytes) => {
+	let binary = "";
+	for (let offset = 0; offset < bytes.length; offset += BASE64_CHUNK_SIZE) binary += String.fromCharCode(...bytes.subarray(offset, offset + BASE64_CHUNK_SIZE));
+	return btoa(binary);
+};
+/** A `Blob` part cannot be backed by shared memory, so prove it is not. */
+const isBlobPart = (bytes) => bytes.buffer instanceof ArrayBuffer;
+const binarySrc = (bytes, mimeType) => {
+	if (isBlobPart(bytes) && typeof Blob === "function" && typeof URL !== "undefined" && typeof URL.createObjectURL === "function") return URL.createObjectURL(new Blob([bytes], { type: mimeType }));
+	if (typeof btoa === "function") return `data:${mimeType};base64,${toBase64(bytes)}`;
+	panic("renderDisplayListToDom: no Blob or btoa to build a binary source from");
+};
+const fontFaceRule = (face, embedded, src) => `@font-face { font-family: ${quoteFontFamily(embedded.id)}; src: url("${src}"); font-weight: ${face.weight}; font-style: ${face.italic ? "italic" : "normal"}; }`;
+/**
+* `@font-face` rules for the faces whose bytes travel with the list. Resolved
+* once per render and shared by every page: an id maps to one blob, so the
+* bytes are held once and one revoke releases them.
+*/
+const embeddedFontFaceCss = (fonts) => {
+	const srcById = /* @__PURE__ */ new Map();
+	const rules = [];
+	for (const face of fonts) {
+		const embedded = face.embedded;
+		if (embedded === void 0) continue;
+		const cached = srcById.get(embedded.id);
+		const src = cached ?? binarySrc(embedded.bytes, FONT_MIME_TYPE);
+		if (cached === void 0) srcById.set(embedded.id, src);
+		rules.push(fontFaceRule(face, embedded, src));
+	}
+	return rules.join("\n");
+};
+const createAbsoluteDiv = (context, rect) => {
+	const element = context.doc.createElement("div");
+	element.style.position = "absolute";
+	element.style.left = px(rect.xPx - context.originXPx);
+	element.style.top = px(rect.yPx - context.originYPx);
+	element.style.width = px(rect.widthPx);
+	element.style.height = px(rect.heightPx);
+	return element;
+};
+const createFilledDiv = (context, rect, fill) => {
+	const element = createAbsoluteDiv(context, rect);
+	if (fill !== void 0) element.style.backgroundColor = cssColor(fill);
+	return element;
+};
+/**
+* A group that transforms its children without changing their coordinates: a
+* zero-sized positioned box at the container's origin is the containing block,
+* so a child keeps the coordinates it had one level up.
+*/
+const createTransparentGroupDiv = (context) => {
+	const element = context.doc.createElement("div");
+	element.style.position = "absolute";
+	element.style.left = "0px";
+	element.style.top = "0px";
+	element.style.width = "0px";
+	element.style.height = "0px";
+	return element;
+};
+const HORIZONTAL_BAR_AXES = {
+	main: "to right",
+	cross: "to bottom"
+};
+const VERTICAL_BAR_AXES = {
+	main: "to bottom",
+	cross: "to right"
+};
+/**
+* How far a stroke reaches across its path. A dash pattern stays within the
+* thickness; `double` spans two lines plus the shared gap, and `wavy` the peak
+* to peak amplitude plus the thickness the curve itself is drawn with.
+*/
+const strokeCrossExtentPx = (stroke) => {
+	switch (stroke.pattern) {
+		case "solid":
+		case "dashed":
+		case "dotted": return stroke.thicknessPx;
+		case "double": return stroke.thicknessPx * 3;
+		case "wavy": return stroke.thicknessPx * 3;
+		default: {
+			const unreachable = stroke.pattern;
+			panic(`renderDisplayListToDom: unhandled stroke pattern ${JSON.stringify(unreachable)}`);
+		}
+	}
+};
+const repeatingBars = (color, axis, barPx, gapPx) => `repeating-linear-gradient(${axis}, ${color} 0px, ${color} ${barPx}px, transparent ${barPx}px, transparent ${barPx + gapPx}px)`;
+const strokeBackground = (stroke, axes) => {
+	const color = cssColor(stroke.color);
+	switch (stroke.pattern) {
+		case "solid": return color;
+		case "dashed":
+		case "dotted": {
+			const { dash, gap } = STROKE_DASH_FACTORS[stroke.pattern];
+			return repeatingBars(color, axes.main, stroke.thicknessPx * dash, stroke.thicknessPx * gap);
+		}
+		case "double": {
+			const rulePercent = 100 / 3;
+			return `linear-gradient(${axes.cross}, ${color} 0%, ${color} ${rulePercent}%, transparent ${rulePercent}%, transparent ${100 - rulePercent}%, ${color} ${100 - rulePercent}%)`;
+		}
+		case "wavy": {
+			const halfPeriod = stroke.thicknessPx * 6 / 2;
+			return repeatingBars(color, "45deg", halfPeriod, halfPeriod);
+		}
+		default: {
+			const unreachable = stroke.pattern;
+			panic(`renderDisplayListToDom: unhandled stroke pattern ${JSON.stringify(unreachable)}`);
+		}
+	}
+};
+/** Strokes are centred on their path, so half the cross extent falls each side. */
+const paintLineSegment = (line, context) => {
+	const { x1Px, y1Px, x2Px, y2Px, stroke } = line;
+	const crossExtentPx = strokeCrossExtentPx(stroke);
+	const halfCrossExtentPx = crossExtentPx / 2;
+	const element = context.doc.createElement("div");
+	element.style.position = "absolute";
+	element.style.boxSizing = "content-box";
+	if (y1Px === y2Px) {
+		element.style.left = px(Math.min(x1Px, x2Px) - context.originXPx);
+		element.style.top = px(y1Px - halfCrossExtentPx - context.originYPx);
+		element.style.width = px(Math.abs(x2Px - x1Px));
+		element.style.height = px(crossExtentPx);
+		element.style.background = strokeBackground(stroke, HORIZONTAL_BAR_AXES);
+	} else if (x1Px === x2Px) {
+		element.style.left = px(x1Px - halfCrossExtentPx - context.originXPx);
+		element.style.top = px(Math.min(y1Px, y2Px) - context.originYPx);
+		element.style.width = px(crossExtentPx);
+		element.style.height = px(Math.abs(y2Px - y1Px));
+		element.style.background = strokeBackground(stroke, VERTICAL_BAR_AXES);
+	} else {
+		const dx = x2Px - x1Px;
+		const dy = y2Px - y1Px;
+		element.style.left = px(x1Px - context.originXPx);
+		element.style.top = px(y1Px - halfCrossExtentPx - context.originYPx);
+		element.style.width = px(Math.hypot(dx, dy));
+		element.style.height = px(crossExtentPx);
+		element.style.transformOrigin = "0 50%";
+		element.style.transform = `rotate(${Math.atan2(dy, dx) * DEGREES_PER_RADIAN}deg)`;
+		element.style.background = strokeBackground(stroke, HORIZONTAL_BAR_AXES);
+	}
+	context.parent.append(element);
+};
+/**
+* Reapply what the measurer added to the advances.
+*
+* The browser shapes the run's text and advances it by what the font says, and
+* none of these three is in the font: without them the painted run is as wide
+* as the glyphs alone, which is not the width the line was fitted at. The CSS
+* is the same CSS the legacy painter emits, so the two agree by construction
+* rather than by coincidence.
+*
+* Spacing goes on before the transform scales it, so the painted-pixel numbers
+* the list carries are divided by the scale first.
+*/
+const applyAdjustments = (span, adjustments) => {
+	if (adjustments === void 0) return;
+	const { letterSpacingPx, horizontalScale, wordSpacingPx } = adjustments;
+	if (letterSpacingPx !== 0) span.style.letterSpacing = px(letterSpacingPx / horizontalScale);
+	if (wordSpacingPx !== 0) span.style.wordSpacing = px(wordSpacingPx / horizontalScale);
+	if (horizontalScale !== 1) {
+		span.style.transform = `scaleX(${String(horizontalScale)})`;
+		span.style.transformOrigin = "left center";
+	}
+};
+/**
+* Where a run's glyphs came from in the editable model, on the element that
+* paints them.
+*
+* An editing surface maps a click and a selection through these, and the
+* browser's own hit-tester resolves the offset inside the run. The story is
+* written beside the range because a page is not one document: the same number
+* addresses a different character in the body, in each header and footer part,
+* and in each note, so a surface has to know which one it landed in before it
+* can use the number at all.
+*/
+const applyModelRange = (span, range) => {
+	if (range === void 0) return;
+	span.className = "layout-run-text";
+	span.dataset["pmStart"] = String(range.start);
+	span.dataset["pmEnd"] = String(range.end);
+	const { story } = range;
+	span.dataset["story"] = story.kind;
+	switch (story.kind) {
+		case "body": break;
+		case "header":
+		case "footer":
+			if (story.rId !== null) span.dataset["hfRid"] = story.rId;
+			break;
+		case "footnote":
+		case "endnote":
+			span.dataset["noteKind"] = story.kind;
+			span.dataset["noteId"] = String(story.id);
+			break;
+		default: panic(`renderDisplayListToDom: unhandled story ${JSON.stringify(story)}`);
+	}
+};
+const paintGlyphRun = (run, context) => {
+	if ([...run.text].length !== run.advancesPx.length) panic(`renderDisplayListToDom: glyph run carries ${run.advancesPx.length} advances for ${[...run.text].length} code points`);
+	const face = resolveFont(run.font, context.fonts);
+	const advanceSum = run.advancesPx.reduce((total, advance) => total + advance, 0);
+	const ascentPx = face.fontBoxAscentRatio * run.fontSizePx;
+	const descentPx = face.fontBoxDescentRatio * run.fontSizePx;
+	const span = context.doc.createElement("span");
+	span.style.position = "absolute";
+	span.style.left = px(run.xPx - context.originXPx);
+	span.style.top = px(run.baselineYPx - ascentPx - context.originYPx);
+	span.style.lineHeight = px(ascentPx + descentPx);
+	span.style.display = "inline-block";
+	span.style.boxSizing = "content-box";
+	span.style.width = px(advanceSum / (run.adjustments?.horizontalScale ?? 1));
+	span.style.whiteSpace = "pre";
+	span.style.fontFamily = fontFamilyStack(face);
+	span.style.fontSize = px(run.fontSizePx);
+	span.style.fontWeight = String(face.weight);
+	span.style.fontStyle = face.italic ? "italic" : "normal";
+	span.style.color = cssColor(run.color);
+	span.style.direction = run.direction;
+	if (run.stroke !== void 0) span.style.webkitTextStroke = `${px(run.stroke.thicknessPx)} ${cssColor(run.stroke.color)}`;
+	span.style.fontKerning = run.kerning ? "normal" : "none";
+	if (run.smallCaps) span.style.fontVariant = "small-caps";
+	applyAdjustments(span, run.adjustments);
+	span.dataset["advanceSum"] = String(advanceSum);
+	applyModelRange(span, run.pmRange);
+	if (run.collapsedEdge !== void 0) {
+		span.dataset[run.collapsedEdge.side === "leading" ? "collapsedLeadingSpaces" : "collapsedTrailingSpaces"] = "true";
+		span.dataset["collapsedSpaceAdvance"] = String(run.collapsedEdge.spaceAdvancePx);
+		span.style.fontSize = "0";
+		span.style.letterSpacing = "0";
+		span.style.wordSpacing = "0";
+	}
+	span.textContent = run.text;
+	context.parent.append(span);
+};
+const grownRect = (rect, amountPx) => ({
+	xPx: rect.xPx - amountPx / 2,
+	yPx: rect.yPx - amountPx / 2,
+	widthPx: rect.widthPx + amountPx,
+	heightPx: rect.heightPx + amountPx
+});
+const rectEdges = ({ xPx, yPx, widthPx, heightPx }) => {
+	const rightPx = xPx + widthPx;
+	const bottomPx = yPx + heightPx;
+	return [
+		{
+			x1Px: xPx,
+			y1Px: yPx,
+			x2Px: rightPx,
+			y2Px: yPx
+		},
+		{
+			x1Px: rightPx,
+			y1Px: yPx,
+			x2Px: rightPx,
+			y2Px: bottomPx
+		},
+		{
+			x1Px: xPx,
+			y1Px: bottomPx,
+			x2Px: rightPx,
+			y2Px: bottomPx
+		},
+		{
+			x1Px: xPx,
+			y1Px: yPx,
+			x2Px: xPx,
+			y2Px: bottomPx
+		}
+	];
+};
+const paintRect = ({ rect, fill, stroke }, context) => {
+	if (stroke === void 0) {
+		context.parent.append(createFilledDiv(context, rect, fill));
+		return;
+	}
+	const painter = RECT_STROKE_PAINTERS[stroke.pattern];
+	switch (painter) {
+		case "border": {
+			const element = createFilledDiv(context, grownRect(rect, stroke.thicknessPx), fill);
+			element.style.boxSizing = "border-box";
+			element.style.border = `${px(stroke.thicknessPx)} solid ${cssColor(stroke.color)}`;
+			context.parent.append(element);
+			return;
+		}
+		case "edges":
+			context.parent.append(createFilledDiv(context, rect, fill));
+			for (const edge of rectEdges(rect)) paintLineSegment({
+				kind: "line",
+				...edge,
+				stroke
+			}, context);
+			return;
+		default: panic(`renderDisplayListToDom: unhandled rect stroke painter ${JSON.stringify(painter)}`);
+	}
+};
+const paintImage = ({ image, rect, crop, opacity }, context) => {
+	const source = resolveImage(image, context.images);
+	const clip = createAbsoluteDiv(context, rect);
+	clip.style.overflow = "hidden";
+	const element = context.doc.createElement("img");
+	element.style.position = "absolute";
+	element.style.opacity = String(opacity);
+	element.style.left = "0px";
+	element.style.top = "0px";
+	element.style.width = px(rect.widthPx);
+	element.style.height = px(rect.heightPx);
+	if (crop !== void 0) {
+		const visibleWidth = 1 - crop.l - crop.r;
+		const visibleHeight = 1 - crop.t - crop.b;
+		if (visibleWidth <= 0 || visibleHeight <= 0) panic(`renderDisplayListToDom: image crop leaves nothing visible (${JSON.stringify(crop)})`);
+		const fullWidth = rect.widthPx / visibleWidth;
+		const fullHeight = rect.heightPx / visibleHeight;
+		element.style.left = px(-crop.l * fullWidth);
+		element.style.top = px(-crop.t * fullHeight);
+		element.style.width = px(fullWidth);
+		element.style.height = px(fullHeight);
+	}
+	element.alt = "";
+	element.src = binarySrc(source.bytes, IMAGE_MIME_TYPES[source.format]);
+	clip.append(element);
+	context.parent.append(clip);
+};
+const paintClipGroup = ({ rect, children, regions }, context) => {
+	const element = createAbsoluteDiv(context, rect);
+	element.style.overflow = "hidden";
+	context.parent.append(element);
+	const inner = {
+		...context,
+		parent: element,
+		originXPx: rect.xPx,
+		originYPx: rect.yPx
+	};
+	paintRegionTree({
+		primitives: children,
+		regions
+	}, inner);
+};
+const paintRotateGroup = ({ degrees, originXPx, originYPx, children }, context) => {
+	const element = createTransparentGroupDiv(context);
+	element.style.transformOrigin = `${px(originXPx - context.originXPx)} ${px(originYPx - context.originYPx)}`;
+	element.style.transform = `rotate(${degrees}deg)`;
+	context.parent.append(element);
+	const inner = {
+		...context,
+		parent: element
+	};
+	for (const child of children) paintPrimitive(child, inner);
+};
+const paintOpacityGroup = ({ opacity, children }, context) => {
+	const element = createTransparentGroupDiv(context);
+	element.style.opacity = String(opacity);
+	context.parent.append(element);
+	const inner = {
+		...context,
+		parent: element
+	};
+	for (const child of children) paintPrimitive(child, inner);
+};
+const paintPrimitive = (primitive, context) => {
+	switch (primitive.kind) {
+		case "glyphRun": return paintGlyphRun(primitive, context);
+		case "rect": return paintRect(primitive, context);
+		case "line": return paintLineSegment(primitive, context);
+		case "image": return paintImage(primitive, context);
+		case "clipGroup": return paintClipGroup(primitive, context);
+		case "rotateGroup": return paintRotateGroup(primitive, context);
+		case "opacityGroup": return paintOpacityGroup(primitive, context);
+		default: panic(`renderDisplayListToDom: unhandled display primitive ${JSON.stringify(primitive)}`);
+	}
+};
+/**
+* A page target loses its `yPx`: a fragment identifier addresses an element,
+* not an offset within one.
+*/
+const linkHref = (target) => {
+	switch (target.kind) {
+		case "external": return target.href;
+		case "page": return `#${PAGE_ELEMENT_ID_PREFIX}${target.pageIndex}`;
+		default: panic(`renderDisplayListToDom: unhandled link target ${JSON.stringify(target)}`);
+	}
+};
+const paintLink = ({ rect, target, tooltip }, context) => {
+	const element = context.doc.createElement("a");
+	element.style.position = "absolute";
+	element.style.left = px(rect.xPx - context.originXPx);
+	element.style.top = px(rect.yPx - context.originYPx);
+	element.style.width = px(rect.widthPx);
+	element.style.height = px(rect.heightPx);
+	element.href = linkHref(target);
+	if (tooltip !== void 0) element.title = tooltip;
+	context.parent.append(element);
+};
+const renderPage = (page, options) => {
+	const element = options.doc.createElement("div");
+	element.className = PAGE_CLASS_NAME;
+	element.id = `${PAGE_ELEMENT_ID_PREFIX}${options.pageIndex}`;
+	element.style.position = "relative";
+	element.style.width = px(page.widthPx);
+	element.style.height = px(page.heightPx);
+	element.style.overflow = "hidden";
+	if (options.pageBackground !== void 0) element.style.backgroundColor = cssColor(options.pageBackground);
+	if (options.fontFaceCss.length > 0) {
+		const style = options.doc.createElement("style");
+		style.textContent = options.fontFaceCss;
+		element.append(style);
+	}
+	const context = {
+		doc: options.doc,
+		fonts: options.fonts,
+		images: options.images,
+		parent: element,
+		originXPx: 0,
+		originYPx: 0
+	};
+	paintRegionTree(page, context);
+	for (const link of page.links) paintLink(link, context);
+	return element;
+};
+/**
+* The element a region becomes.
+*
+* The class names are the ones the interaction layer has always read; naming
+* them here rather than in a painter is what lets a reader keep working while
+* the thing that emits them changes underneath.
+*/
+const REGION_CLASS = {
+	pageContent: "layout-page-content",
+	headerSlot: "layout-page-header",
+	footerSlot: "layout-page-footer",
+	note: "layout-note",
+	paragraph: "layout-paragraph",
+	line: "layout-line",
+	emptyRun: "layout-empty-run",
+	tab: "layout-run-tab",
+	image: "layout-run-image",
+	table: "layout-table",
+	tableRow: "layout-table-row",
+	tableCell: "layout-table-cell",
+	textBox: "layout-text-box"
+};
+/** Model facts a surface reads off the element, as the painter wrote them. */
+const applyRegionModel = (element, region) => {
+	const model = region.model;
+	if (model === void 0) return;
+	if (model.pmRange !== void 0) {
+		element.dataset["pmStart"] = String(model.pmRange.start);
+		element.dataset["pmEnd"] = String(model.pmRange.end);
+	}
+	if (model.blockId !== void 0) element.dataset["blockId"] = model.blockId;
+	if (model.commentIds !== void 0 && model.commentIds.length > 0) element.dataset["commentId"] = String(model.commentIds[0]);
+	if (model.rowIndex !== void 0) element.dataset["rowIndex"] = String(model.rowIndex);
+	if (model.columnIndex !== void 0) element.dataset["columnIndex"] = String(model.columnIndex);
+	const story = model.story ?? model.pmRange?.story;
+	if (story === void 0) return;
+	element.dataset["story"] = story.kind;
+	switch (story.kind) {
+		case "body": break;
+		case "header":
+		case "footer":
+			if (story.rId === null) break;
+			element.dataset["rid"] = story.rId;
+			element.dataset["hfRid"] = story.rId;
+			element.dataset["hfRId"] = story.rId;
+			element.dataset["hfSlotKind"] = story.kind;
+			element.dataset["hfKind"] = story.kind;
+			break;
+		case "footnote":
+		case "endnote":
+			element.dataset["noteKind"] = story.kind;
+			element.dataset["noteId"] = String(story.id);
+			break;
+		default: panic(`renderDisplayListToDom: unhandled story ${JSON.stringify(story)}`);
+	}
+};
+const paintRegionTree = ({ primitives, regions }, context) => {
+	let current = context;
+	const stack = [];
+	walkRegions(primitives, regions, {
+		onPrimitive: (primitive) => {
+			paintPrimitive(primitive, current);
+		},
+		enter: (region) => {
+			const element = current.doc.createElement("div");
+			element.className = REGION_CLASS[region.kind];
+			element.style.position = "absolute";
+			element.style.left = px(region.rect.xPx - current.originXPx);
+			element.style.top = px(region.rect.yPx - current.originYPx);
+			element.style.width = px(region.rect.widthPx);
+			element.style.height = px(region.rect.heightPx);
+			applyRegionModel(element, region);
+			current.parent.append(element);
+			stack.push(current);
+			current = {
+				...current,
+				parent: element,
+				originXPx: region.rect.xPx,
+				originYPx: region.rect.yPx
+			};
+		},
+		exit: () => {
+			current = stack.pop() ?? context;
+		}
+	});
+};
+const renderDisplayPageToDom = (page, options) => renderPage(page, {
+	...options,
+	fontFaceCss: embeddedFontFaceCss(options.fonts)
+});
+/** One `div.layout-page` per display page, in page order. */
+const renderDisplayListToDom = (list, options) => {
+	const fontFaceCss = embeddedFontFaceCss(list.fonts);
+	return list.pages.map((page, pageIndex) => renderPage(page, {
+		...options,
+		fonts: list.fonts,
+		images: list.images,
+		pageIndex,
+		fontFaceCss
+	}));
+};
+//#endregion
+export { renderDisplayListToDom, renderDisplayPageToDom };

package/dist/display-list/editor/displayListPagePainter.d.ts

@@ -0,0 +1,22 @@
+import { Page } from "../../layout-engine/types.js";
+import { DisplayList } from "../types.js";
+import { BuildDisplayListOptions } from "../build/buildDisplayList.js";
+//#region src/display-list/editor/displayListPagePainter.d.ts
+type DisplayListPagePainterOptions = BuildDisplayListOptions & {
+  /** Document to create elements in. */
+  readonly doc: Document;
+};
+type DisplayListPagePainter = {
+  /** Matches `RenderPageOptions.paintPage`. */
+  readonly paintPage: (request: {
+    readonly page: Page;
+  }) => HTMLElement | null;
+  /**
+   * The list as far as the painter has built it, for tests and diagnostics.
+   * Pages nobody painted are absent, because nobody built them.
+   */
+  readonly list: () => DisplayList;
+};
+declare const createDisplayListPagePainter: (options: DisplayListPagePainterOptions) => DisplayListPagePainter;
+//#endregion
+export { DisplayListPagePainter, DisplayListPagePainterOptions, createDisplayListPagePainter };