@brandon_m_behring/book-scaffold-astro 4.24.0 → 4.25.0

package/dist/index.d.ts

@@ -1,11 +1,11 @@
-import { AstroUserConfig, AstroIntegration } from 'astro';
-import { c as BookConfigOptions, f as BookScaffoldIntegrationOptions, h as ChaptersRenderer, l as Style } from './types-CGN95mrX.js';
-export { B as BOOK_PRESETS, a as BOOK_PROFILES, b as BookConfigError, d as BookPreset, e as BookProfile, g as BookSchemasOptions, C as ChapterFor, F as FreshnessAffordance, i as FrontmatterRouteConfig, P as PartKey, j as PartialRouteToggles, k as ProfileDefinition, R as RouteToggles, S as StatusBadge, m as StyleInput, V as VolatilityBadge, n as composeStyles, o as defineProfile, p as defineStyle, q as normalizeFrontmatterConfig, r as resolvePreset, s as resolveProfile } from './types-CGN95mrX.js';
-import { D as volatilityLevels, c as academicParts, Q as Question } from './schemas-DDWDRUxs.js';
-export { A as AcademicChapter, B as BloomLevel, C as CourseNotesChapter, G as GlossaryTerm, M as MinimalChapter, P as Provenance, a as QuestionType, R as ResearchPortfolioChapter, T as ToolsChapter, b as academicChapterSchema, d as bloomLevels, e as changeKinds, f as changelogSchema, g as chapterStatus, h as citationBackstops, i as courseNotesChapterSchema, j as glossarySchema, m as minimalChapterSchema, p as patternCategories, k as patternsSchema, l as provenanceObject, n as provenanceSchema, q as questionDifficulties, o as questionSchema, r as questionTypes, s as refineQuestion, t as refinedQuestionSchema, u as researchPortfolioChapterSchema, v as sourceTiers, w as sourceTiersResearch, x as sourcesSchema, y as toolSlugs, z as toolsChapterSchema } from './schemas-DDWDRUxs.js';
+import { AstroUserConfig, AstroIntegration, MarkdownHeading } from 'astro';
+import { c as BookConfigOptions, f as BookScaffoldIntegrationOptions, h as ChaptersRenderer, l as Style } from './types-Bn7rKhgP.js';
+export { B as BOOK_PRESETS, a as BOOK_PROFILES, b as BookConfigError, d as BookPreset, e as BookProfile, g as BookSchemasOptions, C as ChapterFor, F as FreshnessAffordance, i as FrontmatterRouteConfig, P as PartKey, j as PartialRouteToggles, k as ProfileDefinition, R as RouteToggles, S as StatusBadge, m as StyleInput, V as VolatilityBadge, n as composeStyles, o as defineProfile, p as defineStyle, q as normalizeFrontmatterConfig, r as resolvePreset, s as resolveProfile } from './types-Bn7rKhgP.js';
+import { E as volatilityLevels, c as academicParts, Q as Question } from './schemas-CKipJ5Ie.js';
+export { A as AcademicChapter, B as BloomLevel, C as CourseNotesChapter, G as GlossaryTerm, M as MinimalChapter, P as Provenance, a as QuestionType, R as ResearchPortfolioChapter, T as ToolsChapter, b as academicChapterSchema, d as bloomLevels, e as changeKinds, f as changelogSchema, g as chapterStatus, h as citationBackstops, i as courseNotesChapterSchema, j as glossarySchema, l as layoutModes, m as minimalChapterSchema, p as patternCategories, k as patternsSchema, n as provenanceObject, o as provenanceSchema, q as questionDifficulties, r as questionSchema, s as questionTypes, t as refineQuestion, u as refinedQuestionSchema, v as researchPortfolioChapterSchema, w as sourceTiers, x as sourceTiersResearch, y as sourcesSchema, z as toolSlugs, D as toolsChapterSchema } from './schemas-CKipJ5Ie.js';
 export { KIND_LABEL, ResolvedTheoremLabel, THEOREM_KINDS, TheoremKind, TheoremLabelProps, resolveTheoremNumber, theoremLabel } from './lib/theorem-label.js';
-export { D as DomainScore, E as ExamBlueprint, a as ExamQuestion, b as ExamResult, R as RoutingChapter, c as buildExamManifest, d as deriveDomainRouting, s as sampleExam, e as scoreExam, f as shuffle, g as spreadBlueprint } from './exam-manifest-DbTHo90M.js';
-export { F as FlashcardRef, b as buildFlashcardDeck } from './flashcards-DPFFQhP8.js';
+export { D as DomainScore, E as ExamBlueprint, a as ExamQuestion, b as ExamResult, R as RoutingChapter, c as buildExamManifest, d as deriveDomainRouting, s as sampleExam, e as scoreExam, f as shuffle, g as spreadBlueprint } from './exam-manifest-DnqyzZ9I.js';
+export { F as FlashcardRef, b as buildFlashcardDeck } from './flashcards-okekZcl8.js';
 import 'astro/zod';
 
 /**
@@ -360,6 +360,69 @@ declare function distinctChaptersSorted<T extends {
     data: Pick<Question, 'chapter'>;
 }>(entries: readonly T[]): string[];
 
+/**
+ * section-map.ts — PURE heading-selection + scrollspy logic for the right-gutter
+ * "On this page" section map (#section-map).
+ *
+ * No DOM, no Preact: this is the testable core under both ChapterTOC.astro (the
+ * collapsed mobile fallback) and the SectionMap island (the sticky gutter nav).
+ * Two pure, total functions:
+ *
+ *   - tocHeadings:  the ONE filter (h2+h3) that both the fallback TOC and the
+ *                   gutter map share — a single source of truth so the two
+ *                   never disagree about which headings are "on this page".
+ *   - pickActive:   given the headings currently intersecting the viewport (slug
+ *                   + viewport-relative top), choose which one is "active". The
+ *                   island feeds it IntersectionObserver state; node:test feeds
+ *                   it plain arrays. Browser geometry stays OUT of this file.
+ *
+ * Both are unit-tested in tests/section-map.test.mjs (node:test, no browser),
+ * mirroring exam-engine.ts.
+ */
+
+/**
+ * Filter a chapter's headings to the TOC set: depth 2–3 only. h1 is the chapter
+ * title (rendered by ChapterHeader, not the body) and h4+ is noise in an anchor
+ * list. This is the shared contract — ChapterTOC.astro and SectionMap.astro both
+ * call it so the fallback and the gutter map carry IDENTICAL entries. Pure: it
+ * copies (filter) rather than mutating the input.
+ */
+declare function tocHeadings(headings: MarkdownHeading[]): MarkdownHeading[];
+/**
+ * One visible heading, as the island measures it: its slug and its
+ * viewport-relative top (CSS pixels — `getBoundingClientRect().top`). A negative
+ * `top` means the heading has scrolled above the top of the viewport.
+ */
+interface VisibleHeading {
+    slug: string;
+    /** Viewport-relative top in px (negative = scrolled above the fold). */
+    top: number;
+}
+/**
+ * Choose the active section slug from the headings currently intersecting the
+ * viewport.
+ *
+ * Rule (a stable, total scrollspy):
+ *   1. Prefer the topmost heading at or below the top of the viewport — the
+ *      visible heading with the SMALLEST non-negative `top`. That's the section
+ *      the reader has just scrolled to / is reading into.
+ *   2. If every visible heading is above the fold (all `top` negative — e.g. a
+ *      heading STRADDLING the top edge: its top is slightly negative but its box
+ *      still overlaps the top zone, so it's intersecting yet has no non-negative
+ *      sibling below it), fall back to the one nearest the fold from above: the
+ *      GREATEST `top` (closest to 0 from the negative side). That keeps the
+ *      enclosing section lit instead of going dark mid-section. (A heading whose
+ *      box FULLY scrolled above the top has left `inView` entirely — it isn't in
+ *      `visible` at all, and is handled by the empty-set → `prev` branch below.)
+ *   3. If NOTHING is visible (the observer reports an empty set — between two
+ *      sparse intersections, or scrolled past the last heading), retain `prev`
+ *      so the highlight is sticky rather than flickering off.
+ *
+ * Pure + total: no DOM, no throw, deterministic. Ties (equal `top`) resolve to
+ * the first in iteration order, which the island passes in document order.
+ */
+declare function pickActive(visible: ReadonlyArray<VisibleHeading>, prev: string | null): string | null;
+
 /** One exercise as emitted by `book-scaffold build-exercises` (src/data/exercises.json). */
 interface ReviewExercise {
     id: string;
@@ -488,4 +551,4 @@ type TipsConfigInput = Omit<TipsConfig, typeof TipsConfigBrand | '__tipsConfigVe
  */
 declare function defineTips(opts: TipsConfigInput): TipsConfig;
 
-export { ACADEMIC_PART_NAMES, BRANDON_PORTFOLIO_DEFAULT, BUILTIN_STYLES, BookConfigOptions, BookScaffoldIntegrationOptions, ChaptersRenderer, DEFAULT_GITHUB_BRANCH, type Freshness, type FreshnessStatus, type PartReviewGroup, type PartReviewSelection, Question, type ReviewChapter, type ReviewExercise, Style, type TipsConfig, type TipsConfigInput, UNKNOWN_PART_ORDINAL, type VolatilityLevel, academicChaptersRenderer, academicPartHeading, academicPartName, academicPartOrdinal, academicParts, academicStyle, assertEnumProp, assertKnownDomain, bookScaffoldIntegration, buildGithubUrl, chapterLabel, chapterSortKey, courseNotesStyle, defineBookConfig, defineMdxComponents, defineTips, deriveObjectiveMap, distinctChaptersSorted, fallbackChaptersRenderer, freshnessLabel, getFreshness, groupByChapter, groupByDomain, minimalStyle, originUrlFromGitConfig, parseRepoSlug, researchPortfolioStyle, resolveBookHref, resolveGithubRepo, selectPartExercises, sortQuestions, toolsChaptersRenderer, toolsStyle, volatilityLevels };
+export { ACADEMIC_PART_NAMES, BRANDON_PORTFOLIO_DEFAULT, BUILTIN_STYLES, BookConfigOptions, BookScaffoldIntegrationOptions, ChaptersRenderer, DEFAULT_GITHUB_BRANCH, type Freshness, type FreshnessStatus, type PartReviewGroup, type PartReviewSelection, Question, type ReviewChapter, type ReviewExercise, Style, type TipsConfig, type TipsConfigInput, UNKNOWN_PART_ORDINAL, type VisibleHeading, type VolatilityLevel, academicChaptersRenderer, academicPartHeading, academicPartName, academicPartOrdinal, academicParts, academicStyle, assertEnumProp, assertKnownDomain, bookScaffoldIntegration, buildGithubUrl, chapterLabel, chapterSortKey, courseNotesStyle, defineBookConfig, defineMdxComponents, defineTips, deriveObjectiveMap, distinctChaptersSorted, fallbackChaptersRenderer, freshnessLabel, getFreshness, groupByChapter, groupByDomain, minimalStyle, originUrlFromGitConfig, parseRepoSlug, pickActive, researchPortfolioStyle, resolveBookHref, resolveGithubRepo, selectPartExercises, sortQuestions, tocHeadings, toolsChaptersRenderer, toolsStyle, volatilityLevels };

package/dist/index.mjs

@@ -168,6 +168,7 @@ var chapterStatus = [
   "scaffolded",
   "planned"
 ];
+var layoutModes = ["default", "wide"];
 var citationBackstops = ["research-kb", "manual", "unverified"];
 var provenanceObject = z.object({
   ai_tools: z.array(z.string()).default([]),
@@ -186,6 +187,8 @@ var academicChapterSchema = z.object({
   title: z.string().min(1),
   slug: z.string().optional(),
   // v4.9.0: explicit URL slug override (else filename → entry.id)
+  layout: z.enum(layoutModes).optional(),
+  // 1d: per-page width knob (default measure | 'wide'); threaded as data-layout
   status: z.enum(chapterStatus),
   roadmap_lines: z.tuple([z.number().int(), z.number().int()]).optional(),
   code_path: z.string().optional(),
@@ -207,6 +210,8 @@ var toolsChapterSchema = z.object({
   title: z.string().min(1),
   slug: z.string().optional(),
   // v4.9.0: explicit URL slug override (else filename → entry.id)
+  layout: z.enum(layoutModes).optional(),
+  // 1d: per-page width knob (default measure | 'wide'); threaded as data-layout
   part: z.number().int().min(0).max(10),
   chapter: z.number().int().min(0).max(99),
   volatility: z.enum(volatilityLevels),
@@ -232,6 +237,8 @@ var courseNotesChapterSchema = z.object({
   title: z.string().min(1),
   slug: z.string().optional(),
   // v4.9.0: explicit URL slug override (else filename → entry.id)
+  layout: z.enum(layoutModes).optional(),
+  // 1d: per-page width knob (default measure | 'wide'); threaded as data-layout
   chapter: z.number().int().min(0).max(99),
   part: z.number().int().min(0).max(20).default(1),
   description: z.string().optional(),
@@ -268,6 +275,8 @@ var researchPortfolioChapterSchema = z.object({
   title: z.string().min(1),
   slug: z.string().optional(),
   // explicit slug override (otherwise filename)
+  layout: z.enum(layoutModes).optional(),
+  // 1d: per-page width knob (default measure | 'wide'); threaded as data-layout
   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.
@@ -576,7 +585,7 @@ var academicProfile = defineProfile({
     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"],
+  styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css", "section-map.css"],
   katex: true,
   chaptersRenderer: academicChaptersRenderer,
   // v3.7.0 (#35) — owns /chapters semantics if consumer opts in via routes.chapters
@@ -715,7 +724,8 @@ var toolsProfile = defineProfile({
     "typography.css",
     "print.css",
     "convergence.css",
-    "tool-filter.css"
+    "tool-filter.css",
+    "section-map.css"
   ],
   chaptersRenderer: toolsChaptersRenderer
   // v3.7.0 (#35) — owns /chapters semantics for tools shape
@@ -800,7 +810,7 @@ var minimalProfile = defineProfile({
     landing: true
     // v4.5.0: auto-inject minimal root landing
   },
-  styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css"],
+  styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css", "section-map.css"],
   // v3.7.0 (#35): minimal aliases tools schema; fallback renderer field-dispatches if a consumer opts into routes.chapters
   chaptersRenderer: fallbackChaptersRenderer
 });
@@ -833,7 +843,7 @@ var courseNotesProfile = defineProfile({
     landing: true
     // v4.5.0: auto-inject minimal root landing
   },
-  styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css"],
+  styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css", "section-map.css"],
   // v3.7.0 (#35): course-notes schema has tools-style fields (chapter, volatility, sources) — fallback renderer dispatches via tools renderer
   chaptersRenderer: fallbackChaptersRenderer,
   // v4.6.0 (#76 Secondary): exclude /print/ from sitemap — print-friendly
@@ -870,7 +880,7 @@ var researchPortfolioProfile = defineProfile({
     landing: true
     // v4.5.0: auto-inject minimal root landing
   },
-  styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css"],
+  styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css", "section-map.css"],
   katex: true,
   // math is common in research content
   // v3.7.0 (#35): portfolio schema is a union of academic + tools shapes — fallback renderer dispatches per chapter via field presence
@@ -1749,6 +1759,26 @@ function buildFlashcardDeck(entries) {
   return entries.filter((e) => !e.data.draft).map((e) => ({ id: e.id, front: e.data.term })).sort((a, b) => a.front.localeCompare(b.front));
 }
 
+// src/lib/section-map.ts
+function tocHeadings(headings) {
+  return headings.filter((h) => h.depth >= 2 && h.depth <= 3);
+}
+function pickActive(visible, prev) {
+  if (visible.length === 0) return prev;
+  let bestNonNeg = null;
+  let bestAbove = null;
+  for (const h of visible) {
+    if (h.top >= 0) {
+      if (bestNonNeg === null || h.top < bestNonNeg.top) bestNonNeg = h;
+    } else {
+      if (bestAbove === null || h.top > bestAbove.top) bestAbove = h;
+    }
+  }
+  if (bestNonNeg !== null) return bestNonNeg.slug;
+  if (bestAbove !== null) return bestAbove.slug;
+  return prev;
+}
+
 // src/lib/part-review.ts
 function selectPartExercises(chapters, byChapter, part) {
   const want = String(part);
@@ -1844,6 +1874,7 @@ export {
   glossarySchema,
   groupByChapter,
   groupByDomain,
+  layoutModes,
   minimalChapterSchema,
   minimalStyle,
   normalizeFrontmatterConfig,
@@ -1851,6 +1882,7 @@ export {
   parseRepoSlug,
   patternCategories,
   patternsSchema,
+  pickActive,
   provenanceObject,
   provenanceSchema,
   questionDifficulties,
@@ -1875,6 +1907,7 @@ export {
   sourcesSchema,
   spreadBlueprint,
   theoremLabel,
+  tocHeadings,
   toolSlugs,
   toolsChapterSchema,
   toolsChaptersRenderer,

package/dist/{schemas-DDWDRUxs.d.ts → schemas-CKipJ5Ie.d.ts}

@@ -25,6 +25,7 @@ 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 layoutModes: readonly ["default", "wide"];
 declare const citationBackstops: readonly ["research-kb", "manual", "unverified"];
 declare const provenanceObject: z.ZodObject<{
     ai_tools: z.ZodDefault<z.ZodArray<z.ZodString>>;
@@ -67,6 +68,10 @@ declare const academicChapterSchema: z.ZodObject<{
     }>;
     title: z.ZodString;
     slug: z.ZodOptional<z.ZodString>;
+    layout: z.ZodOptional<z.ZodEnum<{
+        default: "default";
+        wide: "wide";
+    }>>;
     status: z.ZodEnum<{
         implemented: "implemented";
         chapter_only: "chapter_only";
@@ -106,6 +111,10 @@ declare const academicChapterSchema: z.ZodObject<{
 declare const toolsChapterSchema: z.ZodObject<{
     title: z.ZodString;
     slug: z.ZodOptional<z.ZodString>;
+    layout: z.ZodOptional<z.ZodEnum<{
+        default: "default";
+        wide: "wide";
+    }>>;
     part: z.ZodNumber;
     chapter: z.ZodNumber;
     volatility: z.ZodEnum<{
@@ -148,6 +157,10 @@ declare const toolsChapterSchema: z.ZodObject<{
 declare const minimalChapterSchema: z.ZodObject<{
     title: z.ZodString;
     slug: z.ZodOptional<z.ZodString>;
+    layout: z.ZodOptional<z.ZodEnum<{
+        default: "default";
+        wide: "wide";
+    }>>;
     part: z.ZodNumber;
     chapter: z.ZodNumber;
     volatility: z.ZodEnum<{
@@ -205,6 +218,10 @@ declare const sourceTiersResearch: readonly ["T1", "T2", "T3", "T4"];
 declare const courseNotesChapterSchema: z.ZodObject<{
     title: z.ZodString;
     slug: z.ZodOptional<z.ZodString>;
+    layout: z.ZodOptional<z.ZodEnum<{
+        default: "default";
+        wide: "wide";
+    }>>;
     chapter: z.ZodNumber;
     part: z.ZodDefault<z.ZodNumber>;
     description: z.ZodOptional<z.ZodString>;
@@ -269,6 +286,10 @@ declare const courseNotesChapterSchema: z.ZodObject<{
 declare const researchPortfolioChapterSchema: z.ZodObject<{
     title: z.ZodString;
     slug: z.ZodOptional<z.ZodString>;
+    layout: z.ZodOptional<z.ZodEnum<{
+        default: "default";
+        wide: "wide";
+    }>>;
     description: z.ZodOptional<z.ZodString>;
     part: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
     week: z.ZodOptional<z.ZodNumber>;
@@ -488,4 +509,4 @@ declare const glossarySchema: z.ZodObject<{
 }, z.core.$strict>;
 type GlossaryTerm = z.infer<typeof glossarySchema>;
 
-export { type AcademicChapter as A, type BloomLevel as B, type CourseNotesChapter as C, volatilityLevels as D, type GlossaryTerm as G, type MinimalChapter as M, type Provenance as P, type Question as Q, type ResearchPortfolioChapter as R, type ToolsChapter as T, type QuestionType as a, academicChapterSchema as b, academicParts as c, bloomLevels as d, changeKinds as e, changelogSchema as f, chapterStatus as g, citationBackstops as h, courseNotesChapterSchema as i, glossarySchema as j, patternsSchema as k, provenanceObject as l, minimalChapterSchema as m, provenanceSchema as n, questionSchema as o, patternCategories as p, questionDifficulties as q, questionTypes as r, refineQuestion as s, refinedQuestionSchema as t, researchPortfolioChapterSchema as u, sourceTiers as v, sourceTiersResearch as w, sourcesSchema as x, toolSlugs as y, toolsChapterSchema as z };
+export { type AcademicChapter as A, type BloomLevel as B, type CourseNotesChapter as C, toolsChapterSchema as D, volatilityLevels as E, type GlossaryTerm as G, type MinimalChapter as M, type Provenance as P, type Question as Q, type ResearchPortfolioChapter as R, type ToolsChapter as T, type QuestionType as a, academicChapterSchema as b, academicParts as c, bloomLevels as d, changeKinds as e, changelogSchema as f, chapterStatus as g, citationBackstops as h, courseNotesChapterSchema as i, glossarySchema as j, patternsSchema as k, layoutModes as l, minimalChapterSchema as m, provenanceObject as n, provenanceSchema as o, patternCategories as p, questionDifficulties as q, questionSchema as r, questionTypes as s, refineQuestion as t, refinedQuestionSchema as u, researchPortfolioChapterSchema as v, sourceTiers as w, sourceTiersResearch as x, sourcesSchema as y, toolSlugs as z };

package/dist/schemas.d.ts

@@ -1,7 +1,7 @@
 import { defineCollection } from 'astro:content';
-import { g as BookSchemasOptions } from './types-CGN95mrX.js';
+import { g as BookSchemasOptions } from './types-Bn7rKhgP.js';
 import 'astro';
-import './schemas-DDWDRUxs.js';
+import './schemas-CKipJ5Ie.js';
 import 'astro/zod';
 
 /**

package/dist/schemas.mjs

@@ -52,6 +52,7 @@ var chapterStatus = [
   "scaffolded",
   "planned"
 ];
+var layoutModes = ["default", "wide"];
 var citationBackstops = ["research-kb", "manual", "unverified"];
 var provenanceObject = z.object({
   ai_tools: z.array(z.string()).default([]),
@@ -70,6 +71,8 @@ var academicChapterSchema = z.object({
   title: z.string().min(1),
   slug: z.string().optional(),
   // v4.9.0: explicit URL slug override (else filename → entry.id)
+  layout: z.enum(layoutModes).optional(),
+  // 1d: per-page width knob (default measure | 'wide'); threaded as data-layout
   status: z.enum(chapterStatus),
   roadmap_lines: z.tuple([z.number().int(), z.number().int()]).optional(),
   code_path: z.string().optional(),
@@ -91,6 +94,8 @@ var toolsChapterSchema = z.object({
   title: z.string().min(1),
   slug: z.string().optional(),
   // v4.9.0: explicit URL slug override (else filename → entry.id)
+  layout: z.enum(layoutModes).optional(),
+  // 1d: per-page width knob (default measure | 'wide'); threaded as data-layout
   part: z.number().int().min(0).max(10),
   chapter: z.number().int().min(0).max(99),
   volatility: z.enum(volatilityLevels),
@@ -116,6 +121,8 @@ var courseNotesChapterSchema = z.object({
   title: z.string().min(1),
   slug: z.string().optional(),
   // v4.9.0: explicit URL slug override (else filename → entry.id)
+  layout: z.enum(layoutModes).optional(),
+  // 1d: per-page width knob (default measure | 'wide'); threaded as data-layout
   chapter: z.number().int().min(0).max(99),
   part: z.number().int().min(0).max(20).default(1),
   description: z.string().optional(),
@@ -152,6 +159,8 @@ var researchPortfolioChapterSchema = z.object({
   title: z.string().min(1),
   slug: z.string().optional(),
   // explicit slug override (otherwise filename)
+  layout: z.enum(layoutModes).optional(),
+  // 1d: per-page width knob (default measure | 'wide'); threaded as data-layout
   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.
@@ -454,7 +463,7 @@ var academicProfile = defineProfile({
     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"],
+  styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css", "section-map.css"],
   katex: true,
   chaptersRenderer: academicChaptersRenderer,
   // v3.7.0 (#35) — owns /chapters semantics if consumer opts in via routes.chapters
@@ -593,7 +602,8 @@ var toolsProfile = defineProfile({
     "typography.css",
     "print.css",
     "convergence.css",
-    "tool-filter.css"
+    "tool-filter.css",
+    "section-map.css"
   ],
   chaptersRenderer: toolsChaptersRenderer
   // v3.7.0 (#35) — owns /chapters semantics for tools shape
@@ -678,7 +688,7 @@ var minimalProfile = defineProfile({
     landing: true
     // v4.5.0: auto-inject minimal root landing
   },
-  styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css"],
+  styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css", "section-map.css"],
   // v3.7.0 (#35): minimal aliases tools schema; fallback renderer field-dispatches if a consumer opts into routes.chapters
   chaptersRenderer: fallbackChaptersRenderer
 });
@@ -711,7 +721,7 @@ var courseNotesProfile = defineProfile({
     landing: true
     // v4.5.0: auto-inject minimal root landing
   },
-  styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css"],
+  styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css", "section-map.css"],
   // v3.7.0 (#35): course-notes schema has tools-style fields (chapter, volatility, sources) — fallback renderer dispatches via tools renderer
   chaptersRenderer: fallbackChaptersRenderer,
   // v4.6.0 (#76 Secondary): exclude /print/ from sitemap — print-friendly
@@ -748,7 +758,7 @@ var researchPortfolioProfile = defineProfile({
     landing: true
     // v4.5.0: auto-inject minimal root landing
   },
-  styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css"],
+  styles: ["tokens.css", "layout.css", "callouts.css", "chapter.css", "typography.css", "print.css", "section-map.css"],
   katex: true,
   // math is common in research content
   // v3.7.0 (#35): portfolio schema is a union of academic + tools shapes — fallback renderer dispatches per chapter via field presence

package/dist/{types-CGN95mrX.d.ts → types-Bn7rKhgP.d.ts}

@@ -1,5 +1,5 @@
 import { AstroIntegration, AstroUserConfig } from 'astro';
-import { A as AcademicChapter, T as ToolsChapter, M as MinimalChapter, C as CourseNotesChapter, R as ResearchPortfolioChapter } from './schemas-DDWDRUxs.js';
+import { A as AcademicChapter, T as ToolsChapter, M as MinimalChapter, C as CourseNotesChapter, R as ResearchPortfolioChapter } from './schemas-CKipJ5Ie.js';
 
 /**
  * src/lib/chapters-renderer.ts — per-profile strategy interface for the

package/layouts/Chapter.astro

@@ -25,6 +25,7 @@ import Base from './Base.astro';
 import bookConfig from 'virtual:book-scaffold/book-config';
 import ChapterHeader from '../components/ChapterHeader.astro';
 import ChapterTOC from '../components/ChapterTOC.astro';
+import SectionMap from '../components/SectionMap.astro';
 import ChapterNav from '../components/ChapterNav.astro';
 
 interface Props {
@@ -44,6 +45,39 @@ const articlePublished = (entry.data as { published?: Date }).published;
 const articleUpdated = (entry.data as { updated?: Date }).updated;
 const articleTags = ((entry.data as { tags?: string[] }).tags ?? []) as string[];
 const chapterImage = (entry.data as { image?: string }).image;
+
+// (#section-map): best-effort context label for the gutter section map, e.g.
+// "Part 2 · Ch 4" or "Week 1". All hierarchy fields are profile-dependent and
+// Zod-optional (academic carries part+week; tools/research-portfolio carry
+// part+chapter; minimal carries none), so each piece is included only when
+// present — the label is omitted entirely (undefined) when nothing is derivable.
+const dataAny = entry.data as {
+  part?: string | number;
+  chapter?: number;
+  week?: number;
+  layout?: 'default' | 'wide';
+};
+
+// 1d: per-page width knob. `layout` is Zod-optional on every profile schema
+// (closed enum 'default'|'wide'). Emit `data-layout` ONLY for a non-default
+// value so existing chapters (no `layout`, or `layout: default`) render the
+// attribute-free <article> byte-identically — `undefined` makes Astro drop the
+// attribute, and only `.prose[data-layout="wide"]` carries a rule in layout.css.
+const layoutMode =
+  dataAny.layout && dataAny.layout !== 'default' ? dataAny.layout : undefined;
+const labelParts: string[] = [];
+if (dataAny.part !== undefined && dataAny.part !== '') {
+  // Numeric part → "Part N"; string-enum part (academic, e.g. "foundations")
+  // → title-case it as-is.
+  labelParts.push(
+    typeof dataAny.part === 'number'
+      ? `Part ${dataAny.part}`
+      : dataAny.part.charAt(0).toUpperCase() + dataAny.part.slice(1),
+  );
+}
+if (dataAny.chapter !== undefined) labelParts.push(`Ch ${dataAny.chapter}`);
+else if (dataAny.week !== undefined) labelParts.push(`Week ${dataAny.week}`);
+const sectionMapLabel = labelParts.length > 0 ? labelParts.join(' · ') : undefined;
 ---
 
 <Base
@@ -62,9 +96,10 @@ const chapterImage = (entry.data as { image?: string }).image;
     )}
     {articleTags.map((t) => <meta property="article:tag" content={t} />)}
   </Fragment>
-  <article class="prose">
+  <article class="prose" data-layout={layoutMode}>
     <ChapterHeader data={entry.data} />
     <ChapterTOC headings={headings} />
+    <SectionMap headings={headings} label={sectionMapLabel} />
     <slot />
     <ChapterNav currentId={entry.id} />
   </article>

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.24.0",
+  "version": "4.25.0",
   "type": "module",
   "license": "MIT",
   "author": "Brandon Behring",
@@ -59,13 +59,17 @@
     "./components/Diagnostic.astro": "./components/Diagnostic.astro",
     "./components/Divergence.astro": "./components/Divergence.astro",
     "./components/DynConnect.astro": "./components/DynConnect.astro",
+    "./components/Epigraph.astro": "./components/Epigraph.astro",
+    "./components/EvidenceTag.astro": "./components/EvidenceTag.astro",
     "./components/ExampleBox.astro": "./components/ExampleBox.astro",
     "./components/Exercise.astro": "./components/Exercise.astro",
     "./components/ExerciseSolutions.astro": "./components/ExerciseSolutions.astro",
     "./components/Figure.astro": "./components/Figure.astro",
     "./components/InsightBox.astro": "./components/InsightBox.astro",
     "./components/KeyIdea.astro": "./components/KeyIdea.astro",
+    "./components/MarginFigure.astro": "./components/MarginFigure.astro",
     "./components/MarginNote.astro": "./components/MarginNote.astro",
+    "./components/Newthought.astro": "./components/Newthought.astro",
     "./components/NoteBox.astro": "./components/NoteBox.astro",
     "./components/ObjectiveMap.astro": "./components/ObjectiveMap.astro",
     "./components/OpenQuestion.astro": "./components/OpenQuestion.astro",
@@ -82,6 +86,7 @@
     "./components/Rationale.astro": "./components/Rationale.astro",
     "./components/Recovery.astro": "./components/Recovery.astro",
     "./components/ResultBox.astro": "./components/ResultBox.astro",
+    "./components/SectionMap.astro": "./components/SectionMap.astro",
     "./components/Sidebar.astro": "./components/Sidebar.astro",
     "./components/Sidenote.astro": "./components/Sidenote.astro",
     "./components/SkillBox.astro": "./components/SkillBox.astro",
@@ -111,6 +116,10 @@
       "types": "./dist/components/Flashcards.d.ts",
       "import": "./dist/components/Flashcards.mjs"
     },
+    "./components/SectionMap": {
+      "types": "./dist/components/SectionMap.d.ts",
+      "import": "./dist/components/SectionMap.mjs"
+    },
     "./components/WarnBox.astro": "./components/WarnBox.astro",
     "./components/WeekRef.astro": "./components/WeekRef.astro",
     "./components/WorkedExample.astro": "./components/WorkedExample.astro",
@@ -127,6 +136,7 @@
     "./styles/tool-filter.css": "./styles/tool-filter.css",
     "./styles/exam-runner.css": "./styles/exam-runner.css",
     "./styles/flashcards.css": "./styles/flashcards.css",
+    "./styles/section-map.css": "./styles/section-map.css",
     "./layouts/Base.astro": "./layouts/Base.astro",
     "./layouts/Chapter.astro": "./layouts/Chapter.astro",
     "./lib": {

package/recipes/04-component-library.md

@@ -65,8 +65,12 @@ Supported `type` values: `theorem`, `proposition`, `lemma`, `corollary`, `defini
 | `Cite` | Inline citation linked to `/references` | `<Cite key="gu2024mamba" page="3" />` |
 | `XRef` | Cross-reference to a labeled element | `<XRef id="thm:zoh-stability" />` |
 | `Figure` | Image/SVG + caption + id; local SVGs inline for a11y + dark mode (`alt`, `desc`) | `<Figure src="/figures/week04/eigenvalues.svg" caption="…" alt="…" id="fig-eig" />` |
-| `MarginNote` | Right-margin annotation (Tufte-style) | `<MarginNote>side comment</MarginNote>` |
-| `Sidenote` | Auto-numbered marginalia | `<Sidenote>numbered note</Sidenote>` |
+| `MarginFigure` | A `Figure` that **floats into the right gutter** (Tufte margin figure; ≥64rem, inline on mobile). Same props as `Figure`; rendering delegated to it. For full-bleed use `<Figure class="wide">` | `<MarginFigure src="/figures/week04/eig.svg" caption="…" alt="…" id="fig-eig-m" />` |
+| `MarginNote` | **Inline** colored callout in the text column (does **not** float to the margin, despite the name) — load-bearing aside the reader must see | `<MarginNote>side comment</MarginNote>` |
+| `Sidenote` | Auto-numbered Tufte marginalia that **floats into the right gutter** on desktop (inline on mobile) | `<Sidenote>numbered note</Sidenote>` |
+| `EvidenceTag` | Inline claim-confidence pill after a claim (`verified`/`inference`/`audit-corrected`) | `<EvidenceTag kind="verified" /> … <EvidenceTag kind="inference" />` |
+| `Newthought` | Tufte run-in small-caps section opener | `<p><Newthought>In practice</Newthought>, …</p>` |
+| `Epigraph` | Chapter-opening italic quotation with right-aligned attribution | `<Epigraph>…<Fragment slot="attribution">Hamming</Fragment></Epigraph>` |
 | `WeekRef` | Jump-link to a week chapter | `<WeekRef week={4} />` |
 | `CodeRef` | GitHub-deep-link to file:line | `<CodeRef path="experiments/jax/foo.py" line={42} />` |
 | `CodeBlock` | Embed code-file range with syntax highlight | `<CodeBlock src="…" lines="10-30" />` |

package/recipes/16-tikz-figures.md

@@ -95,6 +95,45 @@ Common failures:
 
 If you hit friction with the TikZ pipeline (a TikZ feature that doesn't compile, an obscure error message, a workflow pattern that doesn't fit), file an issue at https://github.com/brandon-behring/book-scaffold-astro/issues with the `consumer:<your-workspace>` label. v4.x is the iteration window.
 
+## Margin & full-width figure placement (1d)
+
+Once a figure exists, three placements are available — all reuse the existing Tufte float + gutter technique (the same one `Sidenote`/SectionMap use); none introduce a grid.
+
+**In the running text (default).** Plain `<Figure>` constrained to the main measure:
+
+```mdx
+<Figure src="/figures/topic/diagram.svg" caption="…" alt="…" id="fig-x" />
+```
+
+**In the right margin** — `<MarginFigure>` floats into the gutter at ≥64rem and reflows inline below on mobile. Same props as `<Figure>` (rendering is delegated to it); `width` defaults to `100%` of the ~28ch gutter column, and the caption shrinks:
+
+```mdx
+import MarginFigure from '@brandon_m_behring/book-scaffold-astro/components/MarginFigure.astro';
+
+<MarginFigure src="/figures/topic/diagram.svg" caption="A small aside figure." alt="…" id="fig-x-margin" />
+```
+
+**Full-bleed** — a wide figure/table/code block that spans the gutter column too. Use the canonical `.wide` escape (or its alias `.column-page`):
+
+```mdx
+<Figure src="/figures/topic/wide-plot.svg" caption="…" alt="…" id="fig-wide" class="wide" />
+```
+
+**Generic gutter block** — to float a non-figure block (a small note, a key figure number) into the margin, add `class="column-margin"` to any element. It uses the identical gutter float.
+
+### Per-page width knob: `layout: wide`
+
+For a chapter that's figure- or table-heavy, widen the **main text measure** via an optional frontmatter field (closed enum `default` | `wide`, accepted by every profile):
+
+```yaml
+---
+title: "Architecture Atlas"
+layout: wide      # widens --measure-main to 80ch; omit (or 'default') for the standard 65ch
+---
+```
+
+`Chapter.astro` threads this as `data-layout="wide"` on `<article class="prose">`, and `layout.css` maps `.prose[data-layout="wide"] { --measure-main: 80ch }`. Omitting the field (or setting `layout: default`) emits no attribute and applies no rule — existing chapters render unchanged. A value outside the enum fails the build at content load.
+
 ## See also
 
 - `recipes/06-figures.md` — overall figure pipeline + matplotlib/svg sources