Skip to content

A one-of-a-kind resume builder that keeps your privacy in mind. Completely secure, customizable, portable, open-source and free forever. Try it out today!

23.6 KB
Raw Blame
import type { ResumeRenderOptions } from "../context";
import type { PageMap } from "../page-map";
import type { ConvertedDocument } from "./to-forme";
import type { ElementInfo, RenderWithLayoutResult } from "@formepdf/core";
import type { FormeDocument, FormeNode, FormeStyle } from "@formepdf/react";
import type { ResumeData } from "@reactive-resume/schema/resume/data";
import type { Template } from "@reactive-resume/schema/templates";
import type { Locale } from "@reactive-resume/utils/locale";
import type { ReactElement } from "react";
import { createElement } from "react";
import { ResumeDocument } from "../document";
import { resolvePdfFonts, resumeContentScripts, resumeUsesItalic } from "../hooks/use-register-fonts";
import { extractPageMap, NODE_CONTENT_PREFIX, NODE_SOURCE_PREFIX, parseResumeNodeKey } from "../page-map";
import { loadFonts } from "./fonts";
import { loadRequestedIcons } from "./icons";
import { imageSources, loadImages } from "./images";
import { renderHostTree } from "./reconciler";
import { FIXED_SOURCE, FREE_FORM_MEASURE_HEIGHT, LIST_ROLE, toFormeDocument } from "./to-forme";

/** The Forme entry point for this runtime: `@formepdf/core` in Node, `@formepdf/core/worker` in browsers. */
export type FormeEngine = {
	renderSerializedDocWithLayout: (document: Record<string, unknown>) => Promise<RenderWithLayoutResult>;
	/** What to hand Forme for a font's bytes, given every character the document draws (see `browser.tsx`). */
	prepareFont?: ((bytes: Uint8Array, text: string) => Uint8Array | string | Promise<Uint8Array | string>) | undefined;
};

export type RenderResumeInput = {
	/** Parsed with `parseResumeData`: the entry points check data at their boundary. */
	data: ResumeData;
	template?: Template | undefined;
	renderOptions?: ResumeRenderOptions | undefined;
	readImage?: ((source: string) => Promise<Uint8Array>) | undefined;
	/** Computer Modern mirror supplied by the server entry; browser callers leave it unset. */
	webFontBaseUrl?: string | undefined;
};

export type RenderedResume = {
	pdf: Uint8Array;
	/** Header, section and item boxes, for click-to-edit, Check and Fit (see `page-map.ts`). */
	pageMap: PageMap;
	/** Forme's layout of every page, for tests and diagnostics. */
	layout: RenderWithLayoutResult["layout"];
	/** Font families that couldn't be downloaded; their text falls back to the standard PDF fonts. */
	missingFonts: string[];
	/** Rendering diagnostics; `lostCharacters` reads the characters no font could draw from them. */
	warnings: string[];
};

/** A failed font download would print the resume in other fonts: the file waits for a retry instead. */
export function assertPdfFonts({ missingFonts }: Pick<RenderedResume, "missingFonts">) {
	if (missingFonts.length > 0)
		throw new Error(`Fonts could not be loaded: ${missingFonts.join(", ")}. Retry the export.`, {
			cause: "pdf-text-loss",
		});
}

/**
 * The characters no font in the resume can draw, as Forme names them (`"₹" (U+20B9)`); Forme draws them as "?".
 * Null when every character rendered; empty when text was lost without Forme naming the characters.
 */
export function lostCharacters(warnings: readonly string[]): string[] | null {
	const lost = warnings.filter(
		(warning) =>
			warning.includes('was rendered as "?"') || warning.includes("character(s) of source text did not render"),
	);
	if (lost.length === 0) return null;
	return [...new Set(lost.flatMap((warning) => warning.match(/"[^"]*" \(U\+[0-9A-F]+\)/g) ?? []))];
}

const uncoveredCharacters = (warnings: readonly string[]) =>
	new Set((lostCharacters(warnings) ?? []).map((character) => character.slice(1, character.lastIndexOf('"'))));

/** Substitute in render-owned text only, asking the same engine which fonts actually need the replacement. */
async function substituteMissingGlyphs(
	document: FormeDocument,
	characters: ReadonlySet<string>,
	draw: (document: FormeDocument) => Promise<RenderWithLayoutResult>,
	cache: Map<string, Set<string>>,
) {
	const groups = new Map<string, { style: FormeStyle; characters: Set<string>; text: { content: string }[] }>();
	const collect = (text: { content: string }, inherited: FormeStyle) => {
		const candidates = [...text.content].filter((character) => characters.has(character));
		if (candidates.length === 0) return;
		const style = {
			fontFamily: inherited.fontFamily ?? "Helvetica",
			fontWeight: inherited.fontWeight ?? 400,
			fontStyle: inherited.fontStyle ?? "Normal",
		};
		const key = JSON.stringify(style);
		let group = groups.get(key);
		if (!group) groups.set(key, (group = { style, characters: new Set(), text: [] }));
		for (const character of candidates) group.characters.add(character);
		group.text.push(text);
	};
	const visit = (node: FormeNode, inherited: FormeStyle) => {
		const style = { ...inherited, ...node.style };
		const { kind } = node;
		if (kind.type === "Text" || kind.type === "Heading") {
			if (kind.runs?.length) for (const run of kind.runs) collect(run, { ...style, ...run.style });
			else collect(kind, style);
		}
		for (const child of node.children) visit(child, style);
	};
	for (const child of document.children) visit(child, document.defaultStyle ?? {});
	let changed = false;
	for (const [key, group] of groups) {
		const content = [...group.characters].sort().join("");
		const cacheKey = `${key}:${content}`;
		let missing = cache.get(cacheKey);
		if (!missing) {
			const probe = await draw({
				...document,
				children: [
					{
						kind: { type: "Page", config: document.defaultPage },
						style: {},
						children: [{ kind: { type: "Text", content }, style: group.style, children: [] }],
					},
				],
			});
			missing = uncoveredCharacters(probe.warnings);
			cache.set(cacheKey, missing);
		}
		for (const text of group.text) {
			const replacement = [...text.content].map((character) => (missing.has(character) ? "?" : character)).join("");
			changed ||= replacement !== text.content;
			text.content = replacement;
		}
	}
	return changed;
}

/** Every character in the document's strings, sorted: its text, plus style values and links, which cost little. */
function documentText(document: FormeDocument): string {
	const characters = new Set<string>();
	const visit = (value: unknown, key?: string) => {
		if (typeof value === "string") {
			// Pictures are data URIs: base64 adds no character a font needs.
			if (key !== "src") for (const character of value) characters.add(character);
		} else if (Array.isArray(value)) for (const item of value) visit(item);
		else if (value && typeof value === "object") for (const [name, item] of Object.entries(value)) visit(item, name);
	};
	visit(document);
	return [...characters].sort().join("");
}

// A4 height: a free-form page is never shorter than a sheet of paper, as before.
const FREE_FORM_MIN_HEIGHT = 841.89;

type PageKind = Extract<FormeDocument["children"][number]["kind"], { type: "Page" }>;

// Forme leaves a box it failed to place at ±Number.MAX_VALUE; the page is then likely wrong.
const offPage = (value: number) => !(Math.abs(value) < 1e6);
const misplacesABox = (result: RenderWithLayoutResult) =>
	result.layout.pages.some((page) =>
		page.elements.some(function bad(element): boolean {
			return offPage(element.y) || offPage(element.height) || element.children.some(bad);
		}),
	);

/** Missing sections and items with text Forme failed to place while splitting a column. */
function unplacedBlocks(layout: RenderWithLayoutResult["layout"]): string[] {
	const placed = new Set(
		extractPageMap(layout)
			.nodes.filter((node) => node.kind === "section")
			.map((node) => node.key),
	);
	const missing = new Set<string>();
	const visit = (element: ElementInfo, itemKey?: string) => {
		let ownerItemKey = itemKey;
		const source = element.sourceLocation?.file;
		if (source?.startsWith(NODE_SOURCE_PREFIX) || source?.startsWith(NODE_CONTENT_PREFIX)) {
			const key = source.slice(source.indexOf(":") + 1);
			if (parseResumeNodeKey(key)?.kind === "item") ownerItemKey = key;
		}
		if (source?.startsWith(NODE_SOURCE_PREFIX) && (offPage(element.y) || offPage(element.height))) {
			const key = source.slice(NODE_SOURCE_PREFIX.length);
			if (parseResumeNodeKey(key)?.kind === "section" && !placed.has(key)) missing.add(key);
		}
		if (element.kind === "Text" && offPage(element.y) && ownerItemKey) missing.add(ownerItemKey);
		for (const child of element.children) visit(child, ownerItemKey);
	};
	for (const page of layout.pages) for (const element of page.elements) visit(element);
	return [...missing];
}

/** Measure stable keep-with-next space; oversized descriptions still split after their first line. */
function entryPaginationRepairs(layout: RenderWithLayoutResult["layout"], splitItems: ReadonlySet<number>) {
	const headers = new Map<
		string,
		{ page: number; lastPage: number; top: number; bottom: number; height: number; available: number }
	>();
	const bodies = new Map<string, { page: number; y: number; height: number; lineHeight: number }>();
	for (const [pageIndex, page] of layout.pages.entries()) {
		const visit = (element: ElementInfo, parentSource?: ElementInfo["sourceLocation"]) => {
			const source = element.sourceLocation ?? parentSource;
			if (source && !offPage(element.y) && !offPage(element.height)) {
				const key = source.file.replace(/^(rr-node:|rr-in:)/, "");
				const item = key.match(/^(.+\/section-items\/item-[^/]+)/)?.[1];
				if (item && element.kind === "Text" && key.startsWith(`${item}/item-header`)) {
					const header = headers.get(item);
					if (!header)
						headers.set(item, {
							page: pageIndex,
							lastPage: pageIndex,
							top: element.y,
							bottom: element.y + element.height,
							height: 0,
							available: page.contentHeight,
						});
					else {
						if (header.lastPage === pageIndex) {
							header.top = Math.min(header.top, element.y);
							header.bottom = Math.max(header.bottom, element.y + element.height);
						} else {
							header.height += header.bottom - header.top;
							header.lastPage = pageIndex;
							header.top = element.y;
							header.bottom = element.y + element.height;
						}
					}
				} else if (
					item &&
					!key.startsWith(`${item}/item-header`) &&
					!bodies.has(item) &&
					(source.column === LIST_ROLE.item || (element.kind === "Text" && source.column !== LIST_ROLE.marker))
				) {
					const lineHeight = element.style.fontSize * element.style.lineHeight;
					bodies.set(item, {
						page: pageIndex,
						y: element.y,
						lineHeight,
						height:
							source.column === LIST_ROLE.item && !splitItems.has(source.line - 1)
								? element.height + element.style.margin.top + element.style.margin.bottom
								: lineHeight,
					});
				}
			}
			for (const child of element.children) visit(child, source);
		};
		for (const element of page.elements) visit(element);
	}
	const presenceAhead = new Map<string, number>();
	const orphans: string[] = [];
	for (const [key, header] of headers) {
		const body = bodies.get(key);
		if (!body) continue;
		const headerKey = `${key}/item-header`;
		const gap = body.page === header.lastPage ? Math.max(0, body.y - header.bottom) : body.lineHeight;
		const ahead = body.height + gap;
		if (header.height + header.bottom - header.top + ahead <= header.available) {
			presenceAhead.set(headerKey, ahead);
			if (body.page > header.page) orphans.push(headerKey);
		}
	}
	return { orphans, presenceAhead };
}

const isFixed = (element: ElementInfo): boolean =>
	element.sourceLocation?.file === FIXED_SOURCE || element.children.some(isFixed);

/** Flow constraints for large items, and marker/row repairs for items that still split (see `LIST_ROLE`). */
function listPaginationRepairs(layout: RenderWithLayoutResult["layout"]) {
	const markerPage = new Map<number, number>();
	const contentPage = new Map<number, number>();
	const itemPage = new Map<number, number>();
	const split = new Set<number>();
	const oversized = new Set<number>();
	const contentPages = new Map<number, Set<number>>();
	layout.pages.forEach((page, pageIndex) => {
		const visit = (element: ElementInfo, availableHeight: number, parentSource?: ElementInfo["sourceLocation"]) => {
			const source = element.sourceLocation;
			const inheritedSource = source ?? parentSource;
			if (inheritedSource?.column === LIST_ROLE.content && element.kind === "Text" && !offPage(element.y)) {
				const pages = contentPages.get(inheritedSource.line) ?? new Set<number>();
				pages.add(pageIndex);
				contentPages.set(inheritedSource.line, pages);
			}
			const { margin, padding, borderWidth } = element.style;
			if (source?.column === LIST_ROLE.item) {
				const height = element.height + margin.top + margin.bottom;
				// Prefer splitting large rows for page fill; only rows exceeding a fresh page cannot stay whole.
				if (height > availableHeight / 4) split.add(source.line - 1);
				if (height > availableHeight) oversized.add(source.line - 1);
			}
			const pages =
				source?.column === LIST_ROLE.marker
					? markerPage
					: source?.column === LIST_ROLE.content
						? contentPage
						: source?.column === LIST_ROLE.item
							? itemPage
							: null;
			// Forme leaves some fragments of a splitting box at y ±Number.MAX_VALUE; they aren't on this page.
			if (source && pages && !pages.has(source.line) && !offPage(element.y)) pages.set(source.line, pageIndex);
			const innerHeight = availableHeight - padding.top - padding.bottom - borderWidth.top - borderWidth.bottom;
			for (const child of element.children) visit(child, innerHeight, inheritedSource);
		};
		for (const element of page.elements) visit(element, page.contentHeight);
	});
	const breakBefore = [...markerPage]
		.flatMap(([line, page]) => {
			const content = contentPage.get(line) ?? page;
			// Forme can move both companions to a new page but drop their row, reserving only the marker's line height.
			const detached = page > 0 && content === page && itemPage.get(line) !== page;
			return content > page || detached ? [line - 1] : [];
		})
		.sort((a, b) => a - b);
	const unsplit = [...contentPages].flatMap(([line, pages]) => (pages.size === 1 ? [line - 1] : []));
	return { split, oversized, breakBefore, unsplit };
}

/**
 * Where a box's content ends on a free-form measuring page. A box reaching the bottom of the space it sits in was
 * stretched to fill the measuring page (the content box around repeated backgrounds, a row page's columns,
 * `minHeight: "100%"`), so it ends where its own children do instead.
 */
function contentBottom(element: ElementInfo, limit: number): number {
	const bottom = element.y + element.height;
	if (bottom + element.style.margin.bottom < limit - 0.5) return bottom;
	const { padding, borderWidth } = element.style;
	const end = padding.bottom + borderWidth.bottom;
	const content = element.children.reduce(
		(lowest, child) => Math.max(lowest, contentBottom(child, bottom - end) + child.style.margin.bottom),
		element.y + padding.top + borderWidth.top,
	);
	return content + end;
}

/** A free-form page's content height: where its content ends plus the page's bottom margin. */
function measuredHeight(result: RenderWithLayoutResult, pageIndex: number, marginBottom: number) {
	const page = result.layout.pages[pageIndex];
	if (!page) return FREE_FORM_MIN_HEIGHT;
	// Repeated backgrounds span the page they're measured on, so they don't count.
	const content = page.elements.filter((element) => !isFixed(element));
	const pageBottom = page.contentY + page.contentHeight;
	const bottom = content.reduce((lowest, element) => Math.max(lowest, contentBottom(element, pageBottom)), 0);
	return Math.max(FREE_FORM_MIN_HEIGHT, Math.ceil(bottom + marginBottom));
}

/** The font faces a resume's PDF embeds: its typography, italics if it uses any, and a fallback per writing system. */
export const resumeFontRequests = (data: ResumeData) =>
	resolvePdfFonts(
		data.metadata.typography,
		data.metadata.page.locale as Locale,
		resumeContentScripts(data),
		resumeUsesItalic(data),
	).fonts;

/**
 * Renders a resume or letter to PDF bytes with its page map. Every PDF in the app goes through here: the live
 * preview, downloads, thumbnails, the public page and the server export.
 */
export function renderResume(engine: FormeEngine, input: RenderResumeInput): Promise<RenderedResume> {
	const { data } = input;
	return renderResumeElement(
		engine,
		createElement(ResumeDocument, {
			data,
			template: input.template ?? data.metadata.template,
			...(input.renderOptions ? { renderOptions: input.renderOptions } : {}),
		}),
		input.readImage,
		input.webFontBaseUrl,
	);
}

/**
 * Renders an element tree (normally a `ResumeDocument`) to PDF. The fonts come from the `data` prop of the root
 * element when it has one; without it, only the standard PDF fonts are available.
 */
export async function renderResumeElement(
	engine: FormeEngine,
	element: ReactElement,
	readImage?: (source: string) => Promise<Uint8Array>,
	webFontBaseUrl?: string,
): Promise<RenderedResume> {
	const data = (element.props as { data?: ResumeData }).data;
	// Font downloads start first: they're the largest wait, and the tree needs only the icons.
	const fontsLoaded = loadFonts(data ? resumeFontRequests(data) : [], webFontBaseUrl);
	let tree = renderHostTree(element);
	// Icons load on first use: a tree that asked for new ones is drawn again once they arrive.
	if (await loadRequestedIcons()) tree = renderHostTree(element);
	const [{ fonts, warnings: fontWarnings, missing }, { images, warnings: imageWarnings }] = await Promise.all([
		fontsLoaded,
		loadImages(imageSources(tree), readImage),
	]);

	const breakBeforeListItems = new Set<number>();
	const splitListItems = new Set<number>();
	const breakBeforeNodes = new Set<string>();
	const presenceAheadNodes = new Map<string, number>();
	// Every pass draws the same text, so the fonts are prepared once, from the first pass's document.
	let formeFonts: typeof fonts | undefined;
	const missingGlyphs = new Set<string>();
	const missingGlyphWarnings = new Set<string>();
	const glyphSubstitutions = new Map<string, Set<string>>();
	const layOutOnce = async (keepNestedRowsWhole: boolean) => {
		const convert = (freeFormHeights?: (number | undefined)[]) =>
			toFormeDocument(tree, {
				images,
				keepNestedRowsWhole,
				breakBeforeListItems,
				splitListItems,
				breakBeforeNodes,
				presenceAheadNodes,
				freeFormHeights,
			});
		// Forme rewrites the font entries it's given (bytes to base64), so each render gets its own.
		const render = async ({ document }: ConvertedDocument) => {
			if (!formeFonts) {
				const { prepareFont } = engine;
				const text = prepareFont ? documentText(document) : "";
				formeFonts = prepareFont
					? await Promise.all(
							fonts.map(async (font) => ({ ...font, src: await prepareFont(font.src as Uint8Array, text) })),
						)
					: fonts;
			}
			const preparedFonts = formeFonts;
			const draw = (input: FormeDocument) =>
				engine.renderSerializedDocWithLayout({ ...input, fonts: preparedFonts.map((font) => ({ ...font })) });
			if (missingGlyphs.size) await substituteMissingGlyphs(document, missingGlyphs, draw, glyphSubstitutions);
			let result = await draw(document);
			const uncovered = uncoveredCharacters(result.warnings);
			if (uncovered.size) {
				for (const character of uncovered) missingGlyphs.add(character);
				for (const warning of result.warnings)
					if (uncoveredCharacters([warning]).size) missingGlyphWarnings.add(warning);
				// shortcut: Forme 0.29 measures missing glyphs before substituting "?"; remove this retry when fixed upstream.
				if (await substituteMissingGlyphs(document, missingGlyphs, draw, glyphSubstitutions))
					result = await draw(document);
			}
			return result;
		};
		let converted = convert();
		let result = await render(converted);

		// Free-form pages grow with their content: measure it, then convert and render once more at that height, so
		// what spans the page (repeated backgrounds, percentages of it) spans the measured one.
		const heights = converted.document.children.map((page, index) => {
			const kind = page.kind as PageKind;
			if (kind.type !== "Page" || typeof kind.config.size !== "object") return undefined;
			if (kind.config.size.Custom.height !== FREE_FORM_MEASURE_HEIGHT) return undefined;
			return measuredHeight(result, index, kind.config.margin.bottom);
		});
		if (heights.some((height) => height !== undefined)) {
			converted = convert(heights);
			result = await render(converted);
		}
		return { result, warnings: converted.warnings };
	};

	// Flow constraints remain valid when earlier rows move: batch repairs of rows that fit a fresh page. Only
	// oversized rows need positional repairs, whose later break positions must be rechecked after each move.
	const layOut = async (keepNestedRowsWhole: boolean) => {
		breakBeforeListItems.clear();
		splitListItems.clear();
		const whole = new Set<number>();
		let measuredOversized: ReadonlySet<number> | undefined;
		for (;;) {
			const laidOut = await layOutOnce(keepNestedRowsWhole);
			const repairs = listPaginationRepairs(laidOut.result.layout);
			// Capture full intrinsic heights before reopening rows; later fragments do not measure the whole row.
			const oversized = (measuredOversized ??= repairs.oversized);
			let changed = false;
			for (const item of repairs.split) {
				if (whole.has(item) || splitListItems.has(item)) continue;
				splitListItems.add(item);
				changed = true;
			}
			if (changed) continue;
			if (repairs.breakBefore.some((item) => !oversized.has(item))) {
				// Reserve fitting rows already in one piece too, so later rows do not repeat the same defect after reflow.
				// Preserve genuine continuations: their content already spans pages without leaving its marker behind.
				for (const item of [...repairs.breakBefore, ...repairs.unsplit]) {
					if (oversized.has(item) || whole.has(item) || !splitListItems.has(item)) continue;
					whole.add(item);
					splitListItems.delete(item);
					changed = true;
				}
			}
			if (changed) continue;
			// shortcut: oversized rows need sequential marker repair until Forme supports atomic first fragments.
			const first = repairs.breakBefore.find((item) => oversized.has(item) && !breakBeforeListItems.has(item));
			if (first === undefined) {
				if (repairs.breakBefore.some((item) => !oversized.has(item)) && !misplacesABox(laidOut.result))
					throw new Error("The PDF engine could not keep a list marker with its content.");
				return laidOut;
			}
			breakBeforeListItems.add(first);
		}
	};

	let { result, warnings } = await layOut(false);
	let keepNestedRowsWhole = misplacesABox(result);
	if (keepNestedRowsWhole) ({ result, warnings } = await layOut(true));
	// shortcut: three repairs cap rendering cost until Forme supports keep-with-next and reliable nested pagination.
	for (let pass = 0; pass < 3; pass++) {
		const first = unplacedBlocks(result.layout).find((key) => !breakBeforeNodes.has(key));
		const headers = entryPaginationRepairs(result.layout, splitListItems);
		const reserveHeaders = headers.orphans.length > 0 && presenceAheadNodes.size === 0;
		if (!first && !reserveHeaders) break;
		// Reserve all first fragments together: the constraint remains valid after earlier entries move.
		if (reserveHeaders) for (const [key, height] of headers.presenceAhead) presenceAheadNodes.set(key, height);
		if (first) breakBeforeNodes.add(first);
		keepNestedRowsWhole ||= first !== undefined || misplacesABox(result);
		({ result, warnings } = await layOut(keepNestedRowsWhole));
	}
	if (entryPaginationRepairs(result.layout, splitListItems).orphans.length > 0)
		warnings.push("render defect: the engine couldn't keep an entry header with its content");
	if (misplacesABox(result))
		warnings.push("render defect: the engine couldn't place a box; a page may be laid out wrong");

	return {
		pdf: result.pdf,
		pageMap: extractPageMap(result.layout),
		missingFonts: [...new Set(missing)],
		layout: result.layout,
		warnings: [
			...new Set([...fontWarnings, ...imageWarnings, ...warnings, ...result.warnings, ...missingGlyphWarnings]),
		],
	};
}