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

package/components/Sidebar.astro

@@ -0,0 +1,268 @@
+---
+/**
+ * Sidebar — left-pinned chapter navigation.
+ *
+ * Profile-aware: reads BOOK_PROFILE to decide how to group + sort.
+ *   academic: groups by part (foundations / ssm-core / ...), sorts by week
+ *   tools/minimal: groups by part (numeric 0-10), sorts by chapter
+ *
+ * Rendered by Base.astro when `showSidebar` is true (default).
+ * Hidden below 1024px (`@media (max-width: 64rem)` in layout.css) —
+ * mobile gets single-column chapter content with no nav (user reaches
+ * the chapter index via /chapters/).
+ *
+ * Visual: ~280px wide, sticky to top, scrollable independently of main.
+ * Site title at top doubles as a "home" link.
+ *
+ * Customize: edit the `siteTitle` / `siteSubtitle` strings below or pass
+ * them in as Astro.props from Base.astro if you want per-page overrides.
+ */
+import { getCollection } from 'astro:content';
+
+const profile = import.meta.env.BOOK_PROFILE ?? 'minimal';
+const siteTitle = 'Book';
+const siteSubtitle = 'A scaffold-astro book';
+
+// Academic profile: part is a string enum.
+const ACADEMIC_PART_ORDER = [
+  'foundations',
+  'ssm-core',
+  'beyond-ssm',
+  'integration',
+  'synthesis',
+] as const;
+const ACADEMIC_PART_LABEL: Record<string, string> = {
+  foundations: 'Part I · Foundations',
+  'ssm-core': 'Part II · SSM Core',
+  'beyond-ssm': 'Part III · Beyond SSMs',
+  integration: 'Part IV · Integration',
+  synthesis: 'Part V · Synthesis',
+};
+
+const rawChapters = await getCollection('chapters', (entry) => !entry.data.draft);
+
+// Pre-shape chapters into render-ready rows. All TS casts happen here in
+// the frontmatter so the template stays free of type annotations (Astro's
+// JSX parser mis-tokenizes `as Type<X, Y>` inside expression containers).
+interface ChapterRow {
+  id: string;
+  partKey: string;
+  prefix: string;
+  title: string;
+  sortPart: number;
+  sortRank: number;
+}
+
+function rowOf(entry: typeof rawChapters[number]): ChapterRow {
+  const d = entry.data as Record<string, unknown>;
+  if (profile === 'academic') {
+    const week = (d.week as number) ?? 0;
+    return {
+      id: entry.id,
+      partKey: (d.part as string) ?? '',
+      prefix: `W${String(week).padStart(2, '0')}`,
+      title: (d.title as string) ?? entry.id,
+      sortPart: ACADEMIC_PART_ORDER.indexOf((d.part as typeof ACADEMIC_PART_ORDER[number]) ?? 'foundations'),
+      sortRank: week,
+    };
+  }
+  const partNum = (d.part as number) ?? 0;
+  const chapter = (d.chapter as number) ?? 0;
+  return {
+    id: entry.id,
+    partKey: String(partNum),
+    prefix: `Ch${chapter}`,
+    title: (d.title as string) ?? entry.id,
+    sortPart: partNum,
+    sortRank: chapter,
+  };
+}
+
+const rows: ChapterRow[] = rawChapters.map(rowOf).sort((a, b) => {
+  if (a.sortPart !== b.sortPart) return a.sortPart - b.sortPart;
+  return a.sortRank - b.sortRank;
+});
+
+// Group rows by part. Academic profile uses the ACADEMIC_PART_ORDER as
+// the canonical key sequence so empty parts still appear (in part headers
+// rather than gaps).
+const byPart = new Map<string, ChapterRow[]>();
+if (profile === 'academic') {
+  for (const part of ACADEMIC_PART_ORDER) byPart.set(part, []);
+}
+for (const r of rows) {
+  if (!byPart.has(r.partKey)) byPart.set(r.partKey, []);
+  byPart.get(r.partKey)!.push(r);
+}
+
+const currentPath = Astro.url.pathname;
+function isCurrent(id: string): boolean {
+  return currentPath === `/chapters/${id}/` || currentPath === `/chapters/${id}`;
+}
+
+function partLabel(key: string): string {
+  if (profile === 'academic') return ACADEMIC_PART_LABEL[key] ?? key;
+  return `Part ${key}`;
+}
+---
+
+<aside class="sidebar" aria-label="Chapter navigation">
+  <div class="sidebar-inner">
+    <a href="/" class="sidebar-home">
+      <strong>{siteTitle}</strong>
+      <span class="sidebar-subtitle">{siteSubtitle}</span>
+    </a>
+
+    <nav class="sidebar-nav">
+      <a
+        href="/chapters/"
+        class={`sidebar-link sidebar-link-index ${currentPath === '/chapters/' ? 'is-current' : ''}`}
+      >
+        All chapters
+      </a>
+      {profile === 'academic' && (
+        <a
+          href="/references/"
+          class={`sidebar-link sidebar-link-index ${currentPath === '/references/' ? 'is-current' : ''}`}
+        >
+          References
+        </a>
+      )}
+
+      {Array.from(byPart.entries()).map(([part, list]) => list.length === 0 ? null : (
+        <section class="sidebar-part">
+          <h3 class="sidebar-part-heading">{partLabel(part)}</h3>
+          <ol class="sidebar-list">
+            {list.map((r) => (
+              <li>
+                <a
+                  href={`/chapters/${r.id}/`}
+                  class={`sidebar-link ${isCurrent(r.id) ? 'is-current' : ''}`}
+                >
+                  <span class="sidebar-week">{r.prefix}</span>
+                  <span class="sidebar-chapter-title">{r.title}</span>
+                </a>
+              </li>
+            ))}
+          </ol>
+        </section>
+      ))}
+    </nav>
+  </div>
+</aside>
+
+<style>
+  .sidebar {
+    grid-area: sidebar;
+    border-right: 1px solid var(--color-border);
+    background: var(--color-bg-subtle);
+    font-size: var(--text-sm);
+  }
+  .sidebar-inner {
+    position: sticky;
+    top: 0;
+    max-height: 100vh;
+    overflow-y: auto;
+    padding: var(--space-6) var(--space-4) var(--space-6) var(--space-5);
+  }
+
+  .sidebar-home {
+    display: block;
+    text-decoration: none;
+    color: inherit;
+    margin-bottom: var(--space-5);
+    line-height: 1.3;
+  }
+  .sidebar-home strong {
+    display: block;
+    font-size: var(--text-base);
+    color: var(--color-heading);
+  }
+  .sidebar-home .sidebar-subtitle {
+    display: block;
+    font-size: var(--text-xs);
+    color: var(--color-text-muted);
+    margin-top: 0.15em;
+  }
+
+  .sidebar-nav {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-4);
+  }
+
+  .sidebar-link-index {
+    display: block;
+    padding: var(--space-2) var(--space-3);
+    border-radius: var(--radius-sm);
+    text-decoration: none;
+    color: var(--color-text);
+    font-weight: 500;
+    margin-bottom: 1px;
+    border-left: 2px solid transparent;
+  }
+  .sidebar-link-index:hover {
+    background: var(--color-bg);
+  }
+  .sidebar-link-index.is-current {
+    background: var(--warm-blue-tint);
+    border-left-color: var(--callout-info);
+  }
+
+  .sidebar-part {
+    border-top: 1px solid var(--color-border);
+    padding-top: var(--space-3);
+  }
+  .sidebar-part:first-of-type {
+    border-top: 0;
+    padding-top: 0;
+  }
+  .sidebar-part-heading {
+    font-family: var(--font-code);
+    font-size: var(--text-xs);
+    text-transform: uppercase;
+    letter-spacing: 0.04em;
+    color: var(--color-text-muted);
+    margin: 0 0 var(--space-2) 0;
+    padding: 0 var(--space-3);
+  }
+
+  .sidebar-list {
+    list-style: none;
+    padding: 0;
+    margin: 0;
+  }
+  .sidebar-list li {
+    margin: 0;
+  }
+  .sidebar-link {
+    display: grid;
+    grid-template-columns: 2.4em 1fr;
+    gap: var(--space-2);
+    align-items: baseline;
+    padding: var(--space-2) var(--space-3);
+    border-radius: var(--radius-sm);
+    text-decoration: none;
+    color: var(--color-text);
+    line-height: var(--leading-normal);
+    border-left: 2px solid transparent;
+  }
+  .sidebar-link:hover {
+    background: var(--color-bg);
+    text-decoration: none;
+  }
+  .sidebar-link.is-current {
+    background: var(--warm-blue-tint);
+    border-left-color: var(--callout-info);
+    font-weight: 500;
+  }
+  .sidebar-week {
+    font-family: var(--font-code);
+    font-size: var(--text-xs);
+    color: var(--color-text-muted);
+    text-transform: uppercase;
+  }
+  .sidebar-chapter-title {
+    color: inherit;
+  }
+</style>

package/components/Sidenote.astro

@@ -0,0 +1,26 @@
+---
+/**
+ * Sidenote — a marginalia note that appears in the right margin on
+ * desktop and as an inline-flow aside on mobile. Auto-numbered via CSS
+ * counters (.prose counter-resets, marker increments).
+ *
+ * Per Q6 in the plan: never hidden, never tap-to-reveal. The only
+ * thing that changes across breakpoints is where the note sits.
+ *
+ * Usage (inline within a paragraph):
+ *   <p>
+ *     The argument<Sidenote>supporting evidence here</Sidenote>
+ *     convinced me.
+ *   </p>
+ *
+ * Rendered HTML structure:
+ *   <sup class="sidenote-marker"></sup>      ← the numeric marker
+ *   <span class="sidenote">content</span>    ← the note itself
+ *
+ * The <span> (not <aside>) is deliberate: keeps HTML valid inside
+ * <p> and naturally wraps. Role="note" + .sidenote::before
+ * rendering the number give assistive tech the right semantics.
+ */
+---
+<sup class="sidenote-marker" aria-hidden="true"></sup>
+<span class="sidenote" role="note"><slot /></span>

package/components/SkillBox.astro

@@ -0,0 +1,24 @@
+---
+/**
+ * SkillBox — tactical how-to. Bounded, practitioner-oriented.
+ *
+ * Used when a chapter teaches a concrete technique: "How to warm the
+ * cache before a long session", "How to audit CLAUDE.md bloat", etc.
+ * Deliberately narrower than the surrounding prose — a skill box is a
+ * recipe, not a principle.
+ *
+ * Usage:
+ *   <SkillBox title="Warm-cache workflow">
+ *     1. Run `/context` to see current budget.
+ *     2. ...
+ *   </SkillBox>
+ */
+interface Props {
+  title: string;
+}
+const { title } = Astro.props;
+---
+<aside class="callout callout-skill" role="note" aria-label={`Skill: ${title}`}>
+  <strong class="callout-title">Skill · {title}</strong>
+  <div class="callout-body"><slot /></div>
+</aside>

package/components/SourceArchive.astro

@@ -0,0 +1,285 @@
+---
+/**
+ * SourceArchive — renders every entry in sources/manifest.yaml grouped
+ * by tier in descending authority (T1 → T4).
+ *
+ * Used from Appendix D (`d-source-archive-index.mdx`) to replace the
+ * static hand-maintained listing with an auto-generated view that
+ * always reflects the manifest.
+ *
+ * Empty-tier behavior: renders an honest placeholder ("No sources at
+ * this tier yet.") rather than hiding the section. This matches the
+ * pedagogy of Appendix D — the archive is intentionally sparse in the
+ * early book, and the gap is visible by design.
+ */
+import { sourceTiers } from '../content.config';
+import {
+  getSourcesByTier,
+  TIER_LABELS,
+  TIER_DESCRIPTIONS,
+} from '../src/lib/sources';
+
+const grouped = await getSourcesByTier();
+
+function formatDate(d: Date | undefined): string {
+  if (!d) return '—';
+  return d.toISOString().slice(0, 10);
+}
+
+function year(d: Date | undefined): string | null {
+  if (!d) return null;
+  return String(d.getUTCFullYear());
+}
+---
+<section class="source-archive" aria-label="Source archive">
+  {sourceTiers.map((tier) => {
+    const entries = grouped[tier];
+    const empty = entries.length === 0;
+    return (
+      <section
+        class="source-archive-tier"
+        data-tier={tier}
+        id={`tier-${tier}`}
+      >
+        <header class="source-archive-tier-header">
+          <h3 class="source-archive-tier-label">
+            <span class={`tier-badge tier-${tier}`}>{TIER_LABELS[tier]}</span>
+            <span class="source-archive-tier-count">
+              {empty ? 'no entries yet' : `${entries.length} entr${entries.length === 1 ? 'y' : 'ies'}`}
+            </span>
+          </h3>
+          <p class="source-archive-tier-description">{TIER_DESCRIPTIONS[tier]}</p>
+        </header>
+
+        {empty ? (
+          <p class="source-archive-empty">
+            No sources at this tier yet. Appendix D is intentionally sparse in the early book; this slot fills as chapters leave draft.
+          </p>
+        ) : (
+          <ol
+            class="source-archive-list"
+            role="list"
+            aria-label={`${TIER_LABELS[tier]} sources`}
+          >
+            {entries.map((entry) => {
+              const d = entry.data;
+              return (
+                <li class="source-archive-entry" id={`source-${entry.id}`}>
+                  <div class="source-archive-entry-title">
+                    <a href={d.url} rel="external noopener">{d.title}</a>
+                  </div>
+                  <div class="source-archive-entry-meta">
+                    {d.author && (
+                      <span class="source-archive-entry-author">{d.author}</span>
+                    )}
+                    {year(d.publish_date) && (
+                      <span class="source-archive-entry-year">{year(d.publish_date)}</span>
+                    )}
+                    <span class="source-archive-entry-captured">
+                      captured {formatDate(d.captured_at)}
+                    </span>
+                    <span class="source-archive-entry-tool">tool: {d.tool}</span>
+                  </div>
+                  <div class="source-archive-entry-links">
+                    <a href={d.url} rel="external noopener" class="source-archive-link">original</a>
+                    {d.perma_cc && (
+                      <a href={d.perma_cc} rel="external noopener" class="source-archive-link">archived (Perma.cc)</a>
+                    )}
+                    <code class="source-archive-slug">id: {entry.id}</code>
+                  </div>
+                </li>
+              );
+            })}
+          </ol>
+        )}
+      </section>
+    );
+  })}
+</section>
+
+<style>
+  .source-archive {
+    margin: var(--space-6) 0;
+  }
+  .source-archive-tier {
+    margin: var(--space-6) 0;
+    padding-bottom: var(--space-4);
+    border-bottom: 1px solid var(--color-border);
+  }
+  .source-archive-tier:last-child {
+    border-bottom: none;
+  }
+
+  .source-archive-tier-header {
+    margin-bottom: var(--space-3);
+  }
+  .source-archive-tier-label {
+    display: flex;
+    align-items: baseline;
+    gap: var(--space-3);
+    margin: 0 0 var(--space-2) 0;
+    font-size: var(--text-lg);
+  }
+  .source-archive-tier-count {
+    font-family: var(--font-code);
+    font-size: var(--text-sm);
+    color: var(--color-text-muted);
+    font-weight: 400;
+  }
+  .source-archive-tier-description {
+    margin: 0;
+    font-size: var(--text-sm);
+    color: var(--color-text-muted);
+    text-indent: 0;
+  }
+
+  /* Tier badges: muted palette, rendered at the heading level.
+   * Follows the citation-tier visual language so the archive and
+   * inline citations feel like the same system. */
+  .tier-badge {
+    display: inline-block;
+    padding: 0.1em 0.55em;
+    font-family: var(--font-code);
+    font-size: 0.8em;
+    font-weight: 500;
+    letter-spacing: 0.05em;
+    border-radius: var(--radius-sm);
+    border: 1px solid var(--color-border);
+    background: var(--color-bg);
+    color: var(--color-text);
+  }
+  .tier-T1-official {
+    background: var(--warm-plum-tint);
+    color: var(--warm-plum);
+    border-color: var(--warm-plum);
+  }
+  .tier-T2-release-notes {
+    background: var(--warm-blue-tint);
+    color: var(--warm-blue);
+    border-color: var(--warm-blue);
+  }
+  .tier-T3-practitioner {
+    background: var(--warm-green-tint);
+    color: var(--warm-green);
+    border-color: var(--warm-green);
+  }
+  .tier-T4-conjecture {
+    background: var(--warm-rose-tint);
+    color: var(--warm-rose);
+    border-color: var(--warm-rose);
+  }
+
+  .source-archive-empty {
+    color: var(--color-text-muted);
+    font-style: italic;
+    padding: var(--space-3);
+    background: var(--color-bg-subtle);
+    border-radius: var(--radius-sm);
+    text-indent: 0;
+  }
+
+  .source-archive-list {
+    list-style: none;
+    padding: 0;
+    margin: 0;
+    display: grid;
+    gap: var(--space-3);
+  }
+  .source-archive-entry {
+    padding: var(--space-3);
+    border: 1px solid var(--color-border);
+    border-radius: var(--radius-md);
+    background: var(--color-bg);
+    scroll-margin-top: var(--space-6); /* anchor targets clear of fixed chrome */
+    transition: border-color 120ms ease, background 120ms ease;
+  }
+  .source-archive-entry:hover {
+    border-color: var(--color-link);
+  }
+  .source-archive-entry:target {
+    border-color: var(--warm-blue);
+    background: var(--warm-blue-tint);
+  }
+  .source-archive-entry-title {
+    font-size: var(--text-lg);
+    font-weight: 500;
+    margin-bottom: var(--space-1);
+  }
+  .source-archive-entry-title a {
+    color: var(--color-link);
+    text-decoration: none;
+  }
+  .source-archive-entry-title a:hover {
+    text-decoration: underline;
+  }
+  .source-archive-entry-meta {
+    display: flex;
+    flex-wrap: wrap;
+    gap: var(--space-3);
+    font-size: var(--text-sm);
+    color: var(--color-text-muted);
+    font-family: var(--font-code);
+    margin-bottom: var(--space-2);
+  }
+  .source-archive-entry-author {
+    color: var(--color-text);
+  }
+  .source-archive-entry-links {
+    display: flex;
+    flex-wrap: wrap;
+    gap: var(--space-3);
+    align-items: center;
+    font-size: var(--text-sm);
+  }
+  .source-archive-link {
+    color: var(--color-link);
+  }
+  .source-archive-slug {
+    font-family: var(--font-code);
+    font-size: var(--text-xs);
+    color: var(--color-text-muted);
+    background: var(--color-bg-subtle);
+    padding: 0.1em 0.4em;
+    border-radius: var(--radius-sm);
+    border: 0;
+  }
+
+  @media (max-width: 48rem) {
+    .source-archive-tier-label {
+      flex-direction: column;
+      align-items: flex-start;
+      gap: var(--space-1);
+    }
+    .source-archive-entry-meta,
+    .source-archive-entry-links {
+      gap: var(--space-2);
+    }
+  }
+
+  /* Long URLs in the slug or author line can force horizontal scroll
+   * on narrow viewports. Let them wrap anywhere. */
+  .source-archive-entry a,
+  .source-archive-slug {
+    word-break: break-word;
+    overflow-wrap: anywhere;
+  }
+
+  /* Print: borders soften, hover/target highlighting off, slug code
+   * visible (readers of the printed edition still need the citation
+   * key to cross-reference chapters). */
+  @media print {
+    .source-archive-entry {
+      border-width: 0.5pt;
+      border-color: #aaa;
+      background: transparent !important;
+      break-inside: avoid;
+    }
+    .source-archive-entry:target {
+      background: transparent !important;
+      border-color: #aaa !important;
+    }
+    .source-archive-tier {
+      break-inside: avoid;
+    }
+  }
+</style>

package/components/StatusBadge.astro

@@ -0,0 +1,51 @@
+---
+/**
+ * StatusBadge — translates the internal 7-state taxonomy from
+ * docs/STATUS.md into a simplified 3-state public label.
+ *
+ * Public mapping (locked in plan Q4):
+ *   Published   = implemented | chapter_only | prose_only | reading_only
+ *   Draft       = code_only
+ *   Coming Soon = scaffolded  | planned
+ *
+ * Internal frontmatter retains the 7-state value for STATUS.md alignment;
+ * this component is the public-facing translator.
+ */
+type InternalStatus =
+  | 'implemented'
+  | 'chapter_only'
+  | 'reading_only'
+  | 'prose_only'
+  | 'code_only'
+  | 'scaffolded'
+  | 'planned';
+
+type PublicStatus = 'published' | 'draft' | 'coming-soon';
+
+const PUBLIC_OF: Record<InternalStatus, PublicStatus> = {
+  implemented: 'published',
+  chapter_only: 'published',
+  reading_only: 'published',
+  prose_only: 'published',
+  code_only: 'draft',
+  scaffolded: 'coming-soon',
+  planned: 'coming-soon',
+};
+
+const PUBLIC_LABEL: Record<PublicStatus, string> = {
+  published: 'Published',
+  draft: 'Draft',
+  'coming-soon': 'Coming Soon',
+};
+
+interface Props {
+  status: InternalStatus;
+}
+
+const { status } = Astro.props;
+const publicStatus = PUBLIC_OF[status];
+const label = PUBLIC_LABEL[publicStatus];
+---
+<span class="status-badge" data-status={publicStatus} title={`Internal: ${status}`}>
+  {label}
+</span>