@brandon_m_behring/book-scaffold-astro 4.4.0 → 4.5.0

package/dist/index.d.ts

@@ -1,8 +1,24 @@
 import { AstroUserConfig, AstroIntegration } from 'astro';
-import { c as BookConfigOptions, f as BookScaffoldIntegrationOptions, Q as volatilityLevels, h as ChaptersRenderer, n as Style } from './types-BhlCranN.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, i as CourseNotesChapter, F as FreshnessAffordance, j as FrontmatterRouteConfig, M as MinimalChapter, P as PartKey, k as PartialRouteToggles, l as ProfileDefinition, R as ResearchPortfolioChapter, m as RouteToggles, S as StatusBadge, o as StyleInput, T as ToolsChapter, V as VolatilityBadge, p as academicChapterSchema, q as academicParts, r as changeKinds, s as changelogSchema, t as chapterStatus, u as composeStyles, v as courseNotesChapterSchema, w as defineProfile, x as defineStyle, y as minimalChapterSchema, z as normalizeFrontmatterConfig, D as patternCategories, E as patternsSchema, G as researchPortfolioChapterSchema, H as resolvePreset, I as resolveProfile, J as sourceTiers, K as sourceTiersResearch, L as sourcesSchema, N as toolSlugs, O as toolsChapterSchema } from './types-BhlCranN.js';
+import { c as BookConfigOptions, f as BookScaffoldIntegrationOptions, Q as volatilityLevels, h as ChaptersRenderer, n as Style } from './types-DLIpEgTm.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, i as CourseNotesChapter, F as FreshnessAffordance, j as FrontmatterRouteConfig, M as MinimalChapter, P as PartKey, k as PartialRouteToggles, l as ProfileDefinition, R as ResearchPortfolioChapter, m as RouteToggles, S as StatusBadge, o as StyleInput, T as ToolsChapter, V as VolatilityBadge, p as academicChapterSchema, q as academicParts, r as changeKinds, s as changelogSchema, t as chapterStatus, u as composeStyles, v as courseNotesChapterSchema, w as defineProfile, x as defineStyle, y as minimalChapterSchema, z as normalizeFrontmatterConfig, D as patternCategories, E as patternsSchema, G as researchPortfolioChapterSchema, H as resolvePreset, I as resolveProfile, J as sourceTiers, K as sourceTiersResearch, L as sourcesSchema, N as toolSlugs, O as toolsChapterSchema } from './types-DLIpEgTm.js';
 import 'astro/zod';
 
+/**
+ * v4.5.0: Default portfolio backlink baked into the scaffold. Rendered in
+ * the auto-injected `/` landing footer for every consumer that doesn't
+ * explicitly override `portfolio` in defineBookConfig.
+ *
+ * Single source of truth for the brandon-behring.dev URL across all
+ * consumers — update here, bump scaffold version, every consumer inherits
+ * on next build. This is the intentional Brandon-specific default
+ * discussed in plan §Phase 6-pre. Consumers outside the brandon-behring.dev
+ * ecosystem set `portfolio: false` (no link) or pass `{ url, label }` to
+ * override.
+ */
+declare const BRANDON_PORTFOLIO_DEFAULT: {
+    readonly url: "https://brandon-behring.dev";
+    readonly label: "brandon-behring.dev";
+};
 declare function defineBookConfig(opts: BookConfigOptions): Promise<AstroUserConfig>;
 
 declare function bookScaffoldIntegration(opts: BookScaffoldIntegrationOptions): AstroIntegration;
@@ -244,4 +260,4 @@ type TipsConfigInput = Omit<TipsConfig, typeof TipsConfigBrand | '__tipsConfigVe
  */
 declare function defineTips(opts: TipsConfigInput): TipsConfig;
 
-export { BUILTIN_STYLES, BookConfigOptions, BookScaffoldIntegrationOptions, ChaptersRenderer, type Freshness, type FreshnessStatus, Style, type TipsConfig, type TipsConfigInput, type VolatilityLevel, academicChaptersRenderer, academicStyle, bookScaffoldIntegration, chapterSortKey, courseNotesStyle, defineBookConfig, defineMdxComponents, defineTips, fallbackChaptersRenderer, freshnessLabel, getFreshness, minimalStyle, researchPortfolioStyle, toolsChaptersRenderer, toolsStyle, volatilityLevels };
+export { BRANDON_PORTFOLIO_DEFAULT, BUILTIN_STYLES, BookConfigOptions, BookScaffoldIntegrationOptions, ChaptersRenderer, type Freshness, type FreshnessStatus, Style, type TipsConfig, type TipsConfigInput, type VolatilityLevel, academicChaptersRenderer, academicStyle, bookScaffoldIntegration, chapterSortKey, courseNotesStyle, defineBookConfig, defineMdxComponents, defineTips, fallbackChaptersRenderer, freshnessLabel, getFreshness, minimalStyle, researchPortfolioStyle, toolsChaptersRenderer, toolsStyle, volatilityLevels };

package/dist/index.mjs

@@ -380,8 +380,10 @@ var academicProfile = defineProfile({
     // opt-in per book; see #7
     tips: false,
     // v4.3.0 #70: opt-in per book; requires build-tips
-    exercises: false
+    exercises: false,
     // v4.4.0: opt-in per book; requires build-exercises
+    landing: true
+    // v4.5.0: auto-inject minimal root landing; consumers override via src/pages/index.astro
   },
   styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css"],
   katex: true,
@@ -498,8 +500,10 @@ var toolsProfile = defineProfile({
     // opt-in per book; see #7
     tips: false,
     // v4.3.0 #70: opt-in per book
-    exercises: false
+    exercises: false,
     // v4.4.0: opt-in per book
+    landing: true
+    // v4.5.0: auto-inject minimal root landing
   },
   styles: [
     "tokens.css",
@@ -580,8 +584,10 @@ var minimalProfile = defineProfile({
     // opt-in per book; see #7
     tips: false,
     // v4.3.0 #70: opt-in per book
-    exercises: false
+    exercises: false,
     // v4.4.0: opt-in per book
+    landing: true
+    // v4.5.0: auto-inject minimal root landing
   },
   styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css"],
   // v3.7.0 (#35): minimal aliases tools schema; fallback renderer field-dispatches if a consumer opts into routes.chapters
@@ -603,8 +609,10 @@ var courseNotesProfile = defineProfile({
     // opt-in per book; see #7
     tips: false,
     // v4.3.0 #70: opt-in per book
-    exercises: false
+    exercises: false,
     // v4.4.0: opt-in per book
+    landing: true
+    // v4.5.0: auto-inject minimal root landing
   },
   styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css"],
   // v3.7.0 (#35): course-notes schema has tools-style fields (chapter, volatility, sources) — fallback renderer dispatches via tools renderer
@@ -627,8 +635,10 @@ var researchPortfolioProfile = defineProfile({
     // portfolios universally need title/disclosure/banner pages
     tips: false,
     // v4.3.0 #70: opt-in per book
-    exercises: false
+    exercises: false,
     // v4.4.0: opt-in per book
+    landing: true
+    // v4.5.0: auto-inject minimal root landing
   },
   styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css"],
   katex: true,
@@ -833,6 +843,11 @@ var ROUTE_REGISTRY = {
   // v4.4.0: exercises index by chapter. Opt-in via routes.exercises: true;
   // pairs with build-exercises script + <ExerciseSolutions auto /> mode.
   exercises: { pattern: "/exercises", file: "exercises.astro" },
+  // v4.5.0: minimal root landing page. Reads title/description/portfolio/routes
+  // from vite.define-injected import.meta.env vars. Default-on per profile;
+  // consumers with their own src/pages/index.astro override (file-system route
+  // wins over injectRoute).
+  landing: { pattern: "/", file: "index.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).
@@ -850,7 +865,16 @@ function resolvePage(file) {
   return fileURLToPath(new URL(`../pages/${file}`, import.meta.url));
 }
 function bookScaffoldIntegration(opts) {
-  const { profile, routes: userOverrides = {}, extraStyles = [], mdxComponentsModule } = opts;
+  const {
+    profile,
+    routes: userOverrides = {},
+    extraStyles = [],
+    mdxComponentsModule,
+    // v4.5.0: landing-page data, propagated via vite.define to /index.astro.
+    title,
+    description,
+    portfolio
+  } = opts;
   const def = PROFILES[profile];
   const fmNormalized = normalizeFrontmatterConfig(userOverrides.frontmatter);
   const fmEnabled = fmNormalized?.enabled ?? def.routes.frontmatter;
@@ -891,12 +915,20 @@ function bookScaffoldIntegration(opts) {
         const consumerRoot = fileURLToPath(config.root);
         const resolvedMdxPath = resolveMdxComponentsPath(consumerRoot, mdxComponentsModule);
         const presetLiteral = JSON.stringify(profile);
+        const enabledRouteNames = Object.entries(enabledRoutes).filter(([, on]) => on).map(([name]) => name);
         updateConfig({
           vite: {
             plugins: [makeMdxComponentsVitePlugin(resolvedMdxPath)],
             define: {
               "import.meta.env.BOOK_PRESET": presetLiteral,
-              "import.meta.env.BOOK_PROFILE": presetLiteral
+              "import.meta.env.BOOK_PROFILE": presetLiteral,
+              // v4.5.0: landing-page data. JSON.stringify on undefined → 'undefined'
+              // (which evaluates to JavaScript undefined at use site); on object →
+              // the JSON literal; on false → 'false'.
+              "import.meta.env.BOOK_TITLE": JSON.stringify(title ?? null),
+              "import.meta.env.BOOK_DESCRIPTION": JSON.stringify(description ?? null),
+              "import.meta.env.BOOK_PORTFOLIO": JSON.stringify(portfolio ?? null),
+              "import.meta.env.BOOK_ROUTES_ENABLED": JSON.stringify(enabledRouteNames)
             }
           }
         });
@@ -906,6 +938,10 @@ function bookScaffoldIntegration(opts) {
 }
 
 // src/config.ts
+var BRANDON_PORTFOLIO_DEFAULT = {
+  url: "https://brandon-behring.dev",
+  label: "brandon-behring.dev"
+};
 function v3MigrationError(opts) {
   const v3Value = opts.preset ?? opts.profile;
   const v3FieldUsed = "preset" in opts ? "preset" : "profile";
@@ -986,6 +1022,7 @@ async function defineBookConfig(opts) {
       }
     ]);
   }
+  const resolvedPortfolio = opts.portfolio === false ? false : opts.portfolio ?? BRANDON_PORTFOLIO_DEFAULT;
   const integrations = [
     mdx(),
     preact(),
@@ -993,7 +1030,12 @@ async function defineBookConfig(opts) {
       profile,
       routes: mergedRoutes,
       mdxComponentsModule,
-      extraStyles: mergedExtraStyles
+      extraStyles: mergedExtraStyles,
+      // v4.5.0: pass landing-page data through to the integration so it can
+      // be exposed to the auto-injected /index.astro via vite.define.
+      title: opts.title,
+      description: opts.description,
+      portfolio: resolvedPortfolio
     }),
     ...mergedExtraIntegrations
   ];
@@ -1028,6 +1070,10 @@ async function defineBookConfig(opts) {
     extraStyles: _extraStyles,
     markdown: _markdown,
     katexMacros: _katexMacros,
+    // v4.5.0: strip new landing-related opts so they don't leak into AstroUserConfig.
+    title: _title,
+    description: _description,
+    portfolio: _portfolio,
     ...rest
   } = opts;
   void _styles;
@@ -1039,6 +1085,9 @@ async function defineBookConfig(opts) {
   void _extraStyles;
   void _markdown;
   void _katexMacros;
+  void _title;
+  void _description;
+  void _portfolio;
   const katexExternals = wantsKatex ? [] : ["remark-math", "rehype-katex", "katex"];
   const config = {
     site,
@@ -1115,6 +1164,7 @@ function defineTips(opts) {
 export {
   BOOK_PRESETS,
   BOOK_PROFILES,
+  BRANDON_PORTFOLIO_DEFAULT,
   BUILTIN_STYLES,
   BookConfigError,
   academicChapterSchema,

package/dist/schemas.d.ts

@@ -1,5 +1,5 @@
 import { defineCollection } from 'astro:content';
-import { g as BookSchemasOptions } from './types-BhlCranN.js';
+import { g as BookSchemasOptions } from './types-DLIpEgTm.js';
 import 'astro';
 import 'astro/zod';
 

package/dist/schemas.mjs

@@ -265,8 +265,10 @@ var academicProfile = defineProfile({
     // opt-in per book; see #7
     tips: false,
     // v4.3.0 #70: opt-in per book; requires build-tips
-    exercises: false
+    exercises: false,
     // v4.4.0: opt-in per book; requires build-exercises
+    landing: true
+    // v4.5.0: auto-inject minimal root landing; consumers override via src/pages/index.astro
   },
   styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css"],
   katex: true,
@@ -383,8 +385,10 @@ var toolsProfile = defineProfile({
     // opt-in per book; see #7
     tips: false,
     // v4.3.0 #70: opt-in per book
-    exercises: false
+    exercises: false,
     // v4.4.0: opt-in per book
+    landing: true
+    // v4.5.0: auto-inject minimal root landing
   },
   styles: [
     "tokens.css",
@@ -465,8 +469,10 @@ var minimalProfile = defineProfile({
     // opt-in per book; see #7
     tips: false,
     // v4.3.0 #70: opt-in per book
-    exercises: false
+    exercises: false,
     // v4.4.0: opt-in per book
+    landing: true
+    // v4.5.0: auto-inject minimal root landing
   },
   styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css"],
   // v3.7.0 (#35): minimal aliases tools schema; fallback renderer field-dispatches if a consumer opts into routes.chapters
@@ -488,8 +494,10 @@ var courseNotesProfile = defineProfile({
     // opt-in per book; see #7
     tips: false,
     // v4.3.0 #70: opt-in per book
-    exercises: false
+    exercises: false,
     // v4.4.0: opt-in per book
+    landing: true
+    // v4.5.0: auto-inject minimal root landing
   },
   styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css"],
   // v3.7.0 (#35): course-notes schema has tools-style fields (chapter, volatility, sources) — fallback renderer dispatches via tools renderer
@@ -512,8 +520,10 @@ var researchPortfolioProfile = defineProfile({
     // portfolios universally need title/disclosure/banner pages
     tips: false,
     // v4.3.0 #70: opt-in per book
-    exercises: false
+    exercises: false,
     // v4.4.0: opt-in per book
+    landing: true
+    // v4.5.0: auto-inject minimal root landing
   },
   styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css"],
   katex: true,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@brandon_m_behring/book-scaffold-astro",
   "description": "Astro 6 + MDX toolkit for long-form technical books. Profile-aware (academic / tools / minimal); ships Tufte typography, KaTeX, BibTeX citations, Pagefind, Cloudflare Workers deploy. See PACKAGE_DESIGN.md for the API contract.",
-  "version": "4.4.0",
+  "version": "4.5.0",
   "type": "module",
   "license": "MIT",
   "author": "Brandon Behring",

package/pages/index.astro

@@ -0,0 +1,111 @@
+---
+/**
+ * /index — minimal default landing page (v4.5.0).
+ *
+ * Auto-injected by bookScaffoldIntegration when routes.landing === true
+ * (default for every profile). Consumers with their own src/pages/index.astro
+ * override automatically — file-system routes win over injectRoute, no extra
+ * config needed.
+ *
+ * Reads book identity + portfolio + enabled-routes from vite.define-injected
+ * env vars (see integration.ts §4.5.0). Renders:
+ *   - h1 with book title (fallback: 'book-scaffold-astro')
+ *   - lead paragraph with description (omitted if not set)
+ *   - "Read" list of links to enabled scaffold routes (filtered to only
+ *     routes the integration actually injected; respects routes.<x>: false)
+ *   - portfolio backlink in the footer (omitted if portfolio: false)
+ *
+ * Override paths:
+ *   - Disable entirely: defineBookConfig({ routes: { landing: false } })
+ *   - Compose differently: create src/pages/index.astro in your consumer
+ *     repo (file wins; this page never renders)
+ *   - Change portfolio target: defineBookConfig({ portfolio: { url, label } })
+ *     or defineBookConfig({ portfolio: false })
+ */
+import Base from '../layouts/Base.astro';
+
+// Vite-injected at build time. JSON.stringify(value ?? null) is the
+// integration's convention; null means "not set", an object/string means real value.
+const title = (import.meta.env.BOOK_TITLE as string | null) ?? 'book-scaffold-astro';
+const description = import.meta.env.BOOK_DESCRIPTION as string | null;
+const portfolio = import.meta.env.BOOK_PORTFOLIO as { url: string; label: string } | false | null;
+const enabledRoutes = (import.meta.env.BOOK_ROUTES_ENABLED as string[] | undefined) ?? [];
+
+// Map from internal route name → display label + URL. Only routes that
+// produce a single landing-list entry are listed here (frontmatter is a
+// slug pattern; chaptersSlug is dynamic; landing IS this page).
+const ROUTE_LABELS: Record<string, { label: string; href: string }> = {
+  chapters:    { label: 'Chapters',     href: '/chapters/' },
+  search:      { label: 'Search',       href: '/search/' },
+  references:  { label: 'References',   href: '/references/' },
+  print:       { label: 'Print view',   href: '/print/' },
+  convergence: { label: 'Convergence',  href: '/convergence/' },
+  tips:        { label: 'Tips',         href: '/tips/' },
+  exercises:   { label: 'Exercises',    href: '/exercises/' },
+};
+
+const visibleRoutes = enabledRoutes
+  .filter((name) => name in ROUTE_LABELS)
+  .map((name) => ROUTE_LABELS[name]!);
+---
+
+<Base title={title} description={description ?? undefined}>
+  <article class="prose landing">
+    <h1>{title}</h1>
+    {description && <p class="lead">{description}</p>}
+
+    {visibleRoutes.length > 0 && (
+      <>
+        <h2 class="read-heading">Read</h2>
+        <ul class="route-list">
+          {visibleRoutes.map((r) => (
+            <li><a href={r.href}>{r.label}</a></li>
+          ))}
+        </ul>
+      </>
+    )}
+
+    {portfolio && portfolio !== false && (
+      <p class="portfolio-footer">
+        <small>
+          Part of <a href={portfolio.url}>{portfolio.label}</a>
+        </small>
+      </p>
+    )}
+  </article>
+</Base>
+
+<style>
+  .landing {
+    max-width: 60ch;
+    margin: 2rem auto;
+  }
+  .lead {
+    font-size: 1.1rem;
+    line-height: 1.5;
+    margin: 1.25rem 0 2.5rem 0;
+  }
+  .read-heading {
+    font-size: 0.85rem;
+    text-transform: uppercase;
+    letter-spacing: 0.08em;
+    color: var(--color-text-muted, #555);
+    margin-top: 2.5rem;
+    margin-bottom: 0.75rem;
+  }
+  .route-list {
+    list-style: none;
+    padding: 0;
+    margin: 0;
+  }
+  .route-list li {
+    padding: 0.4rem 0;
+    font-family: var(--font-sans, sans-serif);
+    font-size: 1rem;
+  }
+  .portfolio-footer {
+    margin-top: 3rem;
+    color: var(--color-text-muted, #555);
+    font-family: var(--font-sans, sans-serif);
+  }
+</style>

package/src/profile-kit.ts

@@ -41,6 +41,16 @@ export interface RouteToggles {
   print: boolean;
   chapters: boolean;
   convergence: boolean;
+  /**
+   * v4.5.0: auto-inject a minimal `/` landing page that reads the book's
+   * `title`, `description`, and `portfolio` from defineBookConfig and
+   * renders a route list (filtered to enabled routes). Defaults to `true`
+   * on every profile. Consumers with their own `src/pages/index.astro` keep
+   * their custom landing (file-system routes win over `injectRoute`). Set
+   * to `false` to suppress the auto-injection entirely without writing
+   * a custom landing.
+   */
+  landing: boolean;
   /**
    * v3.4.0 (closes #7): auto-inject `/frontmatter/[slug]/` rendering a
    * consumer-defined `frontmatter` content collection. Default `false` per

package/src/profiles/academic.ts

@@ -25,6 +25,7 @@ export const academicProfile = defineProfile({
     frontmatter: false,     // opt-in per book; see #7
     tips: false,            // v4.3.0 #70: opt-in per book; requires build-tips
     exercises: false,       // v4.4.0: opt-in per book; requires build-exercises
+    landing: true,          // v4.5.0: auto-inject minimal root landing; consumers override via src/pages/index.astro
   },
   styles: ['tokens.css', 'layout.css', 'callouts.css', 'chapter.css', 'typography.css', 'print.css'],
   katex: true,

package/src/profiles/course-notes.ts

@@ -27,6 +27,7 @@ export const courseNotesProfile = defineProfile({
     frontmatter: false,     // opt-in per book; see #7
     tips: false,            // v4.3.0 #70: opt-in per book
     exercises: false,       // v4.4.0: opt-in per book
+    landing: true,          // v4.5.0: auto-inject minimal root landing
   },
   styles: ['tokens.css', 'layout.css', 'callouts.css', 'chapter.css', 'typography.css', 'print.css'],
   // v3.7.0 (#35): course-notes schema has tools-style fields (chapter, volatility, sources) — fallback renderer dispatches via tools renderer

package/src/profiles/minimal.ts

@@ -22,6 +22,7 @@ export const minimalProfile = defineProfile({
     frontmatter: false,     // opt-in per book; see #7
     tips: false,            // v4.3.0 #70: opt-in per book
     exercises: false,       // v4.4.0: opt-in per book
+    landing: true,          // v4.5.0: auto-inject minimal root landing
   },
   styles: ['tokens.css', 'layout.css', 'callouts.css', 'chapter.css', 'typography.css', 'print.css'],
   // v3.7.0 (#35): minimal aliases tools schema; fallback renderer field-dispatches if a consumer opts into routes.chapters

package/src/profiles/research-portfolio.ts

@@ -38,6 +38,7 @@ export const researchPortfolioProfile = defineProfile({
     frontmatter: true,           // portfolios universally need title/disclosure/banner pages
     tips: false,                 // v4.3.0 #70: opt-in per book
     exercises: false,            // v4.4.0: opt-in per book
+    landing: true,               // v4.5.0: auto-inject minimal root landing
   },
   styles: ['tokens.css', 'layout.css', 'callouts.css', 'chapter.css', 'typography.css', 'print.css'],
   katex: true,                   // math is common in research content

package/src/profiles/tools.ts

@@ -22,6 +22,7 @@ export const toolsProfile = defineProfile({
     frontmatter: false,     // opt-in per book; see #7
     tips: false,            // v4.3.0 #70: opt-in per book
     exercises: false,       // v4.4.0: opt-in per book
+    landing: true,          // v4.5.0: auto-inject minimal root landing
   },
   styles: [
     'tokens.css', 'layout.css', 'callouts.css', 'chapter.css',