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

package/components/Tag.astro

@@ -0,0 +1,60 @@
+---
+/**
+ * Tag — inline practice tag that flags the provenance of a stated claim.
+ *
+ * Maps LaTeX `\tagofficial{}`, `\tagpractitioner{}`, `\tagconv{}` which are
+ * placed immediately after a claim to flag its trust level:
+ *
+ *   official       Vendor / paper / canonical reference. Pair with \cite{...}.
+ *   practitioner   Repo lore or one-shop convention. Useful but not load-bearing.
+ *   convergence    >=2 independent implementations agree. Stronger than practitioner,
+ *                  weaker than official.
+ *
+ * Usage:
+ *   S4D-Lin is the default initialization <Tag kind="convergence" />
+ *   in the S4D, S5, and mamba-minimal reference codebases.
+ */
+type Kind = 'official' | 'practitioner' | 'convergence';
+
+interface Props {
+  kind: Kind;
+}
+
+const { kind } = Astro.props;
+
+const LABEL: Record<Kind, string> = {
+  official: 'Official',
+  practitioner: 'Practitioner',
+  convergence: 'Convergence',
+};
+
+const TITLE: Record<Kind, string> = {
+  official: 'Vendor or canonical reference — paired with a citation',
+  practitioner: 'Repo lore or single-shop convention — not load-bearing',
+  convergence: 'Two or more independent implementations agree',
+};
+---
+<span class="practice-tag" data-kind={kind} title={TITLE[kind]}>
+  [{LABEL[kind]}]
+</span>
+
+<style>
+  .practice-tag {
+    display: inline-block;
+    font-family: var(--font-code);
+    font-size: 0.75em;
+    font-weight: 500;
+    padding: 0 0.4em;
+    margin: 0 0.1em;
+    border-radius: var(--radius-sm);
+    background: var(--color-bg-subtle);
+    border: 1px solid var(--color-border);
+    color: var(--color-text-muted);
+    vertical-align: 0.1em;
+    letter-spacing: 0.04em;
+    text-transform: uppercase;
+  }
+  .practice-tag[data-kind="official"]    { border-color: var(--callout-official); color: var(--callout-official); }
+  .practice-tag[data-kind="convergence"] { border-color: var(--callout-insight); color: var(--callout-insight); }
+  .practice-tag[data-kind="practitioner"] { border-color: var(--callout-tip); color: var(--callout-tip); }
+</style>

package/components/Theorem.astro

@@ -0,0 +1,65 @@
+---
+/**
+ * Theorem — unified component for amsthm-family environments.
+ *
+ * Maps LaTeX `\begin{theorem}`, `\begin{proposition}`, `\begin{lemma}`,
+ * `\begin{corollary}`, `\begin{definition}`, `\begin{example}`,
+ * `\begin{exercise}`, `\begin{remark}` to a single component with a
+ * `kind` prop.
+ *
+ * Auto-numbering note: the LaTeX preamble shares a counter between
+ * theorem/proposition/lemma/corollary (`\newtheorem{lemma}[theorem]`)
+ * and gives each of definition/example/exercise/remark its own counter.
+ * In MDX we accept that as a contract: per-chapter counters are
+ * implemented in Phase 2.6 (label scanner) — for now, the author
+ * passes `n` explicitly when numbering matters.
+ *
+ * Usage:
+ *   <Theorem kind="theorem" n="4.2" name="Stable continuous-time eigenvalues" id="thm-w4-stability">
+ *     For …
+ *   </Theorem>
+ *
+ *   <Theorem kind="definition" n="4.1" name="HiPPO-LegS">
+ *     The HiPPO-LegS state matrix …
+ *   </Theorem>
+ */
+type Kind =
+  | 'theorem'
+  | 'proposition'
+  | 'lemma'
+  | 'corollary'
+  | 'definition'
+  | 'example'
+  | 'exercise'
+  | 'remark'
+  | 'proof';
+
+interface Props {
+  kind: Kind;
+  n?: string;
+  name?: string;
+  id?: string;
+}
+
+const { kind, n, name, id } = Astro.props;
+
+const KIND_LABEL: Record<Kind, string> = {
+  theorem: 'Theorem',
+  proposition: 'Proposition',
+  lemma: 'Lemma',
+  corollary: 'Corollary',
+  definition: 'Definition',
+  example: 'Example',
+  exercise: 'Exercise',
+  remark: 'Remark',
+  proof: 'Proof',
+};
+
+const label = KIND_LABEL[kind];
+const numbered = n ? `${label} ${n}` : label;
+const fullLabel = name ? `${numbered} (${name})` : numbered;
+---
+<div class="theorem" data-kind={kind} id={id}>
+  <span class="theorem-label">{fullLabel}.</span>
+  <span class="theorem-body"><slot /></span>
+</div>

package/components/TipBox.astro

@@ -0,0 +1,15 @@
+---
+/**
+ * TipBox — maps to LaTeX `tipbox` env.
+ * Default use: one-off practical hints, side-shows.
+ * Family: green (tip).
+ */
+interface Props {
+  title?: string;
+}
+const { title = 'Tip' } = Astro.props;
+---
+<aside class="callout callout-tip" role="note">
+  <strong class="callout-title">{title}</strong>
+  <div class="callout-body"><slot /></div>
+</aside>

package/components/ToolFilter.tsx

@@ -0,0 +1,160 @@
+/**
+ * ToolFilter — Preact island for per-tool chapter filtering.
+ *
+ * Renders a filter button in the chrome row that opens a chip panel.
+ * Each chip toggles one tool slug in the active filter set. Empty set
+ * means "show all". The selection persists to localStorage and is
+ * announced via CustomEvent so non-hydrated pages (e.g., /chapters/)
+ * can react without a hydration cost of their own.
+ *
+ * Hydrated with `client:idle` from Base.astro. Keeps initial paint fast.
+ *
+ * Event contract (commit 2 emits; commit 3 adds a consumer on
+ * /chapters/):
+ *   event name:   "book:tool-filter:change"
+ *   event detail: { selected: string[] }   // tool slugs, may be empty
+ *
+ * Note: 'cross-tool' is intentionally not a chip. Chapters tagged as
+ * cross-tool should remain visible under any filter selection; the
+ * consumer script handles that rule.
+ */
+import { useState, useRef, useEffect } from 'preact/hooks';
+
+const STORAGE_KEY = 'book:tool-filter';
+const EVENT_NAME = 'book:tool-filter:change';
+
+// Filter chips. 'cross-tool' is omitted on purpose (see module doc).
+const FILTERABLE_TOOLS = ['claude-code', 'gemini-cli', 'codex-cli'] as const;
+type FilterableTool = (typeof FILTERABLE_TOOLS)[number];
+
+function readSaved(): string[] {
+  try {
+    const raw = localStorage.getItem(STORAGE_KEY);
+    if (!raw) return [];
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) return [];
+    return parsed.filter((s): s is string => typeof s === 'string');
+  } catch {
+    return [];
+  }
+}
+
+function writeSaved(selected: string[]): void {
+  try {
+    localStorage.setItem(STORAGE_KEY, JSON.stringify(selected));
+  } catch {
+    /* localStorage unavailable — keep in-memory state only */
+  }
+}
+
+function announce(selected: string[]): void {
+  window.dispatchEvent(
+    new CustomEvent(EVENT_NAME, { detail: { selected } }),
+  );
+}
+
+export default function ToolFilter() {
+  const [open, setOpen] = useState(false);
+  const [selected, setSelected] = useState<string[]>([]);
+  const ref = useRef<HTMLDivElement>(null);
+
+  // Hydrate from localStorage on mount, then announce so consumers
+  // apply the persisted filter immediately after hydration.
+  useEffect(() => {
+    const saved = readSaved();
+    setSelected(saved);
+    announce(saved);
+  }, []);
+
+  // Close on outside click or Escape.
+  useEffect(() => {
+    if (!open) return;
+    const onClick = (e: MouseEvent) => {
+      if (ref.current && !ref.current.contains(e.target as Node)) {
+        setOpen(false);
+      }
+    };
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') setOpen(false);
+    };
+    window.addEventListener('click', onClick);
+    window.addEventListener('keydown', onKey);
+    return () => {
+      window.removeEventListener('click', onClick);
+      window.removeEventListener('keydown', onKey);
+    };
+  }, [open]);
+
+  function toggle(tool: FilterableTool): void {
+    const next = selected.includes(tool)
+      ? selected.filter((s) => s !== tool)
+      : [...selected, tool];
+    setSelected(next);
+    writeSaved(next);
+    announce(next);
+  }
+
+  function clearAll(): void {
+    setSelected([]);
+    writeSaved([]);
+    announce([]);
+  }
+
+  const activeCount = selected.length;
+  const buttonLabel =
+    activeCount === 0
+      ? 'Filter chapters by tool (showing all)'
+      : `Filter chapters by tool (${activeCount} active)`;
+
+  return (
+    <div class="tool-filter" ref={ref}>
+      <button
+        type="button"
+        class="chrome-button tool-filter-trigger"
+        aria-label={buttonLabel}
+        title={buttonLabel}
+        aria-expanded={open}
+        aria-haspopup="true"
+        onClick={() => setOpen((v) => !v)}
+      >
+        <span aria-hidden="true">⚐</span>
+        {activeCount > 0 && (
+          <span class="tool-filter-count" aria-hidden="true">{activeCount}</span>
+        )}
+      </button>
+      {open && (
+        <div class="tool-filter-panel" role="group" aria-label="Tool filters">
+          <p class="tool-filter-heading">Show chapters for</p>
+          <ul class="tool-filter-chips">
+            {FILTERABLE_TOOLS.map((tool) => {
+              const on = selected.includes(tool);
+              return (
+                <li>
+                  <button
+                    type="button"
+                    class={`tool-filter-chip${on ? ' tool-filter-chip-on' : ''}`}
+                    aria-pressed={on}
+                    onClick={() => toggle(tool)}
+                  >
+                    {tool}
+                  </button>
+                </li>
+              );
+            })}
+          </ul>
+          <div class="tool-filter-footer">
+            <button
+              type="button"
+              class="tool-filter-clear"
+              onClick={clearAll}
+              disabled={activeCount === 0}
+            >Clear</button>
+            <span class="tool-filter-note">
+              Cross-tool chapters stay visible under any filter.
+            </span>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}

package/components/TryThis.astro

@@ -0,0 +1,23 @@
+---
+/**
+ * TryThis — practice exercise, <10 minutes, applies to reader's own
+ * project. Converts reading to doing.
+ *
+ * Default title is "Try this" — override for specificity:
+ *   <TryThis title="Measure your context budget">...</TryThis>
+ *
+ * Usage:
+ *   <TryThis>
+ *     Open a chapter from your current work and run `/context`. What
+ *     percentage is already filled? What would you evict first?
+ *   </TryThis>
+ */
+interface Props {
+  title?: string;
+}
+const { title = 'Try this' } = Astro.props;
+---
+<aside class="callout callout-try" role="note" aria-label={title}>
+  <strong class="callout-title">{title}</strong>
+  <div class="callout-body"><slot /></div>
+</aside>

package/components/VersionSelector.tsx

@@ -0,0 +1,85 @@
+/**
+ * VersionSelector — Preact island for the version dropdown.
+ *
+ * Stage 0: stub data. The real version list arrives in Stage 3 when
+ * multi-version CI deploys exist; the component is wired now to prove
+ * the islands architecture works with hydration, state, and event
+ * handlers.
+ *
+ * Hydrated with `client:idle` from Base.astro — won't run until the
+ * main thread is idle, keeping initial paint fast.
+ *
+ * Stage 3 will replace the STUB_VERSIONS constant with a runtime fetch
+ * or a build-time-injected prop that lists all deployed versions.
+ */
+import { useState, useRef, useEffect } from 'preact/hooks';
+
+type VersionEntry = {
+  id: string;        // URL subpath segment ('' for latest)
+  label: string;     // display label
+  date: string;      // release date
+  current: boolean;  // mark the version being viewed
+};
+
+// Stub data for Stage 0. Stage 3 will inject the real list.
+const STUB_VERSIONS: VersionEntry[] = [
+  { id: '',     label: 'Latest (main)', date: '2026-04-17', current: true },
+  { id: 'v1.0', label: 'v1.0',          date: '2026-05-01', current: false },
+];
+
+export default function VersionSelector() {
+  const [open, setOpen] = useState(false);
+  const ref = useRef<HTMLDivElement>(null);
+
+  // Close on outside click or Escape.
+  useEffect(() => {
+    if (!open) return;
+    const onClick = (e: MouseEvent) => {
+      if (ref.current && !ref.current.contains(e.target as Node)) {
+        setOpen(false);
+      }
+    };
+    const onKey = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') setOpen(false);
+    };
+    window.addEventListener('click', onClick);
+    window.addEventListener('keydown', onKey);
+    return () => {
+      window.removeEventListener('click', onClick);
+      window.removeEventListener('keydown', onKey);
+    };
+  }, [open]);
+
+  const current = STUB_VERSIONS.find((v) => v.current) || STUB_VERSIONS[0];
+
+  return (
+    <div class="version-selector" ref={ref}>
+      <button
+        type="button"
+        class="chrome-button version-selector-trigger"
+        aria-label="Select book version"
+        title={`Current: ${current.label} (${current.date})`}
+        aria-expanded={open}
+        aria-haspopup="listbox"
+        onClick={() => setOpen((v) => !v)}
+      >
+        <span aria-hidden="true">v</span>
+      </button>
+      {open && (
+        <ul class="version-selector-menu" role="listbox">
+          {STUB_VERSIONS.map((v) => (
+            <li role="option" aria-selected={v.current}>
+              <a
+                href={v.id ? `/${v.id}/` : '/'}
+                class={v.current ? 'version-current' : ''}
+              >
+                <span class="version-label">{v.label}</span>
+                <span class="version-date">{v.date}</span>
+              </a>
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}

package/components/WarnBox.astro

@@ -0,0 +1,15 @@
+---
+/**
+ * WarnBox — maps to LaTeX `warnbox` env.
+ * Default use: caveats, failure modes, pitfalls.
+ * Family: rose (warn).
+ */
+interface Props {
+  title?: string;
+}
+const { title = 'Warning' } = Astro.props;
+---
+<aside class="callout callout-warn" role="note">
+  <strong class="callout-title">{title}</strong>
+  <div class="callout-body"><slot /></div>
+</aside>

package/components/WeekRef.astro

@@ -0,0 +1,51 @@
+---
+/**
+ * WeekRef — inline pointer to another chapter, mapping LaTeX `\weekref{N}{body}`.
+ *
+ * Renders as: "-> Week N: body" with "Week N" hyperlinked to /chapters/weekNN/.
+ *
+ * Used for forward and backward references in prose. The target chapter
+ * may not exist yet (other weeks not yet converted to MDX); the link
+ * will 404 gracefully — once the target chapter lands, links resolve
+ * without further author work.
+ *
+ * Usage:
+ *   <WeekRef week={4}>
+ *     S4 layer uses SSMParam from this chapter for separate LR
+ *     treatment of HiPPO parameters.
+ *   </WeekRef>
+ */
+interface Props {
+  week: number;
+}
+const { week } = Astro.props;
+const slug = `week${String(week).padStart(2, '0')}`;
+const href = `/chapters/${slug}/`;
+---
+<aside class="week-ref">
+  <span class="week-ref-arrow" aria-hidden="true">→</span>
+  <a href={href} class="week-ref-link">Week {week}</a>:
+  <span class="week-ref-body"><slot /></span>
+</aside>
+
+<style>
+  .week-ref {
+    margin: var(--space-3) 0;
+    padding: var(--space-2) var(--space-3);
+    background: var(--color-bg-subtle);
+    border-left: 2px solid var(--callout-info);
+    border-radius: 0 var(--radius-sm) var(--radius-sm) 0;
+    font-size: var(--text-sm);
+  }
+  .week-ref-arrow {
+    color: var(--callout-info);
+    font-weight: 600;
+    margin-right: var(--space-1);
+  }
+  .week-ref-link {
+    font-weight: 500;
+  }
+  .week-ref-body {
+    color: var(--color-text-muted);
+  }
+</style>

package/components/XRef.astro

@@ -0,0 +1,40 @@
+---
+/**
+ * XRef — resolves a `\cref{label}` LaTeX reference to a hyperlink.
+ *
+ * Reads src/data/labels.json built by scripts/build-labels.mjs
+ * (Phase 2.6). For each known id, the map provides:
+ *   { href: "/chapters/week04#thm-w4-stability", display: "Theorem 4.2" }
+ *
+ * Phase 2.2 (now): labels.json ships empty. An unknown id renders an
+ * inline "[?label]" placeholder so the build doesn't fail before we
+ * have chapters with labels. Once Phase 2.6 lands, the validator
+ * promotes "unknown label" from a warning to a build error.
+ *
+ * Usage:
+ *   By <XRef id="thm:w4:stability" />, the discretized eigenvalues …
+ */
+type LabelEntry = { href: string; display: string };
+
+// Resolve labels.json from the consumer's project root (Vite resolves `/`
+// to project root, not the package). Missing file -> empty map -> [?id]
+// placeholders (silent degrade for dev ergonomics; validator catches at CI).
+const labelsModules = import.meta.glob<{ default: Record<string, LabelEntry> }>(
+  '/src/data/labels.json',
+  { eager: true },
+);
+const labelsModule = labelsModules['/src/data/labels.json'];
+const map = (labelsModule?.default ?? {}) as Record<string, LabelEntry>;
+
+interface Props {
+  id: string;
+}
+
+const { id } = Astro.props;
+const entry = map[id];
+---
+{entry ? (
+  <a href={entry.href} class="xref">{entry.display}</a>
+) : (
+  <span class="xref xref-unknown" title={`Unknown label: ${id}`}>[?{id}]</span>
+)}

package/dist/index.d.ts

@@ -0,0 +1,135 @@
+import { AstroUserConfig, AstroIntegration } from 'astro';
+import { b as BookConfigOptions, d as BookScaffoldIntegrationOptions } from './types-Cz-pwE1N.js';
+export { B as BOOK_PROFILES, a as BookConfigError, c as BookProfile, e as BookSchemasOptions, r as resolveProfile } from './types-Cz-pwE1N.js';
+import { z } from 'astro/zod';
+
+declare function defineBookConfig(opts: BookConfigOptions): Promise<AstroUserConfig>;
+
+declare function bookScaffoldIntegration(opts: BookScaffoldIntegrationOptions): AstroIntegration;
+
+/**
+ * Zod schemas + enum constants for book content collections.
+ *
+ * Imports `z` from `astro/zod` (a real module re-export) so schemas can
+ * be constructed at package-load time outside an Astro runtime context.
+ * `defineBookSchemas` in index.ts wraps these into Astro `defineCollection`
+ * calls at the consumer's content-config load time.
+ *
+ * Schemas ported verbatim from v2.0 src/content.config.ts. See
+ * PACKAGE_DESIGN.md §5 for the public reproduction.
+ */
+
+declare const toolSlugs: readonly ["claude-code", "gemini-cli", "codex-cli", "cross-tool"];
+declare const volatilityLevels: readonly ["stable-principle", "architectural-pattern", "feature-surface"];
+declare const sourceTiers: readonly ["T1-official", "T2-release-notes", "T3-practitioner", "T4-conjecture"];
+declare const changeKinds: readonly ["added", "removed", "changed", "deprecated"];
+declare const patternCategories: readonly ["safety", "scale", "context", "interaction", "extension", "other"];
+declare const academicParts: readonly ["foundations", "ssm-core", "beyond-ssm", "integration", "synthesis"];
+declare const chapterStatus: readonly ["implemented", "chapter_only", "reading_only", "prose_only", "code_only", "scaffolded", "planned"];
+declare const academicChapterSchema: z.ZodObject<{
+    week: z.ZodNumber;
+    part: z.ZodEnum<{
+        foundations: "foundations";
+        "ssm-core": "ssm-core";
+        "beyond-ssm": "beyond-ssm";
+        integration: "integration";
+        synthesis: "synthesis";
+    }>;
+    title: z.ZodString;
+    status: z.ZodEnum<{
+        implemented: "implemented";
+        chapter_only: "chapter_only";
+        reading_only: "reading_only";
+        prose_only: "prose_only";
+        code_only: "code_only";
+        scaffolded: "scaffolded";
+        planned: "planned";
+    }>;
+    roadmap_lines: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+    code_path: z.ZodOptional<z.ZodString>;
+    tests_path: z.ZodOptional<z.ZodString>;
+    notebook_path: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    draft: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+declare const toolsChapterSchema: z.ZodObject<{
+    title: z.ZodString;
+    part: z.ZodNumber;
+    chapter: z.ZodNumber;
+    volatility: z.ZodEnum<{
+        "stable-principle": "stable-principle";
+        "architectural-pattern": "architectural-pattern";
+        "feature-surface": "feature-surface";
+    }>;
+    tools_compared: z.ZodArray<z.ZodEnum<{
+        "claude-code": "claude-code";
+        "gemini-cli": "gemini-cli";
+        "codex-cli": "codex-cli";
+        "cross-tool": "cross-tool";
+    }>>;
+    last_verified: z.ZodDate;
+    sources: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    description: z.ZodOptional<z.ZodString>;
+    draft: z.ZodDefault<z.ZodBoolean>;
+    updated: z.ZodOptional<z.ZodDate>;
+}, z.core.$strip>;
+declare const sourcesSchema: z.ZodObject<{
+    url: z.ZodString;
+    title: z.ZodString;
+    author: z.ZodOptional<z.ZodString>;
+    publish_date: z.ZodOptional<z.ZodDate>;
+    captured_at: z.ZodDate;
+    content_hash: z.ZodOptional<z.ZodString>;
+    tier: z.ZodEnum<{
+        "T1-official": "T1-official";
+        "T2-release-notes": "T2-release-notes";
+        "T3-practitioner": "T3-practitioner";
+        "T4-conjecture": "T4-conjecture";
+    }>;
+    tool: z.ZodEnum<{
+        "claude-code": "claude-code";
+        "gemini-cli": "gemini-cli";
+        "codex-cli": "codex-cli";
+        "cross-tool": "cross-tool";
+    }>;
+    perma_cc: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    local_cache: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+}, z.core.$strip>;
+declare const changelogSchema: z.ZodObject<{
+    tool: z.ZodEnum<{
+        "claude-code": "claude-code";
+        "gemini-cli": "gemini-cli";
+        "codex-cli": "codex-cli";
+        "cross-tool": "cross-tool";
+    }>;
+    versions: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        version: z.ZodString;
+        date: z.ZodDate;
+        changes: z.ZodDefault<z.ZodArray<z.ZodObject<{
+            pattern: z.ZodString;
+            kind: z.ZodEnum<{
+                added: "added";
+                removed: "removed";
+                changed: "changed";
+                deprecated: "deprecated";
+            }>;
+            note: z.ZodString;
+            source_key: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+declare const patternsSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    category: z.ZodOptional<z.ZodEnum<{
+        safety: "safety";
+        scale: "scale";
+        context: "context";
+        interaction: "interaction";
+        extension: "extension";
+        other: "other";
+    }>>;
+    convergence_date: z.ZodOptional<z.ZodNullable<z.ZodDate>>;
+}, z.core.$strip>;
+
+export { BookConfigOptions, BookScaffoldIntegrationOptions, academicChapterSchema, academicParts, bookScaffoldIntegration, changeKinds, changelogSchema, chapterStatus, defineBookConfig, patternCategories, patternsSchema, sourceTiers, sourcesSchema, toolSlugs, toolsChapterSchema, volatilityLevels };