@stll/folio-core 0.32.2 → 0.33.0

package/dist/pdf/paint.js

@@ -0,0 +1,442 @@
+import { STROKE_DASH_FACTORS, glyphCellOffsetsPx } from "../display-list/primitives.js";
+import { needsShaping } from "../shaping/placeRun.js";
+import { TEXT_RENDER_MODE, createContentStream } from "./contentStream.js";
+import { basePageMatrix, rotationMatrix } from "./pageSpace.js";
+import { Result, TaggedError, panic } from "better-result";
+//#region src/pdf/paint.ts
+/**
+* Display list to content stream.
+*
+* Everything here is emitted in display-list coordinates: CSS px, origin at
+* the page's top-left, y down. The page's base CTM (see `pageSpace.ts`)
+* converts once, at the stream's first operator, which is why no primitive
+* below does any arithmetic on the page height.
+*/
+var PaintError = class extends TaggedError("PaintError") {};
+/** Thousandths of an em, the unit of a `TJ` adjustment. */
+const TEXT_SPACE_UNITS_PER_EM = 1e3;
+const OPAQUE = 1;
+/** Points sampled along one period of a `wavy` stroke. */
+const WAVY_SAMPLES_PER_PERIOD = 8;
+/** A `double` stroke is drawn as two lines, one either side of the path. */
+const DOUBLE_STROKE_LINES = 2;
+const withAlpha = (context, alpha) => ({
+	...context,
+	alpha
+});
+/**
+* Opens a graphics-state block for one primitive. Alpha is multiplied down
+* from the enclosing groups rather than replaced, so a half-transparent run
+* inside a half-transparent watermark paints at a quarter and not at a half.
+* PDF's `/ca` is per-object, so a group's alpha reaches its children this way
+* instead of compositing the group as a unit; overlapping children inside one
+* opacity group therefore show their seams where a true transparency group
+* would not.
+*/
+const beginPrimitive = (context, alpha) => {
+	context.stream.save();
+	if (alpha < OPAQUE) context.stream.setAlpha(alpha);
+};
+const applyStrokeState = (stream, stroke, widthPx) => {
+	stream.setStrokeColor(stroke.color);
+	stream.setLineWidth(widthPx);
+	const dash = STROKE_DASH_FACTORS[stroke.pattern];
+	if (dash !== null) stream.setDash([dash.dash * stroke.thicknessPx, dash.gap * stroke.thicknessPx], 0);
+};
+/** Unit normal of a segment, or null when the segment has no length. */
+const segmentNormal = (segment) => {
+	const dx = segment.x2Px - segment.x1Px;
+	const dy = segment.y2Px - segment.y1Px;
+	const length = Math.hypot(dx, dy);
+	if (length === 0) return null;
+	return {
+		nx: -dy / length,
+		ny: dx / length
+	};
+};
+const strokeWavy = (stream, stroke, segment) => {
+	const normal = segmentNormal(segment);
+	if (normal === null) return;
+	const dx = segment.x2Px - segment.x1Px;
+	const dy = segment.y2Px - segment.y1Px;
+	const length = Math.hypot(dx, dy);
+	const period = 6 * stroke.thicknessPx;
+	const amplitude = 2 * stroke.thicknessPx / 2;
+	const steps = Math.max(WAVY_SAMPLES_PER_PERIOD, Math.ceil(length / period * WAVY_SAMPLES_PER_PERIOD));
+	for (let step = 0; step <= steps; step += 1) {
+		const along = length * step / steps;
+		const offset = amplitude * Math.sin(2 * Math.PI * along / period);
+		const x = segment.x1Px + dx * step / steps + normal.nx * offset;
+		const y = segment.y1Px + dy * step / steps + normal.ny * offset;
+		if (step === 0) stream.moveTo(x, y);
+		else stream.lineTo(x, y);
+	}
+	stream.stroke();
+};
+const strokeDouble = (stream, stroke, segment) => {
+	const normal = segmentNormal(segment);
+	if (normal === null) return;
+	const offset = 1 * stroke.thicknessPx * DOUBLE_STROKE_LINES / 2;
+	for (const side of [-1, 1]) {
+		stream.moveTo(segment.x1Px + normal.nx * offset * side, segment.y1Px + normal.ny * offset * side);
+		stream.lineTo(segment.x2Px + normal.nx * offset * side, segment.y2Px + normal.ny * offset * side);
+		stream.stroke();
+	}
+};
+const paintSegment = (context, stroke, segment) => {
+	const alpha = context.alpha * stroke.color.a;
+	beginPrimitive(context, alpha);
+	const { stream } = context;
+	switch (stroke.pattern) {
+		case "solid":
+		case "dashed":
+		case "dotted":
+			applyStrokeState(stream, stroke, stroke.thicknessPx);
+			stream.moveTo(segment.x1Px, segment.y1Px);
+			stream.lineTo(segment.x2Px, segment.y2Px);
+			stream.stroke();
+			break;
+		case "double":
+			applyStrokeState(stream, stroke, stroke.thicknessPx);
+			strokeDouble(stream, stroke, segment);
+			break;
+		case "wavy":
+			applyStrokeState(stream, stroke, stroke.thicknessPx);
+			strokeWavy(stream, stroke, segment);
+			break;
+		default: {
+			const unreachable = stroke.pattern;
+			panic(`unhandled stroke pattern: ${String(unreachable)}`);
+		}
+	}
+	stream.restore();
+};
+const paintRect = (context, primitive) => {
+	const { rect, fill, stroke } = primitive;
+	if (fill !== void 0) {
+		beginPrimitive(context, context.alpha * fill.a);
+		context.stream.setFillColor(fill);
+		context.stream.appendRect(rect.xPx, rect.yPx, rect.widthPx, rect.heightPx);
+		context.stream.fill();
+		context.stream.restore();
+	}
+	if (stroke === void 0) return;
+	if (stroke.pattern === "solid") {
+		beginPrimitive(context, context.alpha * stroke.color.a);
+		applyStrokeState(context.stream, stroke, stroke.thicknessPx);
+		context.stream.appendRect(rect.xPx, rect.yPx, rect.widthPx, rect.heightPx);
+		context.stream.stroke();
+		context.stream.restore();
+		return;
+	}
+	const { xPx, yPx, widthPx, heightPx } = rect;
+	const edges = [
+		{
+			x1Px: xPx,
+			y1Px: yPx,
+			x2Px: xPx + widthPx,
+			y2Px: yPx
+		},
+		{
+			x1Px: xPx + widthPx,
+			y1Px: yPx,
+			x2Px: xPx + widthPx,
+			y2Px: yPx + heightPx
+		},
+		{
+			x1Px: xPx + widthPx,
+			y1Px: yPx + heightPx,
+			x2Px: xPx,
+			y2Px: yPx + heightPx
+		},
+		{
+			x1Px: xPx,
+			y1Px: yPx + heightPx,
+			x2Px: xPx,
+			y2Px: yPx
+		}
+	];
+	for (const edge of edges) paintSegment(context, stroke, edge);
+};
+/**
+* Left edge of every code point, from the ordering the display list pins
+* down. The mirroring rule is shared with the DOM backend rather than stated
+* twice: two backends agreeing by coincidence is the divergence the display
+* list exists to prevent.
+*/
+const glyphOrigins = (run) => glyphCellOffsetsPx(run).map((offsetPx) => run.xPx + offsetPx);
+/**
+* Where each glyph of an embedded run goes.
+*
+* Cluster origins come from the display list's own advances whichever path
+* produced the glyphs, so letter spacing and every other adjustment the
+* measurer applied survive: the line was broken on those numbers. What shaping
+* contributes is which glyphs there are and where they sit inside their
+* cluster.
+*/
+const placeEmbeddedRun = (run, font, origins) => {
+	const shaped = font.placeShapedRun({
+		text: run.text,
+		direction: run.direction,
+		fontSizePx: run.fontSizePx
+	});
+	if (shaped === null) return [...run.text].map((character, index) => {
+		const { resourceIndex, glyphId, widthUnits } = font.glyphFor(character.codePointAt(0) ?? 0);
+		return {
+			resourceIndex,
+			glyphId,
+			widthUnits,
+			xPx: origins[index] ?? run.xPx,
+			yPx: run.baselineYPx,
+			advancePx: run.advancesPx[index] ?? 0,
+			displaced: false
+		};
+	});
+	const placed = [];
+	let penPx = run.xPx;
+	let openCluster = null;
+	for (const glyph of shaped) {
+		if (glyph.clusterIndex !== openCluster) {
+			penPx = origins[glyph.clusterIndex] ?? penPx;
+			openCluster = glyph.clusterIndex;
+		}
+		const displaced = glyph.xOffsetPx !== 0 || glyph.yOffsetPx !== 0;
+		placed.push({
+			resourceIndex: glyph.resourceIndex,
+			glyphId: glyph.glyphId,
+			widthUnits: glyph.widthUnits,
+			xPx: penPx + glyph.xOffsetPx,
+			yPx: run.baselineYPx - glyph.yOffsetPx,
+			advancePx: glyph.xAdvancePx,
+			displaced
+		});
+		penPx += glyph.xAdvancePx;
+	}
+	return placed;
+};
+/** Glyphs one text-showing operator can draw together, in painting order. */
+const spanGlyphs = (placed, fontSizePx) => {
+	const spans = [];
+	for (const [index, glyph] of placed.entries()) {
+		const next = placed[index + 1];
+		const open = spans.at(-1);
+		const continues = open !== void 0 && !glyph.displaced && open.resourceIndex === glyph.resourceIndex && open.yPx === glyph.yPx;
+		const delta = next === void 0 || next.displaced || next.yPx !== glyph.yPx ? glyph.advancePx : next.xPx - glyph.xPx;
+		const positioned = {
+			glyphId: glyph.glyphId,
+			adjustment: glyph.widthUnits - delta * TEXT_SPACE_UNITS_PER_EM / fontSizePx
+		};
+		if (continues && open !== void 0) {
+			open.glyphs.push(positioned);
+			continue;
+		}
+		spans.push({
+			resourceIndex: glyph.resourceIndex,
+			xPx: glyph.xPx,
+			yPx: glyph.yPx,
+			glyphs: [positioned]
+		});
+	}
+	return spans;
+};
+const paintGlyphRun = (context, run) => {
+	const codePoints = [...run.text];
+	if (codePoints.length === 0 || run.fontSizePx <= 0) return;
+	const font = context.fonts.get(run.font) ?? panic(`glyph run refers to unprepared font ${String(run.font)}`);
+	const origins = glyphOrigins(run);
+	const { stream } = context;
+	beginPrimitive(context, context.alpha * run.color.a);
+	stream.setFillColor(run.color);
+	if (run.stroke !== void 0) {
+		stream.setStrokeColor(run.stroke.color);
+		stream.setLineWidth(run.stroke.thicknessPx);
+	}
+	stream.beginText();
+	switch (font.kind) {
+		case "embedded": {
+			const spans = spanGlyphs(placeEmbeddedRun(run, font, origins), run.fontSizePx);
+			for (const [spanIndex, span] of spans.entries()) {
+				stream.setFont(span.resourceIndex, run.fontSizePx);
+				if (spanIndex === 0 && run.stroke !== void 0) stream.setTextRenderMode(TEXT_RENDER_MODE.fillThenStroke);
+				stream.setTextMatrix([
+					1,
+					0,
+					0,
+					-1,
+					span.xPx,
+					span.yPx
+				]);
+				stream.showGlyphs(span.glyphs);
+			}
+			break;
+		}
+		case "standard":
+			stream.setFont(font.resourceIndex, run.fontSizePx);
+			if (run.stroke !== void 0) stream.setTextRenderMode(TEXT_RENDER_MODE.fillThenStroke);
+			for (const [index, codePoint] of codePoints.entries()) {
+				stream.setTextMatrix([
+					1,
+					0,
+					0,
+					-1,
+					origins[index] ?? run.xPx,
+					run.baselineYPx
+				]);
+				stream.showBytes([font.byteFor(codePoint.codePointAt(0) ?? 0)]);
+			}
+			break;
+		default: panic(`unhandled prepared font: ${JSON.stringify(font)}`);
+	}
+	stream.endText();
+	stream.restore();
+};
+const paintImage = (context, primitive) => {
+	const { rect, crop, opacity } = primitive;
+	const { stream } = context;
+	beginPrimitive(context, context.alpha * opacity);
+	if (crop === void 0) {
+		stream.concat([
+			rect.widthPx,
+			0,
+			0,
+			-rect.heightPx,
+			rect.xPx,
+			rect.yPx + rect.heightPx
+		]);
+		stream.drawImage(primitive.image);
+		stream.restore();
+		return;
+	}
+	const visibleWidth = 1 - crop.l - crop.r;
+	const visibleHeight = 1 - crop.t - crop.b;
+	if (visibleWidth <= 0 || visibleHeight <= 0) {
+		stream.restore();
+		return;
+	}
+	stream.appendRect(rect.xPx, rect.yPx, rect.widthPx, rect.heightPx);
+	stream.clipToCurrentPath();
+	const fullWidth = rect.widthPx / visibleWidth;
+	const fullHeight = rect.heightPx / visibleHeight;
+	const left = rect.xPx - crop.l * fullWidth;
+	const top = rect.yPx - crop.t * fullHeight;
+	stream.concat([
+		fullWidth,
+		0,
+		0,
+		-fullHeight,
+		left,
+		top + fullHeight
+	]);
+	stream.drawImage(primitive.image);
+	stream.restore();
+};
+const paintPrimitive = (context, primitive) => {
+	switch (primitive.kind) {
+		case "glyphRun":
+			paintGlyphRun(context, primitive);
+			return;
+		case "rect":
+			paintRect(context, primitive);
+			return;
+		case "line":
+			paintSegment(context, primitive.stroke, {
+				x1Px: primitive.x1Px,
+				y1Px: primitive.y1Px,
+				x2Px: primitive.x2Px,
+				y2Px: primitive.y2Px
+			});
+			return;
+		case "image":
+			paintImage(context, primitive);
+			return;
+		case "clipGroup":
+			context.stream.save();
+			context.stream.appendRect(primitive.rect.xPx, primitive.rect.yPx, primitive.rect.widthPx, primitive.rect.heightPx);
+			context.stream.clipToCurrentPath();
+			for (const child of primitive.children) paintPrimitive(context, child);
+			context.stream.restore();
+			return;
+		case "rotateGroup":
+			context.stream.save();
+			context.stream.concat(rotationMatrix(primitive.degrees, primitive.originXPx, primitive.originYPx));
+			for (const child of primitive.children) paintPrimitive(context, child);
+			context.stream.restore();
+			return;
+		case "opacityGroup": {
+			const alpha = context.alpha * primitive.opacity;
+			context.stream.save();
+			context.stream.setAlpha(alpha);
+			const inner = withAlpha(context, alpha);
+			for (const child of primitive.children) paintPrimitive(inner, child);
+			context.stream.restore();
+			return;
+		}
+		default: panic(`unhandled display primitive: ${JSON.stringify(primitive)}`);
+	}
+};
+const paintPage = ({ page, fonts }) => {
+	const stream = createContentStream();
+	stream.concat(basePageMatrix(page.heightPx));
+	const context = {
+		stream,
+		fonts,
+		alpha: OPAQUE
+	};
+	for (const primitive of page.primitives) paintPrimitive(context, primitive);
+	return stream.parts();
+};
+const collectPrimitive = (primitive, fontCount, imageCount, into) => {
+	switch (primitive.kind) {
+		case "glyphRun": {
+			if (primitive.font < 0 || primitive.font >= fontCount) return new PaintError({ message: `glyph run refers to font ${String(primitive.font)}, outside the font table` });
+			const codePoints = [...primitive.text];
+			if (codePoints.length !== primitive.advancesPx.length) return new PaintError({ message: `glyph run carries ${String(primitive.advancesPx.length)} advances for ${String(codePoints.length)} code points` });
+			const seen = into.codePointsByFont.get(primitive.font) ?? /* @__PURE__ */ new Set();
+			for (const codePoint of codePoints) seen.add(codePoint.codePointAt(0) ?? 0);
+			into.codePointsByFont.set(primitive.font, seen);
+			if (needsShaping(primitive.text)) {
+				const runs = into.shapedRunsByFont.get(primitive.font) ?? [];
+				runs.push({
+					text: primitive.text,
+					direction: primitive.direction,
+					fontSizePx: primitive.fontSizePx
+				});
+				into.shapedRunsByFont.set(primitive.font, runs);
+			}
+			return null;
+		}
+		case "rect":
+		case "line": return null;
+		case "image":
+			if (primitive.image < 0 || primitive.image >= imageCount) return new PaintError({ message: `image primitive refers to image ${String(primitive.image)}, outside the image table` });
+			into.imageIndices.add(primitive.image);
+			return null;
+		case "clipGroup":
+		case "rotateGroup":
+		case "opacityGroup":
+			for (const child of primitive.children) {
+				const error = collectPrimitive(child, fontCount, imageCount, into);
+				if (error !== null) return error;
+			}
+			return null;
+		default: return panic(`unhandled display primitive: ${JSON.stringify(primitive)}`);
+	}
+};
+/**
+* Walks the pages once before anything is written, because subsetting needs
+* every glyph the document uses before the first one is emitted.
+*/
+const collectUsage = (pages, fontCount, imageCount) => {
+	const into = {
+		codePointsByFont: /* @__PURE__ */ new Map(),
+		shapedRunsByFont: /* @__PURE__ */ new Map(),
+		imageIndices: /* @__PURE__ */ new Set()
+	};
+	for (const page of pages) for (const primitive of page.primitives) {
+		const error = collectPrimitive(primitive, fontCount, imageCount, into);
+		if (error !== null) return Result.err(error);
+	}
+	return Result.ok(into);
+};
+//#endregion
+export { PaintError, collectUsage, paintPage };

package/dist/pdf/writePdf.d.ts

@@ -0,0 +1,56 @@
+import { DisplayList } from "../display-list/types.js";
+import { PdfFontSource, PdfSubstitution } from "./fonts.js";
+import { Result } from "better-result";
+//#region src/pdf/writePdf.d.ts
+type WritePdfOptions = {
+  readonly fonts: PdfFontSource;
+  /**
+   * Creation and modification instant stamped into the PDF, ISO-8601.
+   * Required rather than defaulted so a caller cannot get a
+   * nondeterministic document by omission.
+   */
+  readonly timestamp: string;
+  readonly producer?: string;
+  /**
+   * Refuse to write a document containing a code point no supplied face can
+   * encode, instead of painting `.notdef` and reporting it. For a caller that
+   * would rather fail than hand a reader a page of empty boxes.
+   */
+  readonly strictGlyphCoverage?: boolean;
+};
+/**
+ * A code point no binary of its face could encode. It is painted as `.notdef`
+ * and reported here, never dropped and never silently substituted: a reader
+ * cannot tell an empty box from a character the document never had, and every
+ * such code point collapses onto glyph 0, so even `/ToUnicode` cannot tell
+ * them apart afterwards.
+ */
+type PdfUnencodable = {
+  readonly codePoint: number;
+  readonly family: string;
+  readonly weight: number;
+  readonly italic: boolean;
+};
+type WritePdfResult = {
+  readonly bytes: Uint8Array;
+  /** Faces the font source could not supply, painted with a base-14 stand-in. */
+  readonly substitutions: readonly PdfSubstitution[];
+  /** Code points painted as `.notdef` because no supplied face covers them. */
+  readonly unencodable: readonly PdfUnencodable[];
+};
+declare const WritePdfError_base: import("better-result").TaggedErrorClass<"WritePdfError">;
+declare class WritePdfError extends WritePdfError_base<{
+  message: string;
+  cause?: unknown;
+}> {}
+/**
+ * Writes the display list as a PDF.
+ *
+ * Asynchronous for one reason: a run in a script that shapes needs the shaper,
+ * and the shaper is fetched the first time a document actually contains one. A
+ * document in Latin, Cyrillic or Greek never awaits anything but the resolved
+ * promise this returns.
+ */
+declare const writePdf: (list: DisplayList, options: WritePdfOptions) => Promise<Result<WritePdfResult, WritePdfError>>;
+//#endregion
+export { type PdfFontSource, type PdfSubstitution, PdfUnencodable, WritePdfError, WritePdfOptions, WritePdfResult, writePdf };