@stll/folio-core 0.32.2 → 0.33.0

package/dist/display-list/build/imagePrimitives.js

@@ -0,0 +1,264 @@
+import { parseRotationDegrees } from "../../utils/rotationBoundingBox.js";
+import { sanitizeImageSrc } from "../../utils/sanitizeImageSrc.js";
+import { resolveBorderStroke } from "./strokes.js";
+import { UNSUPPORTED_CONSTRUCT } from "./unsupported.js";
+import { Result } from "better-result";
+//#region src/display-list/build/imagePrimitives.ts
+/**
+* Images: the source table, and the primitives an image draws.
+*
+* The display list carries raw bytes plus the format they are already in, so a
+* backend never owns a codec. This module therefore decodes only far enough to
+* fill `pixelWidth`/`pixelHeight` and to know PNG from JPEG. It transcodes
+* nothing: a WMF, EMF, TIFF, SVG, GIF or BMP source is reported through
+* `unsupported` and paints nothing, because a silently missing picture is worse
+* than a named one.
+*/
+const DATA_URL_PATTERN = /^data:([^;,]*)(;base64)?,(.*)$/su;
+/**
+* `undefined` for a payload `atob` rejects: a malformed `data:` URL is a
+* document the builder reports, not an exception that aborts the build.
+*/
+const decodeBase64 = (encoded) => {
+	const decoded = Result.try(() => atob(encoded));
+	if (decoded.isErr()) return;
+	const binary = decoded.value;
+	const bytes = new Uint8Array(binary.length);
+	for (let index = 0; index < binary.length; index += 1) bytes[index] = binary.charCodeAt(index);
+	return bytes;
+};
+const readUint32BE = (bytes, offset) => bytes[offset] << 24 | bytes[offset + 1] << 16 | bytes[offset + 2] << 8 | bytes[offset + 3];
+const readUint16BE = (bytes, offset) => bytes[offset] << 8 | bytes[offset + 1];
+const startsWith = (bytes, signature) => bytes.length >= signature.length && signature.every((byte, index) => bytes[index] === byte);
+const PNG_SIGNATURE = [
+	137,
+	80,
+	78,
+	71,
+	13,
+	10,
+	26,
+	10
+];
+const JPEG_SIGNATURE = [
+	255,
+	216,
+	255
+];
+/** PNG's IHDR is always the first chunk: 8-byte signature, 8-byte header, then w/h. */
+const PNG_WIDTH_OFFSET = 16;
+const decodePng = (bytes) => {
+	if (bytes.length < 24) return { reason: "PNG shorter than its IHDR chunk" };
+	return {
+		format: "png",
+		bytes,
+		pixelWidth: readUint32BE(bytes, PNG_WIDTH_OFFSET),
+		pixelHeight: readUint32BE(bytes, 20)
+	};
+};
+/**
+* Frame markers that carry the image dimensions. Every other `SOFn` code in the
+* `0xC0..0xCF` block is a table or restart marker, not a frame header.
+*/
+const JPEG_FRAME_MARKERS = /* @__PURE__ */ new Set([
+	192,
+	193,
+	194,
+	195,
+	197,
+	198,
+	199,
+	201,
+	202,
+	203,
+	205,
+	206,
+	207
+]);
+const decodeJpeg = (bytes) => {
+	let offset = 2;
+	while (offset + 9 < bytes.length) {
+		if (bytes[offset] !== 255) {
+			offset += 1;
+			continue;
+		}
+		const marker = bytes[offset + 1];
+		if (JPEG_FRAME_MARKERS.has(marker)) return {
+			format: "jpeg",
+			bytes,
+			pixelHeight: readUint16BE(bytes, offset + 5),
+			pixelWidth: readUint16BE(bytes, offset + 7)
+		};
+		const segmentLength = readUint16BE(bytes, offset + 2);
+		if (segmentLength < 2) return { reason: "JPEG segment length is degenerate" };
+		offset += 2 + segmentLength;
+	}
+	return { reason: "JPEG carries no frame header" };
+};
+const sniffOtherFormat = (bytes) => {
+	if (startsWith(bytes, [
+		71,
+		73,
+		70,
+		56
+	])) return "GIF";
+	if (startsWith(bytes, [66, 77])) return "BMP";
+	if (startsWith(bytes, [
+		73,
+		73,
+		42,
+		0
+	]) || startsWith(bytes, [
+		77,
+		77,
+		0,
+		42
+	])) return "TIFF";
+	if (startsWith(bytes, [
+		215,
+		205,
+		198,
+		154
+	]) || startsWith(bytes, [
+		1,
+		0,
+		0,
+		0
+	])) return "WMF/EMF";
+	if (startsWith(bytes, [
+		60,
+		63,
+		120,
+		109
+	]) || startsWith(bytes, [
+		60,
+		115,
+		118,
+		103
+	])) return "SVG";
+};
+const decodeImageBytes = (bytes) => {
+	if (startsWith(bytes, PNG_SIGNATURE)) return decodePng(bytes);
+	if (startsWith(bytes, JPEG_SIGNATURE)) return decodeJpeg(bytes);
+	const other = sniffOtherFormat(bytes);
+	return { reason: other === void 0 ? "unrecognised image bytes" : `${other} is not PNG or JPEG` };
+};
+/**
+* Sources interned in first-use order, so two builds of one layout produce the
+* same `DisplayImageRef` for the same picture.
+*/
+var ImageTable = class {
+	sources = [];
+	refBySrc = /* @__PURE__ */ new Map();
+	failureBySrc = /* @__PURE__ */ new Map();
+	/** `undefined` means "do not paint"; the reason is available via {@link failureFor}. */
+	intern(src) {
+		const cached = this.refBySrc.get(src);
+		if (cached !== void 0) return cached ?? void 0;
+		const fail = (reason) => {
+			this.refBySrc.set(src, null);
+			this.failureBySrc.set(src, reason);
+		};
+		const safeSrc = sanitizeImageSrc(src);
+		if (safeSrc === void 0) return fail("image source is not a data: or blob: URL");
+		const match = DATA_URL_PATTERN.exec(safeSrc);
+		if (!match) return fail("image bytes are not inline (blob: URLs need a fetch the builder cannot do)");
+		if (match[2] === void 0) return fail("only base64 data: URLs carry decodable bytes");
+		const bytes = decodeBase64(match[3]);
+		if (bytes === void 0) return fail("image data: URL payload is not valid base64");
+		if (bytes.length === 0) return fail("image data: URL decoded to no bytes");
+		const decoded = decodeImageBytes(bytes);
+		if ("reason" in decoded) return fail(decoded.reason);
+		const ref = this.sources.length;
+		this.sources.push(decoded);
+		this.refBySrc.set(src, ref);
+		return ref;
+	}
+	failureFor(src) {
+		return this.failureBySrc.get(src);
+	}
+	snapshot() {
+		return this.sources;
+	}
+};
+const cropOf = (source) => {
+	const l = source.cropLeft ?? 0;
+	const t = source.cropTop ?? 0;
+	const r = source.cropRight ?? 0;
+	const b = source.cropBottom ?? 0;
+	if (!(l || t || r || b)) return;
+	return {
+		l,
+		t,
+		r,
+		b
+	};
+};
+/**
+* The primitives one picture draws: the bitmap (rotated and/or washed as the
+* source asks) followed by its border. Empty when the bytes are unusable, with
+* the reason already reported.
+*/
+const paintImage = ({ source, rect, context, label }) => {
+	const primitives = [];
+	const ref = context.images.intern(source.src);
+	if (ref === void 0) {
+		const reason = context.images.failureFor(source.src) ?? "image could not be decoded";
+		const construct = reason.includes("not PNG or JPEG") ? UNSUPPORTED_CONSTRUCT.imageFormat : UNSUPPORTED_CONSTRUCT.imageSource;
+		context.unsupported.report(construct, context.pageIndex, `${label}: ${reason}`);
+	} else {
+		const crop = cropOf(source);
+		const image = {
+			kind: "image",
+			image: ref,
+			rect,
+			...crop === void 0 ? {} : { crop },
+			opacity: source.opacity == null ? 1 : Math.min(1, Math.max(0, source.opacity))
+		};
+		const degrees = parseRotationDegrees(source.transform);
+		if (degrees === 0) primitives.push(image);
+		else primitives.push({
+			kind: "rotateGroup",
+			degrees,
+			originXPx: rect.xPx + rect.widthPx / 2,
+			originYPx: rect.yPx + rect.heightPx / 2,
+			children: [image]
+		});
+	}
+	if (source.borderWidth != null && source.borderWidth > 0) {
+		const { stroke, unresolvedColor } = resolveBorderStroke({
+			width: source.borderWidth,
+			style: source.borderStyle ?? "solid",
+			color: source.borderColor ?? "#000000"
+		});
+		if (unresolvedColor !== void 0) context.unsupported.report(UNSUPPORTED_CONSTRUCT.unresolvedColor, context.pageIndex, `${label} border colour ${unresolvedColor}`);
+		if (stroke) {
+			const inset = stroke.thicknessPx / 2;
+			primitives.push({
+				kind: "rect",
+				rect: {
+					xPx: rect.xPx + inset,
+					yPx: rect.yPx + inset,
+					widthPx: Math.max(0, rect.widthPx - stroke.thicknessPx),
+					heightPx: Math.max(0, rect.heightPx - stroke.thicknessPx)
+				},
+				stroke
+			});
+		}
+	}
+	return primitives;
+};
+/** An anchored or block image fragment placed by the layout engine. */
+const paintImageFragment = (fragment, block, context) => paintImage({
+	source: block,
+	rect: {
+		xPx: fragment.x,
+		yPx: fragment.y,
+		widthPx: fragment.width,
+		heightPx: fragment.height
+	},
+	context,
+	label: `image block ${String(fragment.blockId)}`
+});
+//#endregion
+export { ImageTable, paintImage, paintImageFragment };

package/dist/display-list/build/pageBorderPrimitives.d.ts

@@ -0,0 +1,23 @@
+import { document_d_exports } from "../../types/document.js";
+import { Page } from "../../layout-engine/types.js";
+import { RenderPageOptions } from "../../layout-painter/renderPage.js";
+import { DisplayPrimitive } from "../types.js";
+import { BuildContext } from "./buildContext.js";
+//#region src/display-list/build/pageBorderPrimitives.d.ts
+/** The section's `w:pgBorders`, as the painter already receives them. */
+type PageBorders = NonNullable<RenderPageOptions["pageBorders"]>;
+type PageBorderPaintOptions = {
+  readonly page: Page;
+  readonly borders: PageBorders;
+  readonly theme?: document_d_exports.Theme | null;
+  readonly context: BuildContext;
+};
+/**
+ * The four page-border strokes, or nothing when this page does not carry them.
+ * `offsetFrom` decides what the box is measured from: `page` insets `w:space`
+ * from the paper edge, `text` insets the margin less `w:space` and the stroke
+ * itself, so the authored gap between text and border survives a thick rule.
+ */
+declare const paintPageBorders: ({ page, borders, theme, context }: PageBorderPaintOptions) => readonly DisplayPrimitive[];
+//#endregion
+export { PageBorderPaintOptions, PageBorders, paintPageBorders };

package/dist/display-list/build/pageBorderPrimitives.js

@@ -0,0 +1,111 @@
+import { resolveColor } from "../../utils/colorResolver.js";
+import { eighthsToPixels, pointsToPixels } from "../../utils/units.js";
+import { resolveBorderStroke } from "./strokes.js";
+import { UNSUPPORTED_CONSTRUCT } from "./unsupported.js";
+//#region src/display-list/build/pageBorderPrimitives.ts
+/** `borderToStyle`: a border with no `w:sz` paints a hairline, not nothing. */
+const HAIRLINE_WIDTH_PX = 1;
+const SIDES = [
+	"top",
+	"right",
+	"bottom",
+	"left"
+];
+/** `pageBorderShouldRender`: `w:display` is about the physical page number. */
+const shouldRender = (pageNumber, display) => {
+	switch (display ?? "allPages") {
+		case "firstPage": return pageNumber === 1;
+		case "notFirstPage": return pageNumber !== 1;
+		case "allPages": return true;
+		default: return true;
+	}
+};
+const spacePx = (border) => border?.space === void 0 ? 0 : pointsToPixels(border.space);
+const strokeOf = (border, theme, context) => {
+	if (!border) return;
+	const { stroke, unresolvedColor } = resolveBorderStroke({
+		width: border.size === void 0 || border.size === 0 ? HAIRLINE_WIDTH_PX : eighthsToPixels(border.size),
+		style: border.style,
+		color: resolveColor(border.color, theme)
+	});
+	if (unresolvedColor !== void 0) context.unsupported.report(UNSUPPORTED_CONSTRUCT.unresolvedColor, context.pageIndex, `page border colour ${unresolvedColor}`);
+	return stroke;
+};
+/**
+* The four page-border strokes, or nothing when this page does not carry them.
+* `offsetFrom` decides what the box is measured from: `page` insets `w:space`
+* from the paper edge, `text` insets the margin less `w:space` and the stroke
+* itself, so the authored gap between text and border survives a thick rule.
+*/
+const paintPageBorders = ({ page, borders, theme, context }) => {
+	if (!shouldRender(page.number, borders.display)) return [];
+	const strokes = {
+		top: strokeOf(borders.top, theme, context),
+		right: strokeOf(borders.right, theme, context),
+		bottom: strokeOf(borders.bottom, theme, context),
+		left: strokeOf(borders.left, theme, context)
+	};
+	if (SIDES.every((side) => strokes[side] === void 0)) return [];
+	const insetPx = (side) => {
+		const border = borders[side];
+		if ((borders.offsetFrom ?? "text") === "page") return spacePx(border);
+		const marginPx = page.margins[side];
+		return Math.max(0, marginPx - spacePx(border) - (strokes[side]?.thicknessPx ?? 0));
+	};
+	const leftPx = insetPx("left");
+	const topPx = insetPx("top");
+	const rightPx = page.size.w - insetPx("right");
+	const bottomPx = page.size.h - insetPx("bottom");
+	const primitives = [];
+	for (const side of SIDES) {
+		const stroke = strokes[side];
+		if (stroke === void 0) continue;
+		const half = stroke.thicknessPx / 2;
+		switch (side) {
+			case "top":
+				primitives.push({
+					kind: "line",
+					x1Px: leftPx,
+					y1Px: topPx + half,
+					x2Px: rightPx,
+					y2Px: topPx + half,
+					stroke
+				});
+				break;
+			case "bottom":
+				primitives.push({
+					kind: "line",
+					x1Px: leftPx,
+					y1Px: bottomPx - half,
+					x2Px: rightPx,
+					y2Px: bottomPx - half,
+					stroke
+				});
+				break;
+			case "left":
+				primitives.push({
+					kind: "line",
+					x1Px: leftPx + half,
+					y1Px: topPx,
+					x2Px: leftPx + half,
+					y2Px: bottomPx,
+					stroke
+				});
+				break;
+			case "right":
+				primitives.push({
+					kind: "line",
+					x1Px: rightPx - half,
+					y1Px: topPx,
+					x2Px: rightPx - half,
+					y2Px: bottomPx,
+					stroke
+				});
+				break;
+			default:
+		}
+	}
+	return primitives;
+};
+//#endregion
+export { paintPageBorders };

package/dist/display-list/build/pageFurniture.d.ts

@@ -0,0 +1,35 @@
+import { FootnoteContent, Page } from "../../layout-engine/types.js";
+import { DisplayColor, DisplayPrimitive } from "../types.js";
+import { BuildContext } from "./buildContext.js";
+import { PageComposer } from "./regions.js";
+//#region src/display-list/build/pageFurniture.d.ts
+declare const paintPageBackground: (page: Page, fill: DisplayColor) => DisplayPrimitive;
+/**
+ * Vertical rules between newspaper columns. The painter assumes equal columns
+ * with a uniform gap (it ignores `columns.widths` / `columns.gaps`), and so
+ * does this: diverging here would put the export's rules somewhere the editor
+ * never drew them.
+ */
+declare const paintColumnSeparators: (page: Page) => readonly DisplayPrimitive[];
+type FootnoteAreaPaintOptions = {
+  readonly composer: PageComposer;
+  readonly page: Page;
+  readonly context: BuildContext;
+  /**
+   * The bodies, by `w:footnote` id. Absent, or missing an id the page carries,
+   * means the caller did not supply that body: the band still opens with its
+   * rule and reserves its height, and the missing bodies are named.
+   */
+  readonly contentById?: ReadonlyMap<number, FootnoteContent>;
+};
+/**
+ * The footnote band at the foot of the body column: the separator rule, then
+ * one body per note the paginator put on this page.
+ *
+ * The band's top comes from the reservation the paginator made, clamped up to
+ * what the bodies actually need, so a stack that under-reserved by a pixel ends
+ * at the page bottom instead of spilling past it.
+ */
+declare const paintFootnoteArea: ({ composer, page, context, contentById }: FootnoteAreaPaintOptions) => void;
+//#endregion
+export { FootnoteAreaPaintOptions, paintColumnSeparators, paintFootnoteArea, paintPageBackground };

package/dist/display-list/build/pageFurniture.js

@@ -0,0 +1,141 @@
+import "../../layout-engine/types.js";
+import { calculateFootnoteAreaRenderHeight } from "../../layout-painter/renderPage.js";
+import { HIT_REGION_KINDS } from "../primitives.js";
+import { DOC_CANVAS_TEXT } from "./colors.js";
+import { paintFootnoteBlocks } from "./storyPrimitives.js";
+import { UNSUPPORTED_CONSTRUCT } from "./unsupported.js";
+//#region src/display-list/build/pageFurniture.ts
+/**
+* Page furniture: everything on a page that is not a body fragment.
+*
+* `renderPage.ts` is the authority on the order and on the geometry, and it
+* takes most of this from `RenderPageOptions` rather than from the `Layout`:
+* page borders, watermarks, footnote bodies and header/footer stories all reach
+* the DOM painter as render options the layout never carried. The builder is
+* handed the same inputs, so a construct the caller supplies is painted and a
+* construct the layout shows evidence of but the caller withheld is reported.
+* The furniture that is derivable from the `Layout` alone — the page
+* background, the column separators and the footnote separator rule — is always
+* painted.
+*/
+/** `renderPage.ts:2049`: a hairline in the canvas ink colour. */
+const COLUMN_SEPARATOR_WIDTH_PX = .5;
+/** `renderPage.ts:1354-1360`: a 0.5px rule across a third of the column, centred in its 12px slot. */
+const FOOTNOTE_RULE_THICKNESS_PX = .5;
+const FOOTNOTE_RULE_WIDTH_FRACTION = .33;
+const FOOTNOTE_RULE_MARGIN_PX = (12 - FOOTNOTE_RULE_THICKNESS_PX) / 2;
+const paintPageBackground = (page, fill) => ({
+	kind: "rect",
+	rect: {
+		xPx: 0,
+		yPx: 0,
+		widthPx: page.size.w,
+		heightPx: page.size.h
+	},
+	fill
+});
+/**
+* Vertical rules between newspaper columns. The painter assumes equal columns
+* with a uniform gap (it ignores `columns.widths` / `columns.gaps`), and so
+* does this: diverging here would put the export's rules somewhere the editor
+* never drew them.
+*/
+const paintColumnSeparators = (page) => {
+	const columns = page.columns;
+	if (!columns?.separator || columns.count <= 1) return [];
+	const contentWidthPx = page.size.w - page.margins.left - page.margins.right;
+	const contentHeightPx = page.size.h - page.margins.top - page.margins.bottom;
+	const columnWidthPx = (contentWidthPx - (columns.count - 1) * columns.gap) / columns.count;
+	const primitives = [];
+	for (let column = 0; column < columns.count - 1; column += 1) {
+		const offsetPx = (column + 1) * columnWidthPx + column * columns.gap + columns.gap / 2;
+		primitives.push({
+			kind: "rect",
+			rect: {
+				xPx: page.margins.left + offsetPx,
+				yPx: page.margins.top,
+				widthPx: COLUMN_SEPARATOR_WIDTH_PX,
+				heightPx: contentHeightPx
+			},
+			fill: DOC_CANVAS_TEXT
+		});
+	}
+	return primitives;
+};
+/**
+* The footnote band at the foot of the body column: the separator rule, then
+* one body per note the paginator put on this page.
+*
+* The band's top comes from the reservation the paginator made, clamped up to
+* what the bodies actually need, so a stack that under-reserved by a pixel ends
+* at the page bottom instead of spilling past it.
+*/
+const paintFootnoteArea = ({ composer, page, context, contentById }) => {
+	const reservedHeightPx = page.footnoteReservedHeight ?? 0;
+	const noteIds = page.footnoteIds ?? [];
+	if (reservedHeightPx <= 0 || noteIds.length === 0) return;
+	const bodies = noteIds.map((noteId) => ({
+		noteId,
+		content: contentById?.get(noteId)
+	}));
+	const missing = bodies.flatMap(({ noteId, content }) => content === void 0 ? [noteId] : []);
+	if (missing.length > 0) context.unsupported.report(UNSUPPORTED_CONSTRUCT.footnoteContent, context.pageIndex, `footnote bodies ${missing.join(", ")} were not supplied to the builder, so the band reserves their height and paints nothing`);
+	const items = bodies.map(({ noteId, content }) => ({
+		noteId,
+		displayNumber: String(content?.displayNumber ?? noteId),
+		...content === void 0 ? {} : { content: {
+			blocks: content.blocks,
+			measures: content.measures,
+			height: content.height
+		} }
+	}));
+	const contentHeightPx = page.size.h - page.margins.top - page.margins.bottom;
+	const contentWidthPx = page.size.w - page.margins.left - page.margins.right;
+	const bandHeightPx = Math.max(reservedHeightPx, calculateFootnoteAreaRenderHeight(items));
+	const areaTopPx = page.margins.top + Math.max(-page.margins.top, contentHeightPx - bandHeightPx);
+	const primitives = [{
+		kind: "rect",
+		rect: {
+			xPx: page.margins.left,
+			yPx: areaTopPx + FOOTNOTE_RULE_MARGIN_PX,
+			widthPx: contentWidthPx * FOOTNOTE_RULE_WIDTH_FRACTION,
+			heightPx: FOOTNOTE_RULE_THICKNESS_PX
+		},
+		fill: DOC_CANVAS_TEXT
+	}];
+	composer.push(primitives);
+	for (const [index, { noteId, content }] of bodies.entries()) {
+		if (content === void 0) continue;
+		const offsetPx = calculateFootnoteAreaRenderHeight(items.slice(0, index));
+		const story = {
+			kind: "footnote",
+			id: noteId
+		};
+		composer.region({
+			kind: HIT_REGION_KINDS.note,
+			rect: {
+				xPx: page.margins.left,
+				yPx: areaTopPx + offsetPx,
+				widthPx: contentWidthPx,
+				heightPx: content.height
+			},
+			model: { story }
+		}, () => {
+			paintFootnoteBlocks({
+				composer,
+				blocks: content.blocks,
+				measures: content.measures,
+				xPx: page.margins.left,
+				yPx: areaTopPx + offsetPx,
+				widthPx: contentWidthPx,
+				context: {
+					...context,
+					story
+				},
+				label: `footnote ${content.displayNumber}`
+			});
+		});
+	}
+};
+//#endregion
+export { paintColumnSeparators, paintFootnoteArea, paintPageBackground };

package/dist/display-list/build/paragraphPrimitives.d.ts

@@ -0,0 +1,19 @@
+import { ParagraphBlock, ParagraphBorders, ParagraphFragment, ParagraphMeasure } from "../../layout-engine/types.js";
+import { BuildContext } from "./buildContext.js";
+import { PageComposer } from "./regions.js";
+//#region src/display-list/build/paragraphPrimitives.d.ts
+type ParagraphPaintOptions = {
+  /** Where the primitives and the regions over them are collected. */
+  readonly composer: PageComposer;
+  readonly fragment: ParagraphFragment;
+  readonly block: ParagraphBlock;
+  readonly measure: ParagraphMeasure;
+  readonly context: BuildContext;
+  /** Borders of the adjacent paragraphs, for ECMA-376 §17.3.1.24 border grouping. */
+  readonly prevBorders?: ParagraphBorders;
+  readonly nextBorders?: ParagraphBorders;
+};
+/** Every primitive a paragraph fragment paints, back to front. */
+declare const paintParagraphFragment: (options: ParagraphPaintOptions) => void;
+//#endregion
+export { ParagraphPaintOptions, paintParagraphFragment };