@brandon_m_behring/book-scaffold-astro 3.3.0 → 3.5.0

package/components/AICollaborationDisclosure.astro

@@ -0,0 +1,81 @@
+---
+/**
+ * AICollaborationDisclosure — render a structured AI-collaboration disclosure
+ * paragraph from props.
+ *
+ * v3.5.0 (research-portfolio profile, closes #6). Generic primitive.
+ * Research portfolios universally need to disclose AI involvement (per
+ * various norms); this component centralizes the rendering so consumers
+ * don't reinvent the disclosure block per book.
+ *
+ * Usage (props form — recommended):
+ *   <AICollaborationDisclosure
+ *     model="Claude Opus 4.7 + Sonnet 4.6 (Anthropic)"
+ *     role="research collaborator + writing collaborator"
+ *     commit_attribution="Co-Authored-By: Claude <noreply@anthropic.com>"
+ *   />
+ *
+ * Usage (YAML-driven — consumer loads via astro:content data collection):
+ *   ---
+ *   import disclosure from '../data/ai-collaboration.yaml';
+ *   ---
+ *   <AICollaborationDisclosure {...disclosure} />
+ *
+ * The YAML loader is consumer-side (not shipped) to avoid pulling a YAML
+ * dep into the scaffold; Astro consumers commonly use the `astro:content`
+ * file loader with `yaml()` or similar.
+ *
+ * Slots:
+ *   `default` — optional extra prose to append after the model/role line
+ *               (e.g. "All factual claims independently verified by …").
+ */
+interface Props {
+  model: string;
+  role: string;
+  commit_attribution?: string;
+}
+const { model, role, commit_attribution } = Astro.props;
+---
+<aside class="ai-collab-disclosure" role="note" aria-labelledby="ai-collab-h">
+  <h3 id="ai-collab-h">AI collaboration disclosure</h3>
+  <p>
+    This book was authored in collaboration with <strong>{model}</strong>, acting as <em>{role}</em>.
+  </p>
+  {commit_attribution && (
+    <p>
+      Commits attributed to the model carry the trailer
+      <code>{commit_attribution}</code>.
+    </p>
+  )}
+  <slot />
+</aside>
+
+<style>
+  .ai-collab-disclosure {
+    display: block;
+    margin: var(--space-6) 0;
+    padding: var(--space-3) var(--space-4);
+    border-left: var(--border-bar) solid var(--warm-plum);
+    background: var(--warm-plum-tint);
+    border-radius: 0 var(--radius-md) var(--radius-md) 0;
+    font-size: var(--text-sm);
+    line-height: var(--leading-normal);
+  }
+  .ai-collab-disclosure h3 {
+    margin: 0 0 var(--space-2);
+    font-size: var(--text-base);
+    color: var(--warm-plum);
+    letter-spacing: 0.02em;
+  }
+  .ai-collab-disclosure p {
+    margin: var(--space-2) 0;
+    text-indent: 0;
+  }
+  .ai-collab-disclosure code {
+    font-family: var(--font-code);
+    font-size: 0.95em;
+    background: var(--color-code-bg);
+    padding: 0.1em 0.4em;
+    border-radius: var(--radius-sm);
+  }
+</style>

package/components/BlockedByCallout.astro

@@ -0,0 +1,82 @@
+---
+/**
+ * BlockedByCallout — declare that this chapter / section / experiment is
+ * blocked on an upstream dependency (e.g., a tool release, a paper
+ * publication, a hardware acquisition).
+ *
+ * v3.5.0 (research-portfolio profile, closes #6 + the cross-consumer
+ * dogfooding pattern). Research books often have "blocked by X" sections
+ * — explicit, dated, with optional unblock target.
+ *
+ * Usage:
+ *   <BlockedByCallout
+ *     upstream="book-scaffold-astro v3.5.0"
+ *     url="https://github.com/brandon-behring/book-scaffold-astro/issues/6"
+ *     reason="research-portfolio preset + 3 new components"
+ *     unblockedAt="2026-05-19"
+ *   >
+ *     Once the preset ships, this chapter's frontmatter migrates from the
+ *     hand-rolled schema to the upstream `research-portfolio` shape.
+ *   </BlockedByCallout>
+ *
+ * Slot content (optional) appears under the structured fields and is the
+ * place to put migration notes / workaround prose.
+ */
+interface Props {
+  upstream: string;
+  reason: string;
+  url?: string;
+  unblockedAt?: string;
+}
+const { upstream, reason, url, unblockedAt } = Astro.props;
+const upstreamLabel = url ? null : upstream;
+---
+<aside class="blocked-by-callout" role="note" aria-labelledby="blocked-by-h">
+  <h3 id="blocked-by-h">Blocked by upstream</h3>
+  <p>
+    <strong>
+      {url ? <a href={url} rel="external noopener">{upstream}</a> : upstreamLabel}
+    </strong>
+    {' — '}{reason}{unblockedAt && (<span class="unblocked-at"> (expected {unblockedAt})</span>)}.
+  </p>
+  <div class="blocked-by-body">
+    <slot />
+  </div>
+</aside>
+
+<style>
+  .blocked-by-callout {
+    display: block;
+    margin: var(--space-4) 0;
+    padding: var(--space-3) var(--space-4);
+    border-left: var(--border-bar) solid var(--warm-gold);
+    background: var(--warm-gold-tint);
+    border-radius: 0 var(--radius-md) var(--radius-md) 0;
+    font-size: var(--text-sm);
+    line-height: var(--leading-normal);
+  }
+  .blocked-by-callout h3 {
+    margin: 0 0 var(--space-2);
+    font-size: var(--text-base);
+    color: var(--warm-gold);
+    letter-spacing: 0.02em;
+  }
+  .blocked-by-callout p {
+    margin: var(--space-2) 0;
+    text-indent: 0;
+  }
+  .blocked-by-callout a {
+    color: var(--warm-gold);
+    text-decoration: underline;
+  }
+  .unblocked-at {
+    color: var(--color-text-muted);
+    font-style: italic;
+  }
+  .blocked-by-body :global(p:first-child) {
+    margin-top: 0;
+  }
+  .blocked-by-body :global(p:last-child) {
+    margin-bottom: 0;
+  }
+</style>

package/components/PolicyRef.astro

@@ -0,0 +1,46 @@
+---
+/**
+ * PolicyRef — inline link to a repo-root policy document.
+ *
+ * v3.5.0 (research-portfolio profile, closes #6). Generic: any consumer can
+ * use it to cite ETHICS.md / SECURITY.md / CODE_OF_CONDUCT.md / LICENSE /
+ * GOVERNANCE.md without rebuilding the same "link + label" pattern per book.
+ *
+ * Usage:
+ *   <PolicyRef file="ETHICS.md" section="§1 Dual-use disclosure" label="ethics policy" />
+ *   <PolicyRef file="SECURITY.md" />                       // default label = filename
+ *   <PolicyRef file="GOVERNANCE.md" section="Quorum" />    // auto-anchor from section
+ *
+ * The href resolves to `/<file>` by default (assuming the consumer ships the
+ * markdown at site root via public/ or an Astro page). When `section` is set,
+ * a slugified anchor `#<slug>` is appended. The label defaults to the section
+ * name (if present) else the filename.
+ */
+interface Props {
+  file: string;
+  section?: string;
+  label?: string;
+  href?: string;     // explicit override (otherwise computed)
+}
+const { file, section, label, href } = Astro.props;
+
+const slugify = (s: string) =>
+  s.toLowerCase().replace(/[§\W]+/g, '-').replace(/^-+|-+$/g, '');
+
+const resolvedHref = href ?? `/${file}${section ? `#${slugify(section)}` : ''}`;
+const display = label ?? (section ? `${file} ${section}` : file);
+---
+<a class="policy-ref" href={resolvedHref}>{display}</a>
+
+<style>
+  .policy-ref {
+    font-family: var(--font-code);
+    font-size: 0.95em;
+    color: var(--color-link);
+    text-decoration: none;
+    border-bottom: 1px dotted var(--color-link);
+  }
+  .policy-ref:hover {
+    border-bottom-style: solid;
+  }
+</style>

package/components/PreReleaseBanner.astro

@@ -0,0 +1,73 @@
+---
+/**
+ * PreReleaseBanner — site-wide banner declaring the book's release state.
+ *
+ * v3.5.0 (research-portfolio profile, closes #6). Generic primitive; any
+ * profile can use it but research portfolios are the primary use case
+ * (long-running research books pass through alpha → beta → rc states).
+ *
+ * Usage:
+ *   <PreReleaseBanner state="alpha" />
+ *   <PreReleaseBanner state="beta" dismissAt="v0.7.0" />
+ *   <PreReleaseBanner state="rc" message="Final review pass; please open issues." />
+ *   <PreReleaseBanner state="locked" />
+ *
+ * Drop inside a layout or chapter front-matter file. Common placement is the
+ * top of every page via a layout slot — see recipes/13.
+ */
+interface Props {
+  state: 'alpha' | 'beta' | 'rc' | 'locked';
+  dismissAt?: string;
+  message?: string;
+}
+const { state, dismissAt, message } = Astro.props;
+
+const DEFAULTS: Record<Props['state'], string> = {
+  alpha: 'This book is in alpha — expect breaking changes and partial coverage.',
+  beta: 'This book is in beta — most sections stable; minor changes possible.',
+  rc: 'Release candidate — finalizing content; substantive feedback welcome.',
+  locked: 'This release is frozen. See CHANGELOG for the next iteration.',
+};
+const text = message ?? DEFAULTS[state];
+const label = `${state.toUpperCase()}${dismissAt ? ` (until ${dismissAt})` : ''}`;
+---
+<aside class={`pre-release-banner pre-release-banner-${state}`} role="status" aria-live="polite">
+  <strong>{label}:</strong> {text}
+</aside>
+
+<style>
+  .pre-release-banner {
+    display: block;
+    margin: var(--space-2) 0 var(--space-4);
+    padding: var(--space-2) var(--space-3);
+    border-radius: var(--radius-md);
+    border-left: var(--border-bar) solid;
+    font-size: var(--text-sm);
+    line-height: var(--leading-normal);
+  }
+  .pre-release-banner strong {
+    margin-right: var(--space-1);
+    font-weight: 600;
+    letter-spacing: 0.04em;
+  }
+  .pre-release-banner-alpha {
+    background: var(--warm-rose-tint);
+    border-left-color: var(--warm-rose);
+    color: var(--warm-rose);
+  }
+  .pre-release-banner-beta {
+    background: var(--warm-gold-tint);
+    border-left-color: var(--warm-gold);
+    color: var(--warm-gold);
+  }
+  .pre-release-banner-rc {
+    background: var(--warm-blue-tint);
+    border-left-color: var(--warm-blue);
+    color: var(--warm-blue);
+  }
+  .pre-release-banner-locked {
+    background: var(--warm-green-tint);
+    border-left-color: var(--warm-green);
+    color: var(--warm-green);
+  }
+</style>

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { AstroUserConfig, AstroIntegration } from 'astro';
-import { b as BookConfigOptions, d as BookScaffoldIntegrationOptions, v as volatilityLevels } from './types-s8NxCLU2.js';
-export { A as AcademicChapter, B as BOOK_PROFILES, a as BookConfigError, c as BookProfile, e as BookSchemasOptions, C as ChapterFor, f as CourseNotesChapter, M as MinimalChapter, P as ProfileDefinition, R as RouteToggles, T as ToolsChapter, g as academicChapterSchema, h as academicParts, i as changeKinds, j as changelogSchema, k as chapterStatus, l as courseNotesChapterSchema, m as defineProfile, n as minimalChapterSchema, p as patternCategories, o as patternsSchema, r as resolveProfile, s as sourceTiers, q as sourcesSchema, t as toolSlugs, u as toolsChapterSchema } from './types-s8NxCLU2.js';
+import { c as BookConfigOptions, f as BookScaffoldIntegrationOptions, E as volatilityLevels } from './types-CzXybcNA.js';
+export { A as AcademicChapter, B as BOOK_PRESETS, a as BOOK_PROFILES, b as BookConfigError, d as BookPreset, e as BookProfile, g as BookSchemasOptions, C as ChapterFor, h as CourseNotesChapter, M as MinimalChapter, P as ProfileDefinition, R as ResearchPortfolioChapter, i as RouteToggles, T as ToolsChapter, j as academicChapterSchema, k as academicParts, l as changeKinds, m as changelogSchema, n as chapterStatus, o as courseNotesChapterSchema, p as defineProfile, q as minimalChapterSchema, r as patternCategories, s as patternsSchema, t as researchPortfolioChapterSchema, u as resolvePreset, v as resolveProfile, w as sourceTiers, x as sourceTiersResearch, y as sourcesSchema, z as toolSlugs, D as toolsChapterSchema } from './types-CzXybcNA.js';
 import 'astro/zod';
 
 declare function defineBookConfig(opts: BookConfigOptions): Promise<AstroUserConfig>;

package/dist/index.mjs

@@ -192,6 +192,7 @@ var toolsChapterSchema = z.object({
   updated: z.date().optional()
 });
 var minimalChapterSchema = toolsChapterSchema;
+var sourceTiersResearch = ["T1", "T2", "T3", "T4"];
 var courseNotesChapterSchema = z.object({
   // Identity
   title: z.string().min(1),
@@ -217,6 +218,59 @@ var courseNotesChapterSchema = z.object({
   sources: z.array(z.string()).default([]),
   draft: z.boolean().default(false)
 });
+var researchPortfolioChapterSchema = z.object({
+  // Identity
+  title: z.string().min(1),
+  slug: z.string().optional(),
+  // explicit slug override (otherwise filename)
+  description: z.string().optional(),
+  // Hierarchy — accept either academic-style or tools-style; all optional.
+  // The academic 'part' field is a string enum; tools 'part' is a number.
+  // Use z.union to permit either type.
+  part: z.union([z.number().int().min(0).max(20), z.string()]).optional(),
+  week: z.number().int().min(0).max(99).optional(),
+  chapter: z.number().int().min(0).max(99).optional(),
+  // Academic-style status (optional for research-portfolio — books may track
+  // chapters as 'prose_only' / 'experimental-result' / etc.).
+  status: z.enum([
+    "implemented",
+    "chapter_only",
+    "reading_only",
+    "prose_only",
+    "code_only",
+    "scaffolded",
+    "planned"
+  ]).optional(),
+  // Research-portfolio specific: nature of the chapter's content.
+  // Distinct from academic's 'status' (which tracks authoring state) — this
+  // describes the EVIDENCE TYPE the chapter rests on.
+  freshness: z.enum([
+    "experimental-result",
+    // primary data the author produced
+    "literature-survey",
+    // synthesis of others' work
+    "theoretical",
+    // analytical / mathematical argument
+    "reference"
+    // canonical material (definitions, taxonomy)
+  ]).optional(),
+  // Provenance (tools-style — overlap with tools/course-notes profiles).
+  volatility: z.enum(volatilityLevels).optional(),
+  tags: z.array(z.string()).default([]),
+  // freeform; replaces tools_compared
+  // Structured inline sources with T1-T4 tiers.
+  sources: z.array(
+    z.object({
+      tier: z.enum(sourceTiersResearch),
+      url: z.string().url(),
+      label: z.string().min(1)
+    })
+  ).default([]),
+  // Status + dates.
+  last_verified: z.date(),
+  updated: z.date().optional(),
+  draft: z.boolean().default(false)
+});
 var sourcesSchema = z.object({
   url: z.string().url(),
   title: z.string().min(1),
@@ -263,8 +317,10 @@ var academicProfile = defineProfile({
     print: true,
     chapters: false,
     // academic consumers ship their own week-based /chapters listing
-    convergence: false
+    convergence: false,
     // tools-profile-specific
+    frontmatter: false
+    // opt-in per book; see #7
   },
   styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css"],
   katex: true
@@ -280,8 +336,10 @@ var toolsProfile = defineProfile({
     print: true,
     chapters: true,
     // tools profile ships a flat chapter index
-    convergence: true
+    convergence: true,
     // tools profile ships convergence dashboard
+    frontmatter: false
+    // opt-in per book; see #7
   },
   styles: [
     "tokens.css",
@@ -304,7 +362,9 @@ var minimalProfile = defineProfile({
     search: true,
     print: true,
     chapters: false,
-    convergence: false
+    convergence: false,
+    frontmatter: false
+    // opt-in per book; see #7
   },
   styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css"]
 });
@@ -319,22 +379,46 @@ var courseNotesProfile = defineProfile({
     print: true,
     chapters: false,
     // multi-book consumers route via [book]/[slug] themselves
-    convergence: false
+    convergence: false,
+    frontmatter: false
+    // opt-in per book; see #7
   },
   styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css"]
 });
 
+// src/profiles/research-portfolio.ts
+var researchPortfolioProfile = defineProfile({
+  name: "research-portfolio",
+  schema: researchPortfolioChapterSchema,
+  routes: {
+    references: true,
+    search: true,
+    print: true,
+    chapters: false,
+    // portfolio books ship their own landing/index
+    convergence: false,
+    // tools-profile-specific
+    frontmatter: true
+    // portfolios universally need title/disclosure/banner pages
+  },
+  styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css"],
+  katex: true
+  // math is common in research content
+});
+
 // src/profiles/index.ts
 var PROFILES = {
   academic: academicProfile,
   tools: toolsProfile,
   minimal: minimalProfile,
-  "course-notes": courseNotesProfile
+  "course-notes": courseNotesProfile,
+  "research-portfolio": researchPortfolioProfile
 };
 var BOOK_PROFILES = Object.keys(PROFILES);
 
 // src/types.ts
 import { existsSync, readFileSync } from "fs";
+var BOOK_PRESETS = BOOK_PROFILES;
 var BookConfigError = class extends Error {
   constructor(message) {
     super(message);
@@ -359,29 +443,33 @@ function readEnvFile(path = ".env") {
     return {};
   }
 }
-function resolveProfile(explicit) {
-  let candidate = explicit ?? process.env.BOOK_PROFILE;
+function resolvePreset(explicitPreset, explicitProfile) {
+  let candidate = explicitPreset ?? explicitProfile ?? process.env.BOOK_PRESET ?? process.env.BOOK_PROFILE;
   let source = "default";
-  if (explicit) source = "param";
-  else if (process.env.BOOK_PROFILE) source = "env";
+  if (explicitPreset || explicitProfile) source = "param";
+  else if (process.env.BOOK_PRESET || process.env.BOOK_PROFILE) source = "env";
   if (!candidate) {
-    const fromFile = readEnvFile().BOOK_PROFILE;
+    const env = readEnvFile();
+    const fromFile = env.BOOK_PRESET ?? env.BOOK_PROFILE;
     if (fromFile) {
       candidate = fromFile;
       source = "dotenv";
     }
   }
   candidate = candidate ?? "minimal";
-  if (!BOOK_PROFILES.includes(candidate)) {
+  if (!BOOK_PRESETS.includes(candidate)) {
     throw new BookConfigError(
-      `profile must be one of ${BOOK_PROFILES.join(" | ")} (got ${JSON.stringify(candidate)})`
+      `preset must be one of ${BOOK_PRESETS.join(" | ")} (got ${JSON.stringify(candidate)})`
     );
   }
   if (source === "default") {
-    console.warn("book-scaffold-astro: BOOK_PROFILE not set; falling back to 'minimal'.");
+    console.warn("book-scaffold-astro: BOOK_PRESET not set; falling back to 'minimal'.");
   }
   return candidate;
 }
+function resolveProfile(explicit) {
+  return resolvePreset(void 0, explicit);
+}
 
 // src/integration.ts
 import { fileURLToPath } from "url";
@@ -435,7 +523,11 @@ var ROUTE_REGISTRY = {
   search: { pattern: "/search", file: "search.astro" },
   print: { pattern: "/print", file: "print.astro" },
   chapters: { pattern: "/chapters", file: "chapters.astro" },
-  convergence: { pattern: "/convergence", file: "convergence.astro" }
+  convergence: { pattern: "/convergence", file: "convergence.astro" },
+  // v3.4.0 (#7): consumer-collection-backed frontmatter route. Opt-in via
+  // routes: { frontmatter: true } AND content.config.ts defining the
+  // collection (use frontmatterCollection() helper from /schemas subpath).
+  frontmatter: { pattern: "/frontmatter/[slug]", file: "frontmatter/[...slug].astro" }
 };
 function resolvePage(file) {
   return fileURLToPath(new URL(`../pages/${file}`, import.meta.url));
@@ -466,9 +558,14 @@ function bookScaffoldIntegration(opts) {
         }
         const consumerRoot = fileURLToPath(config.root);
         const resolvedMdxPath = resolveMdxComponentsPath(consumerRoot, mdxComponentsModule);
+        const presetLiteral = JSON.stringify(profile);
         updateConfig({
           vite: {
-            plugins: [makeMdxComponentsVitePlugin(resolvedMdxPath)]
+            plugins: [makeMdxComponentsVitePlugin(resolvedMdxPath)],
+            define: {
+              "import.meta.env.BOOK_PRESET": presetLiteral,
+              "import.meta.env.BOOK_PROFILE": presetLiteral
+            }
           }
         });
       }
@@ -478,7 +575,7 @@ function bookScaffoldIntegration(opts) {
 
 // src/config.ts
 async function defineBookConfig(opts) {
-  const profile = resolveProfile(opts.profile);
+  const profile = resolvePreset(opts.preset, opts.profile);
   const remarkPlugins = [];
   const rehypePlugins = [];
   if (profile === "academic") {
@@ -531,6 +628,8 @@ async function defineBookConfig(opts) {
     ...userMarkdown
   };
   const {
+    preset: _preset,
+    // v3.4.0
     profile: _profile,
     routes: _routes,
     // v3.3.0
@@ -541,6 +640,7 @@ async function defineBookConfig(opts) {
     markdown: _markdown,
     ...rest
   } = opts;
+  void _preset;
   void _profile;
   void _routes;
   void _mdxComponentsModule;
@@ -598,6 +698,7 @@ function freshnessLabel(f) {
   }
 }
 export {
+  BOOK_PRESETS,
   BOOK_PROFILES,
   BookConfigError,
   academicChapterSchema,
@@ -615,8 +716,11 @@ export {
   minimalChapterSchema,
   patternCategories,
   patternsSchema,
+  researchPortfolioChapterSchema,
+  resolvePreset,
   resolveProfile,
   sourceTiers,
+  sourceTiersResearch,
   sourcesSchema,
   toolSlugs,
   toolsChapterSchema,

package/dist/schemas.d.ts

@@ -1,7 +1,40 @@
-import { e as BookSchemasOptions } from './types-s8NxCLU2.js';
+import { defineCollection } from 'astro:content';
+import { g as BookSchemasOptions } from './types-CzXybcNA.js';
 import 'astro';
 import 'astro/zod';
 
+/**
+ * v3.4.0 (closes #7): consumer-facing helper to define a `frontmatter`
+ * content collection that the scaffold's auto-injected
+ * `/frontmatter/[slug]` route can render.
+ *
+ * Usage in consumer's content.config.ts:
+ *
+ *   import { defineBookSchemas, frontmatterCollection } from
+ *     '@brandon_m_behring/book-scaffold-astro/schemas';
+ *   import { z } from 'astro:content';
+ *
+ *   export const { collections } = {
+ *     collections: {
+ *       ...defineBookSchemas().collections,
+ *       frontmatter: frontmatterCollection(z.object({
+ *         slug: z.string(),
+ *         title: z.string(),
+ *         order: z.number(),
+ *         description: z.string().optional(),
+ *       })),
+ *     },
+ *   };
+ *
+ * Then enable the route via `defineBookConfig({ routes: { frontmatter: true } })`
+ * and drop MDX files under `src/content/frontmatter/`. The scaffold-injected
+ * route renders each entry with the consumer's mdx-components in scope (issue #2
+ * plumbing applies).
+ *
+ * Default loader: `**\/*.{md,mdx}` under `./src/content/frontmatter` (excluding
+ * underscore-prefixed files). Override `base` via the second arg.
+ */
+declare function frontmatterCollection(schema: Parameters<typeof defineCollection>[0]['schema'], base?: string): unknown;
 /**
  * Returns the package's default content collections. Closed shape per Q5;
  * consumer extends via object spread and Zod `.extend()` (see PACKAGE_DESIGN.md §5).
@@ -10,4 +43,4 @@ declare function defineBookSchemas(opts?: BookSchemasOptions): {
     collections: Record<string, unknown>;
 };
 
-export { defineBookSchemas };
+export { defineBookSchemas, frontmatterCollection };