explico 0.11.0 → 0.12.0

package/src/reference/raw-floats.mjs

@@ -12,11 +12,13 @@
  *   `keyed-jsx-floats.mjs`'s top-level-only scan entirely, so it never even
  *   reaches diagram numbering.
  *
- * A raw table nested in `<Table>`/`<Figure>` is the intended, wrapped case
- * and is not flagged; nesting inside anything else (`<CompactExample>`,
- * `<Aside>`, `<Memo>`, …) still is, because a raw table has no numbering
- * scheme of its own to opt into the way a `<Diagram>`'s top-level/`<Memo>`-
- * transparent scan does.
+ * A raw table counts only where wrapping it would number it: at the top level
+ * of the lesson body or in a `TRANSPARENT_COMPONENTS` body (`<Memo>`,
+ * `<ShortNote>`, `<Fold>`), exactly where `keyed-jsx-floats.mjs` numbers a
+ * `<Table>`. A raw table in `<Table>`/`<Figure>` is the intended, wrapped
+ * case; one in any other component (a worked example's `<CompactExample>`,
+ * an `<Aside>`) is illustrative, like an equation there, and a `<Table>`
+ * there would get no number — so neither is flagged.
  *
  * `scanRawFloats` (raw Markdown, for the manifest builder) and
  * `collectRawFloats` (mdast, for `remark-notation.mjs`) MUST agree on counts
@@ -24,7 +26,11 @@
  * `keyed-jsx-floats.mjs` holds `scanKeyedJsxFloats`/`collectKeyedJsxFloats` to.
  */
 
-import { stripFencedCode } from './equations.mjs';
+import {
+  stripFencedCode,
+  stripJsxComponents,
+  TRANSPARENT_COMPONENTS,
+} from './equations.mjs';
 import { collectKeyedJsxFloats, scanKeyedJsxFloats } from './keyed-jsx-floats.mjs';
 
 /** Blank `<Table>…</Table>` and `<Figure>…</Figure>` bodies — legitimately wrapped, not raw. */
@@ -67,9 +73,16 @@ function findDiagramTags(text) {
 export function scanRawFloats(markdown) {
   const codeStripped = stripFencedCode(String(markdown));
   const withoutWrappedFloats = blankFloatWrappers(codeStripped);
+  // Every component body but a transparent one is blanked — `<Table>` and
+  // `<Figure>` among them — so only the tables a `<Table>` would number remain.
+  const numberableText = stripJsxComponents(
+    codeStripped,
+    undefined,
+    TRANSPARENT_COMPONENTS,
+  );
 
-  const markdownTableCount = findMarkdownTableStarts(withoutWrappedFloats).length;
-  const htmlTableCount = findHtmlTableTags(withoutWrappedFloats).length;
+  const markdownTableCount = findMarkdownTableStarts(numberableText).length;
+  const htmlTableCount = findHtmlTableTags(numberableText).length;
 
   const diagramsOutsideWrappers = findDiagramTags(withoutWrappedFloats).length;
   const visibleDiagrams = scanKeyedJsxFloats(markdown, { tagName: 'Diagram' });
@@ -95,7 +108,10 @@ export function collectRawFloats(tree) {
   const htmlTableNodes = [];
   const allDiagramNodes = [];
 
-  const walk = (node) => {
+  // `numberable`: a `<Table>` here would be numbered — the top level, or a
+  // transparent component's body. Any other MDX component (a capitalized
+  // name, the ones `stripJsxComponents` blanks) ends it for its subtree.
+  const walk = (node, numberable) => {
     if (!node || typeof node !== 'object') return;
     if (
       node.type === 'mdxJsxFlowElement' &&
@@ -103,18 +119,26 @@ export function collectRawFloats(tree) {
     ) {
       return; // legitimately wrapped — don't descend
     }
-    if (node.type === 'table') markdownTableNodes.push(node);
-    if (node.type === 'html' && /<table\b/i.test(String(node.value ?? ''))) {
+    if (numberable && node.type === 'table') markdownTableNodes.push(node);
+    if (
+      numberable &&
+      node.type === 'html' &&
+      /<table\b/i.test(String(node.value ?? ''))
+    ) {
       htmlTableNodes.push(node);
     }
     if (node.type === 'mdxJsxFlowElement' && node.name === 'Diagram') {
       allDiagramNodes.push(node);
     }
+    const component =
+      (node.type === 'mdxJsxFlowElement' || node.type === 'mdxJsxTextElement') &&
+      /^[A-Z]/.test(String(node.name ?? '')) &&
+      !TRANSPARENT_COMPONENTS.includes(node.name);
     if (Array.isArray(node.children)) {
-      for (const child of node.children) walk(child);
+      for (const child of node.children) walk(child, numberable && !component);
     }
   };
-  walk(tree);
+  walk(tree, true);
 
   const visibleDiagrams = collectKeyedJsxFloats(tree, { tagName: 'Diagram' });
   const visibleNodes = new Set(visibleDiagrams.map((diagram) => diagram.node));

package/src/reference/registry.ts

@@ -167,6 +167,18 @@ export function buildNotationRegistry(
   }
   detectCycles(definitions, edgeIndex, diagnostics);
 
+  // A page's own `notation.local` entries are in its scope by construction:
+  // its math binds to one by shape — an operator entry `{}'` for `w'`, the
+  // fix rule N22 itself suggests — even where no `[[key]]` or `\explain`
+  // names it. Each seeds its page's bundle, so the page renders its card.
+  const localIdsByLesson = new Map<string, string[]>();
+  for (const candidate of definitions.values()) {
+    if (candidate.kind !== 'local') continue;
+    const ids = localIdsByLesson.get(candidate.lesson.lessonId) ?? [];
+    ids.push(candidate.id);
+    localIdsByLesson.set(candidate.lesson.lessonId, ids);
+  }
+
   const bundles: NotationPageBundle[] = [];
   const backlinks: NotationBacklink[] = [];
   const reachableDefinitions = new Set<string>();
@@ -176,7 +188,10 @@ export function buildNotationRegistry(
     const directIds = new Set(
       references.map((reference) => reference.definitionId),
     );
-    const definitionIds = transitiveClosure(directIds, edgeIndex);
+    const definitionIds = transitiveClosure(
+      new Set([...directIds, ...(localIdsByLesson.get(lesson.lessonId) ?? [])]),
+      edgeIndex,
+    );
     for (const id of definitionIds) reachableDefinitions.add(id);
 
     const bindingByKey = new Map<string, string>();

package/src/reference/remark-notation.mjs

@@ -46,6 +46,7 @@ import {
   equationAnchorId,
   parseEquationRef,
   stripEquationLabels,
+  TRANSPARENT_COMPONENTS,
 } from './equations.mjs';
 import {
   collectKeyedJsxFloats,
@@ -184,6 +185,25 @@ function lessonIdFrom(file) {
   return typeof lessonId === 'string' ? lessonId : undefined;
 }
 
+/** True for any page under `content/docs/`; a lesson is one of them. */
+function isDocsPageFile(file) {
+  return [file?.path, file?.history?.[0], file?.data?.file].some(
+    (value) => typeof value === 'string' && LESSON_DOC_PATH.test(value),
+  );
+}
+
+/**
+ * The blocks a chapter numbers (`makeFloatCtx` below, and the knowledge
+ * check). Rule S10 keeps each off a page that is not a chapter.
+ */
+const NUMBERED_BLOCK_NAMES = new Set([
+  'Table',
+  'Figure',
+  'Diagram',
+  'CompactExamples',
+  'AssessmentSet',
+]);
+
 const ANY_TERM_KEY = /\[\[\s*([^\][]+?)\s*\]\]/g;
 const ANY_EXPLAIN_KEY = /\\explain\s*\{([^{}]+)\}/g;
 
@@ -467,6 +487,130 @@ function injectFloatNumberAttributes(node, float, prefix) {
   });
 }
 
+/**
+ * The URL path Starlight serves a docs page at: `motion/index.mdx` is
+ * `/motion/`, `motion/speed.mdx` is `/motion/speed/`, `index.mdx` is `/`.
+ */
+function pageUrlFrom(file) {
+  for (const value of [file?.path, file?.history?.[0], file?.data?.file]) {
+    if (typeof value !== 'string') continue;
+    const match = value.match(LESSON_DOC_PATH);
+    if (!match) continue;
+    const route = match[1].replace(/\\/g, '/').replace(/(?:^|\/)index$/, '');
+    return route ? `/${route}/` : '/';
+  }
+  return undefined;
+}
+
+/**
+ * The chapter slug a link's `href` names — `motion/speed` for
+ * `/motion/speed/#sec-x`, for `../speed/` from a sibling page, and for
+ * `/base/motion/speed/` under the course's `base` — or `undefined` for a
+ * same-page anchor, another site, or a scheme such as `mailto:`.
+ */
+function linkedSlug(href, pageUrl, base) {
+  if (typeof href !== 'string' || href === '' || href.startsWith('#')) return undefined;
+  if (href.startsWith('//') || /^[a-z][a-z0-9+.-]*:/i.test(href)) return undefined;
+  let url;
+  try {
+    url = new URL(href, `https://course.invalid${pageUrl ?? '/'}`);
+  } catch {
+    return undefined;
+  }
+  let path;
+  try {
+    path = decodeURIComponent(url.pathname);
+  } catch {
+    return undefined;
+  }
+  const prefix = base && base !== '/' ? base.replace(/\/+$/, '') : '';
+  if (prefix && (path === prefix || path.startsWith(`${prefix}/`))) {
+    path = path.slice(prefix.length);
+  }
+  return path.replace(/^\/+|\/+$/g, '');
+}
+
+/**
+ * A link the author wrote to another chapter shows that chapter's full title
+ * as its native tooltip (`title`): prose names a chapter any way it likes —
+ * "the previous chapter", "Chapter 1.2", "this derivation" — and a reader can
+ * see where the link goes before following it. A Markdown link and a JSX
+ * `<a href>` both get it; a link with a title of its own, or one to the page
+ * it is on, keeps what it has.
+ */
+function titleChapterLinks(tree, file, titleBySlug, base) {
+  if (titleBySlug.size === 0) return;
+  const pageUrl = pageUrlFrom(file);
+  const here = pageUrl?.replace(/^\/+|\/+$/g, '');
+  const titleOf = (href) => {
+    const slug = linkedSlug(href, pageUrl, base);
+    return slug !== undefined && slug !== here ? titleBySlug.get(slug) : undefined;
+  };
+  const walk = (node) => {
+    if (!node || typeof node !== 'object') return;
+    if (node.type === 'link' && !node.title) {
+      const title = titleOf(node.url);
+      if (title) node.title = title;
+    } else if (
+      (node.type === 'mdxJsxTextElement' || node.type === 'mdxJsxFlowElement') &&
+      node.name === 'a'
+    ) {
+      const attributes = node.attributes ?? [];
+      const named = (name) =>
+        attributes.find((attribute) => attribute?.type === 'mdxJsxAttribute' && attribute.name === name);
+      const title = named('title') ? undefined : titleOf(named('href')?.value);
+      if (title) {
+        node.attributes = [...attributes, { type: 'mdxJsxAttribute', name: 'title', value: title }];
+      }
+    }
+    if (Array.isArray(node.children)) node.children.forEach(walk);
+  };
+  walk(tree);
+}
+
+/**
+ * The innermost component around `target` that numbering does not see
+ * through — the reason a float in it has no number — or `undefined`.
+ */
+function blockingComponent(tree, target) {
+  const search = (node, blocking) => {
+    if (node === target) return blocking;
+    if (!node || typeof node !== 'object' || !Array.isArray(node.children)) return undefined;
+    const here =
+      node.type === 'mdxJsxFlowElement' &&
+      node.name &&
+      !TRANSPARENT_COMPONENTS.includes(node.name)
+        ? node.name
+        : blocking;
+    for (const child of node.children) {
+      const found = search(child, here);
+      if (found !== undefined) return found;
+    }
+    return undefined;
+  };
+  return search(tree, undefined);
+}
+
+/**
+ * Why a `<Table>`/`<Figure>` on a lesson page got no number: it sits in a
+ * component other than the `TRANSPARENT_COMPONENTS`, where a float is
+ * illustrative, as an equation there is (`keyed-jsx-floats.mjs`).
+ */
+function unnumberedFloatMessage(tagName, component) {
+  const where = component ? `<${component}>` : 'another component';
+  const noun = tagName === 'Table' ? 'table' : 'figure';
+  const instead =
+    tagName === 'Table'
+      ? 'write it as a plain Markdown table (rule S3 does not flag one there)'
+      : 'show its content without <Figure>';
+  return (
+    `<${tagName}> inside ${where} gets no number: a lesson numbers a ${noun} ` +
+    `at its top level or in a <Memo>, <ShortNote> or <Fold>. A ${noun} in a ` +
+    `worked example or another component is illustrative, like an equation ` +
+    `there: ${instead}, or move the <${tagName}> out of ${where}.`
+  );
+}
+
 /** Resolve a `[[eq-key]]` / `[[slug#eq-key]]` reference to `{ number, href }`. */
 function resolveEquationRef(eqRef, eqCtx, file, node) {
   if (eqRef.lesson) {
@@ -1287,6 +1431,9 @@ export default function remarkNotation(options = {}) {
   // The manifest supplies every numbering input at once; an explicit option
   // still overrides it, so existing per-field wiring keeps working.
   const numbering = { ...numberingFromManifest(options.manifest), ...options };
+  const chapterTitleBySlug = new Map(
+    (options.manifest?.lessons ?? []).map((lesson) => [lesson.slug, lesson.title]),
+  );
   // Every lesson's headings by anchor, built once: `[[lesson#sec-…]]` reads
   // another page's, `[[sec-…]]` the page's own.
   const sectionSettings = { show: true, depth: 4, ...numbering.sectionNumbering };
@@ -1310,6 +1457,9 @@ export default function remarkNotation(options = {}) {
     const suspendedOperators = suspendedOperatorsFromFile(file);
     const lessonId = lessonIdFrom(file);
     const lessonSlug = lessonId ? lessonId.replace(/\./g, '/') : undefined;
+    // The landing page, a part's overview page (rule S10): its math binds
+    // like a chapter's, but it numbers nothing.
+    const nonChapterPage = !lessonId && isDocsPageFile(file);
     // `{ prefix, offset }` per kind of float — see the `numbering` option.
     // Missing ⇒ the legacy `##`-section numbering.
     const equationNumbering = pageNumbering(numbering, lessonSlug, 'equations');
@@ -1329,6 +1479,13 @@ export default function remarkNotation(options = {}) {
     const equationLabels = collectEquationLabels(tree, equationNumbering);
     const pageLabels = new Map();
     for (const label of equationLabels) {
+      if (nonChapterPage) {
+        fail(
+          file,
+          `\\label{eq:${label.key}} on a page that is not a chapter (rule S10): only a chapter numbers an equation. Drop the label to show the equation unnumbered, or link the chapter's own with [[<chapter>#eq-<key>]].`,
+          label.node,
+        );
+      }
       if (pageLabels.has(label.key)) {
         fail(
           file,
@@ -1568,14 +1725,19 @@ export default function remarkNotation(options = {}) {
 
         inspectExplainCalls(value, resolve, file, node, references);
 
-        const bindingScope = lessonId
-          ? mathScope
-          : registryFile
-            ? registryMathDefinitions
-            : undefined;
+        const bindingScope =
+          lessonId || nonChapterPage
+            ? mathScope
+            : registryFile
+              ? registryMathDefinitions
+              : undefined;
 
         if (bindingScope) {
-          const context = lessonId ? 'lesson math' : 'notation definition math';
+          const context = lessonId
+            ? 'lesson math'
+            : nonChapterPage
+              ? 'page math'
+              : 'notation definition math';
 
           let result;
           try {
@@ -1608,7 +1770,9 @@ export default function remarkNotation(options = {}) {
               .join(', ');
             fail(
               file,
-              `Unresolved notation in ${context}: ${unresolved}. Introduce the symbol with [[key]], define it in notation.local, or wrap it in \\explain{key}{latex}.`,
+              nonChapterPage
+                ? `Unresolved notation in ${context}: ${unresolved}. Introduce the symbol with [[key]], or wrap it in \\explain{key}{latex}: a page that is not a chapter recalls shared notation and defines none (rule S10).`
+                : `Unresolved notation in ${context}: ${unresolved}. Introduce the symbol with [[key]], define it in notation.local, or wrap it in \\explain{key}{latex}.`,
               node,
             );
           }
@@ -1668,6 +1832,27 @@ export default function remarkNotation(options = {}) {
           injectFloatNumberAttributes(child, diagramByNode.get(child), 'dia');
         } else if (child?.type === 'mdxJsxFlowElement' && exampleByNode.has(child)) {
           injectFloatNumberAttributes(child, exampleByNode.get(child), 'ex');
+        } else if (
+          nonChapterPage &&
+          child?.type === 'mdxJsxFlowElement' &&
+          NUMBERED_BLOCK_NAMES.has(child.name)
+        ) {
+          // `validate:content` reports this first (gate-non-chapter-pages.ts);
+          // this is the same message for a build that skipped it.
+          fail(
+            file,
+            `<${child.name}> on a page that is not a chapter (rule S10): only a chapter numbers it. Move it into the chapter it belongs to, and link it from here: the link shows it in its card.`,
+            child,
+          );
+        } else if (
+          lessonId &&
+          child?.type === 'mdxJsxFlowElement' &&
+          (child.name === 'Table' || child.name === 'Figure')
+        ) {
+          // Numbered everywhere a lesson numbers one, so this one is nested
+          // in a component that is not transparent. Say so here, at its
+          // line, before the component fails on its missing number.
+          fail(file, unnumberedFloatMessage(child.name, blockingComponent(tree, child)), child);
         }
       }
     };
@@ -1727,6 +1912,9 @@ export default function remarkNotation(options = {}) {
       }
     }
 
+    // Before `visit`, which writes the `[[…]]` reference links: each of
+    // those opens a card of its own.
+    titleChapterLinks(tree, file, chapterTitleBySlug, options.base);
     visit(tree);
 
     file.data.notationReferences = references;

package/src/reference/render-lab-math.ts

@@ -12,6 +12,16 @@ export interface LabMathScopeDefinition {
   readonly notation: string;
 }
 
+export interface RenderLabMathOptions {
+  /**
+   * `false` renders the template as inline math — a `.katex` with no
+   * `.katex-display` — for a formula that sits in a line: a legend entry,
+   * an axis title, a control label. It never scrolls (`global.css`
+   * `.lab-math`). Default `true`, a display equation.
+   */
+  readonly display?: boolean;
+}
+
 interface BindResult {
   latex: string;
   bindings: ReadonlyArray<{ key: string }>;
@@ -36,6 +46,7 @@ const sentinelFor = (index: number): string => `909909${index}.909909`;
 export function renderLabMath(
   template: string,
   scope: readonly LabMathScopeDefinition[],
+  { display = true }: RenderLabMathOptions = {},
 ): RenderedLabMath {
   const slots: Array<{ name: string; fallback: string }> = [];
   const forBinding = template.replace(
@@ -95,7 +106,7 @@ export function renderLabMath(
 
   const html = katex.renderToString(
     bound,
-    createNotationKatexOptions({ displayMode: true }),
+    createNotationKatexOptions({ displayMode: display }),
   );
 
   return {

package/src/rules/catalog.ts

@@ -613,8 +613,15 @@ const RULES: readonly RuleEntry[] = [
     elements: ['plot'],
     doc: 'visualizations.md#v3',
     summary:
-      'An interactive figure is an island under `content/labs/` inside a `<Figure>`, renders its equations through `renderLabMath`, and labels its controls; the figure’s caption is its name, so the lab writes no accessible name or text alternative of its own.',
-    checks: [],
+      'An interactive figure is an island under `content/labs/` inside a `<Figure>`, renders its equations through `renderLabMath` (`{ display: false }` for a legend, an axis title or a label; a `{ math }` run for the caption clause) and never KaTeX directly, and labels its controls; the figure’s caption is its name, so the lab writes no accessible name or text alternative of its own.',
+    checks: [
+      check('lab-katex-direct', 'error', false, {
+        module: 'src/reference/lab-katex-validate.ts',
+        fn: 'validateLabKatexImports',
+      }),
+    ],
+    unchecked:
+      'that a lab labels its controls and writes no name of its own, and math a lab draws without importing `katex` — the build’s rendered check (`figure-symbols.ts`) covers the page it renders.',
   },
   {
     kind: 'rule',
@@ -799,7 +806,7 @@ const RULES: readonly RuleEntry[] = [
     elements: ['table'],
     doc: 'structure-rules.md#s3',
     summary:
-      'Wrap every pipe table or `<table>` in `<Table id="…" caption="…">` so it gets a number and `[[tab-…]]` can reach it.',
+      'Wrap every pipe table or `<table>` in `<Table id="…" caption="…">` so it gets a number and `[[tab-…]]` can reach it; a table in a worked example stays plain.',
     checks: [
       check('raw-table-markdown', 'warning', false, {
         module: 'src/reference/raw-floats-validate.ts',
@@ -906,6 +913,33 @@ const RULES: readonly RuleEntry[] = [
       'Give each figure, table and diagram a `short` caption that names it: it opens the caption line in bold, and names the float in "Hidden here", a copied link and the "Figures and tables" page. The long `caption` goes on from that name to say what the float shows — its subject, its marks and symbols, the case shown — and at most the one thing to notice. The argument drawn from a figure is lesson text after it, and a lab’s instructions are the first line of its `tools`.',
     checks: [],
   },
+  {
+    kind: 'rule',
+    id: 'S10',
+    short: 'A page that is not a chapter explains its symbols but numbers nothing: it links a chapter’s float instead',
+    title:
+      'A page that is not a chapter — the landing page, a part’s overview page — explains its symbols like a chapter, but carries no numbered float: it links the chapter’s float instead.',
+    elements: ['part-page', 'plot', 'table', 'diagram', 'equation', 'notation'],
+    doc: 'structure-rules.md#s10',
+    summary:
+      'On `content/docs/index.mdx`, a `content/docs/<part>/index.mdx`, or any page outside a part: `[[key]]`, `\\explain`, math, citations and `[[chapter#tab-key]]` links work and open cards, and the math and prose gates apply. No `<Table>`, `<Figure>`, `<Diagram>`, `<CompactExamples>`, `<AssessmentSet>`, lab, `\\label{eq:…}` or `notation.local`/`notation.suspend`; no `$…$` or `[[…]]` in `hero.title`, `hero.tagline` or a `<PartOverview chain>` step.',
+    checks: [
+      check('non-chapter-float', 'error', true, {
+        module: 'src/reference/gate-non-chapter-pages.ts',
+        fn: 'gateNonChapterPages',
+      }),
+      check('non-chapter-local-notation', 'error', false, {
+        module: 'src/reference/gate-non-chapter-pages.ts',
+        fn: 'gateNonChapterPages',
+      }),
+      check('non-chapter-plain-text', 'error', false, {
+        module: 'src/reference/gate-non-chapter-pages.ts',
+        fn: 'gateNonChapterPages',
+      }),
+    ],
+    locked:
+      'a float needs a chapter number, and such a page has none — turning the rule off would not render one.',
+  },
 
   // ---- P — prose --------------------------------------------------------------
   {

package/src/styles/global.css

@@ -149,14 +149,15 @@ body {
   color: var(--sl-color-text);
 }
 
-/* Clip only the inline axis: `overflow-x: auto` alone makes the block axis
-   compute to `auto` too, which adds a spurious vertical scrollbar around
-   display math. */
-.lab-math {
+/* A lab's math (`renderLabMath`), in the element the lab puts it in. The
+   wrapper never scrolls: a display template's `.katex-display` scrolls
+   sideways when it is wider than its box, like a lesson equation (below),
+   so a lab equation is one scroll container at most, and one that fits
+   draws no scrollbar. An inline template (`{ display: false }` — a legend
+   entry, an axis title, a control label) has no `.katex-display`: it sits
+   in its line, with no margin and nothing to scroll. */
+.lab-math:has(.katex-display) {
   margin-block: 1.25rem;
-  padding-block: 0.15rem;
-  overflow-x: auto;
-  overflow-y: hidden;
 }
 
 .lab-math .katex-display {
@@ -171,12 +172,20 @@ body {
    edge is KaTeX's metric strut — but glyph ink overshoots its metrics (a
    denominator's `g` descender, a stretched `\right]`), so the bottom of the
    equation was cut off. The padding is the room that ink needs; em-based so
-   it scales with the math. */
-.sl-markdown-content .katex-display {
+   it scales with the math.
+   The inline padding is KaTeX's own: every stacked script box
+   (`.vlist-t2`) has `margin-right: -2px` and holds a 2px spacer cell, which
+   lies outside the box's layout width but inside its scrollable overflow.
+   An equation within 2px of its column's width scrolled by those 2px for
+   nothing. Padding both sides reserves them and keeps a centred equation
+   centred. The same holds for a lab's display math (`.lab-math`, above). */
+.sl-markdown-content .katex-display,
+.lab-math .katex-display {
   max-width: 100%;
   overflow-x: auto;
   overflow-y: hidden;
   padding-block: 0.25em;
+  padding-inline: 2px;
 }
 
 /* Focusable only while it overflows (`KeyedFloatEnhancer.astro`), so it can
@@ -1043,28 +1052,24 @@ details.layout-part-has-open > summary > .group-label {
     display: none;
   }
 
-  /* A panel the reader narrowed past its own labels scrolls sideways rather
-     than wrapping every chapter title into a column of single words. */
-  html[data-navigation-resized] .layout-navigation-content :is(a, summary) {
-    white-space: nowrap;
+  /* A label that does not fit wraps onto more lines, and the side panels
+     never scroll sideways: a word longer than the panel is wide is
+     hyphenated where the language allows, else broken. Starlight's
+     `overflow-wrap: anywhere` on the contents links broke words at any
+     letter before hyphenation got a chance. */
+  .layout-navigation-content,
+  .layout-page-sidebar-content,
+  .layout-page-sidebar-content a {
+    overflow-wrap: break-word;
+    hyphens: auto;
   }
 
-  html[data-navigation-resized] .sidebar-pane {
-    overflow-x: auto;
-  }
-
-  /* A compact chapter's tooltip is a child of one of those links, and it is
-     the one label that must still wrap — it is sized by its own max-width,
-     not by the panel, so inheriting `nowrap` would run its text straight out
-     of its own background. */
-  html[data-navigation-resized]
-    .layout-compact-sidebar
-    details[data-compact]
-    > ul:not(.top-level)
-    > li
-    > a
-    > span {
-    white-space: normal;
+  /* With every label wrapping, what still reaches past the navigation's
+     edge is a compact chapter's resting tooltip (absolutely placed, and
+     invisible): it would only add a sideways scrollbar. A showing tooltip is
+     `position: fixed` (below), so this clip never cuts it. */
+  .sidebar-pane {
+    overflow-x: hidden;
   }
 
   html[data-navigation-hidden] {
@@ -1249,15 +1254,15 @@ details.layout-part-has-open > summary > .group-label {
     max-width: none;
   }
 
-  /* Starlight hides this panel's scrollbar (`scrollbar-width: none`), which
-     would quietly cut a heading the reader narrowed the panel past. */
-  html[data-contents-resized]:not([data-page-sidebar-hidden]) .right-sidebar {
-    overflow-x: auto;
-    scrollbar-width: thin;
-  }
-
-  html[data-contents-resized] .layout-page-sidebar-content :is(a, h2) {
-    white-space: nowrap;
+  /* Starlight sizes the column inside from the navigation's width
+     (`--sl-sidebar-width`), not from this panel: in a panel the reader set,
+     it fills the panel, so its headings wrap at the panel's edge instead of
+     running past it. */
+  html[data-contents-resized]:not([data-page-sidebar-hidden])
+    .right-sidebar-panel
+    .sl-container {
+    width: auto;
+    max-width: none;
   }
 
   html[data-page-sidebar-hidden] {
@@ -1362,6 +1367,15 @@ details.layout-part-has-open > summary > .group-label {
   z-index: calc(var(--sl-z-index-navbar) + 1);
 }
 
+/* Below 50rem Starlight's menu button is not in the header: it is a fixed
+   button in `nav.sidebar`, at the navbar's level, laid over the header's
+   end. It rises above the raised header, or the header's box takes every
+   tap and the navigation never opens on a phone. Starlight hides the
+   button from 50rem up, so the rule needs no media query. */
+starlight-menu-button > button {
+  z-index: calc(var(--sl-z-index-navbar) + 2);
+}
+
 /* A slimmer site header: 3rem at every width, where Starlight's is 3.5rem
    and 4rem from 50rem up. The title, the logo (sized from the height and
    padding) and the search box scale with it, so more of the window goes to
@@ -2024,7 +2038,11 @@ details.layout-part-has-open > summary > .group-label {
   gap: 0.25rem;
 }
 
+/* The line is at least as tall as its buttons (`.float-tool`'s height), so
+   the row never hangs below it — past a figure's body, or into a table's
+   header — even when a course hides the caption's text. */
 .sl-markdown-content .float-caption:has(> .float-tools > .float-tool:not([hidden])) {
+  min-block-size: 1.5rem;
   padding-inline-end: 2.25rem;
 }
 
@@ -2096,6 +2114,7 @@ details.layout-part-has-open > summary > .group-label {
   }
 
   .sl-markdown-content .float-caption:has(> .float-tools) {
+    min-block-size: auto;
     padding-inline-end: 0;
   }
 }