@brandon_m_behring/book-scaffold-astro 3.0.0-alpha.0

package/recipes/10-custom-domain.md

@@ -0,0 +1,72 @@
+# Recipe 10 — Custom domain on Cloudflare
+
+**Profile**: any (deploy is profile-agnostic).
+
+**TL;DR**: Free, ~5 minutes in the dashboard. Cloudflare auto-issues a TLS cert. Works for both apex (`my-book.com`) and subdomain (`book.my-site.com`).
+
+## Prerequisites
+
+- A working `wrangler.toml` deploy (recipe 05). URL: `https://<book-name>.<account>.workers.dev`.
+- A domain you own. Either on Cloudflare DNS already, or willing to add an NS record at your registrar.
+- ~5 minutes of dashboard time.
+
+## Path 1 — Domain already on Cloudflare DNS
+
+This is the smoothest path.
+
+1. **Dashboard → Workers & Pages → your-book-name → Settings → Custom Domains → Add Custom Domain.**
+2. Type the domain (`my-book.com` for apex, or `book.my-site.com` for subdomain).
+3. Cloudflare auto-provisions:
+   - DNS record (CNAME for subdomain, AAAA + A for apex)
+   - TLS cert via Cloudflare's CA
+4. Wait ~30 seconds for propagation. Visit the domain in a fresh tab.
+
+That's the whole flow. The domain becomes the canonical URL; the `.workers.dev` URL still works as a fallback.
+
+## Path 2 — Domain at an external registrar
+
+Move DNS to Cloudflare first, then use Path 1. Two sub-steps:
+
+1. **Dashboard → Websites → Add a Site → Free plan.** Enter your domain.
+2. Cloudflare scans current DNS and shows the records. **Cloudflare then gives you 2 nameservers.**
+3. **At your registrar**, replace the NS records with Cloudflare's 2 nameservers. Save.
+4. Wait for propagation (15 min – 24 h, usually <1 hour). Cloudflare emails you when active.
+5. Once active, follow Path 1.
+
+## Apex vs subdomain
+
+- **Apex (`my-book.com`)**: Cloudflare uses CNAME flattening. Apex with Workers + Static Assets is well-supported; no special config needed.
+- **Subdomain (`book.my-site.com`)**: a plain CNAME record. The rest of `my-site.com` keeps whatever DNS it had.
+
+## Removing the `.workers.dev` URL
+
+The `<book-name>.<account>.workers.dev` URL keeps working alongside the custom domain. To disable it:
+
+**Dashboard → Workers & Pages → your-book-name → Settings → Domains & Routes → workers.dev → toggle off.**
+
+Most authors leave it on as a fallback / debugging surface.
+
+## Common gotchas
+
+- **"Site not active" after adding the domain**: NS records still propagating. Wait. `dig +short NS my-book.com` should return Cloudflare's nameservers when active.
+- **TLS handshake failures for the first ~60 seconds**: cert issuance takes a moment after DNS resolves. Retry.
+- **Mixed-content warnings**: rare with a static Astro build, but if you embedded any `http://` image URLs they'll fail under TLS. Use `//` or `https://`.
+- **Cache TTL too long**: Cloudflare's default cache for Workers + Static Assets is 4 hours for the HTML and 1 year for fingerprinted assets. After redeploying, the HTML may serve stale for a few minutes. Purge: **Dashboard → Caching → Configuration → Purge Everything**.
+
+## Sub-paths
+
+Workers + Static Assets is best for whole-domain sites. If you want a book at `my-site.com/book/` and other content at `my-site.com/`, two options:
+
+- Run two separate Workers, one per path, and use Cloudflare's Routes feature in `wrangler.toml`.
+- Use Cloudflare's Path-based-routing in Workers — more setup, see Cloudflare docs.
+
+Most authors prefer apex or subdomain.
+
+## Canonical files
+
+- `wrangler.toml` — name + assets config (recipe 05)
+- Cloudflare dashboard — where the custom domain is wired up
+
+## Reference
+
+post-transformers ships at `post-transformers-guide.brandon-m-behring.workers.dev` (the default Workers subdomain). Custom domain not yet attached; the workflow above is the documented path for when it is.

package/recipes/README.md

@@ -0,0 +1,43 @@
+# Recipes
+
+Terse pointers into canonical code for the most common book-authoring workflows. Each recipe is 50–100 lines; the canonical implementation lives in the scaffold itself.
+
+## Index
+
+| # | Recipe | Profile | What it covers |
+|---|---|---|---|
+| 00 | [Getting started](00-getting-started.md) | any | Pick a profile, bootstrap, customize, deploy |
+| 01 | [Add math (KaTeX)](01-add-math.md) | academic | KaTeX 36-macro library, strict mode, `$x^2$` and `$$\int$$` |
+| 02 | [Bibliography pipeline](02-bibliography-pipeline.md) | academic | BibTeX → `references.json` via citation-js |
+| 03 | [Asset pipelines](03-asset-pipelines.md) | any | Figures (PDF→SVG) + notebooks (ipynb→HTML), graceful-skip |
+| 04 | [Component library](04-component-library.md) | any | Two callout families, Theorem, utility components |
+| 05 | [Deploy to Cloudflare](05-deploy-cloudflare.md) | any | Workers + Static Assets via `wrangler.toml` |
+| 06 | [Mobile-first layout](06-mobile-first-layout.md) | any | Three-tier Tufte width + left sidebar |
+| 07 | [Chapter shapes](07-chapter-shapes.md) | profile-aware | Week-based vs Koller-Friedman skeletons |
+| 08 | [Decisions ledger](08-decisions-ledger.md) | any | 15 design decisions explained |
+| 09 | [Pre-flight validation](09-validation.md) | any | `validate.mjs` catches bibkey/XRef/Figure typos |
+| 10 | [Custom domain](10-custom-domain.md) | any | Cloudflare dashboard, apex vs subdomain |
+
+## How to read recipes
+
+Each recipe follows the same shape (per decisions ledger D13 — Q11 locked):
+
+1. **Profile** — when this applies
+2. **TL;DR** — single-paragraph summary
+3. **Sections** with concrete commands and file paths
+4. **Common gotchas** — failure modes the recipe maintainer hit
+5. **Canonical files** — line refs into the scaffold for full code
+6. **Reference implementation** — a real book using this pattern
+
+Recipes don't repeat what the code says — they explain *why* the code is shaped that way, *when* to deviate, and *where to look*.
+
+## How to add a recipe
+
+When you discover a non-obvious pattern worth preserving:
+
+1. Pick a recipe number (next available unused number).
+2. Copy `recipes/00-getting-started.md` as a starting template.
+3. Add the recipe to the index above.
+4. Open a PR or commit directly.
+
+Recipes are cheap to write and cheap to maintain. The cost-per-line is low because canonical code lives elsewhere; the recipe is just signal-posts.

package/scripts/build-bib.mjs

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+/**
+ * scripts/build-bib.mjs — Bibliography pipeline (academic profile).
+ *
+ * Reads bibliography.bib at scaffold root (BibTeX), parses via @citation-js,
+ * emits src/data/references.json keyed by bibkey. The .bib path is
+ * overridable via BOOK_BIB_PATH env var for books that keep their .bib
+ * elsewhere (e.g. a shared `guides/shared/references.bib` outside the
+ * Astro project — the post_transformers pattern).
+ *
+ * Run on `prebuild` so every Astro build sees fresh bibliography data.
+ * Idempotent: re-running with no .bib change produces a byte-identical
+ * output (modulo timestamp, which we omit).
+ *
+ * Output shape:
+ *   {
+ *     "gu2024mamba": {
+ *       "id": "gu2024mamba",
+ *       "type": "article-journal",
+ *       "title": "...",
+ *       "author": [{ "family": "Gu", "given": "Albert" }, ...],
+ *       "issued": { "date-parts": [[2024, 1]] },
+ *       ...
+ *     },
+ *     ...
+ *   }
+ *
+ * Build fails (non-zero exit) on:
+ *   - references.bib not readable
+ *   - duplicate bibkeys (citation-js silently overwrites; we surface)
+ *   - parse errors on any entry (citation-js continues; we fail)
+ */
+import { readFile, writeFile, mkdir } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Cite } from '@citation-js/core';
+import '@citation-js/plugin-bibtex';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PROJECT_ROOT = resolve(__dirname, '..');
+
+// Default: bibliography.bib at scaffold root.
+// Override via BOOK_BIB_PATH=path/to/your.bib (absolute or relative to cwd).
+const BIB_PATH = process.env.BOOK_BIB_PATH
+  ? resolve(process.cwd(), process.env.BOOK_BIB_PATH)
+  : resolve(PROJECT_ROOT, 'bibliography.bib');
+const OUT_PATH = resolve(PROJECT_ROOT, 'src/data/references.json');
+
+async function main() {
+  // Graceful skip when the .bib file is absent (minimal/tools profile, or
+  // an academic book that hasn't authored citations yet). Emits an empty
+  // references.json so consumers can still `import refs from '...'`.
+  let bibText;
+  try {
+    bibText = await readFile(BIB_PATH, 'utf8');
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      console.log(
+        `build-bib: ${BIB_PATH.replace(PROJECT_ROOT + '/', '')} not found — ` +
+          `emitting empty references.json (no citations to process).`,
+      );
+      await mkdir(dirname(OUT_PATH), { recursive: true });
+      await writeFile(OUT_PATH, '{}\n', 'utf8');
+      return;
+    }
+    throw err;
+  }
+  const cite = new Cite(bibText);
+  const data = cite.data;
+
+  // Detect duplicates the way biber would (citation-js silently
+  // overwrites the earlier entry, which is the opposite of what we want).
+  const seen = new Set();
+  const dupes = [];
+  for (const entry of data) {
+    if (seen.has(entry.id)) dupes.push(entry.id);
+    seen.add(entry.id);
+  }
+  if (dupes.length > 0) {
+    console.error(`build-bib: ${dupes.length} duplicate bibkeys:`);
+    for (const id of dupes) console.error(`  - ${id}`);
+    process.exit(1);
+  }
+
+  const byKey = Object.fromEntries(data.map((entry) => [entry.id, entry]));
+
+  await mkdir(dirname(OUT_PATH), { recursive: true });
+  await writeFile(OUT_PATH, JSON.stringify(byKey, null, 2) + '\n', 'utf8');
+
+  console.log(
+    `build-bib: ${data.length} entries -> ${OUT_PATH.replace(PROJECT_ROOT + '/', '')}`,
+  );
+}
+
+main().catch((err) => {
+  console.error(`build-bib: failed`);
+  console.error(err);
+  process.exit(1);
+});

package/scripts/build-figures.mjs

@@ -0,0 +1,179 @@
+#!/usr/bin/env node
+/**
+ * scripts/build-figures.mjs — Figure pipeline.
+ *
+ * Walks the figures source tree and converts every PDF to SVG via
+ * pdftocairo, emitting under public/figures/. SVG preserves zoom/quality
+ * and stays small for matplotlib-style plots.
+ *
+ * Default source: figures/ at scaffold root. Override via BOOK_FIGURES_PATH
+ * env var (absolute path or path relative to scaffold root) — useful for
+ * books that share figures with a LaTeX sibling at e.g. ../shared/figures/.
+ *
+ * Subdirectory structure is mirrored to public/figures/ (e.g. figures/foo/x.pdf
+ * → public/figures/foo/x.svg). PDFs at the top level become public/figures/x.svg.
+ *
+ * Falls back to pdftoppm (PNG @ 200 DPI) if pdftocairo produces an
+ * unreasonably small (likely malformed) SVG.
+ *
+ * Idempotent: skips when the target SVG is newer than the source PDF.
+ * Run on `prebuild` so Astro always sees fresh figures.
+ *
+ * Graceful skip: when pdftocairo / pdftoppm aren't on PATH (e.g. Cloudflare
+ * build container), the script warns and exits 0. Committed SVGs/PNGs under
+ * public/figures/ are served as-is. Local devs with poppler-utils regenerate
+ * from PDFs on every `npm run dev`.
+ */
+import { readdir, stat, mkdir } from 'node:fs/promises';
+import { existsSync, statSync } from 'node:fs';
+import { dirname, resolve, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PROJECT_ROOT = resolve(__dirname, '..');
+
+// Default: figures/ at scaffold root.
+// Override via BOOK_FIGURES_PATH=path/to/figures (absolute or relative to
+// scaffold root) — used by post_transformers to point at guides/figures.
+const FIGURES_SRC = process.env.BOOK_FIGURES_PATH
+  ? resolve(PROJECT_ROOT, process.env.BOOK_FIGURES_PATH)
+  : resolve(PROJECT_ROOT, 'figures');
+const FIGURES_DST = resolve(PROJECT_ROOT, 'public/figures');
+
+// Threshold below which we treat a generated SVG as suspect and
+// re-render as PNG via pdftoppm. Tuned empirically: anything under
+// 200 bytes is almost certainly a stub or error output.
+const MIN_SVG_BYTES = 200;
+
+function check(cmd) {
+  const r = spawnSync('which', [cmd], { stdio: 'pipe' });
+  return r.status === 0;
+}
+
+function bail(cmd) {
+  console.warn(
+    `build-figures: '${cmd}' not on $PATH — skipping regeneration. ` +
+      `Committed SVGs under public/figures/ will be served as-is. ` +
+      `(Install poppler-utils locally to regenerate from PDFs.)`,
+  );
+}
+
+/**
+ * Recursively collect PDFs under FIGURES_SRC. Returns an array of
+ * { relPath: 'subdir/file.pdf' | 'file.pdf' } objects so the output
+ * mirrors the input directory structure.
+ */
+async function listPdfsRecursive(root, prefix = '') {
+  if (!existsSync(root)) return [];
+  const entries = await readdir(root, { withFileTypes: true });
+  const out = [];
+  for (const entry of entries) {
+    const relPath = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) {
+      out.push(...(await listPdfsRecursive(resolve(root, entry.name), relPath)));
+    } else if (entry.isFile() && entry.name.endsWith('.pdf')) {
+      out.push({ relPath });
+    }
+  }
+  return out;
+}
+
+function isUpToDate(srcPath, dstPath) {
+  if (!existsSync(dstPath)) return false;
+  const srcMtime = statSync(srcPath).mtimeMs;
+  const dstMtime = statSync(dstPath).mtimeMs;
+  return dstMtime >= srcMtime;
+}
+
+function convertToSvg(srcPath, dstPath) {
+  // pdftocairo wants the destination *without* the .svg extension when
+  // -svg is specified — it appends the extension itself. Strip it.
+  const dstStem = dstPath.replace(/\.svg$/, '');
+  const r = spawnSync('pdftocairo', ['-svg', srcPath, `${dstStem}.svg`], {
+    stdio: 'pipe',
+  });
+  if (r.status !== 0) {
+    const stderr = (r.stderr ?? Buffer.from('')).toString().trim();
+    throw new Error(
+      `pdftocairo failed for ${srcPath}: ${stderr || `exit code ${r.status}`}`,
+    );
+  }
+  // Sanity-check the output size.
+  const size = statSync(dstPath).size;
+  return size >= MIN_SVG_BYTES;
+}
+
+function convertToPng(srcPath, pngStem) {
+  // pdftoppm: -r 200 (DPI), -png, single page (first only).
+  const r = spawnSync(
+    'pdftoppm',
+    ['-r', '200', '-png', '-singlefile', srcPath, pngStem],
+    { stdio: 'pipe' },
+  );
+  if (r.status !== 0) {
+    const stderr = (r.stderr ?? Buffer.from('')).toString().trim();
+    throw new Error(
+      `pdftoppm failed for ${srcPath}: ${stderr || `exit code ${r.status}`}`,
+    );
+  }
+}
+
+async function main() {
+  // Graceful skip when poppler is unavailable (e.g. Cloudflare build
+  // container). The committed SVGs under public/figures/ serve as the
+  // CI artifact; local devs with poppler can refresh them.
+  if (!check('pdftocairo')) { bail('pdftocairo'); return; }
+  if (!check('pdftoppm')) { bail('pdftoppm'); return; }
+
+  if (!existsSync(FIGURES_SRC)) {
+    console.log(
+      `build-figures: ${FIGURES_SRC.replace(PROJECT_ROOT + '/', '')} not found — ` +
+        `skipping (no figures to process).`,
+    );
+    return;
+  }
+
+  const pdfs = await listPdfsRecursive(FIGURES_SRC);
+  if (pdfs.length === 0) {
+    console.log('build-figures: no PDFs found; nothing to do.');
+    return;
+  }
+
+  let total = 0;
+  let converted = 0;
+  let skipped = 0;
+  let pngFallback = 0;
+
+  for (const { relPath } of pdfs) {
+    total++;
+    const srcPath = resolve(FIGURES_SRC, relPath);
+    const stem = relPath.replace(/\.pdf$/, '');
+    const svgPath = resolve(FIGURES_DST, `${stem}.svg`);
+    const pngPath = resolve(FIGURES_DST, `${stem}.png`);
+
+    if (isUpToDate(srcPath, svgPath) || isUpToDate(srcPath, pngPath)) {
+      skipped++;
+      continue;
+    }
+
+    await mkdir(dirname(svgPath), { recursive: true });
+    const svgOK = convertToSvg(srcPath, svgPath);
+    if (!svgOK) {
+      convertToPng(srcPath, svgPath.replace(/\.svg$/, ''));
+      pngFallback++;
+    }
+    converted++;
+  }
+
+  console.log(
+    `build-figures: ${total} total, ${converted} converted ` +
+      `(${pngFallback} png fallback), ${skipped} cached`,
+  );
+}
+
+main().catch((err) => {
+  console.error('build-figures: failed');
+  console.error(err.message ?? err);
+  process.exit(1);
+});

package/scripts/render-notebooks.mjs

@@ -0,0 +1,223 @@
+#!/usr/bin/env node
+/**
+ * scripts/render-notebooks.mjs — Notebook rendering pipeline.
+ *
+ * Walks the notebooks source tree and renders each .ipynb to standalone
+ * HTML under public/notebooks/. Chapter pages link to /notebooks/<stem>.html
+ * as "View executable companion."
+ *
+ * Default source: notebooks/ at scaffold root. Override via
+ * BOOK_NOTEBOOKS_PATH env var (absolute or relative to scaffold root) —
+ * used by post_transformers to point at guides/notebooks/.
+ *
+ * Per the post_transformers convention (and recommended for academic books),
+ * source notebooks are output-free — so the rendered HTML shows code +
+ * markdown only, no embedded matplotlib output. The chapter prose is
+ * canonical; the notebook is a code companion.
+ *
+ * Idempotent: skips when the target HTML is newer than the source .ipynb.
+ * Run on `prebuild` so Astro always sees fresh notebook HTML.
+ *
+ * Style scoping: nbconvert's `basic` template emits HTML without nbviewer
+ * chrome, but with embedded <style> tags. To prevent CSS bleed, each
+ * rendered notebook body is wrapped in <div class="notebook-frame">.
+ *
+ * Graceful skip: when `uv` is not on PATH (e.g. Cloudflare build container),
+ * the script warns and exits 0. Committed HTML under public/notebooks/
+ * serves as the CI artifact; local devs with uv regenerate.
+ *
+ * Prerequisites (local): `uv` on PATH with `jupyter nbconvert` installed
+ * in the active environment (`uv pip install jupyter` or via a `pyproject.toml`).
+ */
+import { readdir, mkdir, readFile, writeFile, unlink } from 'node:fs/promises';
+import { existsSync, statSync } from 'node:fs';
+import { dirname, resolve, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const PROJECT_ROOT = resolve(__dirname, '..');
+
+// Default: notebooks/ at scaffold root.
+// Override via BOOK_NOTEBOOKS_PATH (absolute or relative to scaffold root)
+// — used by post_transformers to point at guides/notebooks/.
+const NOTEBOOKS_SRC = process.env.BOOK_NOTEBOOKS_PATH
+  ? resolve(PROJECT_ROOT, process.env.BOOK_NOTEBOOKS_PATH)
+  : resolve(PROJECT_ROOT, 'notebooks');
+const NOTEBOOKS_DST = resolve(PROJECT_ROOT, 'public/notebooks');
+
+// uv runs from this working directory so its venv discovery climbs to
+// find pyproject.toml / .venv. Defaults to PROJECT_ROOT but post_transformers
+// needs it set to the wider repo root.
+const UV_CWD = process.env.BOOK_UV_CWD
+  ? resolve(PROJECT_ROOT, process.env.BOOK_UV_CWD)
+  : PROJECT_ROOT;
+
+// Skip threshold: source notebooks tagged as "stub" are tiny (<1.5 KB)
+// and not worth rendering until they grow real content. Configurable
+// via env if you want to render every notebook regardless of size.
+const STUB_BYTES = parseInt(process.env.NOTEBOOK_STUB_BYTES ?? '1500', 10);
+
+function check(cmd) {
+  const r = spawnSync('which', [cmd], { stdio: 'pipe' });
+  return r.status === 0;
+}
+
+function bail(cmd) {
+  console.warn(
+    `render-notebooks: '${cmd}' not on $PATH — skipping regeneration. ` +
+      `Committed HTML under public/notebooks/ will be served as-is. ` +
+      `(Install uv locally to refresh from .ipynb sources.)`,
+  );
+}
+
+async function listNotebooks() {
+  if (!existsSync(NOTEBOOKS_SRC)) {
+    console.error(`render-notebooks: ${NOTEBOOKS_SRC} does not exist; skipping.`);
+    return [];
+  }
+  const entries = await readdir(NOTEBOOKS_SRC, { withFileTypes: true });
+  return entries
+    .filter((e) => e.isFile() && e.name.endsWith('.ipynb'))
+    .map((e) => e.name)
+    .sort();
+}
+
+function isUpToDate(srcPath, dstPath) {
+  if (!existsSync(dstPath)) return false;
+  const srcMtime = statSync(srcPath).mtimeMs;
+  const dstMtime = statSync(dstPath).mtimeMs;
+  return dstMtime >= srcMtime;
+}
+
+function isStub(srcPath) {
+  const size = statSync(srcPath).size;
+  return size < STUB_BYTES;
+}
+
+function nbconvertToHtml(srcPath, outDir) {
+  // Use --template=basic to get minimal HTML without nbviewer chrome.
+  // --output specifies just the stem; nbconvert appends .html.
+  const stem = basename(srcPath, '.ipynb');
+  const r = spawnSync(
+    'uv',
+    [
+      'run',
+      'jupyter',
+      'nbconvert',
+      '--to',
+      'html',
+      '--template',
+      'basic',
+      '--output',
+      stem,
+      '--output-dir',
+      outDir,
+      srcPath,
+    ],
+    {
+      stdio: 'pipe',
+      cwd: UV_CWD,
+    },
+  );
+  if (r.status !== 0) {
+    const stderr = (r.stderr ?? Buffer.from('')).toString().trim();
+    throw new Error(
+      `nbconvert failed for ${srcPath}: ${stderr || `exit code ${r.status}`}`,
+    );
+  }
+  return resolve(outDir, `${stem}.html`);
+}
+
+async function wrapInFrame(htmlPath, sourceName) {
+  // Read nbconvert output, wrap body in .notebook-frame so its CSS
+  // doesn't bleed into site styles, and emit a minimal HTML doc.
+  // We don't use Astro's Base layout here — these pages are static
+  // standalone artifacts, not Astro-managed routes.
+  const original = await readFile(htmlPath, 'utf8');
+  const wrapped = `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>${sourceName} — executable companion</title>
+  <style>
+    body { font-family: system-ui, sans-serif; margin: 2rem auto; max-width: 60rem; padding: 0 1rem; }
+    .notebook-frame { font-size: 0.95rem; line-height: 1.55; }
+    .notebook-frame pre { background: #f5f5f4; padding: 0.5rem 0.8rem; border-radius: 4px; overflow-x: auto; }
+    .notebook-frame code { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; }
+    .notebook-frame h1, .notebook-frame h2, .notebook-frame h3 { line-height: 1.2; }
+    .notebook-frame img { max-width: 100%; height: auto; }
+    .notebook-frame table { border-collapse: collapse; }
+    .notebook-frame table td, .notebook-frame table th { padding: 0.3em 0.6em; border: 1px solid #ddd; }
+    .companion-header { padding: 0.5rem 0; border-bottom: 1px solid #ddd; margin-bottom: 1.5rem; font-size: 0.85rem; color: #666; }
+    .companion-header a { color: #3B6FA0; }
+  </style>
+</head>
+<body>
+  <div class="companion-header">
+    Executable companion — <code>${sourceName}</code>.
+  </div>
+  <div class="notebook-frame">
+    ${original}
+  </div>
+</body>
+</html>
+`;
+  await writeFile(htmlPath, wrapped, 'utf8');
+}
+
+async function main() {
+  // Graceful skip when uv is unavailable (e.g. Cloudflare build
+  // container). Committed HTML under public/notebooks/ serves as the
+  // CI artifact; local devs with uv can refresh.
+  if (!check('uv')) { bail('uv'); return; }
+
+  const notebooks = await listNotebooks();
+  if (notebooks.length === 0) {
+    console.log('render-notebooks: no notebooks found; nothing to do.');
+    return;
+  }
+
+  await mkdir(NOTEBOOKS_DST, { recursive: true });
+
+  let total = 0;
+  let rendered = 0;
+  let skipped = 0;
+  let stubsSkipped = 0;
+
+  for (const nb of notebooks) {
+    total++;
+    const srcPath = resolve(NOTEBOOKS_SRC, nb);
+    const stem = basename(nb, '.ipynb');
+    const dstPath = resolve(NOTEBOOKS_DST, `${stem}.html`);
+
+    // Don't bother rendering 1-cell stubs.
+    if (isStub(srcPath)) {
+      stubsSkipped++;
+      // Clean up a stale rendered version if one exists.
+      if (existsSync(dstPath)) await unlink(dstPath);
+      continue;
+    }
+
+    if (isUpToDate(srcPath, dstPath)) {
+      skipped++;
+      continue;
+    }
+
+    nbconvertToHtml(srcPath, NOTEBOOKS_DST);
+    await wrapInFrame(dstPath, nb);
+    rendered++;
+  }
+
+  console.log(
+    `render-notebooks: ${total} total, ${rendered} rendered, ` +
+      `${skipped} cached, ${stubsSkipped} stubs skipped`,
+  );
+}
+
+main().catch((err) => {
+  console.error('render-notebooks: failed');
+  console.error(err.message ?? err);
+  process.exit(1);
+});