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

package/pages/chapters.astro

@@ -0,0 +1,371 @@
+---
+/**
+ * /chapters — book index page.
+ *
+ * Groups non-draft chapters by Part in ascending part+chapter order.
+ * Each card exposes `data-tools="<slug> <slug>..."` so future tool-filter
+ * plumbing (Stage 3.2 commit 3) can hide cards via a single attribute
+ * selector without touching the card rendering.
+ */
+import Base from '../layouts/Base.astro';
+import { getAllChapters, type Chapter } from '../src/lib/chapters';
+import { getFreshness, freshnessLabel } from '../src/lib/freshness';
+
+const chapters = await getAllChapters();
+
+// Stable insertion-order grouping: iterate sorted chapters once.
+const byPart = new Map<number, Chapter[]>();
+for (const c of chapters) {
+  const list = byPart.get(c.data.part);
+  if (list) list.push(c);
+  else byPart.set(c.data.part, [c]);
+}
+
+function formatDate(d: Date): string {
+  return d.toISOString().slice(0, 10);
+}
+
+function partLabel(part: number, appendix: boolean): string {
+  return appendix ? 'Appendices' : `Part ${part}`;
+}
+---
+<Base
+  title="Chapters — Agentic Coding"
+  description="All chapters grouped by Part, with volatility, freshness, and tools-compared metadata at a glance."
+>
+  <article class="prose chapters-index">
+    <header class="chapters-index-header">
+      <h1>Chapters</h1>
+      <p class="chapters-index-lede">
+        Every chapter, grouped by Part. Each card shows its volatility
+        class, freshness status, and the tools it compares. Use a chapter
+        card's metadata to calibrate how much trust to place in its
+        specific claims — stable principles age slowly; feature surfaces
+        age fast.
+      </p>
+      <p class="chapters-index-cross-ref">
+        See also: <a href="/convergence/">convergence dashboard</a> —
+        which patterns have landed in which tools, when.
+      </p>
+    </header>
+
+    <p class="chapters-filter-hint" id="filter-hint" aria-live="polite"></p>
+
+    {Array.from(byPart.entries()).map(([part, list]) => {
+      const appendix = part >= 6;
+      return (
+        <section class="part-group">
+          <h2 class="part-heading">
+            <span class="part-label">{partLabel(part, appendix)}</span>
+          </h2>
+          <ol class="chapter-list">
+            {list.map((c) => {
+              const freshness = getFreshness(c.data.last_verified, c.data.volatility);
+              const freshnessText =
+                freshness.status === 'fresh'
+                  ? 'Fresh'
+                  : freshness.status === 'verify-soon'
+                    ? 'Verify soon'
+                    : 'Stale';
+              const toolsAttr = c.data.tools_compared.join(' ');
+              return (
+                <li
+                  class="chapter-card"
+                  data-tools={toolsAttr}
+                >
+                  <a href={`/${c.id}/`} class="chapter-card-link">
+                    <div class="chapter-card-meta">
+                      <span class="chapter-card-number">
+                        {appendix ? `Appendix ${String.fromCharCode(64 + c.data.chapter).toLowerCase()}` : `Chapter ${c.data.chapter}`}
+                      </span>
+                      <span
+                        class={`volatility-badge volatility-${c.data.volatility}`}
+                        title={`Volatility: ${c.data.volatility}`}
+                      >{c.data.volatility}</span>
+                      <span
+                        class="freshness-badge"
+                        data-status={freshness.status}
+                        aria-label={freshnessLabel(freshness)}
+                        title={freshnessLabel(freshness)}
+                      >{freshnessText}</span>
+                      <span class="chapter-card-verified">
+                        verified {formatDate(c.data.last_verified)}
+                      </span>
+                    </div>
+                    <h3 class="chapter-card-title">{c.data.title}</h3>
+                    {c.data.description && (
+                      <p class="chapter-card-description">{c.data.description}</p>
+                    )}
+                    <div class="chapter-card-tools">
+                      {c.data.tools_compared.map((t) => (
+                        <span class="tool-badge">{t}</span>
+                      ))}
+                    </div>
+                  </a>
+                </li>
+              );
+            })}
+          </ol>
+        </section>
+      );
+    })}
+  </article>
+</Base>
+
+{/* Inline non-island script: applies tool filter from localStorage on
+    load, then reacts to ToolFilter island's "book:tool-filter:change"
+    CustomEvent. Handled as plain DOM so /chapters/ doesn't need its
+    own hydration island. */}
+<script is:inline>
+  (function () {
+    var STORAGE_KEY = 'book:tool-filter';
+    var EVENT_NAME = 'book:tool-filter:change';
+
+    function readSelected() {
+      try {
+        var raw = localStorage.getItem(STORAGE_KEY);
+        if (!raw) return [];
+        var parsed = JSON.parse(raw);
+        return Array.isArray(parsed) ? parsed : [];
+      } catch (e) {
+        return [];
+      }
+    }
+
+    function applyFilter(selected) {
+      var cards = document.querySelectorAll('.chapter-card[data-tools]');
+      var shownCount = 0;
+      var totalCount = cards.length;
+      var active = Array.isArray(selected) && selected.length > 0;
+
+      cards.forEach(function (card) {
+        var attr = card.getAttribute('data-tools') || '';
+        var tools = attr.split(/\s+/).filter(Boolean);
+        var isCrossTool = tools.indexOf('cross-tool') !== -1;
+        var overlaps = false;
+        for (var i = 0; i < tools.length; i++) {
+          if (selected.indexOf(tools[i]) !== -1) {
+            overlaps = true;
+            break;
+          }
+        }
+
+        var hidden = active && !overlaps && !isCrossTool;
+        if (hidden) {
+          card.setAttribute('data-hidden-by-filter', 'true');
+        } else {
+          card.removeAttribute('data-hidden-by-filter');
+          shownCount++;
+        }
+      });
+
+      // Hide entire part sections that become empty under the filter.
+      document.querySelectorAll('.part-group').forEach(function (group) {
+        var visible = group.querySelectorAll(
+          '.chapter-card:not([data-hidden-by-filter="true"])',
+        );
+        if (visible.length === 0) {
+          group.setAttribute('data-hidden-by-filter', 'true');
+        } else {
+          group.removeAttribute('data-hidden-by-filter');
+        }
+      });
+
+      // Update the hint line.
+      var hint = document.getElementById('filter-hint');
+      if (hint) {
+        if (!active) {
+          hint.textContent = '';
+        } else {
+          hint.textContent =
+            'Showing ' + shownCount + ' of ' + totalCount +
+            ' chapters (filter: ' + selected.join(', ') + ').' +
+            ' Cross-tool chapters stay visible.';
+        }
+      }
+    }
+
+    // Apply saved filter on first load, before the island hydrates.
+    applyFilter(readSelected());
+
+    // React to subsequent changes from the ToolFilter island.
+    window.addEventListener(EVENT_NAME, function (e) {
+      var detail = e && e.detail ? e.detail : {};
+      applyFilter(Array.isArray(detail.selected) ? detail.selected : []);
+    });
+  })();
+</script>
+
+<style>
+  .chapters-index-header {
+    margin-bottom: var(--space-8);
+    border-bottom: 1px solid var(--color-border);
+    padding-bottom: var(--space-6);
+  }
+  .chapters-index-lede {
+    font-size: var(--text-lg);
+    color: var(--color-text-muted);
+    max-width: 65ch;
+  }
+  .chapters-index-cross-ref {
+    font-size: var(--text-sm);
+    color: var(--color-text-muted);
+    margin-top: var(--space-3);
+    text-indent: 0;
+  }
+
+  .part-group {
+    margin: var(--space-8) 0;
+  }
+  .part-heading {
+    font-size: var(--text-sm);
+    font-family: var(--font-code);
+    text-transform: uppercase;
+    letter-spacing: 0.08em;
+    color: var(--color-text-muted);
+    border-bottom: 1px solid var(--color-border);
+    padding-bottom: var(--space-2);
+    margin-bottom: var(--space-4);
+  }
+  .part-label {
+    font-weight: 500;
+  }
+
+  .chapter-list {
+    list-style: none;
+    padding: 0;
+    margin: 0;
+    display: grid;
+    gap: var(--space-4);
+  }
+
+  .chapter-card {
+    border: 1px solid var(--color-border);
+    border-radius: var(--radius-md);
+    background: var(--color-bg);
+    transition:
+      border-color 120ms ease,
+      background 120ms ease,
+      opacity 180ms ease,
+      max-height 220ms ease;
+    max-height: 40rem; /* ceiling for the transition; actual height is auto */
+    overflow: hidden;
+  }
+  .chapter-card:hover {
+    border-color: var(--color-link);
+    background: var(--color-bg-subtle);
+  }
+  .chapter-card-link {
+    display: block;
+    padding: var(--space-4);
+    text-decoration: none;
+    color: inherit;
+  }
+  .chapter-card-link:hover {
+    text-decoration: none;
+  }
+
+  .chapter-card-meta {
+    display: flex;
+    flex-wrap: wrap;
+    gap: var(--space-2);
+    align-items: center;
+    font-size: var(--text-sm);
+    color: var(--color-text-muted);
+    margin-bottom: var(--space-2);
+  }
+  .chapter-card-number {
+    font-family: var(--font-code);
+    font-weight: 500;
+    color: var(--color-text);
+    text-transform: uppercase;
+    letter-spacing: 0.04em;
+    font-size: var(--text-xs);
+  }
+  .chapter-card-verified {
+    font-family: var(--font-code);
+    font-size: var(--text-xs);
+  }
+
+  .chapter-card-title {
+    font-size: var(--text-lg);
+    font-weight: 500;
+    margin: 0 0 var(--space-2) 0;
+    color: var(--color-link);
+  }
+  .chapter-card-description {
+    color: var(--color-text);
+    margin: 0 0 var(--space-3) 0;
+    text-indent: 0;
+    line-height: 1.5;
+  }
+  .chapter-card-tools {
+    display: flex;
+    flex-wrap: wrap;
+    gap: var(--space-2);
+  }
+
+  /* Filter target: cards fade + collapse smoothly; full display:none
+   * kicks in after the transition so we don't keep a focusable node
+   * in the list. Part-groups collapse immediately because they're
+   * structural, not reader-facing. */
+  .chapter-card[data-hidden-by-filter='true'] {
+    opacity: 0;
+    max-height: 0;
+    margin: 0;
+    padding: 0;
+    border-width: 0;
+    pointer-events: none;
+    overflow: hidden;
+  }
+  .chapter-card[data-hidden-by-filter='true'] .chapter-card-link {
+    visibility: hidden;
+  }
+  .part-group[data-hidden-by-filter='true'] {
+    display: none;
+  }
+
+  .chapters-filter-hint {
+    font-size: var(--text-sm);
+    color: var(--color-text-muted);
+    font-style: italic;
+    margin: var(--space-2) 0 var(--space-4) 0;
+    min-height: 1.4em;
+  }
+  .chapters-filter-hint:empty {
+    margin: 0;
+    min-height: 0;
+  }
+
+  /* Print override: the filter UI doesn't exist in print (chrome is
+   * hidden), so all chapters must render regardless of any filter
+   * state left over in the viewer. */
+  @media print {
+    .chapter-card[data-hidden-by-filter='true'] {
+      opacity: 1;
+      max-height: none;
+      margin: unset;
+      padding: unset;
+      border-width: 1px;
+      pointer-events: auto;
+      overflow: visible;
+    }
+    .chapter-card[data-hidden-by-filter='true'] .chapter-card-link {
+      visibility: visible;
+    }
+    .part-group[data-hidden-by-filter='true'] {
+      display: block;
+    }
+    .chapters-filter-hint {
+      display: none;
+    }
+  }
+
+  /* Reduced-motion: skip the opacity/height transition for anyone who
+   * prefers less motion. The display change is instant either way. */
+  @media (prefers-reduced-motion: reduce) {
+    .chapter-card {
+      transition: border-color 120ms ease, background 120ms ease;
+    }
+  }
+</style>

package/pages/convergence.astro

@@ -0,0 +1,96 @@
+---
+/**
+ * /convergence — dashboard of agentic-coding patterns across tools.
+ *
+ * For each category, renders every pattern in that category as a
+ * PatternTimeline card. Categories with no patterns render an honest
+ * placeholder so readers see the coverage gaps rather than inferring
+ * the registry is exhaustive.
+ *
+ * Driven entirely from changelog/patterns.yaml + changelog/tools/*.yaml.
+ * No code change is needed to grow the dashboard — add manifest rows.
+ */
+import Base from '../layouts/Base.astro';
+import PatternTimeline from '../components/PatternTimeline.astro';
+import {
+  getPatternsByCategory,
+  CATEGORY_LABELS,
+} from '../src/lib/patterns';
+import { patternCategories } from '../content.config';
+
+const grouped = await getPatternsByCategory();
+const totalPatterns = Object.values(grouped).reduce(
+  (n, arr) => n + arr.length,
+  0,
+);
+---
+<Base
+  title="Convergence — Agentic Coding"
+  description="Which agentic-coding patterns have converged across Claude Code, Gemini CLI, and Codex CLI — and when? A live timeline driven from the changelog manifest."
+>
+  <article class="prose convergence-dashboard">
+    <header class="convergence-header">
+      <h1>Convergence dashboard</h1>
+      <p class="convergence-lede">
+        Each card below tracks one agentic-coding pattern across the
+        three primary tools. A pattern is <em>converged</em> when all
+        three tools have shipped it. The timeline shows the sequence of
+        adoptions — who first, who followed, who has not yet.
+      </p>
+      <p class="convergence-metric">
+        <strong>{totalPatterns}</strong> pattern{totalPatterns === 1 ? '' : 's'}
+        {' '}currently tracked. The registry grows as new patterns
+        converge or as historical patterns get backfilled; expect the
+        count to drift upward, not the existing entries.
+      </p>
+    </header>
+
+    {patternCategories.map((cat) => {
+      const patterns = grouped[cat];
+      return (
+        <section class="convergence-category" data-category={cat} id={`category-${cat}`}>
+          <h2 class="convergence-category-heading">
+            <span class="convergence-category-label">{CATEGORY_LABELS[cat]}</span>
+            <span class="convergence-category-count">
+              {patterns.length === 0
+                ? 'no patterns'
+                : `${patterns.length} pattern${patterns.length === 1 ? '' : 's'}`}
+            </span>
+          </h2>
+          {patterns.length === 0 ? (
+            <p class="convergence-category-empty">
+              No tracked patterns in this category yet. This is a
+              coverage gap, not an assertion that nothing belongs here.
+            </p>
+          ) : (
+            <div class="convergence-card-list">
+              {patterns.map((p) => <PatternTimeline pattern={p} />)}
+            </div>
+          )}
+        </section>
+      );
+    })}
+
+    <section class="convergence-method">
+      <h2>How to read this</h2>
+      <p>
+        The registry lives at <code>changelog/patterns.yaml</code>.
+        Each tool's adoption timeline lives at
+        <code>changelog/tools/&lt;tool&gt;.yaml</code>. The dashboard
+        joins them at build time — no code edits needed to add new
+        patterns or new adoption events.
+      </p>
+      <p>
+        A pattern with <em>convergence_date: null</em> is either a
+        partial convergence (1 or 2 of 3 tools) or an open design
+        space where the right shape is still being argued. Either
+        way, it is information worth surfacing, not hiding.
+      </p>
+      <p>
+        Coverage is intentionally sparse in the early book — the
+        registry grows organically through quarterly audit cycles.
+        Pattern nominations are welcome via Issues.
+      </p>
+    </section>
+  </article>
+</Base>

package/pages/print.astro

@@ -0,0 +1,39 @@
+---
+/**
+ * print.astro — concatenated book rendered as one long document, the
+ * input for pagedjs-cli.
+ *
+ * Walks the chapters collection in reading order, renders each chapter
+ * body, and wraps in a <section.chapter-print> so print.css can force
+ * page breaks between chapters.
+ *
+ * Build pipeline:
+ *   npm run build            → Astro emits dist/print/index.html
+ *   npm run pdf              → pagedjs-cli fetches dist/print/ via preview
+ *                              server, runs Paged.js in headless Chrome,
+ *                              outputs dist-pdf/book.pdf
+ */
+import Base from '../layouts/Base.astro';
+import { render } from 'astro:content';
+import { getAllChapters } from '../src/lib/chapters';
+import ChapterHeader from '../components/ChapterHeader.astro';
+
+const chapters = await getAllChapters();
+const rendered = await Promise.all(
+  chapters.map(async (entry) => {
+    const { Content } = await render(entry);
+    return { entry, Content };
+  })
+);
+---
+
+<Base title="Book (print edition)" description="Full book rendered as a single paginated document for PDF export.">
+  <main class="prose print-edition">
+    {rendered.map(({ entry, Content }) => (
+      <section class="chapter-print">
+        <ChapterHeader data={entry.data} />
+        <Content />
+      </section>
+    ))}
+  </main>
+</Base>

package/pages/references.astro

@@ -0,0 +1,160 @@
+---
+/**
+ * /references — the book's bibliography page.
+ *
+ * Renders every entry in src/data/references.json (produced by
+ * scripts/build-bib.mjs from guides/shared/references.bib). Each
+ * entry gets an anchor ID matching its bibkey, so `<Cite key="gu2024mamba" />`
+ * elsewhere on the site links to /references#gu2024mamba.
+ *
+ * Sorted alphabetically by first-author surname, then by year.
+ * arXiv-style notes are surfaced as direct links when present.
+ */
+import Base from '../layouts/Base.astro';
+
+type CslAuthor = { family?: string; given?: string; literal?: string };
+type CslEntry = {
+  id: string;
+  type?: string;
+  author?: CslAuthor[];
+  issued?: { 'date-parts'?: number[][] };
+  title?: string;
+  'container-title'?: string;
+  publisher?: string;
+  volume?: string;
+  issue?: string;
+  page?: string;
+  URL?: string;
+  DOI?: string;
+  note?: string;
+};
+
+// Resolve references.json from consumer's project root. Missing file -> empty
+// list (page renders an "empty bibliography" notice rather than crashing).
+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>;
+const entries = Object.values(map);
+
+const surname = (a: CslAuthor): string =>
+  (a.family ?? a.literal ?? '').toLowerCase();
+
+const firstAuthor = (e: CslEntry): string =>
+  e.author && e.author.length > 0 ? surname(e.author[0]) : '~';
+
+const year = (e: CslEntry): number =>
+  e.issued?.['date-parts']?.[0]?.[0] ?? 0;
+
+entries.sort((a, b) => {
+  const sa = firstAuthor(a);
+  const sb = firstAuthor(b);
+  if (sa !== sb) return sa < sb ? -1 : 1;
+  return year(a) - year(b);
+});
+
+function formatAuthors(authors: CslAuthor[] | undefined): string {
+  if (!authors || authors.length === 0) return '(anon)';
+  const names = authors.map((a) => {
+    const family = a.family ?? a.literal ?? '';
+    const given = a.given ? `${a.given} ` : '';
+    return `${given}${family}`.trim();
+  });
+  if (names.length === 1) return names[0];
+  if (names.length === 2) return `${names[0]} and ${names[1]}`;
+  return `${names.slice(0, -1).join(', ')}, and ${names[names.length - 1]}`;
+}
+
+// arXiv URL extraction from `note` field (existing .bib uses `note = {arXiv:2111.00396}`).
+function arxivUrl(note?: string): string | null {
+  if (!note) return null;
+  const m = note.match(/arXiv:\s*(\S+)/i);
+  return m ? `https://arxiv.org/abs/${m[1]}` : null;
+}
+---
+<Base
+  title="References — Post-Transformers"
+  description="Bibliography for the post_transformers guide, generated from guides/shared/references.bib."
+>
+  <article class="prose">
+    <header>
+      <h1>References</h1>
+      <p class="lede">
+        Every paper, book, and software citation in this guide, sorted
+        alphabetically by first-author surname. Click an entry's
+        anchor to share a deep link, or follow the arXiv / DOI / URL
+        for the source.
+      </p>
+      <p>
+        <small>
+          {entries.length} entries. Generated from
+          <code>guides/shared/references.bib</code> at build time via
+          <code>scripts/build-bib.mjs</code>.
+        </small>
+      </p>
+    </header>
+
+    <ol class="references-list">
+      {entries.map((e) => {
+        const y = year(e);
+        const arxiv = arxivUrl(e.note);
+        const primaryUrl = arxiv ?? e.URL ?? (e.DOI ? `https://doi.org/${e.DOI}` : null);
+        return (
+          <li id={e.id} class="reference-entry">
+            <span class="reference-key" aria-label="bibkey">[{e.id}]</span>
+            <span class="reference-text">
+              {formatAuthors(e.author)}
+              {y > 0 && <> ({y})</>}.
+              {' '}
+              <em>{e.title}</em>.
+              {e['container-title'] && <> {e['container-title']}.</>}
+              {e.publisher && !e['container-title'] && <> {e.publisher}.</>}
+              {e.volume && <> Vol. {e.volume}{e.issue && <>, no. {e.issue}</>}.</>}
+              {e.page && <> pp. {e.page}.</>}
+              {primaryUrl && (
+                <>
+                  {' '}
+                  <a href={primaryUrl} rel="external noopener">link</a>.
+                </>
+              )}
+            </span>
+          </li>
+        );
+      })}
+    </ol>
+  </article>
+</Base>
+
+<style>
+  .references-list {
+    list-style: none;
+    padding: 0;
+    counter-reset: ref;
+  }
+  .reference-entry {
+    margin: var(--space-3) 0;
+    padding: var(--space-2) 0 var(--space-2) var(--space-4);
+    border-left: 2px solid transparent;
+    transition: border-color 200ms ease;
+  }
+  .reference-entry:target {
+    border-left-color: var(--callout-info);
+    background: var(--warm-blue-tint);
+  }
+  .reference-key {
+    display: inline-block;
+    font-family: var(--font-code);
+    font-size: var(--text-xs);
+    color: var(--color-text-muted);
+    margin-right: var(--space-2);
+    vertical-align: baseline;
+  }
+  .reference-text {
+    line-height: var(--leading-normal);
+  }
+  .reference-text em {
+    font-style: italic;
+  }
+</style>