rikiki-deck 0.6.0 → 0.7.2

package/bin/lib/scan-external.mjs

@@ -0,0 +1,126 @@
+// ════════════════════════════════════════════════════════════════
+// scanExternal · everything a supposedly self-contained deck could still
+// fetch at runtime.
+//
+// The previous check only matched absolute URLs from a hardcoded domain list,
+// so a bundle that reached for `./vendor/mermaid.min.js` reported success and
+// rendered an empty diagram offline. This one works the other way round: it
+// finds every reference the page can load by itself, then subtracts the ones
+// that are genuinely inert (data:, blob:, in-page fragments, user-facing links).
+//
+// Scripts are scanned separately and narrowly · minified JS is full of strings
+// that look like markup (`href:n.href`, `"http://"`), and a whole-file regex
+// reports those on every clean bundle.
+// ════════════════════════════════════════════════════════════════
+
+/** Attributes through which an element loads something on its own. */
+const LOADING_ATTRS = ['src', 'srcset', 'poster', 'href'];
+
+/** `href` only loads for these elements · on `<a>` and `<use>` it is navigation. */
+const HREF_LOADS_ON = /^(?:link|image|script|iframe|embed|track|source)$/i;
+
+const isInert = (ref) =>
+  !ref ||
+  ref.startsWith('data:') ||
+  ref.startsWith('blob:') ||
+  ref.startsWith('#') ||
+  ref.startsWith('mailto:') ||
+  ref.startsWith('tel:') ||
+  ref.startsWith('javascript:');
+
+/** Keep every opening tag, drop the text inside <script> and <style>.
+ *  Their bodies are code, not markup · a `<link …>` quoted in a CSS comment or
+ *  a JS string is documentation, not a resource the page loads. */
+function stripCodeBodies(html) {
+  return html.replace(/<(script|style)\b[^>]*>[\s\S]*?<\/\1>/gi, (m, tag) => {
+    const open = m.match(new RegExp(`<${tag}\\b[^>]*>`, 'i'));
+    return open ? `${open[0]}</${tag}>` : '';
+  });
+}
+
+function scriptBodies(html) {
+  return [...html.matchAll(/<script\b[^>]*>([\s\S]*?)<\/script>/gi)].map((m) => m[1]);
+}
+
+function styleBodies(html) {
+  return [...html.matchAll(/<style\b[^>]*>([\s\S]*?)<\/style>/gi)].map((m) => m[1]);
+}
+
+function scanTags(html, out) {
+  for (const tag of html.matchAll(/<([a-zA-Z][\w-]*)\b([^>]*)>/g)) {
+    const name = tag[1];
+    const attrs = tag[2] ?? '';
+    for (const attr of LOADING_ATTRS) {
+      // Quoted first, then unquoted · the inliner only ever handled quoted
+      // values, which is how an unquoted src survived it.
+      const re = new RegExp(`\\b${attr}\\s*=\\s*(?:"([^"]*)"|'([^']*)'|([^\\s"'>]+))`, 'gi');
+      for (const m of attrs.matchAll(re)) {
+        const ref = (m[1] ?? m[2] ?? m[3] ?? '').trim();
+        if (isInert(ref)) continue;
+        if (attr === 'href' && !HREF_LOADS_ON.test(name)) continue;
+        out.push({ kind: 'attribute', element: name.toLowerCase(), attr, ref });
+      }
+    }
+  }
+}
+
+function scanCss(rawCss, out) {
+  // A commented-out rule is not a dependency · tokens.css documents an
+  // alternative <link> inside its header comment.
+  const css = rawCss.replace(/\/\*[\s\S]*?\*\//g, '');
+  for (const m of css.matchAll(/@import\s+(?:url\(\s*)?["']?([^;"')]+)/g)) {
+    const ref = m[1].trim();
+    if (!isInert(ref)) out.push({ kind: 'css-import', ref });
+  }
+  // url() outside an @import · @import matches are removed first so a single
+  // reference is not reported twice.
+  const withoutImports = css.replace(/@import[^;]*;?/g, '');
+  for (const m of withoutImports.matchAll(/url\(\s*["']?([^)"']+)["']?\s*\)/g)) {
+    const ref = m[1].trim();
+    if (!isInert(ref)) out.push({ kind: 'css-url', ref });
+  }
+}
+
+function scanScript(js, out) {
+  // Only constructs that actually fetch · a bare string in minified code does not.
+  for (const m of js.matchAll(/new URL\(\s*["'`]([^"'`]+)["'`]\s*,\s*import\.meta\.url/g)) {
+    if (!isInert(m[1])) out.push({ kind: 'module-url', ref: m[1] });
+  }
+  for (const m of js.matchAll(/\bimport\(\s*["'`]([^"'`]+)["'`]\s*\)/g)) {
+    if (!isInert(m[1])) out.push({ kind: 'dynamic-import', ref: m[1] });
+  }
+  // A static import specifier is never a template literal, and the statement
+  // starts a line or follows a `;`/`}` · without both constraints, prose inside
+  // a library's own error message ("import `x` from `y`") reads as an import.
+  for (const m of js.matchAll(/(?:^|[;}])\s*import\s+[^;'"`]*?from\s*["']([^"']+)["']/gm)) {
+    if (!isInert(m[1])) out.push({ kind: 'static-import', ref: m[1] });
+  }
+  for (const m of js.matchAll(/importScripts\(\s*["'`]([^"'`]+)["'`]/g)) {
+    if (!isInert(m[1])) out.push({ kind: 'worker-import', ref: m[1] });
+  }
+}
+
+/** Every runtime reference that would leave the file, deduplicated by ref.
+ *  An empty array is the only proof that a bundle is self-contained. */
+export function scanExternal(html) {
+  const out = [];
+  const markup = stripCodeBodies(html);
+  scanTags(markup, out);
+  // Style bodies come from the ORIGINAL html · markup has had them emptied.
+  for (const css of styleBodies(html)) scanCss(css, out);
+  for (const js of scriptBodies(html)) scanScript(js, out);
+  // Inline style="" attributes can carry url() too.
+  for (const m of markup.matchAll(/\bstyle\s*=\s*"([^"]*)"/gi)) scanCss(m[1], out);
+
+  const seen = new Set();
+  return out.filter((hit) => {
+    if (seen.has(hit.ref)) return false;
+    seen.add(hit.ref);
+    return true;
+  });
+}
+
+/** One line per hit, ready to print. */
+export function formatExternal(hits) {
+  return hits.map((h) => `    · [${h.kind}] ${h.ref}`).join('\n');
+}

package/bin/lib/starter.mjs

@@ -1,7 +1,12 @@
 // ════════════════════════════════════════════════════════════════
-// Starter deck template for `rikiki init`. Returns plain deck HTML whose
-// refs (tokens.css / themes / dist) resolve against the rikiki package
-// root · the inliner then folds everything into one self-contained file.
+// Starter deck template for `rikiki init`. Returns plain deck HTML.
+//
+// `assetBase` decides which of the two shapes it takes:
+//   ''         · refs resolve against the rikiki package root · the inliner
+//                then folds everything into one self-contained file.
+//   'rikiki/'  · refs point at the runtime copied next to the deck · the file
+//                stays a readable source you serve over HTTP and keep editing.
+// Both are bundle-able: the inliner maps a `rikiki/…` ref back to the package.
 // ════════════════════════════════════════════════════════════════
 
 const esc = (s) => String(s).replace(/[&<>"]/g, (c) =>
@@ -13,21 +18,23 @@ const esc = (s) => String(s).replace(/[&<>"]/g, (c) =>
  * @param {'rikiki'|'siliceum'} o.theme
  * @param {boolean} o.withMermaid include + preload the mermaid runtime
  * @param {boolean} o.withShiki   include + activate the Shiki highlighter
+ * @param {string}  o.assetBase   prefix every asset ref ('' or 'rikiki/')
  */
-export function starterHtml({ title = 'My deck', theme = 'rikiki', withMermaid = false, withShiki = false } = {}) {
-  const themeHref = theme === 'siliceum' ? 'themes/siliceum.css' : 'tokens.css';
+export function starterHtml({ title = 'My deck', theme = 'rikiki', withMermaid = false, withShiki = false, assetBase = '' } = {}) {
+  const asset = (path) => assetBase + path;
+  const themeHref = asset(theme === 'siliceum' ? 'themes/siliceum.css' : 'tokens.css');
 
   // Heavy plugins · injected as refs the inliner folds in. mermaid's UMD sets
   // window.mermaid (deck-mermaid then skips its network load); the shiki module
   // exposes the vendored highlighter as a global and activates it.
   const mermaidTag = withMermaid
-    ? '<script src="dist/vendor/mermaid.min.js"></script>\n'
+    ? `<script src="${asset('dist/vendor/mermaid.min.js')}"></script>\n`
     : '';
   const shikiTag = withShiki
     ? `<script type="module">
-import { createHighlighter } from './dist/vendor/shiki.js';
+import { createHighlighter } from './${asset('dist/vendor/shiki.js')}';
 globalThis.__rikikiShiki = createHighlighter;
-import { installShiki } from './dist/shiki.js';
+import { installShiki } from './${asset('dist/shiki.js')}';
 await installShiki();
 </script>\n`
     : '';
@@ -49,7 +56,7 @@ await installShiki();
 <meta name="viewport" content="width=device-width, initial-scale=1.0">
 <title>${esc(title)}</title>
 <link rel="stylesheet" href="${themeHref}">
-${mermaidTag}${shikiTag}<script type="module" src="dist/index.js"></script>
+${mermaidTag}${shikiTag}<script type="module" src="${asset('dist/index.js')}"></script>
 </head>
 <body>
 
@@ -57,23 +64,29 @@ ${mermaidTag}${shikiTag}<script type="module" src="dist/index.js"></script>
 
   <deck-cover brand="rikiki" speaker="Your name" duration="~10 min" audience="Your audience">
     <h1>${esc(title)} <span class="accent">deck</span></h1>
-    <p class="sub">A self-contained, shareable slide deck.</p>
+    <p class="sub">${assetBase ? 'An editable deck · one HTML file you own.' : 'A self-contained, shareable slide deck.'}</p>
   </deck-cover>
 
   <deck-feature eyebrow="Start here">
     <h1 slot="title">Edit <span class="accent">this file</span></h1>
     <deck-md>
-This whole deck is **one HTML file** with zero external links.
+${assetBase
+  ? `This deck is **plain HTML** you edit by hand.
+
+- each \`&lt;deck-*&gt;\` element is a slide
+- the runtime sits in \`${assetBase.replace(/\/$/, '')}/\` next to this file
+- serve the folder over HTTP, then \`rikiki bundle\` it to share one file`
+  : `This whole deck is **one HTML file** with zero external links.
 
 - open it anywhere, offline
-- each \`<deck-*>\` element is a slide
-- press **?** for keyboard shortcuts
+- each \`&lt;deck-*&gt;\` element is a slide
+- press **?** for keyboard shortcuts`}
     </deck-md>
   </deck-feature>
 ${mermaidSlide}
   <deck-takeaway>
     <h1>Ship it</h1>
-    <p>One file. No network. Share it.</p>
+    <p>${assetBase ? 'Write, check, bundle, share.' : 'One file. No network. Share it.'}</p>
   </deck-takeaway>
 
 </deck-root>

package/bin/lib/visual.mjs

@@ -0,0 +1,120 @@
+// ════════════════════════════════════════════════════════════════
+// What a slide looks like, measured on the pixels rather than on the DOM.
+//
+// The DOM says a box is 400px tall. It does not say the slide reads as
+// top-heavy, or that the ink sits in one corner. Those are pixel facts, and
+// they are the ones a room reacts to first.
+//
+// The signals here follow the low-level design cues that correlate with human
+// judgement of slide quality (Inui et al., 2025): ink density and spatial
+// balance carry most of it. We measure only what is objective and act only on
+// the imbalance · empty space on its own is a choice, never a defect.
+// ════════════════════════════════════════════════════════════════
+
+/** Runs in the page: decode a screenshot and measure where the ink sits. */
+const MEASURE_INK = `async (dataUrl) => {
+  const img = new Image();
+  img.src = dataUrl;
+  await img.decode();
+
+  // Downscale · the layout facts survive, and a 240-wide grid is 100x cheaper
+  // to walk than the full canvas.
+  const w = 240;
+  const h = Math.max(1, Math.round((img.height / img.width) * w));
+  const canvas = document.createElement('canvas');
+  canvas.width = w;
+  canvas.height = h;
+  const ctx = canvas.getContext('2d', { willReadFrequently: true });
+  ctx.drawImage(img, 0, 0, w, h);
+  const { data } = ctx.getImageData(0, 0, w, h);
+
+  const at = (x, y) => {
+    const i = (y * w + x) * 4;
+    return [data[i], data[i + 1], data[i + 2]];
+  };
+  // The background is the most common colour · a deck paints its own ground.
+  const tally = new Map();
+  for (let y = 0; y < h; y++) {
+    for (let x = 0; x < w; x++) {
+      const key = at(x, y).map((c) => c >> 4).join(',');
+      tally.set(key, (tally.get(key) ?? 0) + 1);
+    }
+  }
+  const ground = [...tally.entries()].sort((a, b) => b[1] - a[1])[0][0]
+    .split(',').map((c) => (Number(c) << 4) + 8);
+
+  const far = (p) =>
+    Math.abs(p[0] - ground[0]) + Math.abs(p[1] - ground[1]) + Math.abs(p[2] - ground[2]) > 40;
+
+  let inked = 0;
+  let sumY = 0;
+  let sumX = 0;
+  let top = h;
+  let bottom = -1;
+  let left = w;
+  let right = -1;
+  const rowInk = new Array(h).fill(0);
+  for (let y = 0; y < h; y++) {
+    for (let x = 0; x < w; x++) {
+      if (!far(at(x, y))) continue;
+      inked++;
+      rowInk[y]++;
+      sumY += y;
+      sumX += x;
+      if (y < top) top = y;
+      if (y > bottom) bottom = y;
+      if (x < left) left = x;
+      if (x > right) right = x;
+    }
+  }
+  if (inked === 0) return { inkRatio: 0, empty: true };
+
+  return {
+    empty: false,
+    inkRatio: inked / (w * h),
+    // 0 = ink centred on the slide, negative = pulled up, positive = pulled down.
+    verticalBias: (sumY / inked) / h - 0.5,
+    horizontalBias: (sumX / inked) / w - 0.5,
+    // The band under the last content row, as a share of the slide height.
+    tailBand: 1 - (bottom + 1) / h,
+    headBand: top / h,
+    box: { top: top / h, bottom: bottom / h, left: left / w, right: right / w },
+  };
+}`;
+
+/** The engine's own furniture · counted as ink, it makes every slide look
+ *  bottom-anchored. Hidden for the measurement, restored after. */
+const HIDE_CHROME = `() => {
+  const root = document.querySelector('deck-root');
+  if (!root?.shadowRoot) return;
+  const style = document.createElement('style');
+  style.id = 'rik-measure-chrome';
+  style.textContent =
+    '#progress,#counter,#step-dots,#nav-arrows,#kb-hint,#live{display:none !important}';
+  root.shadowRoot.appendChild(style);
+}`;
+
+const SHOW_CHROME = `() => {
+  document.querySelector('deck-root')?.shadowRoot?.getElementById('rik-measure-chrome')?.remove();
+}`;
+
+/**
+ * Photograph each slide and measure where its ink sits.
+ * `goTo(index)` must leave the page on that slide, settled.
+ */
+export async function measureSlides(page, count, goTo) {
+  await page.evaluate((fn) => new Function('return ' + fn)()(), HIDE_CHROME);
+  const out = [];
+  for (let index = 1; index <= count; index++) {
+    await goTo(index);
+    const shot = await page.screenshot({ type: 'png' });
+    const dataUrl = 'data:image/png;base64,' + shot.toString('base64');
+    const ink = await page.evaluate(
+      ({ fn, url }) => new Function('return ' + fn)()(url),
+      { fn: MEASURE_INK, url: dataUrl },
+    );
+    out.push({ index, ...ink });
+  }
+  await page.evaluate((fn) => new Function('return ' + fn)()(), SHOW_CHROME);
+  return out;
+}