@twango/twiki 0.0.0-stage → 0.1.0-rc.0

package/site/tooling/lib/r-runtime.ts

@@ -0,0 +1,257 @@
+import { execFileSync } from 'node:child_process';
+import { createHash, randomBytes } from 'node:crypto';
+import { existsSync, lstatSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { resolveProject, declaredContentCourses, discoverSourceFiles } from './project-config';
+
+const runtimeEnvironment = [
+	'PATH',
+	'R_HOME',
+	'RHOME',
+	'R_LIBS',
+	'R_LIBS_SITE',
+	'R_LIBS_USER',
+	'R_ENVIRON',
+	'R_ENVIRON_USER',
+	'R_PROFILE',
+	'R_PROFILE_USER',
+	'LD_LIBRARY_PATH',
+	'FONTCONFIG_PATH',
+	'FONTCONFIG_FILE',
+	'FONTCONFIG_SYSROOT',
+	'FC_LANG',
+	'XDG_CONFIG_HOME',
+	'XDG_DATA_HOME'
+] as const;
+const probes = new Map<string, string>();
+const unavailableFontIdentity = randomBytes(16).toString('hex');
+
+/** Font paths locate inputs; only portable face metadata and content hashes enter the identity. */
+export function rFontIdentity(environment: NodeJS.ProcessEnv = process.env) {
+	const deadline = performance.now() + 5_000;
+	const maximumBytes = 256 * 1024 * 1024;
+	let bytes = 0;
+	const hashes = new Map<string, string>();
+	const hashFile = (file: string, maximumSize: number) => {
+		if (hashes.has(file)) return hashes.get(file)!;
+		const info = statSync(file);
+		if (
+			!info.isFile() ||
+			info.size > maximumSize ||
+			bytes + info.size > maximumBytes ||
+			hashes.size >= 512 ||
+			performance.now() >= deadline
+		)
+			throw new Error('Font identity exceeds its probe budget');
+		const content = readFileSync(file);
+		bytes += content.length;
+		const hash = createHash('sha256').update(content).digest('hex');
+		hashes.set(file, hash);
+		return hash;
+	};
+	const run = (command: string, args: string[]) => {
+		const remaining = Math.floor(deadline - performance.now());
+		if (remaining < 1) throw new Error('Font identity probe timed out');
+		return execFileSync(command, args, {
+			env: environment,
+			encoding: 'utf8',
+			timeout: Math.min(2_000, remaining),
+			maxBuffer: 1024 * 1024,
+			stdio: ['ignore', 'pipe', 'pipe']
+		});
+	};
+	const format =
+		'%{file}\t%{family}\t%{style}\t%{fontversion}\t%{foundry}\t%{index}\t%{antialias}\t%{hinting}\t%{hintstyle}\t%{rgba}\n';
+	const faces = (output: string) =>
+		[
+			...new Set(
+				output
+					.split('\n')
+					.filter(Boolean)
+					.map((line) => {
+						const [file, ...metadata] = line.split('\t');
+						if (!file || metadata.length !== 9) throw new Error('Invalid resolved font metadata');
+						return JSON.stringify([metadata, hashFile(file, 64 * 1024 * 1024)]);
+					})
+			)
+		].sort();
+	try {
+		const inventory = faces(run('fc-list', ['--format', format]));
+		if (!inventory.length) throw new Error('Font inventory is empty');
+		const matches = [];
+		for (const family of ['', 'sans', 'serif', 'monospace', 'symbol']) {
+			for (const style of ['', 'Bold', 'Italic', 'Bold Italic']) {
+				const pattern = family + (style ? `:style=${style}` : '');
+				const resolved = faces(run('fc-match', ['--format', format, pattern]));
+				if (!resolved.length) throw new Error('Default font cannot be resolved');
+				matches.push([pattern, resolved]);
+			}
+		}
+		const configuration = run('fc-conflist', [])
+			.split('\n')
+			.filter((line) => line.startsWith('+ '))
+			.map((line) => {
+				const separator = line.indexOf(': ', 2);
+				if (separator < 0) throw new Error('Invalid active font configuration');
+				return hashFile(line.slice(2, separator), 1024 * 1024);
+			});
+		if (performance.now() >= deadline) throw new Error('Font identity probe timed out');
+		return (
+			'fontconfig-v1:' +
+			createHash('sha256')
+				.update(JSON.stringify([inventory, matches, configuration]))
+				.digest('hex')
+		);
+	} catch {
+		// R can use native devices without Fontconfig tools. Render normally, but
+		// previews bypass cache reads, while the process identity keeps source guards stable.
+		return `fontconfig-unverified-v1:${process.platform}:${unavailableFontIdentity}`;
+	}
+}
+
+function selection(environment: NodeJS.ProcessEnv) {
+	const executable = environment.RSCRIPT ?? 'Rscript';
+	const locations = executable.includes(path.sep)
+		? [path.resolve(executable)]
+		: (environment.PATH ?? '')
+				.split(path.delimiter)
+				.map((directory) => path.resolve(directory, executable));
+	const binary = locations.find(existsSync);
+	let metadata: unknown;
+	if (binary) {
+		try {
+			const info = statSync(binary);
+			metadata = [binary, info.dev, info.ino, info.size, info.mtimeMs, info.ctimeMs];
+		} catch (error) {
+			if (!['ENOENT', 'ENOTDIR'].includes((error as NodeJS.ErrnoException).code ?? '')) throw error;
+		}
+	}
+	return JSON.stringify([
+		executable,
+		runtimeEnvironment.map((name) => [name, environment[name]]),
+		metadata
+	]);
+}
+
+/** Share the version probe with rendering, but refresh before accepting a saved dev snapshot. */
+export function rRuntimeVersion(environment: NodeJS.ProcessEnv = process.env, refresh = false) {
+	const key = selection(environment);
+	if (!refresh && probes.has(key)) return probes.get(key)!;
+	try {
+		const version = execFileSync(
+			environment.RSCRIPT ?? 'Rscript',
+			[
+				'--vanilla',
+				'-e',
+				'cat(R.version.string); for (p in c("knitr", "evaluate", "highr", "xfun", "yaml")) cat(p, as.character(packageVersion(p))); cat("\\n"); dput(R.version); dput(capabilities()); dput(extSoftVersion()); dput(grDevices::grSoftVersion()); dput(Sys.getlocale()); dput(Sys.timezone()); packages <- utils::installed.packages(); packages <- packages[order(packages[, "Package"], packages[, "Version"], packages[, "Built"]), c("Package", "Version", "Built"), drop = FALSE]; cat("\\n", apply(packages, 1, paste, collapse = " "), sep = "\\n")'
+			],
+			{ env: environment, encoding: 'utf8', timeout: 30_000, stdio: 'pipe' }
+		);
+		const identity = `${version}\n${rFontIdentity(environment)}`;
+		probes.set(key, identity);
+		return identity;
+	} catch (error) {
+		probes.delete(key);
+		throw new Error(
+			'R Markdown previews require R and knitr. Install r-base-core and r-cran-knitr (see site/README.md).',
+			{ cause: error }
+		);
+	}
+}
+
+export interface RRenderProfile {
+	schemaVersion: 1;
+	platform: string;
+	architecture: string;
+	runtime: string;
+	runtimeSha256: string;
+}
+
+/** Capture only dependency/device/version provenance from an actual renderer, never note data. */
+export function captureRRenderProfile(
+	environment: NodeJS.ProcessEnv = process.env
+): RRenderProfile {
+	return renderProfile(rRuntimeVersion(environment, true));
+}
+
+function renderProfile(runtime: string): RRenderProfile {
+	const separator = runtime.lastIndexOf('\nfontconfig-');
+	if (separator < 0) throw new Error('Missing renderer font provenance');
+	const versions = runtime.slice(0, separator);
+	const platform = process.platform;
+	const architecture = process.arch;
+	return {
+		schemaVersion: 1,
+		platform,
+		architecture,
+		runtime: versions,
+		runtimeSha256: createHash('sha256')
+			.update(JSON.stringify(['r-render-profile-v1', platform, architecture, versions]))
+			.digest('hex')
+	};
+}
+
+export function readRRenderProfile(site: string, environment: NodeJS.ProcessEnv = process.env) {
+	const file = path.resolve(
+		environment.WISCONSIN_R_RENDER_PROFILE_FILE ?? path.join(site, 'tooling/r-render-profile.json')
+	);
+	if (!existsSync(file)) return;
+	if (!lstatSync(file).isFile() || realpathSync(file) !== file)
+		throw new Error('R render profile must be an owned regular lock file');
+	const value: RRenderProfile = JSON.parse(readFileSync(file, 'utf8'));
+	if (
+		value.schemaVersion !== 1 ||
+		value.platform !== process.platform ||
+		value.architecture !== process.arch ||
+		typeof value.runtime !== 'string' ||
+		!value.runtime ||
+		!/^[a-f0-9]{64}$/.test(value.runtimeSha256) ||
+		renderProfile(`${value.runtime}\nfontconfig-v1:unused`).runtimeSha256 !== value.runtimeSha256
+	)
+		throw new Error('Invalid or incompatible R render profile lock');
+	return value;
+}
+
+/** A provisioned renderer must match the maintained lock, rather than silently updating policy. */
+export function verifyRRenderProfile(
+	site: string,
+	runtime: string,
+	environment: NodeJS.ProcessEnv = process.env
+) {
+	if (environment.WISCONSIN_R_CACHE_ONLY !== '1' && environment.WISCONSIN_R_REQUIRE_PROFILE !== '1')
+		return;
+	const expected = readRRenderProfile(site, environment);
+	if (!expected) throw new Error('A verified R render profile lock is required by this build');
+	if (expected && renderProfile(runtime).runtimeSha256 !== expected.runtimeSha256)
+		throw new Error(
+			'Installed R renderer does not match tooling/r-render-profile.json; provision the locked dependencies or explicitly update the verified lock'
+		);
+}
+
+/** Reconstruct an approved identity only from the maintained lock and independently observed fonts. */
+export function lockedRRuntime(site: string, environment: NodeJS.ProcessEnv = process.env) {
+	const profile = readRRenderProfile(site, environment);
+	if (!profile) throw new Error('R cache-only reuse requires a verified render profile lock');
+	const fonts = rFontIdentity(environment);
+	if (!/^fontconfig-v1:[a-f0-9]{64}$/.test(fonts))
+		throw new Error('R cache-only reuse requires independently verified fonts');
+	return `${profile.runtime}\n${fonts}`;
+}
+
+/** Probe conservatively for indexed worksheets in declared, initialized courses. */
+export function rRendererIdentity(repo: string, environment: NodeJS.ProcessEnv = process.env) {
+	const project = resolveProject(process.cwd(), repo, environment);
+	const courses = declaredContentCourses(project);
+	if (!courses.length) return 'unused';
+	const hasWorksheet = discoverSourceFiles(project).some(
+		(file) => /\.rmd$/i.test(file) && courses.some((course) => file.startsWith(course.name + '/'))
+	);
+	if (!hasWorksheet) return 'unused';
+	let version: string | null;
+	try {
+		version = rRuntimeVersion(environment, true);
+	} catch {
+		version = null;
+	}
+	return JSON.stringify([selection(environment), version]);
+}

package/site/tooling/lib/rebuild-queue.ts

@@ -0,0 +1,25 @@
+/** Coalesce a burst and retain at most one follow-up while a build is running. */
+export function rebuildQueue(build: () => Promise<void>, delay = 100) {
+	let dirty = false;
+	let running = false;
+	let pending = Promise.resolve();
+	return {
+		schedule() {
+			dirty = true;
+			if (running) return;
+			running = true;
+			pending = (async () => {
+				try {
+					await new Promise((resolve) => setTimeout(resolve, delay));
+					while (dirty) {
+						dirty = false;
+						await build();
+					}
+				} finally {
+					running = false;
+				}
+			})();
+		},
+		wait: () => pending
+	};
+}

package/site/tooling/lib/rmd-preflight.ts

@@ -0,0 +1,166 @@
+import { createHash } from 'node:crypto';
+import { lstatSync, readFileSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+import matter from 'gray-matter';
+import yaml from 'js-yaml';
+import type { CourseFile } from '../../src/lib/files';
+import { stageFingerprint } from '../fingerprint';
+import { resolveProject, declaredContentCourses, discoverSourceFiles } from './project-config';
+import { browsablePath } from './file-policy';
+import { publicationFilter } from './publishing';
+import { lockedRRuntime, readRRenderProfile } from './r-runtime';
+import { readRmdPreviewResult, rmdCourseInputs } from './rmd-preview-cache';
+import { slugifyFilePath, type FilePath } from './slug';
+
+export interface RmdPreflight {
+	schemaVersion: 1;
+	requiresR: boolean;
+	worksheets: number;
+	verified: number;
+	reason: 'unused' | 'verified' | 'profile-or-fonts' | 'missing-or-stale' | 'invalid-inputs';
+	runtimeSha256?: string;
+}
+
+/** Reconstruct the renderer's broad, indexed course closure without executing R or a worksheet. */
+export async function preflightRmdPreviews(
+	site: string,
+	repo: string,
+	environment: NodeJS.ProcessEnv = process.env
+): Promise<RmdPreflight> {
+	let worksheets = 0,
+		verified = 0;
+	try {
+		const project = resolveProject(site, repo, environment);
+		const courses = new Set(declaredContentCourses(project).map((course) => course.name));
+		if (!courses.size)
+			return { schemaVersion: 1, requiresR: false, worksheets: 0, verified: 0, reason: 'unused' };
+		const sources = new Map<string, { relative: string; source: string }[]>();
+		const paths = discoverSourceFiles(project);
+		for (const tracked of paths) {
+			const [course, ...segments] = tracked.split('/');
+			const relative = segments.join('/');
+			if (!courses.has(course) || !browsablePath(relative)) continue;
+			const source = path.resolve(project.contentDir, tracked);
+			const info = lstatSync(source, { throwIfNoEntry: false });
+			if (!info?.isFile() || realpathSync(source) !== source) continue;
+			const files = sources.get(course) ?? [];
+			files.push({ relative, source });
+			sources.set(course, files);
+		}
+		const worksheetCourses = [...sources].filter(([, files]) =>
+			files.some((file) => /\.rmd$/i.test(file.relative))
+		);
+		if (!worksheetCourses.length)
+			return { schemaVersion: 1, requiresR: false, worksheets: 0, verified: 0, reason: 'unused' };
+		const published = publicationFilter(repo, project);
+		const editions: { course: string; files: CourseFile[] }[] = [];
+		for (const [course, sources] of worksheetCourses) {
+			const noteSlugs = new Set<string>();
+			// Match the compiler's whole non-draft catalog, including locked notes.
+			for (const tracked of paths) {
+				if (
+					!tracked.startsWith(`${course}/`) ||
+					path.extname(tracked).toLowerCase() !== '.md' ||
+					tracked.split('/').some((segment) => segment.startsWith('.'))
+				)
+					continue;
+				const source = path.resolve(project.contentDir, tracked);
+				const info = lstatSync(source, { throwIfNoEntry: false });
+				if (!info?.isFile() || realpathSync(source) !== source) continue;
+				if (info.size > 25 * 1024 * 1024) throw new Error('Uncertain oversized note catalog');
+				const { data } = matter(readFileSync(source, 'utf8'), {
+					engines: { yaml: (value) => yaml.load(value, { schema: yaml.JSON_SCHEMA }) as object }
+				});
+				if (data.draft !== true && data.draft !== 'true')
+					noteSlugs.add(slugifyFilePath(tracked as FilePath));
+			}
+			const full: CourseFile[] = [],
+				publicFiles: CourseFile[] = [];
+			for (const { relative, source } of sources) {
+				const size = lstatSync(source).size;
+				const bytes = size <= 25 * 1024 * 1024 ? readFileSync(source) : undefined;
+				const hash = bytes && createHash('sha256').update(bytes).digest('hex');
+				const extension = path.extname(source).slice(1).toLowerCase();
+				const suffix =
+					extension === 'pdf'
+						? 'pdf'
+						: ['png', 'jpg', 'jpeg', 'gif', 'webp', 'avif'].includes(extension)
+							? extension
+							: 'bin';
+				const file: CourseFile = {
+					path: relative,
+					size,
+					kind:
+						bytes && ['png', 'jpg', 'jpeg', 'gif', 'webp', 'avif'].includes(extension)
+							? 'image'
+							: 'binary',
+					download: hash ? `/_files/blobs/${hash}.${suffix}` : undefined
+				};
+				const slug = slugifyFilePath(`${course}/${relative}` as FilePath);
+				if (extension === 'md' && noteSlugs.has(slug))
+					file.note = '/' + (slug.endsWith('/index') ? slug.slice(0, -6) : slug);
+				full.push(file);
+				const locked =
+					!published(`${course}/${relative}`) || (extension === 'md' && !noteSlugs.has(slug));
+				publicFiles.push(
+					locked ? { ...file, kind: 'binary', locked: true, download: undefined } : { ...file }
+				);
+			}
+			for (const files of [publicFiles, full]) {
+				worksheets += files.filter(
+					(file) => !file.locked && file.download && /\.rmd$/i.test(file.path)
+				).length;
+				editions.push({ course, files });
+			}
+		}
+		if (!worksheets)
+			return { schemaVersion: 1, requiresR: false, worksheets: 0, verified: 0, reason: 'unused' };
+		let runtime: string;
+		try {
+			runtime = lockedRRuntime(site, environment);
+		} catch {
+			return {
+				schemaVersion: 1,
+				requiresR: true,
+				worksheets,
+				verified,
+				reason: 'profile-or-fonts'
+			};
+		}
+		const policy = await stageFingerprint('rmd');
+		for (const { course, files } of editions) {
+			const inputs = rmdCourseInputs(files);
+			for (const worksheet of files.filter(
+				(file) => !file.locked && file.download && /\.rmd$/i.test(file.path)
+			)) {
+				if (
+					!readRmdPreviewResult(site, {
+						runtime,
+						policy,
+						course,
+						inputs,
+						worksheet: worksheet.path
+					})
+				)
+					return {
+						schemaVersion: 1,
+						requiresR: true,
+						worksheets,
+						verified,
+						reason: 'missing-or-stale'
+					};
+				verified++;
+			}
+		}
+		return {
+			schemaVersion: 1,
+			requiresR: false,
+			worksheets,
+			verified,
+			reason: 'verified',
+			runtimeSha256: readRRenderProfile(site, environment)!.runtimeSha256
+		};
+	} catch {
+		return { schemaVersion: 1, requiresR: true, worksheets, verified, reason: 'invalid-inputs' };
+	}
+}

package/site/tooling/lib/rmd-preview-cache.ts

@@ -0,0 +1,93 @@
+import { createHash } from 'node:crypto';
+import { lstatSync, readFileSync, realpathSync } from 'node:fs';
+import path from 'node:path';
+import type { CourseFile, RmdPreview } from '../../src/lib/files';
+
+const sha256 = (bytes: string | Uint8Array) => createHash('sha256').update(bytes).digest('hex');
+export type RmdPreviewInputs = {
+	runtime: string;
+	policy: string;
+	course: string;
+	inputs: string;
+	worksheet: string;
+};
+export type RmdPreviewResult = { preview: string; blobs: string[] };
+
+export function rmdCourseInputs(files: CourseFile[]) {
+	return JSON.stringify({
+		available: files
+			.filter((file) => !file.locked && file.download)
+			.map(({ path, download }) => [path, download])
+			.sort(),
+		// parseRmd also resolves links and embeds against locked or oversized entries.
+		// Preserve catalog order, which determines the first exact matching candidate.
+		catalog: files.map((file) => [
+			file.path,
+			file.kind === 'image',
+			Boolean(file.locked),
+			file.note ?? null,
+			file.download ?? null
+		])
+	});
+}
+
+export function rmdPreviewKey(inputs: RmdPreviewInputs) {
+	return sha256(
+		`${inputs.runtime}\n${inputs.policy}\n${inputs.course}\n${inputs.inputs}\n${inputs.worksheet}`
+	);
+}
+
+export function rmdPreviewRecord(inputs: RmdPreviewInputs, result: RmdPreviewResult) {
+	return { schemaVersion: 2, ...inputs, ...result };
+}
+
+/** Validate actual immutable bytes, not only existence or restored file timestamps. */
+export function readRmdPreviewResult(
+	site: string,
+	inputs: RmdPreviewInputs
+): RmdPreviewResult | undefined {
+	try {
+		if (!/\nfontconfig-v1:[a-f0-9]{64}$/.test(inputs.runtime)) return;
+		const directory = path.resolve(site, 'build/generated/cache/rmd', rmdPreviewKey(inputs));
+		if (realpathSync(directory) !== directory) return;
+		const read = (name: string) => {
+			const file = path.join(directory, name);
+			if (!lstatSync(file).isFile() || realpathSync(file) !== file)
+				throw new Error('Unsafe R preview cache file');
+			const info = lstatSync(file);
+			if (info.size > 25 * 1024 * 1024) throw new Error('Oversized R preview cache file');
+			return readFileSync(file);
+		};
+		const saved = JSON.parse(read('result.json').toString());
+		if (
+			saved.schemaVersion !== 2 ||
+			Object.entries(inputs).some(([name, value]) => saved[name] !== value) ||
+			!Array.isArray(saved.blobs) ||
+			!saved.blobs.length ||
+			saved.blobs.length > 1024 ||
+			typeof saved.preview !== 'string' ||
+			!saved.blobs.includes(saved.preview) ||
+			new Set(saved.blobs).size !== saved.blobs.length
+		)
+			return;
+		for (const blob of saved.blobs) {
+			if (typeof blob !== 'string' || !/^[a-f0-9]{64}\.(?:json|png|jpg|jpeg|svg|pdf)$/.test(blob))
+				return;
+			if (sha256(read(blob)) !== blob.slice(0, 64)) return;
+		}
+		if (!saved.preview.endsWith('.json')) return;
+		const preview: RmdPreview = JSON.parse(read(saved.preview).toString());
+		if (typeof preview.title !== 'string' || typeof preview.html !== 'string') return;
+		const downloads = new Set<string>();
+		for (const [, download] of JSON.parse(inputs.inputs).available) {
+			if (typeof download === 'string' && /^\/_files\/blobs\/[a-f0-9]{64}\.[a-z]+$/.test(download))
+				downloads.add(path.basename(download));
+		}
+		for (const match of preview.html.matchAll(/\/_files\/blobs\/([a-f0-9]{64}\.[a-z]+)/g)) {
+			if (!saved.blobs.includes(match[1]) && !downloads.has(match[1])) return;
+		}
+		return { preview: saved.preview, blobs: saved.blobs };
+	} catch {
+		return;
+	}
+}

package/site/tooling/lib/rmd-previews.ts

@@ -0,0 +1,129 @@
+import { stageFingerprint } from '../fingerprint';
+import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, copyFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { parseRmd } from '../../src/lib/rmd';
+import type { CourseFile, RmdPreview } from '../../src/lib/files';
+import { writeChanged } from './output';
+import { lockedRRuntime, rRuntimeVersion, verifyRRenderProfile } from './r-runtime';
+import {
+	readRmdPreviewResult,
+	rmdCourseInputs,
+	rmdPreviewKey,
+	rmdPreviewRecord
+} from './rmd-preview-cache';
+
+const runner = path.join(import.meta.dirname, 'knit-rmd.R');
+const digest = (bytes: string | Uint8Array) => createHash('sha256').update(bytes).digest('hex');
+const limit = 25 * 1024 * 1024;
+
+/** Knit only available course files, in a temporary copy, never in the source checkout. */
+export async function buildRmdPreviews(
+	site: string,
+	course: string,
+	files: CourseFile[],
+	output: string,
+	retain: (file: string) => void
+) {
+	const worksheets = files.filter(
+		(file) => !file.locked && file.download && /\.rmd$/i.test(file.path)
+	);
+	if (!worksheets.length) return;
+	const cacheOnly = process.env.WISCONSIN_R_CACHE_ONLY === '1';
+	let runtime: string;
+	try {
+		runtime = cacheOnly ? lockedRRuntime(site) : rRuntimeVersion();
+	} catch (error) {
+		if (cacheOnly || process.env.WISCONSIN_R_REQUIRE_PROFILE === '1')
+			throw new Error(
+				'Verified R previews are unavailable; install the locked R renderer before building',
+				{ cause: error }
+			);
+		const message = error instanceof Error ? error.message : String(error);
+		console.warn(`rmd: ${message} Using Source and Interactive views.`);
+		for (const worksheet of worksheets) delete worksheet.rmdPreview;
+		return;
+	}
+	verifyRRenderProfile(site, runtime);
+	const available = files.filter((file) => !file.locked && file.download);
+	const inputs = rmdCourseInputs(files);
+	const policy = await stageFingerprint('rmd');
+	for (const worksheet of worksheets) {
+		const context = { runtime, policy, course, inputs, worksheet: worksheet.path };
+		const key = rmdPreviewKey(context);
+		const cache = path.join(site, 'build/generated/cache/rmd', key);
+		const record = path.join(cache, 'result.json');
+		let result = readRmdPreviewResult(site, context);
+		if (!result && cacheOnly)
+			throw new Error(
+				`Verified R preview is missing or stale for ${course}/${worksheet.path}; install the locked R renderer before building`
+			);
+		if (!result) {
+			const scratch = mkdtempSync(path.join(tmpdir(), 'wisconsin-rmd-'));
+			try {
+				const working = path.join(scratch, 'course');
+				for (const file of available) {
+					const target = path.join(working, file.path);
+					mkdirSync(path.dirname(target), { recursive: true });
+					copyFileSync(path.join(output, 'blobs', path.basename(file.download!)), target);
+				}
+				const figures = path.join(scratch, 'figures');
+				mkdirSync(figures);
+				const knitted = path.join(scratch, 'knitted.md');
+				execFileSync(
+					process.env.RSCRIPT ?? 'Rscript',
+					['--vanilla', runner, path.join(working, worksheet.path), knitted, figures],
+					{ cwd: working, timeout: 120_000, maxBuffer: 8 * 1024 * 1024, stdio: 'pipe' }
+				);
+				let markdown = readFileSync(knitted, 'utf8');
+				const blobs: string[] = [];
+				const save = (bytes: Uint8Array, extension: string) => {
+					if (bytes.length > limit)
+						throw new Error('Rendered R Markdown asset exceeds the 25 MiB hosting limit');
+					const blob = `${digest(bytes)}.${extension}`;
+					writeChanged(path.join(cache, blob), bytes);
+					blobs.push(blob);
+					return blob;
+				};
+				for (const figure of readdirSync(figures, { recursive: true, withFileTypes: true })) {
+					if (!figure.isFile()) continue;
+					const source = path.join(figure.parentPath, figure.name);
+					const extension = path.extname(source).slice(1);
+					if (!['png', 'jpg', 'jpeg', 'svg', 'pdf'].includes(extension))
+						throw new Error(`Unsupported R plot format: ${extension}`);
+					const blob = save(readFileSync(source), extension);
+					markdown = markdown.split(source).join(`/_files/blobs/${blob}`);
+				}
+				const parsed = await parseRmd(markdown, course, worksheet.path, files);
+				if (parsed.blocks.some((block) => block.kind === 'r'))
+					throw new Error('Knitting left an unevaluated R chunk');
+				const preview: RmdPreview = {
+					title: parsed.title,
+					html: parsed.blocks
+						.map((block) => (block.kind === 'markdown' ? block.html : ''))
+						.join('\n')
+				};
+				result = {
+					preview: save(Buffer.from(JSON.stringify(preview)), 'json'),
+					blobs: [...new Set(blobs)]
+				};
+				writeChanged(record, JSON.stringify(rmdPreviewRecord(context, result)));
+				console.log(`rmd: rendered ${course}/${worksheet.path}`);
+			} catch (error) {
+				throw new Error(`Could not render ${course}/${worksheet.path}: ${String(error)}`, {
+					cause: error
+				});
+			} finally {
+				rmSync(scratch, { recursive: true, force: true });
+			}
+		}
+		for (const blob of result.blobs) {
+			const destination = path.join(output, 'blobs', blob);
+			writeChanged(destination, readFileSync(path.join(cache, blob)));
+			retain(destination);
+		}
+		worksheet.rmdPreview = `/_files/blobs/${result.preview}`;
+	}
+}