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

package/CLAUDE.md

@@ -0,0 +1,179 @@
+# CLAUDE.md — Authoring guide for AI assistants
+
+This file is auto-loaded by Claude Code (and cross-tool agents via the symmetric `AGENTS.md`) when working in a repo bootstrapped from `book-scaffold-astro`. Read this first; the patterns below are pre-tested.
+
+## Inherits from
+
+Cross-project conventions live in the hub at `~/Claude/lever_of_archimedes/patterns/`. Defer to those for:
+
+- **Git commit format** — `~/Claude/lever_of_archimedes/patterns/git.md`
+- **Testing patterns** — `~/Claude/lever_of_archimedes/patterns/testing.md`
+- **Session workflows** — `~/Claude/lever_of_archimedes/patterns/sessions.md`
+
+If the hub isn't available in your environment (e.g. external contributor), the scaffold's `CHANGELOG.md` documents commit conventions inline.
+
+## Profile
+
+Read `BOOK_PROFILE` from the environment or `.env`. It controls:
+
+- Which content-collection schema is enforced (`academic` / `tools` / `minimal`)
+- Which markdown integrations run (KaTeX gated on `academic`)
+- Which callout family is the "default" import in templates
+- Whether ToolFilter / VersionSelector Preact islands mount in the chrome row
+
+When in doubt, run `grep BOOK_PROFILE .env astro.config.mjs src/content.config.ts` to see the wiring.
+
+## Frontmatter schemas
+
+### Academic profile (`src/content.config.ts:academicChapterSchema`)
+
+```yaml
+---
+week: 1                  # int, required, 1-99
+part: foundations        # required: foundations|ssm-core|beyond-ssm|integration|synthesis
+title: "..."             # string, required
+status: implemented      # required: implemented|chapter_only|prose_only|code_only|reading_only|scaffolded|planned
+# optional:
+roadmap_lines: [10, 42]  # [start, end] line refs into roadmap.md
+code_path: experiments/jax/week01/foo.py
+tests_path: experiments/jax/week01/test_foo.py
+notebook_path: notebooks/week01.ipynb
+description: "..."       # SEO/meta
+draft: false
+---
+```
+
+### Tools profile (`src/content.config.ts:toolsChapterSchema`)
+
+```yaml
+---
+title: "..."                       # required
+part: 1                            # int, required, 0-10
+chapter: 1                         # int, required, 0-99
+volatility: architectural-pattern  # required: stable-principle|architectural-pattern|feature-surface
+tools_compared: [claude-code]      # required, ≥1 of: claude-code|gemini-cli|codex-cli|cross-tool
+last_verified: 2026-05-18          # date, required
+sources: []                        # array of source-manifest keys
+# optional: description, draft, updated
+---
+```
+
+## Component reference
+
+Two callout families coexist. Authors import what they need.
+
+**Tools family** (`src/components/callouts/`, 8 components): `SkillBox`, `CaseStudy`, `ConceptBox`, `KeyIdea`, `TryThis`, `Recovery`, `Convergence`, `Divergence`.
+
+**Academic family** (`src/components/callouts/`, 10 components): `NoteBox`, `ExampleBox`, `DynConnect`, `InsightBox`, `WarnBox`, `CounterBox`, `TipBox`, `OpenQuestion`, `PaperBox`, `ResultBox`. Plus `Theorem` (unified for theorem/proposition/lemma/corollary/definition/example/exercise/remark/proof).
+
+**Utility components** (`src/components/`, any profile): `Cite`, `XRef`, `Figure`, `MarginNote`, `Sidenote`, `WeekRef`, `CodeRef`, `CodeBlock`, `Tag`, `StatusBadge`.
+
+Full reference in `recipes/04-component-library.md`.
+
+## Citation patterns
+
+Academic profile uses BibTeX → `references.json`:
+
+```mdx
+The HiPPO theory <Cite key="gu2020hippo" /> shows that …
+For the kernel decomposition see <Cite key="gu2024mamba" page="3" />.
+```
+
+Build: `npm run build:bib` reads `bibliography.bib` and writes `src/data/references.json`. Run after any `.bib` edit. The pre-build hook handles this automatically.
+
+Tools profile uses the YAML source manifest (`sources/manifest.yaml`); cite via `sources` array in frontmatter, rendered by `SourceArchive.astro`.
+
+## Build + dev commands
+
+```bash
+npm install                  # once after clone
+npm run dev                  # localhost:4321
+npm run build                # astro build + pagefind index → dist/
+npm run validate             # pre-flight check (recipe 09)
+npm run build:bib            # rebuild references.json after .bib edit
+npm run pdf                  # render dist-pdf/book.pdf via Paged.js
+```
+
+`prebuild` chains: `build:assets` (bib + figures + notebooks) → `validate` → `astro build`.
+
+## Deploy
+
+Cloudflare Workers + Static Assets via `wrangler.toml`. Recipe 05 has the dashboard flow. URL after first deploy: `https://<book-name>.<account>.workers.dev`.
+
+For monorepo Astro projects (Astro project in subdir), prefix build + deploy commands with `cd <subdir> &&`.
+
+## Validation
+
+`npm run validate` (also runs in prebuild) catches:
+
+- Unknown `<Cite key>` (academic) — bibkey not in `references.json`
+- Unknown `<XRef id>` — id not in `labels.json` (XRef silently renders `[?label]` otherwise)
+- Missing `<Figure src>` files under `public/`
+- Internal markdown links that don't resolve
+
+See `recipes/09-validation.md` to extend.
+
+## Common authoring tasks
+
+### Add a new chapter
+
+1. Copy `examples/chapter-template-{academic,tools}.mdx` to `src/content/chapters/`.
+2. Edit frontmatter (title, week/chapter, status/volatility).
+3. Write.
+4. `npm run dev` to preview at `/chapters/<slug>/`.
+
+### Add a citation
+
+1. Edit `bibliography.bib` (academic profile) — add the BibTeX entry.
+2. `npm run build:bib` regenerates `src/data/references.json`.
+3. Use `<Cite key="<bibkey>" />` in chapter.
+
+### Add a figure
+
+1. Drop PDF in `figures/<topic>/<name>.pdf` (or set `BOOK_FIGURES_PATH`).
+2. `npm run build:figures` produces `public/figures/<topic>/<name>.svg`.
+3. Reference: `<Figure src="/figures/<topic>/<name>.svg" caption="..." id="..." />`.
+
+### Add a new component
+
+1. Create `src/components/<Foo>.astro`.
+2. Add an entry to `recipes/04-component-library.md`.
+3. Update this file's "Component reference" section.
+
+## Commit conventions
+
+Inherit from the hub's `git.md`. Format:
+
+```
+type(scope): Short imperative subject
+
+Body paragraphs explaining what and why.
+
+- Bullet for each significant change
+- Another bullet
+
+Generated with Claude Code
+
+Co-Authored-By: Claude <noreply@anthropic.com>
+```
+
+Types: `feat` / `fix` / `refactor` / `docs` / `test` / `chore` / `release`. One commit per logical unit; small commits over big ones.
+
+## Don't
+
+- Don't use `npm create astro@latest` to bootstrap a fresh repo — the scaffold is not vanilla Astro.
+- Don't bypass the validator with `--no-verify` on a commit. If validate fails, fix the underlying issue.
+- Don't commit large binaries (PDFs > 5 MB, model checkpoints) — keep them in research-kb or a separate asset host.
+- Don't auto-import from both callout families in the same chapter unless you have a reason. Pick a default family and stay with it.
+
+## Reference repos
+
+- `~/Claude/post_transformers/guides/web/` — academic-profile reference, deployed at `post-transformers-guide.brandon-m-behring.workers.dev`
+- `~/Claude/book-template-astro/` — tools-profile reference, "Agentic Coding" book in production
+- `~/Claude/book-scaffold-astro/` — this canonical scaffold
+
+## Reading this guide didn't help?
+
+- `recipes/README.md` — index of all 11 recipes
+- `recipes/08-decisions-ledger.md` — why everything is shaped the way it is
+- `~/.claude/plans/i-want-to-investigate-recursive-yao.md` — full design discussion

package/bin/book-scaffold.mjs

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+/**
+ * book-scaffold — single-dispatcher CLI for the book-scaffold-astro toolkit.
+ *
+ * Per PACKAGE_DESIGN.md §8: one bin entry, sub-command parsed from argv[2].
+ * Sub-commands import the corresponding script module; the script's own
+ * argv parsing handles flags.
+ */
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import { readFileSync } from 'node:fs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const handlers = {
+  validate: '../scripts/validate.mjs',
+  'build-labels': '../scripts/build-labels.mjs',
+  'build-bib': '../scripts/build-bib.mjs',
+  'build-figures': '../scripts/build-figures.mjs',
+  'render-notebooks': '../scripts/render-notebooks.mjs',
+};
+
+const HELP = `Usage: book-scaffold <sub-command> [args...]
+
+Sub-commands:
+  validate           Pre-flight content validator (XRef ids, Cite keys, Figure srcs).
+  build-labels       Emit src/data/labels.json for cross-references (Phase C).
+  build-bib          BibTeX -> CSL JSON for the <Cite> component.
+  build-figures      PDF -> SVG via pdftocairo / pdftoppm fallback.
+  render-notebooks   ipynb -> HTML via Jupyter nbconvert.
+
+  --help, -h         This message.
+  --version, -v      Print the package version.
+
+See: https://github.com/brandon-behring/book-scaffold-astro
+`;
+
+const [, , sub, ...rest] = process.argv;
+
+if (!sub || sub === '--help' || sub === '-h') {
+  process.stdout.write(HELP);
+  process.exit(sub ? 0 : 1);
+}
+
+if (sub === '--version' || sub === '-v') {
+  const pkgPath = resolve(__dirname, '../package.json');
+  const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+  process.stdout.write(`${pkg.version}\n`);
+  process.exit(0);
+}
+
+if (!(sub in handlers)) {
+  process.stderr.write(`book-scaffold: unknown sub-command '${sub}'.\n\n${HELP}`);
+  process.exit(2);
+}
+
+// Hand off argv to the sub-command's script. The script reads process.argv
+// directly so flag parsing stays consistent with v2.0 standalone usage.
+const scriptPath = resolve(__dirname, handlers[sub]);
+process.argv = [process.argv[0], scriptPath, ...rest];
+await import(scriptPath);

package/components/CaseStudy.astro

@@ -0,0 +1,36 @@
+---
+/**
+ * CaseStudy — concrete anecdote, dated. Grounds a principle in a real
+ * event: "When Gemini's 1M window launched (Feb 2026)...", "A team hit
+ * context rot at 60K tokens in Q3 2025..."
+ *
+ * The date is required and rendered prominently to help readers
+ * calibrate relevance against current tool state. Stale case studies
+ * don't pretend to be recent.
+ *
+ * Usage:
+ *   <CaseStudy date="2026-02">
+ *     When Gemini shipped the 1M-token window, teams initially filled
+ *     it to ~800K and watched retrieval accuracy collapse by Q3...
+ *   </CaseStudy>
+ */
+interface Props {
+  date: string;       // human-readable or ISO — not parsed, just displayed
+  title?: string;
+}
+const { date, title } = Astro.props;
+---
+<aside class="callout callout-case" role="note" aria-label="Case study">
+  <strong class="callout-title">
+    Case study{title ? ` · ${title}` : ''} <span class="case-date">· {date}</span>
+  </strong>
+  <div class="callout-body"><slot /></div>
+</aside>
+
+<style>
+  .case-date {
+    font-weight: 400;
+    color: var(--color-text-muted);
+    font-size: var(--text-sm);
+  }
+</style>

package/components/ChapterHeader.astro

@@ -0,0 +1,61 @@
+---
+/**
+ * ChapterHeader — renders the metadata block at the top of every chapter.
+ * Surfaces provenance signals the LaTeX book conveyed implicitly:
+ *   - Part + chapter number (position in the book)
+ *   - Volatility class (freshness calibration for the reader)
+ *   - Tools compared (scope signal)
+ *   - Last verified date (how stale are the claims?)
+ *
+ * Driven entirely from the chapter's frontmatter (see content.config.ts).
+ */
+import type { CollectionEntry } from 'astro:content';
+import { getFreshness, freshnessLabel } from '../src/lib/freshness';
+
+interface Props {
+  data: CollectionEntry<'chapters'>['data'];
+}
+const { data } = Astro.props;
+
+function formatDate(d: Date): string {
+  return d.toISOString().slice(0, 10);
+}
+
+const freshness = getFreshness(data.last_verified, data.volatility);
+const freshnessText =
+  freshness.status === 'fresh'
+    ? 'Fresh'
+    : freshness.status === 'verify-soon'
+      ? 'Verify soon'
+      : 'Stale';
+---
+<header class="chapter-header">
+  <div class="chapter-meta">
+    <span>Part {data.part}</span>
+    <span>Chapter {data.chapter}</span>
+    <span>
+      Last verified {formatDate(data.last_verified)}
+      <span
+        class="freshness-badge"
+        data-status={freshness.status}
+        aria-label={freshnessLabel(freshness)}
+        title={freshnessLabel(freshness)}
+      >{freshnessText}</span>
+    </span>
+    {data.updated && <span>Updated {formatDate(data.updated)}</span>}
+  </div>
+  <h1>{data.title}</h1>
+  {data.description && <p class="chapter-description">{data.description}</p>}
+  <div class="chapter-badge-row">
+    <span class="chapter-badge-row-label">Volatility:</span>
+    <span class={`volatility-badge volatility-${data.volatility}`}>
+      {data.volatility}
+    </span>
+  </div>
+  {data.tools_compared.length > 0 && (
+    <div class="chapter-badge-row">
+      <span class="chapter-badge-row-label">Tools compared:</span>
+      {data.tools_compared.map((t) => <span class="tool-badge">{t}</span>)}
+    </div>
+  )}
+</header>

package/components/ChapterNav.astro

@@ -0,0 +1,29 @@
+---
+/**
+ * ChapterNav — prev / next chapter links at the bottom of each chapter.
+ * Derived from the ordered chapters collection via getNeighbors.
+ */
+import { getNeighbors } from '../src/lib/chapters';
+
+interface Props {
+  currentId: string;
+}
+const { currentId } = Astro.props;
+const { prev, next } = await getNeighbors(currentId);
+---
+{(prev || next) && (
+  <nav class="chapter-nav" aria-label="Chapter navigation">
+    {prev && (
+      <a href={`/${prev.id}/`} class="prev">
+        <span class="nav-label">← Previous</span>
+        <span class="nav-title">{prev.data.title}</span>
+      </a>
+    )}
+    {next && (
+      <a href={`/${next.id}/`} class="next">
+        <span class="nav-label">Next →</span>
+        <span class="nav-title">{next.data.title}</span>
+      </a>
+    )}
+  </nav>
+)}

package/components/ChapterTOC.astro

@@ -0,0 +1,33 @@
+---
+/**
+ * ChapterTOC — collapsible "On this page" anchor list.
+ *
+ * Uses native <details> — collapsed by default; no JavaScript required.
+ * Shows h2 and h3 headings only (h1 is the chapter title; h4+ is noise
+ * in a TOC). Each heading link uses the slug Astro's MDX generates.
+ *
+ * If the chapter has fewer than 3 matching headings, the TOC renders
+ * nothing — an anchor list for a short chapter is clutter.
+ */
+import type { MarkdownHeading } from 'astro';
+
+interface Props {
+  headings: MarkdownHeading[];
+}
+const { headings } = Astro.props;
+
+const toc = headings.filter((h) => h.depth >= 2 && h.depth <= 3);
+const showToc = toc.length >= 3;
+---
+{showToc && (
+  <details class="chapter-toc">
+    <summary>On this page</summary>
+    <ol>
+      {toc.map((h) => (
+        <li class={`toc-h${h.depth}`}>
+          <a href={`#${h.slug}`}>{h.text}</a>
+        </li>
+      ))}
+    </ol>
+  </details>
+)}

package/components/Citation.astro

@@ -0,0 +1,94 @@
+---
+/**
+ * Citation — renders a reference to a source from sources/manifest.yaml.
+ *
+ * Resolves the source slug at build time via Astro's content collections.
+ * An unknown slug fails the build with a precise error, not at runtime.
+ *
+ * Two display modes:
+ *   as="sidenote" (default) — wraps the citation in a <Sidenote>. Shows
+ *     in the desktop right margin / mobile inline aside. Contains title,
+ *     author, year, tier badge, plus links to original and Perma.cc.
+ *   as="inline" — renders the citation inline in the main text as a
+ *     subtle reference (title + author + year). For cases where the
+ *     citation is part of the sentence rather than a reference.
+ *
+ * Usage:
+ *   Context rot<Citation src="anthropic-context-2026" /> is observed
+ *   in all three tools.
+ *
+ * Or inline:
+ *   See <Citation src="gwern-sidenote" as="inline" /> for the argument.
+ */
+import { getEntry } from 'astro:content';
+import Sidenote from './Sidenote.astro';
+
+interface Props {
+  src: string;
+  as?: 'sidenote' | 'inline';
+}
+
+const { src, as = 'sidenote' } = Astro.props;
+const source = await getEntry('sources', src);
+
+if (!source) {
+  throw new Error(
+    `Citation: source slug "${src}" not found in sources/manifest.yaml. ` +
+    `Add an entry with id: ${src}, or correct the typo.`
+  );
+}
+
+const { data } = source;
+const publishYear = data.publish_date
+  ? new Date(data.publish_date).getUTCFullYear()
+  : null;
+---
+
+{as === 'sidenote' ? (
+  <Sidenote>
+    <strong>{data.title}</strong>
+    {data.author && <>{' · '}{data.author}</>}
+    {publishYear && <>{' ('}{publishYear}{')'}</>}
+    <span class="citation-tier" title={`Source tier: ${data.tier}`}>{data.tier}</span>
+    {' '}
+    <a href={data.url} rel="external noopener" class="citation-link">original</a>
+    {data.perma_cc && (
+      <>
+        {' · '}
+        <a href={data.perma_cc} rel="external noopener" class="citation-link">archived</a>
+      </>
+    )}
+  </Sidenote>
+) : (
+  <span class="citation-inline">
+    <a href={data.url} rel="external noopener">{data.title}</a>
+    {data.author && <> · {data.author}</>}
+    {publishYear && <> ({publishYear})</>}
+  </span>
+)}
+
+<style is:global>
+  /* Tier badge styling — muted, uppercase, small, monospaced */
+  .citation-tier {
+    display: inline-block;
+    margin-left: 0.4em;
+    padding: 0 0.4em;
+    font-family: var(--font-code);
+    font-size: 0.7em;
+    font-style: normal;
+    font-weight: 500;
+    color: var(--color-text-muted);
+    background: var(--color-bg);
+    border: 1px solid var(--color-border);
+    border-radius: var(--radius-sm);
+    vertical-align: 0.1em;
+    letter-spacing: 0.05em;
+  }
+  .citation-link {
+    font-style: normal;
+  }
+  .citation-inline {
+    font-style: italic;
+    color: var(--color-text-muted);
+  }
+</style>

package/components/Cite.astro

@@ -0,0 +1,71 @@
+---
+/**
+ * Cite — renders a `\cite{bibkey}` LaTeX citation as a clickable
+ * inline reference to the bibliography page.
+ *
+ * Reads src/data/references.json (built by scripts/build-bib.mjs from
+ * guides/shared/references.bib). Unknown bibkeys fail the build with
+ * a precise error so typos surface at the same point biber would have
+ * caught them.
+ *
+ * Display:
+ *   - Single author: "Gu (2024)"
+ *   - Two authors:   "Gu & Dao (2024)"
+ *   - 3+ authors:    "Gu et al. (2024)"
+ *   - With page:     "Gu et al. (2024, p. 42)"
+ *
+ * The link target is /references#<bibkey>, where the references page
+ * (src/pages/references.astro) renders all entries with anchor IDs
+ * matching their bibkeys.
+ *
+ * Usage:
+ *   The HiPPO theory <Cite key="gu2020hippo" /> shows that …
+ *   See <Cite key="gu2024mamba" page="3" /> for the kernel decomposition.
+ */
+type CslAuthor = { family?: string; given?: string; literal?: string };
+type CslEntry = {
+  id: string;
+  author?: CslAuthor[];
+  issued?: { 'date-parts'?: number[][] };
+  title?: string;
+};
+
+// Resolve references.json from consumer's project root. Missing file -> empty
+// map -> any <Cite> throws below (strict per D3 — bibkeys must resolve at build).
+const refsModules = import.meta.glob<{ default: Record<string, CslEntry> }>(
+  '/src/data/references.json',
+  { eager: true },
+);
+const refsModule = refsModules['/src/data/references.json'];
+const map = (refsModule?.default ?? {}) as Record<string, CslEntry>;
+
+interface Props {
+  key: string;
+  page?: string;
+}
+
+const { key, page } = Astro.props;
+const entry = map[key];
+if (!entry) {
+  throw new Error(
+    `Cite: unknown bibkey "${key}". Check guides/shared/references.bib ` +
+      `for the expected key, or re-run build:bib if the .bib was just edited.`,
+  );
+}
+
+const authors = entry.author ?? [];
+const surname = (a: CslAuthor) => a.family ?? a.literal ?? '(anon)';
+
+let authorText: string;
+if (authors.length === 0) authorText = '(anon)';
+else if (authors.length === 1) authorText = surname(authors[0]);
+else if (authors.length === 2)
+  authorText = `${surname(authors[0])} & ${surname(authors[1])}`;
+else authorText = `${surname(authors[0])} et al.`;
+
+const year = entry.issued?.['date-parts']?.[0]?.[0] ?? 'n.d.';
+const yearText = page ? `${year}, p. ${page}` : `${year}`;
+---
+<a href={`/references#${key}`} class="cite" title={entry.title ?? key}>
+  {authorText} ({yearText})
+</a>

package/components/CodeBlock.astro

@@ -0,0 +1,115 @@
+---
+/**
+ * CodeBlock — embed a slice of a real source file from the repo at
+ * build time, with syntax highlighting and a "View on GitHub" header
+ * link pointing to the exact line range.
+ *
+ * Reads the file from the repo root (resolved relative to
+ * guides/web/), slices `lines` ("N-M" or "N"), and hands the snippet
+ * to Astro's `<Code>` component for Shiki rendering.
+ *
+ * Build fails if:
+ *   - The file does not exist on disk
+ *   - The requested line range is out of bounds
+ *   - `lines` is malformed
+ *
+ * Usage:
+ *   <CodeBlock
+ *     src="experiments/jax/week04/s4_hippo.py"
+ *     lines="42-58"
+ *     lang="python"
+ *   />
+ *
+ *   <CodeBlock src="experiments/jax/week04/s4_hippo.py" lines="42" lang="python" />
+ *
+ * If `lang` is omitted, it is inferred from the file extension.
+ */
+import { Code } from 'astro:components';
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { buildGithubUrl } from '../src/lib/repo-url';
+
+interface Props {
+  src: string;
+  lines: string; // "N" or "N-M" (1-indexed, inclusive)
+  lang?: string;
+}
+
+const { src, lines, lang } = Astro.props;
+
+// Resolve src relative to repo root. Astro's build runs with cwd =
+// guides/web/, so the repo root is two levels up. Using process.cwd()
+// (not import.meta.dirname) survives Astro's bundling — at runtime
+// import.meta.dirname points to the emitted .mjs chunk, not the source.
+const REPO_ROOT = resolve(process.cwd(), '..', '..');
+const absPath = resolve(REPO_ROOT, src);
+
+if (!existsSync(absPath)) {
+  throw new Error(
+    `CodeBlock: file not found at ${absPath} (src="${src}"). ` +
+      `Check the path is relative to the repo root.`,
+  );
+}
+
+const rangeMatch = lines.match(/^(\d+)(?:-(\d+))?$/);
+if (!rangeMatch) {
+  throw new Error(
+    `CodeBlock: lines="${lines}" is malformed. Use "N" or "N-M" (1-indexed).`,
+  );
+}
+
+const startLine = parseInt(rangeMatch[1], 10);
+const endLine = rangeMatch[2] ? parseInt(rangeMatch[2], 10) : startLine;
+
+if (endLine < startLine) {
+  throw new Error(
+    `CodeBlock: lines="${lines}" — end line ${endLine} is before start ${startLine}.`,
+  );
+}
+
+const fileLines = readFileSync(absPath, 'utf8').split('\n');
+if (startLine < 1 || endLine > fileLines.length) {
+  throw new Error(
+    `CodeBlock: requested lines ${startLine}-${endLine} fall outside ` +
+      `file extent (1-${fileLines.length}) for ${src}.`,
+  );
+}
+
+const snippet = fileLines.slice(startLine - 1, endLine).join('\n');
+
+const inferLang = (path: string): string => {
+  const ext = path.split('.').pop()?.toLowerCase() ?? '';
+  const map: Record<string, string> = {
+    py: 'python',
+    jl: 'julia',
+    js: 'javascript',
+    ts: 'typescript',
+    mjs: 'javascript',
+    sh: 'bash',
+    yaml: 'yaml',
+    yml: 'yaml',
+    json: 'json',
+    md: 'markdown',
+    mdx: 'mdx',
+    rs: 'rust',
+    go: 'go',
+    cpp: 'cpp',
+    c: 'c',
+    tex: 'latex',
+  };
+  return map[ext] ?? 'text';
+};
+
+const language = (lang ?? inferLang(src)) as Parameters<typeof Code>[0]['lang'];
+
+const githubUrl = buildGithubUrl(src, startLine, endLine);
+const rangeText = startLine === endLine ? `:${startLine}` : `:${startLine}-${endLine}`;
+const displayPath = `${src}${rangeText}`;
+---
+<div class="codeblock-frame">
+  <div class="codeblock-header">
+    <code>{displayPath}</code>
+    <a href={githubUrl} rel="external noopener">View on GitHub →</a>
+  </div>
+  <Code code={snippet} lang={language} theme="css-variables" wrap={false} />
+</div>