@brandon_m_behring/book-scaffold-astro 4.25.3 → 4.26.2

package/recipes/22-responsive-nav-and-multibook-routing.md

@@ -0,0 +1,92 @@
+# Recipe 22 — Responsive navigation & multi-book routing (v4.26.0, #80)
+
+The scaffold's navigation (left `Sidebar`, prev/next `ChapterNav`) is **book-aware**
+and **responsive**: it serves a single-book site unchanged, a multi-book consumer
+(one Astro app at `/<book>/<slug>/`) correctly, and adds a mobile/tablet drawer.
+
+## Single-book — zero config (byte-identical)
+
+Do nothing. The defaults reproduce the pre-4.26 behavior:
+
+- chapter links are `${BASE_URL}chapters/<id>/`,
+- the sidebar lists every chapter, prev/next walk the full collection,
+- you additionally get a **mobile drawer** for free (hamburger in the chrome row,
+  below 80rem), where the auto-hidden sidebar previously left no nav.
+
+## Multi-book — four `defineBookConfig` fields
+
+For a consumer that owns `/[book]/[...chapter]` routing and serves chapters at
+`/<book>/<slug>/` (each chapter's `entry.id` is `'<book>/<slug>'` and carries a
+`book` frontmatter field):
+
+```js
+// astro.config.mjs
+export default await defineBookConfig({
+  // … styles, routes, etc. …
+  chapterRoute: '/:id/',                 // entry.id is '<book>/<slug>' → '/<book>/<slug>/'
+  bookField: 'book',                     // scope sidebar/drawer/prev-next to the current book
+  apparatusRoute: '/:book/:route/',      // → '/<book>/practice-exam/', etc.
+  apparatusRoutes: ['practice-exam', 'glossary', 'flashcards', 'answers'],
+});
+```
+
+Tokens (base-relative; `BASE_URL` is applied for you):
+
+| token   | value                                   |
+|---------|-----------------------------------------|
+| `:id`   | `entry.id` verbatim (slashes kept)      |
+| `:book` | the entry's book (`bookField`), or `''` |
+| `:slug` | `entry.id` minus the leading `<book>/`  |
+| `:route`| an apparatus route slug                 |
+
+The nav then:
+
+- lists **only the current book's** chapters (the current book is derived from the
+  URL's first path segment, validated against the books that exist),
+- emits `/<book>/<slug>/` links and highlights the current chapter (`aria-current`),
+- keeps prev/next **within the current book** (`getNeighbors` is book-scoped),
+- surfaces the per-book apparatus links from `apparatusRoutes`.
+
+**Landing pages** (a multi-book corpus front door) should pass
+`showSidebar={false}` to `Base` — there is no "current book" there, so the chapter
+nav would otherwise fall back to the single-book all-chapters list.
+
+## The mobile/tablet drawer
+
+Below **80rem (1280px)** the full 3-column layout doesn't fit beside the sidebar,
+so the sidebar is replaced by a slide-in **drawer** reached from a hamburger in
+the chrome row. It reuses `NavContent` (the same book-scoped nav), is a
+`role="dialog"` with focus-trap / ESC / backdrop close (an inline controller in
+`Base.astro`), and degrades to a `:target` CSS open with **no JS**. Nothing to
+configure — it appears automatically wherever the sidebar is enabled.
+
+## The Tufte right-gutter ("on this page" scrollspy)
+
+The floated gutter scrollspy (`SectionMap`) + sidenotes need room the sidebar
+steals, so the **full 3-column activates at ≥80rem (1280px)**. Below that the
+drawer is the nav and the collapsed in-flow `ChapterTOC` is the "on this page".
+The shared text measure (`--measure-main` / `--measure-side`, `tokens.css`) is
+tuned so `main + gutter` fits inside `viewport − sidebar` at every desktop width
+— the scrollspy **fits**, it is not hidden. (BC note: single-book sidebar
+consumers see the sidebar + scrollspy from 1280px up, was 1024px, with a slightly
+narrower body measure.)
+
+## Owning your own route components
+
+The resolver is exported for consumers who render their own nav (recipe 18):
+
+```ts
+import { chapterHref, apparatusHref, bookOf, isCurrentChapter }
+  from '@brandon_m_behring/book-scaffold-astro';
+```
+
+Pure functions, no `astro:content` — pass a `{ id, data }` and the same
+`chapterRoute` / `bookField` you set in `defineBookConfig`.
+
+## Verify
+
+A consumer should drive a cross-device audit (Playwright is ideal): for each rich
+page across `{390, 768, 1024, 1440}` × `{light, dark}`, assert no horizontal page
+overflow (`scrollWidth ≤ clientWidth`), a visible sidebar ≥1280 / hamburger+drawer
+below, and that no nav link points outside the current book. See the
+`dlai-study-notes` consumer's `tests/responsive.spec.ts` for a worked harness.

package/src/lib/chapters.ts

@@ -11,6 +11,7 @@
  */
 import { getCollection, type CollectionEntry } from 'astro:content';
 import { chapterSortKey } from './chapter-sort.js';
+import { bookOf } from './nav-href.js';
 
 export type Chapter = CollectionEntry<'chapters'>;
 
@@ -27,18 +28,30 @@ export async function getAllChapters(): Promise<Chapter[]> {
 }
 
 /**
- * Given a chapter id, return its ordered neighbors.
- * Either may be null at the edges of the book.
+ * Given a chapter id, return its ordered neighbors. Either may be null at the
+ * edges of the book.
+ *
+ * v4.26.0 (#80): book-aware. When the entry carries a book (multi-book consumer,
+ * `data[bookField]`), neighbors are scoped to the SAME book so prev/next never
+ * bleed across books. Single-book schemas have no book field → no scoping → the
+ * pre-4.26 global ordering (byte-identical BC).
  */
-export async function getNeighbors(id: string): Promise<{
-  prev: Chapter | null;
-  next: Chapter | null;
-}> {
+export async function getNeighbors(
+  id: string,
+  opts: { bookField?: string } = {},
+): Promise<{ prev: Chapter | null; next: Chapter | null }> {
+  const { bookField = 'book' } = opts;
   const all = await getAllChapters();
-  const idx = all.findIndex((c) => c.id === id);
+  const self = all.find((c) => c.id === id);
+  if (!self) return { prev: null, next: null };
+  const selfBook = bookOf({ id: self.id, data: self.data as Record<string, unknown> }, bookField);
+  const scoped = selfBook
+    ? all.filter((c) => bookOf({ id: c.id, data: c.data as Record<string, unknown> }, bookField) === selfBook)
+    : all;
+  const idx = scoped.findIndex((c) => c.id === id);
   if (idx === -1) return { prev: null, next: null };
   return {
-    prev: idx > 0 ? all[idx - 1] : null,
-    next: idx < all.length - 1 ? all[idx + 1] : null,
+    prev: idx > 0 ? scoped[idx - 1]! : null,
+    next: idx < scoped.length - 1 ? scoped[idx + 1]! : null,
   };
 }

package/src/lib/define-style.ts

@@ -123,6 +123,8 @@ export interface Style {
    *  - `'pages'`: Cloudflare Pages (default for research-portfolio/course-notes)
    *  Closes #50. */
   readonly deploy?: 'pages' | 'workers';
+  /** v4.27.0 (#149): release-state banner; shallow override (last wins). */
+  readonly releaseStatus?: { state: 'alpha' | 'beta' | 'rc' | 'locked'; dismissAt?: string; message?: string };
 
   /**
    * Scoped consumer-side metadata. Ignored by the toolkit; survives composition

package/src/lib/nav-href.ts

@@ -0,0 +1,100 @@
+/**
+ * src/lib/nav-href.ts — pure route-href resolver (#80 multi-book navigation).
+ *
+ * No `astro:content` import (mirrors chapter-sort.ts) so tsup can include it in
+ * the DTS bundle without dragging Astro virtual modules into the build graph.
+ * The nav components (Sidebar, ChapterNav, NavContent, …) call these helpers
+ * instead of hardcoding the single-book `/chapters/<id>/` URL shape — so ONE set
+ * of components serves both a single-book site (the default pattern) and a
+ * multi-book consumer whose chapters render at `/<book>/<slug>/`.
+ *
+ * Patterns are base-relative TOKEN STRINGS (a resolver *function* could not
+ * survive the book-config virtual module's `JSON.stringify`, so the config
+ * surface is a declarative string resolved here):
+ *   :id   → entry.id verbatim, slashes preserved          e.g. 'kg/01-intro'
+ *   :book → the entry's book name (see `bookField`), or '' e.g. 'kg'
+ *   :slug → entry.id with a leading '<book>/' stripped     e.g. '01-intro'
+ * BASE_URL is applied here, so patterns are written base-relative (lead '/').
+ *
+ * Defaults reproduce the single-book behavior BYTE-FOR-BYTE:
+ *   chapterRoute   = '/chapters/:id/'  → `${base}chapters/${id}/`
+ *   bookField      = 'book'   (academic/tools schemas have no `book` → bookOf
+ *                              returns null → "show all chapters", today's nav)
+ *   apparatusRoute = '/:route/'        → `${base}<route>/`
+ */
+
+/** Minimal shape the resolver needs from a chapter collection entry. */
+export interface ChapterLike {
+  id: string;
+  data: Record<string, unknown>;
+}
+
+/** Normalize a base URL to exactly one trailing slash (`''` → `'/'`). */
+function normBase(baseUrl: string): string {
+  return (baseUrl || '/').replace(/\/*$/, '/');
+}
+
+/** Replace `:book` / `:slug` / `:route` / `:id` tokens; `\b` keeps each token
+ *  whole, so order is irrelevant and `:id` never matches inside `:identifier`. */
+function fillTokens(pattern: string, tokens: Record<string, string>): string {
+  return pattern.replace(/:(book|slug|route|id)\b/g, (_m, k: string) => tokens[k] ?? '');
+}
+
+/**
+ * The entry's book name from `data[bookField]`, or `null` when absent/blank.
+ * Single-book schemas (academic/tools/minimal) have no such field → `null`,
+ * which callers read as "this is the only book — show every chapter".
+ */
+export function bookOf(entry: ChapterLike, bookField = 'book'): string | null {
+  const v = entry.data[bookField];
+  return typeof v === 'string' && v.length > 0 ? v : null;
+}
+
+/** `entry.id` with a leading `'<book>/'` stripped (multi-book) or unchanged. */
+export function slugOf(entry: ChapterLike, bookField = 'book'): string {
+  const book = bookOf(entry, bookField);
+  return book && entry.id.startsWith(`${book}/`) ? entry.id.slice(book.length + 1) : entry.id;
+}
+
+/** Resolve a chapter entry to a base-prefixed href via the `chapterRoute` pattern. */
+export function chapterHref(
+  entry: ChapterLike,
+  pattern = '/chapters/:id/',
+  baseUrl = '/',
+  bookField = 'book',
+): string {
+  const path = fillTokens(pattern, {
+    id: entry.id,
+    book: bookOf(entry, bookField) ?? '',
+    slug: slugOf(entry, bookField),
+  }).replace(/\/{2,}/g, '/').replace(/^\//, '');   // collapse empties (absent token) — never a protocol-relative //
+  return normBase(baseUrl) + path;
+}
+
+/**
+ * Resolve a per-book apparatus route (glossary / practice-exam / flashcards /
+ * answers) to a base-prefixed href via the `apparatusRoute` pattern.
+ */
+export function apparatusHref(
+  route: string,
+  book: string | null,
+  pattern = '/:route/',
+  baseUrl = '/',
+): string {
+  const path = fillTokens(pattern, { route, book: book ?? '' })
+    .replace(/\/{2,}/g, '/')   // F2 (#80): an absent :book must collapse, never yield a protocol-relative //
+    .replace(/^\//, '');
+  return normBase(baseUrl) + path;
+}
+
+/** Whether `entry` is the page at `currentPath` (trailing-slash tolerant). */
+export function isCurrentChapter(
+  entry: ChapterLike,
+  currentPath: string,
+  pattern = '/chapters/:id/',
+  baseUrl = '/',
+  bookField = 'book',
+): boolean {
+  const href = chapterHref(entry, pattern, baseUrl, bookField);
+  return currentPath === href || currentPath === href.replace(/\/$/, '');
+}

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/callouts.css

@@ -192,7 +192,9 @@
   padding: 0 var(--space-2);
   border: 1px solid var(--callout-worked);
   border-radius: var(--radius-sm);
-  color: var(--callout-worked);
+  /* v4.26.0 (#80, a11y): chip TEXT uses the high-contrast heading color (the
+   * accent stays as the border) — the accent as small text failed WCAG-AA 4.5:1. */
+  color: var(--color-heading);
 }
 
 /* Gold — YouWillLearn (v4.1.0, #59). Reuses callout-insight (gold) hue;
@@ -233,7 +235,7 @@
   padding: 0 var(--space-2);
   border: 1px solid var(--callout-diagnostic);
   border-radius: var(--radius-sm);
-  color: var(--callout-diagnostic);
+  color: var(--color-heading);   /* a11y: accent as small text failed 4.5:1 (border keeps the hue) */
 }
 .callout-diagnostic .callout-routing {
   font-size: var(--text-sm);
@@ -247,7 +249,7 @@
   cursor: pointer;
   font-weight: 600;
   font-size: var(--text-sm);
-  color: var(--callout-diagnostic);
+  color: var(--color-text);   /* a11y: teal accent as text failed 4.5:1 */
 }
 
 /* PartReview (#111) — Part-level interleaved exercise-review aggregation.
@@ -575,6 +577,8 @@ figure.figure figcaption {
   letter-spacing: 0.04em;
   text-transform: uppercase;
 }
-.practice-tag[data-kind="official"]     { border-color: var(--callout-official); color: var(--callout-official); }
-.practice-tag[data-kind="convergence"]  { border-color: var(--callout-insight); color: var(--callout-insight); }
-.practice-tag[data-kind="practitioner"] { border-color: var(--callout-tip); color: var(--callout-tip); }
+/* a11y (v4.26.0, #80): hue via the border; text uses the body color (accent as
+ * small text fails WCAG-AA 4.5:1). */
+.practice-tag[data-kind="official"]     { border-color: var(--callout-official); color: var(--color-text); }
+.practice-tag[data-kind="convergence"]  { border-color: var(--callout-insight);  color: var(--color-text); }
+.practice-tag[data-kind="practitioner"] { border-color: var(--callout-tip);      color: var(--color-text); }

package/styles/layout.css

@@ -31,10 +31,15 @@
 }
 
 /* At 1024px+: pin sidebar to left, main content fills remainder. */
-@media (min-width: 64rem) {
+/* v4.26.0 (#80): the full 3-column (sidebar + Tufte gutter) needs room the
+ * sidebar steals, so it activates at 80rem (1280px) — below that the drawer is
+ * the chapter nav and content runs full-width (the gutter/section-map then fits
+ * in the whole viewport). This is where the gutter genuinely fits beside the
+ * sidebar with the trimmed measures. */
+@media (min-width: 80rem) {
   .layout-with-sidebar {
     display: grid;
-    grid-template-columns: 16rem 1fr;
+    grid-template-columns: 14rem 1fr;   /* trimmed so main+gutter fits beside it */
     grid-template-areas: 'sidebar main';
     min-height: 100vh;
   }
@@ -51,7 +56,7 @@
  * titles. */
 @media (min-width: 90rem) {
   .layout-with-sidebar {
-    grid-template-columns: 18rem 1fr;
+    grid-template-columns: 16rem 1fr;
   }
 }
 
@@ -218,3 +223,89 @@
 .prose[data-layout="wide"] {
   --measure-main: 80ch;
 }
+
+/* ===== Mobile/tablet nav drawer (v4.26.0, #80) =====
+ * Below the sidebar breakpoint (64rem) the left Sidebar is display:none — this
+ * is the navigation in that range: a hamburger in the chrome row toggles a
+ * slide-in drawer reusing NavContent (the same book-scoped nav source as the
+ * sidebar). No-JS baseline: `:target` opens it (the toggle is <a href="#nav-drawer">);
+ * the inline controller in Base.astro enhances it with focus-trap + ESC + body
+ * scroll-lock. Hidden at ≥64rem, where the persistent sidebar is the nav. The
+ * ≥64rem gutter-fit (sidenote/section-map overflow) is a separate fix. */
+@media (min-width: 80rem) {
+  .nav-toggle,
+  .nav-drawer {
+    display: none;
+  }
+}
+
+@media (max-width: 79.98rem) {
+  .nav-drawer {
+    position: fixed;
+    inset: 0;
+    z-index: var(--z-drawer, 30);
+    visibility: hidden;
+  }
+  .nav-drawer.is-open,
+  .nav-drawer:target {
+    visibility: visible;
+  }
+  .nav-drawer-backdrop {
+    position: absolute;
+    inset: 0;
+    border: 0;
+    background: rgba(0, 0, 0, 0.5);
+    opacity: 0;
+    transition: opacity 200ms ease;
+  }
+  .nav-drawer-panel {
+    position: absolute;
+    inset-block: 0;
+    inset-inline-start: 0;
+    width: min(20rem, 85vw);
+    max-height: 100vh;
+    overflow-y: auto;
+    background: var(--color-bg-subtle);
+    border-right: 1px solid var(--color-border);
+    padding: var(--space-6) var(--space-5);
+    transform: translateX(-100%);
+    transition: transform 220ms ease;
+  }
+  .nav-drawer.is-open .nav-drawer-panel,
+  .nav-drawer:target .nav-drawer-panel {
+    transform: translateX(0);
+  }
+  .nav-drawer.is-open .nav-drawer-backdrop,
+  .nav-drawer:target .nav-drawer-backdrop {
+    opacity: 1;
+  }
+  .nav-drawer-dismiss {
+    position: absolute;
+    top: var(--space-3);
+    inset-inline-end: var(--space-3);
+    z-index: 1;
+  }
+}
+
+/* Body scroll-lock while the drawer is open (class toggled by the controller). */
+.nav-drawer-locked {
+  overflow: hidden;
+}
+
+/* ===== Gutter-fit (v4.26.0, #80) =====
+ * The Tufte right-gutter (.section-map scrollspy + .sidenote / .column-margin /
+ * .margin-figure floats) used to size its main+gutter measure against the FULL
+ * viewport, ignoring that a left sidebar steals 14–16rem — so the negative-margin
+ * float landed PAST the viewport at 1024px AND 1440px. The fix is in tokens.css:
+ * the `--measure-main` / `--measure-side` tiers are trimmed (60/20ch → 66/20ch →
+ * 78/24ch) and the sidebar to 14/16rem, so `main + gutter ≤ layout-main` (viewport
+ * − sidebar) at every desktop width. The gutter scrollspy now FITS beside the
+ * sidebar instead of overflowing — no suppression, no breakpoint games. Verified
+ * scrollWidth == clientWidth across the responsive audit harness. */
+
+@media (prefers-reduced-motion: reduce) {
+  .nav-drawer-panel,
+  .nav-drawer-backdrop {
+    transition: none;
+  }
+}

package/styles/section-map.css

@@ -30,7 +30,11 @@
   display: none !important;
 }
 
-@media (min-width: 64rem) {
+/* v4.26.0 (#80): the gutter scrollspy floats only alongside the sidebar (≥80rem,
+ * matching layout.css) — below that the drawer is the chapter nav and the in-flow
+ * collapsed ChapterTOC is the "on this page". This keeps the negative-margin gutter
+ * from overflowing the viewport in the cramped 64–80rem band (iPad-landscape). */
+@media (min-width: 80rem) {
   /* Sidenote-aware handshake (#151). The gutter map and <Sidenote>s float into
    * the SAME ~28ch right column (layout.css), so they cannot coexist there:
    *   - A chapter WITH sidenotes → the gutter belongs to the sidenotes; suppress

package/styles/tokens.css

@@ -106,8 +106,8 @@
    * the breakpoints are encoded as literal rem values in the media queries
    * (90rem ≈ 1440px, 120rem ≈ 1920px).
    */
-  --measure-main: 65ch;        /* default: laptop-friendly typographic measure */
-  --measure-side: 28ch;        /* right-margin sidenote column (desktop) */
+  --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 */
@@ -135,30 +135,34 @@
    * same visual language as prose callouts. Dark mode overrides below. */
   --astro-code-foreground:              var(--color-text);
   --astro-code-background:              var(--color-code-bg);
-  --astro-code-token-constant:          var(--warm-rose);
-  --astro-code-token-string:            var(--warm-green);
-  --astro-code-token-string-expression: var(--warm-green);
+  /* a11y (v4.26.0, #80): saturated accents fail 4.5:1 on the light code bg →
+   * darken (the dark-theme overrides below keep their lighter variants). */
+  --astro-code-token-constant:          color-mix(in srgb, var(--warm-rose) 60%, black);
+  --astro-code-token-string:            color-mix(in srgb, var(--warm-green) 55%, black);
+  --astro-code-token-string-expression: color-mix(in srgb, var(--warm-green) 55%, black);
   --astro-code-token-comment:           var(--color-text-muted);
-  --astro-code-token-keyword:           var(--warm-plum);
+  --astro-code-token-keyword:           color-mix(in srgb, var(--warm-plum) 60%, black);
   --astro-code-token-parameter:         var(--warm-blue);
-  --astro-code-token-function:          var(--warm-gold);
+  --astro-code-token-function:          color-mix(in srgb, var(--warm-gold) 55%, black);  /* a11y: warm-gold alone is 2.46:1 on the code bg (dark-mode override below) */
   --astro-code-token-punctuation:       var(--color-text-muted);
   --astro-code-token-link:              var(--color-link);
 }
 
-/* Tier 2: wide desktop (1440px+). Main 80ch, sidenote 24ch. */
+/* Tier 2: wide desktop (1440px+). v4.26.0 (#80): main 70ch + gutter 22ch keeps
+ * the main+gutter measure inside `layout-main` (viewport − 16rem sidebar) so the
+ * Tufte gutter/section-map fits beside the sidebar instead of overflowing. */
 @media (min-width: 90rem) {
   :root {
-    --measure-main: 80ch;
-    --measure-side: 24ch;
+    --measure-main: 66ch;
+    --measure-side: 20ch;
   }
 }
 
-/* Tier 3: ultrawide (1920px+). Main 90ch, sidenote 26ch. */
+/* Tier 3: ultrawide (1920px+). Room to widen both again and still fit. */
 @media (min-width: 120rem) {
   :root {
-    --measure-main: 90ch;
-    --measure-side: 26ch;
+    --measure-main: 78ch;
+    --measure-side: 24ch;
   }
 }
 

package/styles/typography.css

@@ -233,3 +233,19 @@ th {
   color: var(--warm-blue);
   font-style: italic;
 }
+
+/* ===== Narrow-viewport overflow guards (v4.26.0, #80) =====
+ * Defensive: stop a long INLINE-code identifier (e.g. a dotted module path) or a
+ * wide table from forcing horizontal PAGE scroll on a phone. `overflow-wrap:
+ * anywhere` only breaks when a token would otherwise overflow, so normal prose is
+ * untouched; fenced blocks are excluded (`:not(pre) > code`) so they keep their
+ * own `pre { overflow-x: auto }` inner scroll. Wide tables scroll within their own
+ * box (`display:block; overflow-x:auto`) instead of stretching the page. */
+:not(pre) > code {
+  overflow-wrap: anywhere;
+}
+.prose > table {
+  display: block;
+  overflow-x: auto;
+  max-width: 100%;
+}