@heyramzi/ui 2.11.0 → 2.11.2

package/dist/slides/export/ffmpeg.js

@@ -1,85 +1,89 @@
+// Encode frames to an mp4 with the ffmpeg on the machine. The package ships no
+// binary; pass `ffmpeg` to name one that is not on PATH.
 import { spawn } from "node:child_process";
 import { mkdir, rm } from "node:fs/promises";
 import path from "node:path";
+/** Runs ffmpeg and resolves when it exits 0; the error carries the tail of its stderr. */
 export function runFfmpeg(args, ffmpeg = "ffmpeg") {
-    return new Promise((resolve, reject)=>{
-        const child = spawn(ffmpeg, args, {
-            stdio: [
-                "ignore",
-                "ignore",
-                "pipe"
-            ]
-        });
-        let stderr = "";
-        child.stderr.on("data", (chunk)=>{
-            stderr += chunk;
-        });
-        child.on("error", (error)=>reject(new Error(`${ffmpeg} could not be started (${error.message}). Video export needs ffmpeg on PATH, or pass its path.`)));
-        child.on("close", (code)=>code === 0 ? resolve() : reject(new Error(`${ffmpeg} exited ${code}:\n${stderr.slice(-1500)}`)));
-    });
+	return new Promise((resolve, reject) => {
+		const child = spawn(ffmpeg, args, { stdio: [
+			"ignore",
+			"ignore",
+			"pipe"
+		] });
+		let stderr = "";
+		child.stderr.on("data", (chunk) => {
+			stderr += chunk;
+		});
+		child.on("error", (error) => reject(new Error(`${ffmpeg} could not be started (${error.message}). Video export needs ffmpeg on PATH, or pass its path.`)));
+		child.on("close", (code) => code === 0 ? resolve() : reject(new Error(`${ffmpeg} exited ${code}:\n${stderr.slice(-1500)}`)));
+	});
 }
+/** The ffmpeg arguments for a silent yuv420p H.264 mp4 from a numbered image sequence. */
 export function encodeArgs(dir, outFile, options) {
-    return [
-        "-y",
-        "-hide_banner",
-        "-loglevel",
-        "error",
-        "-framerate",
-        String(options.fps),
-        "-i",
-        path.join(dir, options.pattern ?? "%04d.png"),
-        "-an",
-        "-vf",
-        "format=yuv420p",
-        "-c:v",
-        "libx264",
-        "-preset",
-        options.preset ?? "slow",
-        "-crf",
-        String(options.crf ?? 23),
-        "-movflags",
-        "+faststart",
-        outFile
-    ];
+	return [
+		"-y",
+		"-hide_banner",
+		"-loglevel",
+		"error",
+		"-framerate",
+		String(options.fps),
+		"-i",
+		path.join(dir, options.pattern ?? "%04d.png"),
+		"-an",
+		"-vf",
+		"format=yuv420p",
+		"-c:v",
+		"libx264",
+		"-preset",
+		options.preset ?? "slow",
+		"-crf",
+		String(options.crf ?? 23),
+		"-movflags",
+		"+faststart",
+		outFile
+	];
 }
+/** Encodes a folder of numbered frames. There is no audio stream at all. */
 export async function encodeFrames(dir, outFile, options) {
-    await mkdir(path.dirname(outFile), {
-        recursive: true
-    });
-    await runFfmpeg(encodeArgs(dir, outFile, options), options.ffmpeg);
+	await mkdir(path.dirname(outFile), { recursive: true });
+	await runFfmpeg(encodeArgs(dir, outFile, options), options.ffmpeg);
 }
+/** Frames for a loop of this length: whole frames only, never fewer than one. */
 export function loopFrameCount(seconds, fps) {
-    return Math.max(1, Math.round(seconds * fps));
+	return Math.max(1, Math.round(seconds * fps));
 }
+/**
+* Renders a seamless loop from `drawFrame` at t = 0 to (n-1)/n, never 1, so the cut back
+* to frame zero is the same step as every other.
+*/
 export async function renderLoop(outFile, options) {
-    const fps = options.fps ?? 30;
-    const seconds = options.seconds ?? 2.5;
-    const frames = loopFrameCount(seconds, fps);
-    const work = `${outFile}.frames`;
-    await mkdir(work, {
-        recursive: true
-    });
-    try {
-        for(let index = 0; index < frames; index++){
-            await options.drawFrame({
-                index,
-                t: index / frames,
-                file: path.join(work, `${String(index).padStart(4, "0")}.png`)
-            });
-        }
-        await encodeFrames(work, outFile, {
-            ...options,
-            fps
-        });
-    } finally{
-        await rm(work, {
-            recursive: true,
-            force: true
-        });
-    }
-    return {
-        file: outFile,
-        frames,
-        seconds
-    };
+	const fps = options.fps ?? 30;
+	const seconds = options.seconds ?? 2.5;
+	const frames = loopFrameCount(seconds, fps);
+	const work = `${outFile}.frames`;
+	await mkdir(work, { recursive: true });
+	try {
+		for (let index = 0; index < frames; index++) {
+			await options.drawFrame({
+				index,
+				t: index / frames,
+				file: path.join(work, `${String(index).padStart(4, "0")}.png`)
+			});
+		}
+		await encodeFrames(work, outFile, {
+			...options,
+			fps
+		});
+	} finally {
+		await rm(work, {
+			recursive: true,
+			force: true
+		});
+	}
+	return {
+		file: outFile,
+		frames,
+		seconds
+	};
 }

package/dist/slides/export/index.js

@@ -1,3 +1,6 @@
+// @heyramzi/ui/slides/export: Node-only. Capture, print and encode slides without
+// depending on Playwright or bundling ffmpeg. Hand it the Playwright pages and
+// browsers you already have.
 export * from "./capture.js";
 export * from "./ffmpeg.js";
 export * from "./launch.js";

package/dist/slides/export/launch.js

@@ -1,8 +1,11 @@
+/**
+* Launches Chromium, falling back to the installed Chrome. The bundled
+* Chromium goes missing after a Playwright bump, and Chrome prints the same.
+* Pass `chromium` from Playwright.
+*/
 export async function launchChromium(chromium) {
-    return chromium.launch({
-        headless: true
-    }).catch(()=>chromium.launch({
-            headless: true,
-            channel: "chrome"
-        }));
+	return chromium.launch({ headless: true }).catch(() => chromium.launch({
+		headless: true,
+		channel: "chrome"
+	}));
 }

package/dist/slides/export/pdf.js

@@ -1,78 +1,84 @@
+// Print a URL or HTML to PDF at a page size, and assemble captured PNGs into one.
 import { readFile } from "node:fs/promises";
+/** Chromium drops backgrounds in its print pipeline without the color-adjust line. */
 export const RESET_CSS = `*{margin:0;padding:0;box-sizing:border-box;}
 html{-webkit-print-color-adjust:exact;print-color-adjust:exact;}`;
+/** The `@page` rule for a page of this size in CSS pixels, with no margin. */
 export function pageRule(size) {
-    return `@page{size:${size.width}px ${size.height}px;margin:0;}`;
+	return `@page{size:${size.width}px ${size.height}px;margin:0;}`;
 }
+/** The reset, the page size and one full-bleed `.page` box per image. */
 export function imagePagesCss(size, background) {
-    return `${RESET_CSS}
+	return `${RESET_CSS}
 ${background ? `body{background:${background};}\n` : ""}${pageRule(size)}
 .page{display:block;width:${size.width}px;height:${size.height}px;break-after:page;}
 .page:last-child{break-after:auto;}`;
 }
+/** One `<img class="page">` per data URL, laid out so each prints on its own page. */
 export function imagePagesHtml(dataUrls, size, background) {
-    const pages = dataUrls.map((dataUrl)=>`<img class="page" src="${dataUrl}" alt="">`).join("");
-    return `<!doctype html><html><head><meta charset="utf-8"><style>
+	const pages = dataUrls.map((dataUrl) => `<img class="page" src="${dataUrl}" alt="">`).join("");
+	return `<!doctype html><html><head><meta charset="utf-8"><style>
 ${imagePagesCss(size, background)}
 </style></head><body>${pages}</body></html>`;
 }
+/** The page count of a PDF, read off its page objects. */
 export function countPdfPages(pdf) {
-    return (Buffer.from(pdf).toString("latin1").match(/\/Type\s*\/Page[^s]/g) ?? []).length;
+	return (Buffer.from(pdf).toString("latin1").match(/\/Type\s*\/Page[^s]/g) ?? []).length;
 }
+/**
+* Prints the page once fonts, images and the caller's signal settle, returning the images
+* that never loaded so a caller can refuse a half-painted sheet.
+*/
 export async function printPage(page, options = {}) {
-    const { ready } = options;
-    if (typeof ready === "string") {
-        await page.waitForSelector(ready, {
-            timeout: options.readyTimeout ?? 60_000
-        });
-    } else if (ready) {
-        await ready(page);
-    }
-    await page.evaluate(()=>document.fonts.ready.then(()=>undefined));
-    if (options.settle) await page.waitForTimeout(options.settle);
-    const brokenImages = await page.evaluate(()=>[
-            ...document.images
-        ].filter((img)=>!img.complete || img.naturalWidth === 0).map((img)=>img.src));
-    const { size } = options;
-    const pdf = await page.pdf({
-        path: options.path,
-        printBackground: true,
-        ...size ? {
-            width: `${size.width}px`,
-            height: `${size.height}px`
-        } : {
-            preferCSSPageSize: true
-        },
-        pageRanges: options.pageRanges
-    });
-    return {
-        pdf,
-        pages: countPdfPages(pdf),
-        brokenImages
-    };
+	const { ready } = options;
+	if (typeof ready === "string") {
+		await page.waitForSelector(ready, { timeout: options.readyTimeout ?? 6e4 });
+	} else if (ready) {
+		await ready(page);
+	}
+	await page.evaluate(() => document.fonts.ready.then(() => undefined));
+	if (options.settle) await page.waitForTimeout(options.settle);
+	const brokenImages = await page.evaluate(() => [...document.images].filter((img) => !img.complete || img.naturalWidth === 0).map((img) => img.src));
+	const { size } = options;
+	const pdf = await page.pdf({
+		path: options.path,
+		printBackground: true,
+		...size ? {
+			width: `${size.width}px`,
+			height: `${size.height}px`
+		} : { preferCSSPageSize: true },
+		pageRanges: options.pageRanges
+	});
+	return {
+		pdf,
+		pages: countPdfPages(pdf),
+		brokenImages
+	};
 }
+/** Opens a URL in the page and prints it. The caller owns the page and any routing on it. */
 export async function printUrl(page, url, options = {}) {
-    const response = await page.goto(url, {
-        waitUntil: options.waitUntil ?? "load"
-    });
-    options.check?.(response, page);
-    return printPage(page, options);
+	const response = await page.goto(url, { waitUntil: options.waitUntil ?? "load" });
+	options.check?.(response, page);
+	return printPage(page, options);
 }
+/** Loads HTML into the page and prints it. */
 export async function printHtml(page, html, options = {}) {
-    await page.setContent(html, {
-        waitUntil: options.waitUntil ?? "load"
-    });
-    return printPage(page, options);
+	await page.setContent(html, { waitUntil: options.waitUntil ?? "load" });
+	return printPage(page, options);
 }
+/**
+* Prints PNGs one per page, never the original document, because Chromium's print pipeline
+* re-rasterises effects: a blurred backdrop lost 47% of its chroma.
+*/
 export async function imagesToPdf(page, images, options) {
-    if (images.length === 0) throw new Error("imagesToPdf needs at least one image.");
-    const dataUrls = await Promise.all(images.map(async (image)=>{
-        const bytes = typeof image === "string" ? await readFile(image) : image;
-        return `data:image/png;base64,${Buffer.from(bytes).toString("base64")}`;
-    }));
-    const { pdf } = await printHtml(page, imagePagesHtml(dataUrls, options.size, options.background), {
-        size: options.size,
-        pageRanges: `1-${images.length}`
-    });
-    return pdf;
+	if (images.length === 0) throw new Error("imagesToPdf needs at least one image.");
+	const dataUrls = await Promise.all(images.map(async (image) => {
+		const bytes = typeof image === "string" ? await readFile(image) : image;
+		return `data:image/png;base64,${Buffer.from(bytes).toString("base64")}`;
+	}));
+	const { pdf } = await printHtml(page, imagePagesHtml(dataUrls, options.size, options.background), {
+		size: options.size,
+		pageRanges: `1-${images.length}`
+	});
+	return pdf;
 }

package/dist/slides/export/types.js

@@ -0,0 +1 @@
+export {};

package/dist/slides/labels.js

@@ -1,26 +1,26 @@
 export const defaultLabels = {
-    deck: "Slide deck",
-    deckRole: "presentation",
-    slideRole: "slide",
-    previous: "Previous slide",
-    next: "Next slide",
-    fullscreen: "Toggle fullscreen",
-    overview: "Slide overview",
-    presenter: "Open presenter view",
-    progress: "Deck progress",
-    slide: (n, of)=>`Slide ${n} of ${of}`,
-    upcoming: "Next",
-    current: "Now",
-    notes: "Notes",
-    noNotes: "No notes for this slide.",
-    endOfDeck: "End of deck.",
-    timer: "Elapsed time",
-    startTimer: "Start timer",
-    pauseTimer: "Pause timer",
-    resetTimer: "Reset timer",
-    unknownType: (type)=>`Unknown slide type: ${type}`
+	deck: "Slide deck",
+	deckRole: "presentation",
+	slideRole: "slide",
+	previous: "Previous slide",
+	next: "Next slide",
+	fullscreen: "Toggle fullscreen",
+	overview: "Slide overview",
+	presenter: "Open presenter view",
+	progress: "Deck progress",
+	slide: (n, of) => `Slide ${n} of ${of}`,
+	upcoming: "Next",
+	current: "Now",
+	notes: "Notes",
+	noNotes: "No notes for this slide.",
+	endOfDeck: "End of deck.",
+	timer: "Elapsed time",
+	startTimer: "Start timer",
+	pauseTimer: "Pause timer",
+	resetTimer: "Reset timer",
+	unknownType: (type) => `Unknown slide type: ${type}`
 };
-export const resolveLabels = (labels)=>({
-        ...defaultLabels,
-        ...labels
-    });
+export const resolveLabels = (labels) => ({
+	...defaultLabels,
+	...labels
+});

package/dist/slides/layout.js

@@ -1,47 +1,45 @@
 export function fitBox(view, canvas) {
-    const scale = Math.max(0, Math.min(view.w / canvas.w, view.h / canvas.h));
-    return {
-        x: (view.w - canvas.w * scale) / 2,
-        y: (view.h - canvas.h * scale) / 2,
-        scale
-    };
+	const scale = Math.max(0, Math.min(view.w / canvas.w, view.h / canvas.h));
+	return {
+		x: (view.w - canvas.w * scale) / 2,
+		y: (view.h - canvas.h * scale) / 2,
+		scale
+	};
 }
+/** The scale at which `cols` columns of `count` canvases fit the view. */
 function scaleFor(cols, count, view, canvas, pad, gap) {
-    const rows = Math.ceil(count / cols);
-    const byWidth = (view.w - 2 * pad - (cols - 1) * gap) / cols / canvas.w;
-    const byHeight = (view.h - 2 * pad - (rows - 1) * gap) / rows / canvas.h;
-    return Math.min(byWidth, byHeight);
+	const rows = Math.ceil(count / cols);
+	const byWidth = (view.w - 2 * pad - (cols - 1) * gap) / cols / canvas.w;
+	const byHeight = (view.h - 2 * pad - (rows - 1) * gap) / rows / canvas.h;
+	return Math.min(byWidth, byHeight);
 }
+/** Lays `count` canvases in the roomiest grid that shows them all, centred. */
 export function gridBoxes(view, canvas, count) {
-    if (count === 0 || view.w <= 0 || view.h <= 0) return {
-        cols: 1,
-        boxes: []
-    };
-    const pad = Math.min(56, Math.max(16, view.w * 0.04));
-    const gap = Math.max(26, pad * 0.6);
-    let cols = 1;
-    let scale = scaleFor(1, count, view, canvas, pad, gap);
-    for(let c = 2; c <= count; c++){
-        const candidate = scaleFor(c, count, view, canvas, pad, gap);
-        if (candidate > scale) [cols, scale] = [
-            c,
-            candidate
-        ];
-    }
-    const cellW = canvas.w * scale;
-    const cellH = canvas.h * scale;
-    const rows = Math.ceil(count / cols);
-    const left = (view.w - (cols * cellW + (cols - 1) * gap)) / 2;
-    const top = (view.h - (rows * cellH + (rows - 1) * gap)) / 2;
-    const boxes = Array.from({
-        length: count
-    }, (_, i)=>({
-            x: left + i % cols * (cellW + gap),
-            y: top + Math.floor(i / cols) * (cellH + gap),
-            scale
-        }));
-    return {
-        cols,
-        boxes
-    };
+	if (count === 0 || view.w <= 0 || view.h <= 0) return {
+		cols: 1,
+		boxes: []
+	};
+	const pad = Math.min(56, Math.max(16, view.w * .04));
+	/* The gap holds the slide number that hangs below each cell. */
+	const gap = Math.max(26, pad * .6);
+	let cols = 1;
+	let scale = scaleFor(1, count, view, canvas, pad, gap);
+	for (let c = 2; c <= count; c++) {
+		const candidate = scaleFor(c, count, view, canvas, pad, gap);
+		if (candidate > scale) [cols, scale] = [c, candidate];
+	}
+	const cellW = canvas.w * scale;
+	const cellH = canvas.h * scale;
+	const rows = Math.ceil(count / cols);
+	const left = (view.w - (cols * cellW + (cols - 1) * gap)) / 2;
+	const top = (view.h - (rows * cellH + (rows - 1) * gap)) / 2;
+	const boxes = Array.from({ length: count }, (_, i) => ({
+		x: left + i % cols * (cellW + gap),
+		y: top + Math.floor(i / cols) * (cellH + gap),
+		scale
+	}));
+	return {
+		cols,
+		boxes
+	};
 }

package/dist/slides/model.js

@@ -1,9 +1,11 @@
-export const defineSlideType = (definition)=>definition;
+/** Identity function that fixes `Content` from the layout. */
+export const defineSlideType = (definition) => definition;
+/** Keys the types by their `type`. Two with the same name is a mistake worth failing on. */
 export function defineRegistry(types) {
-    const registry = {};
-    for (const slide of types){
-        if (slide.type in registry) throw new Error(`Slide type "${slide.type}" is registered twice.`);
-        registry[slide.type] = slide;
-    }
-    return registry;
+	const registry = {};
+	for (const slide of types) {
+		if (slide.type in registry) throw new Error(`Slide type "${slide.type}" is registered twice.`);
+		registry[slide.type] = slide;
+	}
+	return registry;
 }