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

package/components/CodeRef.astro

@@ -0,0 +1,49 @@
+---
+/**
+ * CodeRef — inline reference to a specific file (and optional line range)
+ * in the post_transformers repo on GitHub.
+ *
+ * Maps the LaTeX `\code{path:N}` and `\path{path}` idioms (which only
+ * styled monospace text) to a real hyperlink that lands the reader on
+ * the right line.
+ *
+ * Usage:
+ *   The discretization is implemented in
+ *   <CodeRef path="experiments/jax/week04/s4_hippo.py" line={42}>
+ *     <code>s4_hippo.py:42</code>
+ *   </CodeRef>.
+ *
+ *   Line range:
+ *   See <CodeRef path="experiments/jax/week04/s4_hippo.py" line={42} lineEnd={58}>
+ *     the ZOH discretization block
+ *   </CodeRef>.
+ *
+ *   Bare path (no line):
+ *   The full module lives at <CodeRef path="experiments/jax/week04/s4_hippo.py" />.
+ *
+ * The slot's content is rendered as the link text; if no slot content
+ * is given, a sensible default (the file basename plus line range) is
+ * synthesized.
+ */
+import { buildGithubUrl } from '../src/lib/repo-url';
+
+interface Props {
+  path: string;
+  line?: number;
+  lineEnd?: number;
+}
+
+const { path, line, lineEnd } = Astro.props;
+const url = buildGithubUrl(path, line, lineEnd);
+const hasSlot = await Astro.slots.has('default');
+const basename = path.split('/').pop() ?? path;
+const defaultText =
+  line === undefined
+    ? basename
+    : lineEnd === undefined
+      ? `${basename}:${line}`
+      : `${basename}:${line}-${lineEnd}`;
+---
+<a href={url} rel="external noopener" class="code-ref">
+  {hasSlot ? <slot /> : <code>{defaultText}</code>}
+</a>

package/components/ConceptBox.astro

@@ -0,0 +1,26 @@
+---
+/**
+ * ConceptBox — durable vocabulary / definition. The textbook definition
+ * slot. Used when a term first appears and needs a precise fix.
+ *
+ * The `term` prop is the defined word/phrase and renders in the title;
+ * the body is the definition. By convention, definitions stay in
+ * Representation sections of a chapter (per the Koller-Friedman
+ * decomposition).
+ *
+ * Usage:
+ *   <ConceptBox term="Context rot">
+ *     The degradation of agent output quality as the KV-cache fills,
+ *     observable as drift, loss of early-context references, or
+ *     incoherent code.
+ *   </ConceptBox>
+ */
+interface Props {
+  term: string;
+}
+const { term } = Astro.props;
+---
+<aside class="callout callout-concept" role="note" aria-label={`Concept: ${term}`}>
+  <strong class="callout-title">Concept · {term}</strong>
+  <div class="callout-body"><slot /></div>
+</aside>

package/components/Convergence.astro

@@ -0,0 +1,41 @@
+---
+/**
+ * Convergence — where two or more tools have landed on the same
+ * pattern. Signals: stable principle for the next ~3 years (unless a
+ * new tool paradigm appears).
+ *
+ * Pedagogically central: the KF Evolution cornerstone of every chapter
+ * uses Convergence + Divergence to surface how agentic practices are
+ * solidifying. A convergence box reads as "it is safe to bet on this."
+ *
+ * Props:
+ *   tools — optional array of tool slugs to display as inline badges.
+ *           Omit for a narrative-only convergence (e.g. "On session
+ *           ergonomics, all mainstream CLIs converged by late 2025.")
+ *
+ * Usage:
+ *   <Convergence tools={['claude-code', 'gemini-cli', 'codex-cli']}>
+ *     All three now treat context as a budgeted, decaying resource
+ *     and ship an explicit compaction command.
+ *   </Convergence>
+ */
+import { toolSlugs } from '../src/schemas.js';
+
+type ToolSlug = typeof toolSlugs[number];
+interface Props {
+  tools?: ToolSlug[];
+}
+
+const { tools = [] } = Astro.props;
+---
+<aside class="callout callout-convergence" role="note" aria-label="Convergence">
+  <strong class="callout-title">
+    Convergence
+    {tools.length > 0 && (
+      <span class="tool-badges">
+        {tools.map((t) => <span class="tool-badge">{t}</span>)}
+      </span>
+    )}
+  </strong>
+  <div class="callout-body"><slot /></div>
+</aside>

package/components/CounterBox.astro

@@ -0,0 +1,15 @@
+---
+/**
+ * CounterBox — maps to LaTeX `counterbox` env.
+ * Default use: counter-evidence to the dominant view, limitations of cited claims.
+ * Family: rose (warn).
+ */
+interface Props {
+  title?: string;
+}
+const { title = 'Counter-evidence' } = Astro.props;
+---
+<aside class="callout callout-counter" role="note">
+  <strong class="callout-title">{title}</strong>
+  <div class="callout-body"><slot /></div>
+</aside>

package/components/Divergence.astro

@@ -0,0 +1,32 @@
+---
+/**
+ * Divergence — where tools have NOT converged on a pattern. Signals:
+ * open design space; the choice is still live; practices may shift.
+ *
+ * Same color family as Convergence (gold = insight) but with a dashed
+ * left-bar as the visual signal of instability. Readers should
+ * calibrate confidence accordingly: a Divergence box says "the tradeoff
+ * is still being worked out."
+ *
+ * Props:
+ *   axis — the dimension on which tools differ (e.g. "window size",
+ *          "hook timing", "delegation granularity"). Required — a
+ *          divergence without a named axis is just hand-waving.
+ *
+ * Usage:
+ *   <Divergence axis="window size">
+ *     Claude: 200K · Gemini: 1M · Codex: 128K. The tradeoff between
+ *     retrieval accuracy and ceiling is not settled.
+ *   </Divergence>
+ */
+interface Props {
+  axis: string;
+}
+const { axis } = Astro.props;
+---
+<aside class="callout callout-divergence" role="note" aria-label={`Divergence: ${axis}`}>
+  <strong class="callout-title">
+    Divergence <span class="divergence-axis">· {axis}</span>
+  </strong>
+  <div class="callout-body"><slot /></div>
+</aside>

package/components/DynConnect.astro

@@ -0,0 +1,15 @@
+---
+/**
+ * DynConnect — maps to LaTeX `dynconnect` env.
+ * Default use: dynamical-systems / PhD-bridge connections to the SSM material.
+ * Family: blue accent (info).
+ */
+interface Props {
+  title?: string;
+}
+const { title = 'Dynamical Systems Connection' } = Astro.props;
+---
+<aside class="callout callout-dynconnect" role="note">
+  <strong class="callout-title">{title}</strong>
+  <div class="callout-body"><slot /></div>
+</aside>

package/components/ExampleBox.astro

@@ -0,0 +1,15 @@
+---
+/**
+ * ExampleBox — maps to LaTeX `examplebox` env.
+ * Default use: extended multi-paragraph walkthroughs.
+ * Family: blue accent (info).
+ */
+interface Props {
+  title?: string;
+}
+const { title = 'Example' } = Astro.props;
+---
+<aside class="callout callout-example" role="note">
+  <strong class="callout-title">{title}</strong>
+  <div class="callout-body"><slot /></div>
+</aside>

package/components/Figure.astro

@@ -0,0 +1,35 @@
+---
+/**
+ * Figure — replaces LaTeX `\includegraphics{...}` + `\caption{...}` +
+ * `\label{...}` pattern with a single component.
+ *
+ * Source assets are emitted under public/figures/weekNN/ by
+ * scripts/build-figures.sh (Phase 2.4); src paths are absolute from
+ * site root.
+ *
+ * Usage:
+ *   <Figure
+ *     src="/figures/week04/ex2_hippo_eigenvalues.svg"
+ *     caption="HiPPO-LegS eigenvalue structure for N = 16 and N = 64."
+ *     width="100%"
+ *     id="w4-fig-hippo-eigenvalues"
+ *   />
+ *
+ * The id prop registers the figure with the cross-reference label map
+ * (consumed by `<XRef>`).
+ */
+interface Props {
+  src: string;
+  caption?: string;
+  width?: string;
+  id?: string;
+  alt?: string;
+}
+
+const { src, caption, width = '100%', id, alt } = Astro.props;
+const altText = alt ?? caption ?? '';
+---
+<figure class="figure" id={id}>
+  <img src={src} alt={altText} style={`width: ${width}; max-width: 100%;`} />
+  {caption && <figcaption>{caption}</figcaption>}
+</figure>

package/components/InsightBox.astro

@@ -0,0 +1,15 @@
+---
+/**
+ * InsightBox — maps to LaTeX `insightbox` env.
+ * Default use: non-obvious observations, surprising properties.
+ * Family: gold (insight).
+ */
+interface Props {
+  title?: string;
+}
+const { title = 'Insight' } = Astro.props;
+---
+<aside class="callout callout-insight" role="note">
+  <strong class="callout-title">{title}</strong>
+  <div class="callout-body"><slot /></div>
+</aside>

package/components/KeyIdea.astro

@@ -0,0 +1,21 @@
+---
+/**
+ * KeyIdea — crystallized takeaway. "Memorize this." Carries over from
+ * the LaTeX book's \keybox: thicker left-bar as a visual signal that
+ * the content is high-density.
+ *
+ * Used sparingly — perhaps 1–2 per chapter. If every third paragraph
+ * has a KeyIdea, nothing is a key idea. Place at the end of a section
+ * where an argument resolves to something retention-worthy.
+ *
+ * Usage:
+ *   <KeyIdea>
+ *     Context is a budget, not an infinity. Treat it like a finite
+ *     resource: account for it, spend it deliberately, reclaim it.
+ *   </KeyIdea>
+ */
+---
+<aside class="callout callout-key" role="note" aria-label="Key idea">
+  <strong class="callout-title">Key idea</strong>
+  <div class="callout-body"><slot /></div>
+</aside>

package/components/MarginNote.astro

@@ -0,0 +1,37 @@
+---
+/**
+ * MarginNote — short variant of Sidenote with semantic coloring.
+ *
+ * Maps the three LaTeX margin-callout commands:
+ *   \marginnotebox[title]{body}   → variant="note"    (blue)
+ *   \marginwarning[title]{body}   → variant="warning" (rose)
+ *   \margintip[title]{body}       → variant="tip"     (green)
+ *
+ * Per STANDARDS.md margin notes are capped at 25 words — enforce in
+ * the validator (Phase 2.6); not enforced here at runtime.
+ *
+ * Unlike Sidenote (which floats into the page margin on desktop),
+ * MarginNote always renders inline with the surrounding prose as a
+ * colored aside. Use Sidenote when the note is footnote-like and
+ * should not interrupt the line; use MarginNote when the note is
+ * load-bearing and the reader must see it.
+ */
+type Variant = 'note' | 'warning' | 'tip';
+
+interface Props {
+  variant?: Variant;
+  label?: string;
+}
+
+const { variant = 'note', label } = Astro.props;
+const VARIANT_DEFAULT_LABEL: Record<Variant, string> = {
+  note: 'Note',
+  warning: 'Caveat',
+  tip: 'Tip',
+};
+const displayLabel = label ?? VARIANT_DEFAULT_LABEL[variant];
+---
+<aside class="margin-note" data-variant={variant} role="note">
+  <span class="margin-note-label">[{displayLabel}]</span>
+  <slot />
+</aside>

package/components/NoteBox.astro

@@ -0,0 +1,15 @@
+---
+/**
+ * NoteBox — maps to LaTeX `notebox` env.
+ * Default use: chapter overviews, neutral info, learning objectives.
+ * Family: blue accent (info).
+ */
+interface Props {
+  title?: string;
+}
+const { title = 'Note' } = Astro.props;
+---
+<aside class="callout callout-note" role="note">
+  <strong class="callout-title">{title}</strong>
+  <div class="callout-body"><slot /></div>
+</aside>

package/components/OpenQuestion.astro

@@ -0,0 +1,15 @@
+---
+/**
+ * OpenQuestion — maps to LaTeX `openquestion` env.
+ * Default use: research questions still open at time of writing.
+ * Family: plum (authority).
+ */
+interface Props {
+  title?: string;
+}
+const { title = 'Open Question' } = Astro.props;
+---
+<aside class="callout callout-openquestion" role="note">
+  <strong class="callout-title">{title}</strong>
+  <div class="callout-body"><slot /></div>
+</aside>

package/components/PaperBox.astro

@@ -0,0 +1,15 @@
+---
+/**
+ * PaperBox — maps to LaTeX `paperbox` env.
+ * Default use: contextual restatement of a cited paper's claim.
+ * Family: gray (neutral, dashed border to signal external source).
+ */
+interface Props {
+  title?: string;
+}
+const { title = 'From the literature' } = Astro.props;
+---
+<aside class="callout callout-paper" role="note">
+  <strong class="callout-title">{title}</strong>
+  <div class="callout-body"><slot /></div>
+</aside>

package/components/PatternTimeline.astro

@@ -0,0 +1,133 @@
+---
+/**
+ * PatternTimeline — one card per pattern on the convergence dashboard.
+ *
+ * Renders:
+ *   - Header: pattern name, category, convergence badge (date or "not
+ *     yet converged"), adoption count "N of 3 tools".
+ *   - Description paragraph.
+ *   - 3 horizontal tool tracks (claude-code / gemini-cli / codex-cli).
+ *     Adoption events render as dots positioned along a shared time
+ *     axis (earliest → latest event in this pattern's timeline).
+ *   - Empty state when no tool has adopted the pattern yet.
+ *
+ * Dots carry their metadata in title= attributes so hover in any
+ * browser shows the full note without extra tooltip infrastructure.
+ *
+ * Props:
+ *   pattern — the PatternEntry from getAllPatterns().
+ */
+import type { PatternEntry } from '../src/lib/patterns';
+import {
+  getPatternTimeline,
+  toolsInTimeline,
+  TIMELINE_TOOL_ORDER,
+  CATEGORY_LABELS,
+} from '../src/lib/patterns';
+
+interface Props {
+  pattern: PatternEntry;
+}
+const { pattern } = Astro.props;
+const data = pattern.data;
+
+const timeline = await getPatternTimeline(pattern.id);
+const adopters = toolsInTimeline(timeline);
+
+function formatDate(d: Date): string {
+  return d.toISOString().slice(0, 10);
+}
+
+// Compute position along the shared time axis. A single-event pattern
+// centers its dot at 50%. No events → no axis computed.
+const times = timeline.map((t) => t.date.getTime());
+const minTime = times.length > 0 ? Math.min(...times) : 0;
+const maxTime = times.length > 0 ? Math.max(...times) : 0;
+const span = maxTime - minTime;
+
+function positionPct(date: Date): number {
+  if (span <= 0) return 50;
+  return ((date.getTime() - minTime) / span) * 100;
+}
+
+const converged = data.convergence_date != null;
+const category = data.category ?? 'other';
+---
+<article class="pattern-card" data-pattern={pattern.id}>
+  <header class="pattern-card-header">
+    <div class="pattern-card-title-row">
+      <h3 class="pattern-card-title">{data.name}</h3>
+      <span
+        class={`pattern-category-badge pattern-category-${category}`}
+        title={`Category: ${CATEGORY_LABELS[category]}`}
+      >{CATEGORY_LABELS[category]}</span>
+    </div>
+    <div class="pattern-card-meta">
+      {converged ? (
+        <span class="pattern-convergence-badge converged" title="All tracked tools have adopted">
+          Converged {formatDate(data.convergence_date as Date)}
+        </span>
+      ) : (
+        <span class="pattern-convergence-badge not-converged">
+          Not yet converged
+        </span>
+      )}
+      <span class="pattern-adoption-count">
+        {adopters.length} of {TIMELINE_TOOL_ORDER.length} tools
+      </span>
+    </div>
+  </header>
+
+  {data.description && (
+    <p class="pattern-description">{data.description}</p>
+  )}
+
+  {timeline.length === 0 ? (
+    <p class="pattern-empty-timeline">
+      No tool has adopted this pattern yet (or no data captured).
+    </p>
+  ) : (
+    <div
+      class="pattern-timeline"
+      role="img"
+      aria-label={`Adoption timeline: ${timeline.length} event${timeline.length === 1 ? '' : 's'} across ${adopters.length} of ${TIMELINE_TOOL_ORDER.length} tools.`}
+    >
+      {TIMELINE_TOOL_ORDER.map((tool) => {
+        const events = timeline.filter((e) => e.tool === tool);
+        const adopted = events.length > 0;
+        return (
+          <div
+            class="pattern-timeline-track"
+            data-tool={tool}
+            data-adopted={adopted ? 'true' : 'false'}
+          >
+            <span class="pattern-timeline-tool-label">{tool}</span>
+            <div class="pattern-timeline-rail">
+              {!adopted && (
+                <span class="pattern-timeline-not-yet">not yet</span>
+              )}
+              {events.map((e) => (
+                <span
+                  class="pattern-timeline-dot"
+                  data-kind={e.kind}
+                  style={`left: ${positionPct(e.date)}%`}
+                  title={`${tool} ${e.version} (${formatDate(e.date)}): ${e.note}`}
+                >
+                  <span class="pattern-timeline-dot-label" aria-hidden="true">
+                    v{e.version}
+                  </span>
+                </span>
+              ))}
+            </div>
+          </div>
+        );
+      })}
+      <div class="pattern-timeline-axis">
+        <span class="pattern-timeline-axis-start">{formatDate(new Date(minTime))}</span>
+        {span > 0 && (
+          <span class="pattern-timeline-axis-end">{formatDate(new Date(maxTime))}</span>
+        )}
+      </div>
+    </div>
+  )}
+</article>

package/components/Recovery.astro

@@ -0,0 +1,34 @@
+---
+/**
+ * Recovery — escape route from a named anti-pattern. Structured as
+ * (pattern name, symptom, escape). Pairs with the anti-pattern
+ * chapters; provides actionable recovery when readers recognize they
+ * are in the failure mode.
+ *
+ * Matches the LaTeX book's \recovery{pattern}{symptom}{escape} command
+ * (see claude-best-practices.sty). Symptom is optional; escape can be
+ * the body slot for longer explanations.
+ *
+ * Usage:
+ *   <Recovery
+ *     pattern="CLAUDE.md bloat"
+ *     symptom="Compaction triggers every 3 turns; new features land
+ *              with context rot."
+ *   >
+ *     Split CLAUDE.md into hub-and-spoke. Move project specifics to
+ *     `.claude/rules/*.md` with path-scoped loading. Keep hub under 200 lines.
+ *   </Recovery>
+ */
+interface Props {
+  pattern: string;
+  symptom?: string;
+}
+const { pattern, symptom } = Astro.props;
+---
+<aside class="callout callout-recovery" role="note" aria-label={`Recovery: ${pattern}`}>
+  <strong class="callout-title">Recovery · {pattern}</strong>
+  {symptom && (
+    <p class="recovery-symptom"><strong>Symptom:</strong> {symptom}</p>
+  )}
+  <div class="callout-body"><slot /></div>
+</aside>

package/components/ResultBox.astro

@@ -0,0 +1,15 @@
+---
+/**
+ * ResultBox — maps to LaTeX `resultbox` env.
+ * Default use: author's own experimental findings, key takeaways from a chapter's code.
+ * Family: green (tip / positive).
+ */
+interface Props {
+  title?: string;
+}
+const { title = 'Result' } = Astro.props;
+---
+<aside class="callout callout-result" role="note">
+  <strong class="callout-title">{title}</strong>
+  <div class="callout-body"><slot /></div>
+</aside>