@brandon_m_behring/book-scaffold-astro 4.26.0 → 4.26.3

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { AstroUserConfig, AstroIntegration, MarkdownHeading } from 'astro';
-import { c as BookConfigOptions, f as BookScaffoldIntegrationOptions, h as ChaptersRenderer, l as Style } from './types-BO5qyDqT.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-BO5qyDqT.js';
+import { c as BookConfigOptions, f as BookScaffoldIntegrationOptions, h as ChaptersRenderer, m as Style } from './types-CWXP1S4b.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 ReleaseStatusConfig, l as RouteToggles, S as StatusBadge, n as StyleInput, V as VolatilityBadge, o as composeStyles, p as defineProfile, q as defineStyle, r as normalizeFrontmatterConfig, s as resolvePreset, t as resolveProfile } from './types-CWXP1S4b.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';
@@ -144,18 +144,31 @@ declare const academicChaptersRenderer: ChaptersRenderer;
 
 /**
  * src/profiles/renderers/fallback-chapters.ts — ChaptersRenderer used by
- * profiles that don't ship a dedicated renderer (minimal, course-notes,
- * research-portfolio). Dispatches by field presence — exactly the v3.5.2
+ * profiles that don't ship a dedicated renderer (minimal, course-notes).
+ * Dispatches by field presence — exactly the v3.5.2
  * logic that lived inline in pages/chapters.astro before #35.
  *
  * Safety net for shapes we haven't designed for explicitly. If a consumer
- * opts a course-notes or research-portfolio book into `routes.chapters: true`,
+ * opts a course-notes book into `routes.chapters: true`,
  * the fallback renders reasonably without crashing. Custom output for those
  * profiles is a v4+ extension point (consumer-overridable renderer).
  */
 
 declare const fallbackChaptersRenderer: ChaptersRenderer;
 
+/**
+ * Research-portfolio /chapters renderer.
+ *
+ * The portfolio schema intentionally permits numeric Parts through 20. The
+ * generic fallback renderer inherits the tools profile's historical
+ * `part >= 6` appendix convention, which mislabels a portfolio's sixth Part
+ * as "Appendices" and its chapters as Appendix a/b/.... Keep the fallback's
+ * field-shape dispatch for every other affordance, but make numeric Parts
+ * ordinary numbered Parts throughout the portfolio schema's full range.
+ */
+
+declare const researchPortfolioChaptersRenderer: ChaptersRenderer;
+
 /**
  * src/lib/academic-parts.ts — single source of truth for academic-profile
  * part labels (#95).
@@ -598,4 +611,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, type ChapterLike, 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, apparatusHref, assertEnumProp, assertKnownDomain, bookOf, bookScaffoldIntegration, buildGithubUrl, chapterHref, chapterLabel, chapterSortKey, courseNotesStyle, defineBookConfig, defineMdxComponents, defineTips, deriveObjectiveMap, distinctChaptersSorted, fallbackChaptersRenderer, freshnessLabel, getFreshness, groupByChapter, groupByDomain, isCurrentChapter, minimalStyle, originUrlFromGitConfig, parseRepoSlug, pickActive, researchPortfolioStyle, resolveBookHref, resolveGithubRepo, selectPartExercises, slugOf, sortQuestions, tocHeadings, toolsChaptersRenderer, toolsStyle, volatilityLevels };
+export { ACADEMIC_PART_NAMES, BRANDON_PORTFOLIO_DEFAULT, BUILTIN_STYLES, BookConfigOptions, BookScaffoldIntegrationOptions, type ChapterLike, 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, apparatusHref, assertEnumProp, assertKnownDomain, bookOf, bookScaffoldIntegration, buildGithubUrl, chapterHref, chapterLabel, chapterSortKey, courseNotesStyle, defineBookConfig, defineMdxComponents, defineTips, deriveObjectiveMap, distinctChaptersSorted, fallbackChaptersRenderer, freshnessLabel, getFreshness, groupByChapter, groupByDomain, isCurrentChapter, minimalStyle, originUrlFromGitConfig, parseRepoSlug, pickActive, researchPortfolioChaptersRenderer, researchPortfolioStyle, resolveBookHref, resolveGithubRepo, selectPartExercises, slugOf, sortQuestions, tocHeadings, toolsChaptersRenderer, toolsStyle, volatilityLevels };

package/dist/index.mjs

@@ -851,6 +851,17 @@ var courseNotesProfile = defineProfile({
   sitemapFilter: (page) => !page.includes("/print/")
 });
 
+// src/profiles/renderers/research-portfolio-chapters.ts
+var researchPortfolioChaptersRenderer = {
+  ...fallbackChaptersRenderer,
+  formatPartLabel(part) {
+    return typeof part === "number" ? `Part ${part}` : fallbackChaptersRenderer.formatPartLabel(part);
+  },
+  isAppendix(_part) {
+    return false;
+  }
+};
+
 // src/profiles/research-portfolio.ts
 var researchPortfolioProfile = defineProfile({
   name: "research-portfolio",
@@ -883,8 +894,9 @@ var researchPortfolioProfile = defineProfile({
   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
-  chaptersRenderer: fallbackChaptersRenderer
+  // Portfolio schema is a union of academic + tools shapes, but unlike the
+  // tools profile its numeric Parts remain numbered through the schema max 20.
+  chaptersRenderer: researchPortfolioChaptersRenderer
 });
 
 // src/profiles/index.ts
@@ -971,6 +983,9 @@ function composeStyles(styles) {
     if (style.preset !== void 0) merged.preset = style.preset;
     if (style.site !== void 0) merged.site = style.site;
     if (style.deploy !== void 0) merged.deploy = style.deploy;
+    if (style.releaseStatus !== void 0) {
+      merged.releaseStatus = style.releaseStatus;
+    }
     if (style.mdxComponentsModule !== void 0) {
       merged.mdxComponentsModule = style.mdxComponentsModule;
     }
@@ -1199,6 +1214,7 @@ function bookScaffoldIntegration(opts) {
     // v4.5.0: landing-page data, propagated via virtual module to /index.astro.
     title,
     subtitle,
+    releaseStatus,
     description,
     portfolio,
     // v4.6.0: book-level author + SEO config, propagated through the
@@ -1268,6 +1284,7 @@ function bookScaffoldIntegration(opts) {
               makeBookConfigVitePlugin({
                 title: title ?? null,
                 subtitle: subtitle ?? null,
+                releaseStatus: releaseStatus ?? null,
                 description: description ?? null,
                 portfolio: portfolio ?? false,
                 enabledRoutes: enabledRouteNames,
@@ -1364,6 +1381,7 @@ async function defineBookConfig(opts) {
   const mdxComponentsModule = opts.mdxComponentsModule ?? composed.mdxComponentsModule;
   const composedMarkdown = composed.markdown ?? {};
   const userMarkdown = opts.markdown ?? {};
+  const resolvedReleaseStatus = opts.releaseStatus !== void 0 ? opts.releaseStatus : composed.releaseStatus;
   const wantsKatex = PROFILES[profile]?.katex === true;
   const remarkPlugins = [];
   const rehypePlugins = [];
@@ -1413,6 +1431,8 @@ async function defineBookConfig(opts) {
       title: opts.title,
       // v4.23.0 (#135): sidebar brand subtitle.
       subtitle: opts.subtitle,
+      // v4.26.2 (#149; style inheritance + opt-out fixed in v4.26.3).
+      releaseStatus: resolvedReleaseStatus === false ? void 0 : resolvedReleaseStatus,
       description: opts.description,
       portfolio: resolvedPortfolio,
       // v4.6.0: book-level author + SEO config (ogImage, twitterHandle),
@@ -1470,6 +1490,8 @@ async function defineBookConfig(opts) {
     // v4.5.0: strip new landing-related opts so they don't leak into AstroUserConfig.
     title: _title,
     subtitle: _subtitle,
+    // v4.26.2 (#149): strip the release-state banner config.
+    releaseStatus: _releaseStatus,
     description: _description,
     portfolio: _portfolio,
     // v4.6.0: strip new book-level SEO opts (author + seo block).
@@ -1500,6 +1522,7 @@ async function defineBookConfig(opts) {
   void _katexMacros;
   void _title;
   void _subtitle;
+  void _releaseStatus;
   void _description;
   void _portfolio;
   void _author;
@@ -1953,6 +1976,7 @@ export {
   refineQuestion,
   refinedQuestionSchema,
   researchPortfolioChapterSchema,
+  researchPortfolioChaptersRenderer,
   researchPortfolioStyle,
   resolveBookHref,
   resolveGithubRepo,

package/dist/schemas.d.ts

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

package/dist/schemas.mjs

@@ -729,6 +729,17 @@ var courseNotesProfile = defineProfile({
   sitemapFilter: (page) => !page.includes("/print/")
 });
 
+// src/profiles/renderers/research-portfolio-chapters.ts
+var researchPortfolioChaptersRenderer = {
+  ...fallbackChaptersRenderer,
+  formatPartLabel(part) {
+    return typeof part === "number" ? `Part ${part}` : fallbackChaptersRenderer.formatPartLabel(part);
+  },
+  isAppendix(_part) {
+    return false;
+  }
+};
+
 // src/profiles/research-portfolio.ts
 var researchPortfolioProfile = defineProfile({
   name: "research-portfolio",
@@ -761,8 +772,9 @@ var researchPortfolioProfile = defineProfile({
   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
-  chaptersRenderer: fallbackChaptersRenderer
+  // Portfolio schema is a union of academic + tools shapes, but unlike the
+  // tools profile its numeric Parts remain numbered through the schema max 20.
+  chaptersRenderer: researchPortfolioChaptersRenderer
 });
 
 // src/profiles/index.ts

package/dist/{types-BO5qyDqT.d.ts → types-CWXP1S4b.d.ts}

@@ -379,6 +379,12 @@ interface Style {
      *  - `'pages'`: Cloudflare Pages (default for research-portfolio/course-notes)
      *  Closes #50. */
     readonly deploy?: 'pages' | 'workers';
+    /**
+     * v4.26.2 (#149; style inheritance fixed in v4.26.3): release-state
+     * banner. Shallow override (last defined wins); `false` suppresses a
+     * banner inherited from an earlier style.
+     */
+    readonly releaseStatus?: ReleaseStatusConfig | false;
     /**
      * Scoped consumer-side metadata. Ignored by the toolkit; survives composition
      * as per-key spread (last wins per key). Use this for workflow data that
@@ -439,7 +445,8 @@ declare function defineStyle(opts: StyleInput): Style;
  *   - Top-level `defineBookConfig` fields beat any style (handled in config.ts)
  *
  * Per-key merge strategy:
- *   - `preset`, `site`, `deploy`, `mdxComponentsModule`, `name` → shallow override (last wins)
+ *   - `preset`, `site`, `deploy`, `mdxComponentsModule`, `name`, `releaseStatus`
+ *     → shallow override (last defined wins; `releaseStatus: false` suppresses)
  *   - `routes` → per-route spread (each route key independently overridable)
  *   - `katexMacros` → per-macro spread (each macro key independently overridable)
  *   - `extra` → per-key spread (consumer metadata accumulates across the chain)
@@ -475,6 +482,17 @@ declare function normalizeFrontmatterConfig(v: FrontmatterRouteConfig | undefine
 
 type BookPreset = BookProfile;
 declare const BOOK_PRESETS: readonly ("academic" | "tools" | "minimal" | "course-notes" | "research-portfolio")[];
+/**
+ * v4.26.2 (#149): book-level release state rendered by
+ * `<PreReleaseBanner>` across every page.
+ *
+ * Style inheritance and explicit suppression were fixed in v4.26.3.
+ */
+interface ReleaseStatusConfig {
+    state: 'alpha' | 'beta' | 'rc' | 'locked';
+    dismissAt?: string;
+    message?: string;
+}
 /**
  * Options for `defineBookConfig`. See PACKAGE_DESIGN.md §4.
  *
@@ -600,6 +618,13 @@ interface BookConfigOptions {
      * hardcoded both strings, so every consumer shipped the placeholder).
      */
     subtitle?: string;
+    /**
+     * v4.26.2 (#149; style inheritance fixed in v4.26.3): book-level release
+     * state. When set, Base.astro renders the existing <PreReleaseBanner>
+     * site-wide (top of <body>) with these props. Omit to inherit from the
+     * composed style chain; set `false` to suppress an inherited banner.
+     */
+    releaseStatus?: ReleaseStatusConfig | false;
     /**
      * v4.5.0: Book description. Read by the auto-injected `/` landing page (lead paragraph + <meta description>).
      * Optional; landing renders no description paragraph if unset.
@@ -752,6 +777,9 @@ interface BookScaffoldIntegrationOptions {
     /** v4.23.0 (#135): sidebar brand subtitle, propagated via the book-config
      *  virtual module to Sidebar.astro. */
     subtitle?: string;
+    /** v4.26.2 (#149; style inheritance fixed in v4.26.3): resolved
+     *  release-state banner propagated via the book-config virtual module. */
+    releaseStatus?: ReleaseStatusConfig;
     /** v4.5.0: book description, propagated to `/` landing via vite.define. */
     description?: string;
     /**
@@ -827,4 +855,4 @@ declare function resolvePreset(explicitPreset?: BookPreset, explicitProfile?: Bo
  */
 declare function resolveProfile(explicit?: BookProfile): BookProfile;
 
-export { BOOK_PRESETS as B, type ChapterFor as C, type FreshnessAffordance as F, type PartKey as P, type RouteToggles as R, type StatusBadge as S, type VolatilityBadge as V, BOOK_PROFILES as a, BookConfigError as b, type BookConfigOptions as c, type BookPreset as d, type BookProfile as e, type BookScaffoldIntegrationOptions as f, type BookSchemasOptions as g, type ChaptersRenderer as h, type FrontmatterRouteConfig as i, type PartialRouteToggles as j, type ProfileDefinition as k, type Style as l, type StyleInput as m, composeStyles as n, defineProfile as o, defineStyle as p, normalizeFrontmatterConfig as q, resolvePreset as r, resolveProfile as s };
+export { BOOK_PRESETS as B, type ChapterFor as C, type FreshnessAffordance as F, type PartKey as P, type ReleaseStatusConfig as R, type StatusBadge as S, type VolatilityBadge as V, BOOK_PROFILES as a, BookConfigError as b, type BookConfigOptions as c, type BookPreset as d, type BookProfile as e, type BookScaffoldIntegrationOptions as f, type BookSchemasOptions as g, type ChaptersRenderer as h, type FrontmatterRouteConfig as i, type PartialRouteToggles as j, type ProfileDefinition as k, type RouteToggles as l, type Style as m, type StyleInput as n, composeStyles as o, defineProfile as p, defineStyle as q, normalizeFrontmatterConfig as r, resolvePreset as s, resolveProfile as t };

package/layouts/Base.astro

@@ -59,6 +59,9 @@ import '../styles/print.css';
 import VersionSelector from '@brandon_m_behring/book-scaffold-astro/components/VersionSelector';
 import ToolFilter from '@brandon_m_behring/book-scaffold-astro/components/ToolFilter';
 import Sidebar from '../components/Sidebar.astro';
+// v4.26.2 (#149; style inheritance fixed in v4.26.3): site-wide
+// release-state banner, driven by defineBookConfig.
+import PreReleaseBanner from '../components/PreReleaseBanner.astro';
 // v4.26.0 (#80): the mobile/tablet drawer reuses the same book-scoped nav source.
 import NavContent from '../components/NavContent.astro';
 // v4.6.0: SEO meta tags read book-level identity (title fallback,
@@ -165,6 +168,16 @@ const baseUrl = (import.meta.env.BASE_URL ?? '/').replace(/\/*$/, '/');
     <slot name="head" />
   </head>
   <body>
+    {/* v4.26.2 (#149; style inheritance fixed in v4.26.3): book-level release banner — first element in <body> so
+        every page (chapters, apparatus, landing) declares its state. Renders
+        only when defineBookConfig({ releaseStatus }) is set. */}
+    {bookConfig.releaseStatus && (
+      <PreReleaseBanner
+        state={bookConfig.releaseStatus.state}
+        dismissAt={bookConfig.releaseStatus.dismissAt}
+        message={bookConfig.releaseStatus.message}
+      />
+    )}
     <div class="chrome-buttons">
       {/* v4.26.0 (#80): hamburger → mobile/tablet nav drawer. <a href="#nav-drawer">
           so it opens via :target with no JS; the controller below enhances it. */}

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.26.0",
+  "version": "4.26.3",
   "type": "module",
   "license": "MIT",
   "author": "Brandon Behring",

package/recipes/15-defining-styles.md

@@ -122,7 +122,8 @@ Different fields have different merge semantics. Documented:
 
 | Field | Strategy |
 |---|---|
-| `name`, `preset`, `site`, `deploy`, `mdxComponentsModule` | Shallow override (last wins) |
+| `name`, `preset`, `site`, `deploy`, `mdxComponentsModule` | Shallow override (last defined wins) |
+| `releaseStatus` | Shallow override (last defined object replaces the whole earlier object); `false` suppresses an inherited banner |
 | `routes` | Per-route spread (each route key independently overridable) |
 | `routes.frontmatter` | Per-route spread; later value (boolean OR object) wholly replaces earlier |
 | `katexMacros` | Object spread (per-macro override) |

package/src/lib/define-style.ts

@@ -27,7 +27,7 @@
  * for migration from the v3 `preset:` shorthand.
  */
 import type { AstroIntegration, AstroUserConfig } from 'astro';
-import type { BookPreset, RouteToggles } from '../types.js';
+import type { BookPreset, ReleaseStatusConfig, RouteToggles } from '../types.js';
 
 // ===== Branded nominal type =====
 
@@ -123,6 +123,12 @@ export interface Style {
    *  - `'pages'`: Cloudflare Pages (default for research-portfolio/course-notes)
    *  Closes #50. */
   readonly deploy?: 'pages' | 'workers';
+  /**
+   * v4.26.2 (#149; style inheritance fixed in v4.26.3): release-state
+   * banner. Shallow override (last defined wins); `false` suppresses a
+   * banner inherited from an earlier style.
+   */
+  readonly releaseStatus?: ReleaseStatusConfig | false;
 
   /**
    * Scoped consumer-side metadata. Ignored by the toolkit; survives composition
@@ -193,7 +199,8 @@ export function defineStyle(opts: StyleInput): Style {
  *   - Top-level `defineBookConfig` fields beat any style (handled in config.ts)
  *
  * Per-key merge strategy:
- *   - `preset`, `site`, `deploy`, `mdxComponentsModule`, `name` → shallow override (last wins)
+ *   - `preset`, `site`, `deploy`, `mdxComponentsModule`, `name`, `releaseStatus`
+ *     → shallow override (last defined wins; `releaseStatus: false` suppresses)
  *   - `routes` → per-route spread (each route key independently overridable)
  *   - `katexMacros` → per-macro spread (each macro key independently overridable)
  *   - `extra` → per-key spread (consumer metadata accumulates across the chain)
@@ -216,6 +223,9 @@ export function composeStyles(styles: readonly Style[]): Style {
     if (style.preset !== undefined) merged.preset = style.preset;
     if (style.site !== undefined) merged.site = style.site;
     if (style.deploy !== undefined) merged.deploy = style.deploy;
+    if (style.releaseStatus !== undefined) {
+      merged.releaseStatus = style.releaseStatus;
+    }
     if (style.mdxComponentsModule !== undefined) {
       merged.mdxComponentsModule = style.mdxComponentsModule;
     }

package/src/profiles/renderers/fallback-chapters.ts

@@ -1,11 +1,11 @@
 /**
  * src/profiles/renderers/fallback-chapters.ts — ChaptersRenderer used by
- * profiles that don't ship a dedicated renderer (minimal, course-notes,
- * research-portfolio). Dispatches by field presence — exactly the v3.5.2
+ * profiles that don't ship a dedicated renderer (minimal, course-notes).
+ * Dispatches by field presence — exactly the v3.5.2
  * logic that lived inline in pages/chapters.astro before #35.
  *
  * Safety net for shapes we haven't designed for explicitly. If a consumer
- * opts a course-notes or research-portfolio book into `routes.chapters: true`,
+ * opts a course-notes book into `routes.chapters: true`,
  * the fallback renders reasonably without crashing. Custom output for those
  * profiles is a v4+ extension point (consumer-overridable renderer).
  */

package/src/profiles/renderers/research-portfolio-chapters.ts

@@ -0,0 +1,26 @@
+/**
+ * Research-portfolio /chapters renderer.
+ *
+ * The portfolio schema intentionally permits numeric Parts through 20. The
+ * generic fallback renderer inherits the tools profile's historical
+ * `part >= 6` appendix convention, which mislabels a portfolio's sixth Part
+ * as "Appendices" and its chapters as Appendix a/b/.... Keep the fallback's
+ * field-shape dispatch for every other affordance, but make numeric Parts
+ * ordinary numbered Parts throughout the portfolio schema's full range.
+ */
+import type { ChaptersRenderer } from '../../lib/chapters-renderer.js';
+import { fallbackChaptersRenderer } from './fallback-chapters.js';
+
+export const researchPortfolioChaptersRenderer: ChaptersRenderer = {
+  ...fallbackChaptersRenderer,
+
+  formatPartLabel(part) {
+    return typeof part === 'number'
+      ? `Part ${part}`
+      : fallbackChaptersRenderer.formatPartLabel(part);
+  },
+
+  isAppendix(_part) {
+    return false;
+  },
+};

package/src/profiles/research-portfolio.ts

@@ -22,7 +22,7 @@
  */
 import { defineProfile } from '../profile-kit.js';
 import { researchPortfolioChapterSchema } from '../schemas.js';
-import { fallbackChaptersRenderer } from './renderers/fallback-chapters.js';
+import { researchPortfolioChaptersRenderer } from './renderers/research-portfolio-chapters.js';
 
 export type { ResearchPortfolioChapter } from '../schemas.js';
 
@@ -46,6 +46,7 @@ export const researchPortfolioProfile = defineProfile({
   },
   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
-  chaptersRenderer: fallbackChaptersRenderer,
+  // Portfolio schema is a union of academic + tools shapes, but unlike the
+  // tools profile its numeric Parts remain numbered through the schema max 20.
+  chaptersRenderer: researchPortfolioChaptersRenderer,
 });

package/styles/chapter.css

@@ -244,4 +244,15 @@
   overflow-x: auto;
   /* a little room so the horizontal scrollbar doesn't clip the equation's descenders */
   padding-block-end: 0.25rem;
+  /* Edge scroll-shadow when a wide equation scrolls (v4.25.3; docs/responsive-reading.md).
+   * Same Lea Verou layered technique as code blocks, page-bg covers. */
+  background-image:
+    linear-gradient(to right, var(--color-bg) 30%, rgba(0, 0, 0, 0)),
+    linear-gradient(to right, rgba(0, 0, 0, 0), var(--color-bg) 70%),
+    radial-gradient(farthest-side at 0 50%, rgba(0, 0, 0, 0.12), rgba(0, 0, 0, 0)),
+    radial-gradient(farthest-side at 100% 50%, rgba(0, 0, 0, 0.12), rgba(0, 0, 0, 0));
+  background-position: 0 0, 100% 0, 0 0, 100% 0;
+  background-repeat: no-repeat;
+  background-size: 30px 100%, 30px 100%, 12px 100%, 12px 100%;
+  background-attachment: local, local, scroll, scroll;
 }

package/styles/tokens.css

@@ -108,6 +108,7 @@
    */
   --measure-main: 60ch;        /* default: main+gutter fits beside the sidebar at ≥64rem (v4.26.0, #80) */
   --measure-side: 20ch;        /* right-margin sidenote / section-map column */
+  --measure-code: 48rem;       /* code-block break-out width: fits 80-char lines comfortably (≈88 mono chars @14px before padding); docs/responsive-reading.md */
   --breakpoint-narrow: 48rem;  /* ~768px — mobile fold (sidenotes inline) */
   --breakpoint-wide: 90rem;    /* ~1440px — wide-desktop tier */
   --breakpoint-ultrawide: 120rem; /* ~1920px — ultrawide tier */

package/styles/typography.css

@@ -89,6 +89,43 @@ pre code {
   font-size: var(--text-sm);
 }
 
+/* ===== Responsive reading (v4.25.3) — docs/responsive-reading.md =====
+ * Code blocks break out past the prose text measure to fit ~80-char lines,
+ * capped at --measure-code and centered within .prose. CONTAINER-bounded, not
+ * viewport-bounded: the width comes from the .prose column itself, so a left
+ * sidebar offset + the scrollbar gutter can never push the block into horizontal
+ * PAGE scroll. (The earlier `width: min(100vw - …)` overflowed ~8px at the
+ * 1024px sidebar boundary — #171 review finding A1, guarded by
+ * gallery/tests/fixtures/layout-overflow.spec.ts.) `.wide`/`.column-page` keep
+ * their full-bleed behavior (excluded here). */
+.prose > pre:not(.wide):not(.column-page) {
+  max-width: var(--measure-code);
+  margin-inline: auto;
+  /* Lea Verou layered scroll-shadow: bg-colored covers move with content
+   * (attachment:local); shadow layers are fixed → shown only when scrollable. */
+  background-image:
+    linear-gradient(to right, var(--color-code-bg) 30%, rgba(0, 0, 0, 0)),
+    linear-gradient(to right, rgba(0, 0, 0, 0), var(--color-code-bg) 70%),
+    radial-gradient(farthest-side at 0 50%, rgba(0, 0, 0, 0.18), rgba(0, 0, 0, 0)),
+    radial-gradient(farthest-side at 100% 50%, rgba(0, 0, 0, 0.18), rgba(0, 0, 0, 0));
+  background-position: 0 0, 100% 0, 0 0, 100% 0;
+  background-repeat: no-repeat;
+  background-size: 40px 100%, 40px 100%, 14px 100%, 14px 100%;
+  background-attachment: local, local, scroll, scroll;
+}
+/* Phone (≤40rem): shrink code a touch so more fits before scrolling. Tighter
+ * than the 48rem mobile/table breakpoint below — phones benefit from the smaller
+ * glyphs; tablets (40–48rem) keep the full size. */
+@media (max-width: 40rem) {
+  pre code { font-size: 0.75rem; }
+}
+/* Mobile: scroll a wide table within its own block instead of overflowing the
+ * page. Sticky thead intentionally NOT used — it can't stick inside a
+ * horizontal-scroll wrapper (CSS limitation; see docs/responsive-reading.md). */
+@media (max-width: 48rem) {
+  .prose table { display: block; max-width: 100%; overflow-x: auto; }
+}
+
 /* ===== Links ===== */
 a {
   color: var(--color-link);