rikiki-deck 0.6.0 → 0.7.2

package/bin/lib/cli-error.mjs

@@ -0,0 +1,26 @@
+// ════════════════════════════════════════════════════════════════
+// The difference between "you need to install something" and "rikiki broke".
+// The first is a message the reader acts on; the second is a stack trace the
+// maintainer acts on. Printing a stack for the first one buries the remedy
+// under six lines of package internals.
+// ════════════════════════════════════════════════════════════════
+
+/** An error whose message is the whole story · printed without a stack.
+ *
+ *  `exitCode` lets a command distinguish its own failure modes. `check` uses it
+ *  to separate "the deck has defects" (1) from "I could not look at it" (2),
+ *  which is the difference between a result and no result. */
+export class ExpectedError extends Error {
+  name = 'ExpectedError';
+
+  constructor(message, { exitCode = 1, ...options } = {}) {
+    super(message, options);
+    this.exitCode = exitCode;
+  }
+}
+
+/** What the CLI prints when a command throws. */
+export function formatCliError(e) {
+  if (e instanceof ExpectedError) return 'rikiki · ' + e.message;
+  return 'rikiki · error · ' + ((e && e.stack) || e);
+}

package/bin/lib/component-deps.mjs

@@ -0,0 +1,69 @@
+// What a component needs loaded besides itself.
+//
+// A component may render another component's tag · deck-figure renders
+// <deck-source> for its credit line, deck-annotate does the same, deck-graph
+// renders <deck-icon>. The curated bundle is built from the tags written in
+// the DECK (see scanComponents in inline.mjs), so those tags are invisible to
+// it: the deck shipped without the module and the element stayed unregistered,
+// rendering as bare text. decks/tests/figure.html is the live case.
+//
+// Read from dist/, not src/, for one reason: `rikiki bundle` runs from an
+// installed package, where src/ does not exist. dist/ is also the only thing
+// that can be wrong · a graph derived from what ships cannot disagree with
+// what ships.
+//
+// The scan OVER-APPROXIMATES on purpose. `<deck-code` also appears in a
+// warning string inside deck-code-highlighter and shiki, so both are reported
+// as needing deck-code. That is the safe direction: a false positive adds a
+// module the deck almost certainly wanted anyway (shiki highlights deck-code),
+// while a false negative ships a deck with a missing element. Precision here
+// would mean parsing minified JS to tell a Lit template from a string
+// literal, which is a lot of machinery to save a few hundred bytes.
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** Tags a module mentions in markup · `<deck-thing`. */
+const RENDERED = /<(deck-[a-z0-9-]+)/g;
+
+/** Every loadable module, mapped to the modules it needs beside it.
+ *
+ *  dist/ is flat and a file IS its tag (build.mjs entryNames '[name]'), so the
+ *  filename is the lookup key. A secondary element defined inside a sibling's
+ *  file · deck-kbd in deck-shortcut.js, deck-tier in deck-tier-list.js · has
+ *  no module of its own and travels with its parent, which is why anything
+ *  without a dist/<tag>.js is dropped rather than requested. */
+export function componentGraph(distDir) {
+  const modules = readdirSync(distDir)
+    .filter((f) => f.endsWith('.js') && f.startsWith('deck-'))
+    .map((f) => f.slice(0, -3));
+  const known = new Set(modules);
+
+  const graph = new Map();
+  for (const tag of modules) {
+    const source = readFileSync(join(distDir, `${tag}.js`), 'utf8');
+    const deps = new Set();
+    for (const [, found] of source.matchAll(RENDERED)) {
+      if (found !== tag && known.has(found)) deps.add(found);
+    }
+    graph.set(tag, deps);
+  }
+  return graph;
+}
+
+/** The tags to load so every one of `tags` renders completely.
+ *
+ *  A closure over a visited set · a cycle between two components would be a
+ *  defect to report, not a reason for this to recurse forever. */
+export function expandDeps(tags, distDir, graph = componentGraph(distDir)) {
+  const out = new Set();
+  const queue = [...tags];
+  while (queue.length > 0) {
+    const tag = queue.pop();
+    if (out.has(tag)) continue;
+    out.add(tag);
+    for (const dep of graph.get(tag) ?? []) if (!out.has(dep)) queue.push(dep);
+  }
+  // Keep only what can actually be loaded · a caller may pass deck-kbd.
+  return [...out].filter((t) => existsSync(join(distDir, `${t}.js`)));
+}

package/bin/lib/diff.mjs

@@ -0,0 +1,275 @@
+// ════════════════════════════════════════════════════════════════
+// Did anything move since the last render?
+//
+// After a runtime update, 57 of 64 slides of a real deck changed pixels.
+// Nearly all of it was anti-aliasing; seven were geometry that had actually
+// moved. Finding those seven meant a `cmp` loop in a shell and opening images
+// one by one. So the comparison has to rank: how much moved, and where.
+//
+// There is no image library here, and none is wanted. The comparison runs in
+// the Chromium the CLI already launched: both PNGs go in as `data:` URLs, get
+// drawn on a canvas, and `getImageData` gives the bytes. Everything the answer
+// depends on · the ranking, the threshold, the box, the classification · is a
+// pure function in this file, tested in Node, not a line hidden in a browser.
+// ════════════════════════════════════════════════════════════════
+
+import { readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export const DIFF_SCHEMA = 'rikiki.render-diff/1';
+
+/** How far one channel must move before a pixel counts as changed.
+ *
+ *  Anti-aliasing on a re-render nudges an edge pixel by a handful of levels;
+ *  a glyph that moved paints where there was background. 32 of 255 sits
+ *  between the two, so a re-render of an unchanged deck reads as stable. */
+export const CHANNEL_DELTA = 32;
+
+/** Percent of a slide's pixels that has to change before it is worth looking
+ *  at. `--threshold 0` reports every single pixel that moved. */
+export const DEFAULT_THRESHOLD = 0.5;
+
+/**
+ * The smallest rect containing every pixel in `pixels` (`{x, y}`), or null.
+ *
+ * The in-page pass keeps only the two extreme corners rather than a list of a
+ * million points · that is the same rect, which is why this takes a list.
+ */
+export function boundingBox(pixels) {
+  if (!pixels?.length) return null;
+  let left = Number.POSITIVE_INFINITY;
+  let top = Number.POSITIVE_INFINITY;
+  let right = Number.NEGATIVE_INFINITY;
+  let bottom = Number.NEGATIVE_INFINITY;
+  for (const { x, y } of pixels) {
+    if (x < left) left = x;
+    if (x > right) right = x;
+    if (y < top) top = y;
+    if (y > bottom) bottom = y;
+  }
+  return { left, top, width: right - left + 1, height: bottom - top + 1 };
+}
+
+/** `changed` or `stable` for a measured slide.
+ *
+ *  A slide exactly at the threshold is changed · the threshold is the point
+ *  from which a difference counts, not the first value past it. A slide where
+ *  nothing at all moved is stable whatever the threshold, so `--threshold 0`
+ *  means "every pixel counts", not "every slide is suspect". */
+export function statusForRatio(changedRatio, threshold) {
+  if (changedRatio <= 0) return 'stable';
+  return changedRatio * 100 >= threshold ? 'changed' : 'stable';
+}
+
+/** Which files both sides have, and which only one of them has. */
+export function classifyFiles(currentFiles, baselineFiles) {
+  const baseline = new Set(baselineFiles);
+  const current = new Set(currentFiles);
+  return {
+    compared: currentFiles.filter((f) => baseline.has(f)),
+    added: currentFiles.filter((f) => !baseline.has(f)),
+    missing: baselineFiles.filter((f) => !current.has(f)),
+  };
+}
+
+/**
+ * One report entry from one in-page measurement.
+ *
+ * Two canvases of different sizes have no pixels in common, so a `resized`
+ * slide carries both sizes and no count · a ratio computed across a resize
+ * would be a number that means nothing.
+ */
+export function slideEntry(file, measured, threshold, meta = {}) {
+  const { baselineSize, size } = measured;
+  if (baselineSize.width !== size.width || baselineSize.height !== size.height) {
+    return { file, ...meta, status: 'resized', baselineSize, size };
+  }
+  const changedRatio = measured.total ? measured.changed / measured.total : 0;
+  return {
+    file,
+    ...meta,
+    status: statusForRatio(changedRatio, threshold),
+    changedRatio,
+    changedPixels: measured.changed,
+    totalPixels: measured.total,
+    box: boundingBox(measured.changedCorners),
+  };
+}
+
+/** The slides, loudest first · the ones nobody could measure keep to the end,
+ *  in file order, because they are already named one by one in the report. */
+export function rankSlides(slides) {
+  const loudness = (s) => (typeof s.changedRatio === 'number' ? s.changedRatio : -1);
+  return [...slides].sort((a, b) => loudness(b) - loudness(a) || a.file.localeCompare(b.file));
+}
+
+/** How many slides of each status. */
+export function summarize(slides) {
+  const summary = { changed: 0, stable: 0, added: 0, missing: 0, resized: 0 };
+  for (const s of slides) summary[s.status] += 1;
+  return summary;
+}
+
+/** Whether the render disagrees with its baseline.
+ *
+ *  A slide the baseline never had is what adding a slide looks like · it is
+ *  news, not a regression, so it does not fail the run. */
+export const diffFailed = (summary) => summary.changed + summary.missing + summary.resized > 0;
+
+const percent = (ratio) => (ratio * 100).toFixed(2) + '%';
+
+/** The report as a human reads it · the changed slides ranked, the ones that
+ *  could not be compared named, then the counts. */
+export function formatDiff(report) {
+  const lines = [];
+  const changed = report.slides.filter((s) => s.status === 'changed');
+  if (changed.length) lines.push(`rikiki · diff · ${changed.length} slide(s) changed · most changed first`);
+  for (const s of changed) {
+    const where = s.box ? ` · box ${s.box.left},${s.box.top} ${s.box.width}×${s.box.height}` : '';
+    lines.push(`    · ${percent(s.changedRatio).padStart(7)} ${s.file}${s.title ? ' · ' + s.title : ''}${where}`);
+  }
+  for (const s of report.slides) {
+    if (s.status === 'missing') {
+      lines.push(`    · missing ${s.file} · the baseline has it, this render does not`);
+    } else if (s.status === 'resized') {
+      const { baselineSize: was, size: now } = s;
+      lines.push(`    · resized ${s.file} · ${was.width}×${was.height} → ${now.width}×${now.height}`);
+    }
+  }
+  const { changed: c, stable, added, missing, resized } = report.summary;
+  lines.push(
+    `rikiki · diff · ${c} changed · ${stable} stable · ${added} added · ` +
+      `${missing} missing · ${resized} resized · baseline ${report.baseline}`,
+  );
+  return lines.join('\n');
+}
+
+/**
+ * Compare two PNGs, in the page.
+ *
+ * Serialized into the browser by `diffRender`, so it is self-contained: no
+ * import, no closure over anything in this module. It returns both sizes
+ * always, the count of pixels whose worst channel moved by more than
+ * `channelDelta`, and the two extreme corners of those pixels · never the
+ * pixels themselves, which for a 1920×1080 slide would be two million points
+ * crossing the bridge for a rect.
+ */
+export const COMPARE_IMAGES = `async (baselineUrl, currentUrl, channelDelta) => {
+  const load = (src) => new Promise((ok, fail) => {
+    const img = new Image();
+    img.onload = () => ok(img);
+    img.onerror = () => fail(new Error('could not decode one of the two images'));
+    img.src = src;
+  });
+  const [before, after] = await Promise.all([load(baselineUrl), load(currentUrl)]);
+  const baselineSize = { width: before.naturalWidth, height: before.naturalHeight };
+  const size = { width: after.naturalWidth, height: after.naturalHeight };
+  if (baselineSize.width !== size.width || baselineSize.height !== size.height) {
+    return { baselineSize, size };
+  }
+
+  const { width, height } = size;
+  const bytesOf = (img) => {
+    const canvas = document.createElement('canvas');
+    canvas.width = width;
+    canvas.height = height;
+    const ctx = canvas.getContext('2d', { willReadFrequently: true });
+    ctx.drawImage(img, 0, 0);
+    return ctx.getImageData(0, 0, width, height).data;
+  };
+  const a = bytesOf(before);
+  const b = bytesOf(after);
+
+  let changed = 0;
+  let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity;
+  for (let i = 0, p = 0; i < a.length; i += 4, p += 1) {
+    const delta = Math.max(
+      Math.abs(a[i] - b[i]),
+      Math.abs(a[i + 1] - b[i + 1]),
+      Math.abs(a[i + 2] - b[i + 2]),
+      Math.abs(a[i + 3] - b[i + 3]),
+    );
+    if (delta <= channelDelta) continue;
+    changed += 1;
+    const x = p % width;
+    const y = (p / width) | 0;
+    if (x < minX) minX = x;
+    if (x > maxX) maxX = x;
+    if (y < minY) minY = y;
+    if (y > maxY) maxY = y;
+  }
+  return {
+    baselineSize,
+    size,
+    changed,
+    total: width * height,
+    changedCorners: changed ? [{ x: minX, y: minY }, { x: maxX, y: maxY }] : [],
+  };
+}`;
+
+const pngsIn = (dir) =>
+  readdirSync(dir)
+    .filter((f) => f.toLowerCase().endsWith('.png'))
+    .sort();
+
+const dataUrl = (file) => 'data:image/png;base64,' + readFileSync(file).toString('base64');
+
+/**
+ * Compare a fresh render against a directory of earlier captures.
+ *
+ * Runs on a blank page of the browser `renderDeck` already has open, writes
+ * `diff.json` next to the manifest, and returns the report.
+ *
+ * @param {object} options
+ * @param {import('playwright').Browser} options.browser  the open browser
+ * @param {string} options.outDir       the render that just happened
+ * @param {string} options.baselineDir  the captures to compare it against
+ * @param {number} [options.threshold]  percent of pixels · at or above is `changed`
+ * @param {Array}  [options.shots]      the manifest's shots, to name the slides
+ */
+export async function diffRender({ browser, outDir, baselineDir, threshold = DEFAULT_THRESHOLD, shots = [] }) {
+  const { compared, added, missing } = classifyFiles(pngsIn(outDir), pngsIn(baselineDir));
+  const metaOf = new Map(
+    shots.map((s) => [s.file, { slide: s.index, id: s.id, title: s.title, step: s.step }]),
+  );
+
+  const slides = [];
+  // A page of its own: the deck's own page carries the deck, and a canvas the
+  // size of a slide has no business being appended to it.
+  const context = await browser.newContext();
+  const blank = await context.newPage();
+  try {
+    for (const file of compared) {
+      const measured = await blank.evaluate(
+        async ({ source, baseline, current, channelDelta }) => {
+          const compare = new Function('return ' + source)();
+          return compare(baseline, current, channelDelta);
+        },
+        {
+          source: COMPARE_IMAGES,
+          baseline: dataUrl(join(baselineDir, file)),
+          current: dataUrl(join(outDir, file)),
+          channelDelta: CHANNEL_DELTA,
+        },
+      );
+      slides.push(slideEntry(file, measured, threshold, metaOf.get(file)));
+    }
+  } finally {
+    await context.close().catch(() => {});
+  }
+
+  for (const file of added) slides.push({ file, ...(metaOf.get(file) ?? {}), status: 'added' });
+  for (const file of missing) slides.push({ file, status: 'missing' });
+
+  const ranked = rankSlides(slides);
+  const report = {
+    schema: DIFF_SCHEMA,
+    baseline: baselineDir,
+    threshold,
+    slides: ranked,
+    summary: summarize(ranked),
+  };
+  const diffPath = join(outDir, 'diff.json');
+  writeFileSync(diffPath, JSON.stringify(report, null, 2) + '\n');
+  return { report, diffPath };
+}

package/bin/lib/export-pdf.mjs

@@ -0,0 +1,65 @@
+// ════════════════════════════════════════════════════════════════
+// rikiki export · render a deck to PDF, one slide per page.
+//
+// The page geometry, the page breaks and the backgrounds all come from the
+// deck's own print stylesheet (see slideShell in shared styles and the @page
+// rule deck-root writes from its canvas). This module only asks for the PDF:
+// the browser, the server and the settling live in browser.mjs, which render
+// and check share with it.
+// ════════════════════════════════════════════════════════════════
+
+import { PAGE_LOAD_TIMEOUT_MS, waitForStillFrame, withDeck } from './browser.mjs';
+
+export { rootDepthFor } from './browser.mjs';
+
+/** Page objects in a PDF written by Chrome, which keeps them out of object
+ *  streams · `/Type /Pages` (the tree) and `/Count` on the outline are not pages. */
+export function pdfPageCount(buffer) {
+  return buffer.toString('latin1').match(/\/Type\s*\/Page(?![s\w])/g)?.length ?? 0;
+}
+
+/**
+ * Lay the deck out as paper before the PDF is taken.
+ *
+ * Components that measure themselves (graph edges, annotation marks) only draw
+ * once the layout they measure exists, and a slide never shown on screen has
+ * none. page.pdf() switches to print media and snapshots in the same breath, so
+ * their ResizeObservers never ran: every diagram printed without its arrows.
+ * Switching first and letting frames pass gives them that layout.
+ */
+export async function preparePrint(page) {
+  await page.emulateMedia({ media: 'print' });
+  await waitForStillFrame(page);
+}
+
+/**
+ * Render `deckPath` to `outputPath`.
+ * @returns {Promise<{pages: number, slides: number, missing: string[]}>}
+ *   `pages` is read from the PDF itself, so a slide lost on paper shows up as
+ *   `pages < slides` instead of being reported as printed.
+ */
+export async function exportPdf(deckPath, outputPath, { timeoutMs = PAGE_LOAD_TIMEOUT_MS } = {}) {
+  return withDeck(
+    deckPath,
+    async ({ page, missing }) => {
+      await preparePrint(page);
+      const pdf = await page.pdf({
+        path: outputPath,
+        printBackground: true,
+        preferCSSPageSize: true,
+        // A bookmark per slide title · without an outline a reader has no way
+        // to jump around, and several viewers fall back to a continuous scroll
+        // with no page stops at all.
+        outline: true,
+        // Tagged output carries the reading order and the headings · it is what
+        // makes the outline above meaningful, and what a screen reader needs.
+        tagged: true,
+      });
+      const slides = await page.evaluate(
+        () => document.querySelectorAll('deck-root > *:not(script):not(style):not(template)').length,
+      );
+      return { pages: pdfPageCount(pdf), slides, missing };
+    },
+    { timeoutMs },
+  );
+}

package/bin/lib/graph-hit.mjs

@@ -0,0 +1,86 @@
+// ════════════════════════════════════════════════════════════════
+// Does a painted graph edge cross a node it does not connect?
+//
+// Pure arithmetic, kept out of `check.mjs` because the answer is the whole
+// diagnostic: an edge check that is a few pixels too forgiving reports nothing
+// on a crossing anybody can see from the back of the room, and a check nobody
+// trusts costs more than no check at all.
+//
+// The functions are also serialized into the browser by `check.mjs` (see
+// GRAPH_GEOMETRY_READER), so they must stay self-contained: no imports, no
+// closure over anything in this module.
+// ════════════════════════════════════════════════════════════════
+
+/**
+ * Read the `data-path` that `deck-graph` publishes on each `deck-edge`:
+ * `"x1,y1 x2,y2[ x3,y3 ...]"` in graph-relative CSS pixels.
+ *
+ * Returns `[]` for anything it cannot read whole · half a polyline would be
+ * tested as a shorter edge and quietly miss, which is the failure this module
+ * exists to end. The caller falls back to its own geometry instead.
+ */
+export function parseGraphPath(raw) {
+  if (typeof raw !== 'string' || !raw.trim()) return [];
+  const points = [];
+  for (const pair of raw.trim().split(/\s+/)) {
+    const [x, y] = pair.split(',').map(Number);
+    if (!Number.isFinite(x) || !Number.isFinite(y)) return [];
+    points.push({ x, y });
+  }
+  return points.length >= 2 ? points : [];
+}
+
+/**
+ * Does a polyline put ink inside a rectangle?
+ *
+ * `margin` grows the rectangle before the test. It carries the half width of
+ * the stroke: an edge is a band, not a mathematical line, so a centre line
+ * that misses a node by one pixel still paints over it. Growing the rectangle
+ * rather than fattening the segment squares off the band's corners, which errs
+ * towards reporting · the right direction for a check whose only known defect
+ * was staying silent.
+ */
+export function polylineHitsRect(points, rect, margin = 0) {
+  const box = {
+    left: rect.left - margin,
+    right: rect.right + margin,
+    top: rect.top - margin,
+    bottom: rect.bottom + margin,
+  };
+  if (box.left >= box.right || box.top >= box.bottom) return false;
+  // Liang-Barsky: a segment hits when a slice of its parameter range survives
+  // all four half-planes of the box.
+  const segmentHits = (a, b) => {
+    let t0 = 0;
+    let t1 = 1;
+    const dx = b.x - a.x;
+    const dy = b.y - a.y;
+    for (const [p, q] of [
+      [-dx, a.x - box.left],
+      [dx, box.right - a.x],
+      [-dy, a.y - box.top],
+      [dy, box.bottom - a.y],
+    ]) {
+      if (p === 0) {
+        if (q < 0) return false;
+        continue;
+      }
+      const t = q / p;
+      if (p < 0) t0 = Math.max(t0, t);
+      else t1 = Math.min(t1, t);
+      if (t0 > t1) return false;
+    }
+    return true;
+  };
+  for (let i = 0; i + 1 < points.length; i++) {
+    if (segmentHits(points[i], points[i + 1])) return true;
+  }
+  return false;
+}
+
+/** The same two functions, as source, for `page.evaluate` · the inspector runs
+ *  in the browser and cannot import from here. */
+export const GRAPH_GEOMETRY_READER = `({
+  parseGraphPath: ${parseGraphPath},
+  polylineHitsRect: ${polylineHitsRect},
+})`;