explico 0.11.1 → 0.13.0

package/src/components/notation/render-notation-math.ts

@@ -10,6 +10,7 @@ import {
   stripNotationMarkers,
 } from '../../reference/math-glyphs.mjs';
 import type { GlyphScopeEntry } from '../../reference/gloss';
+import type { DerivedUse, IndexedSymbol } from '../../reference/types';
 
 interface HastText {
   type: 'text';
@@ -284,14 +285,27 @@ function sanitizeNode(node: HastNode): SafeMathNode {
     throw new Error(`Unexpected KaTeX node: ${node.type}.`);
   }
 
+  const properties = safeProperties(node);
   return Object.freeze({
     type: 'element',
     tagName: node.tagName,
-    properties: safeProperties(node),
+    // KaTeX writes each formula twice, as MathML (with its LaTeX in an
+    // `<annotation>`) for assistive technology and as visible glyphs; the
+    // site search indexes the glyphs alone (`withSearchOnce`).
+    properties: withSearchOnce(properties),
     children: Object.freeze(node.children.map(sanitizeNode)),
   });
 }
 
+/** `data-pagefind-ignore` on KaTeX's MathML copy of a formula. */
+function withSearchOnce(
+  properties: Readonly<Record<string, string>>,
+): Readonly<Record<string, string>> {
+  return properties.class?.split(' ').includes('katex-mathml')
+    ? Object.freeze({ ...properties, 'data-pagefind-ignore': '' })
+    : properties;
+}
+
 // Re-exported so existing imports of `stripNotationMarkers` from this module
 // (the notation popup card's "Copy LaTeX" button) keep working. The
 // implementation lives in `math-glyphs.mjs` because `remark-notation.mjs`
@@ -388,19 +402,34 @@ export function renderNotationMath(latex: string): readonly SafeMathNode[] {
 export function renderNotationFormula(
   formula: string,
   scope: readonly GlyphScopeEntry[],
+  { derive = false }: { readonly derive?: boolean } = {},
 ): {
   readonly nodes: readonly SafeMathNode[];
+  /** The LaTeX `nodes` were rendered from: `formula` with its glyphs bound, or as written. */
+  readonly latex: string;
   readonly unresolved: readonly string[];
   readonly degraded: boolean;
+  /** Why the formula could not be bound, when `degraded`: the resolver's own message. */
+  readonly reason?: string;
+  /** With `derive` (page math, rule N23): the derived cards the formula uses. */
+  readonly derived: readonly DerivedUse[];
+  /** How each symbol with a subscript is explained (rule N23). */
+  readonly indices: readonly IndexedSymbol[];
 } {
   let bound = formula;
   let unresolved: string[] = [];
   let degraded = false;
+  let reason: string | undefined;
+  let derived: DerivedUse[] = [];
+  let indices: IndexedSymbol[] = [];
   try {
-    const result = resolveMathGlyphs(formula, [...scope]);
+    const result = resolveMathGlyphs(formula, [...scope], { derive });
     bound = result.latex;
     unresolved = result.unresolved.map(({ token }: { token: string }) => token);
+    derived = result.derived;
+    indices = result.indices;
   } catch (error) {
+    reason = error instanceof Error ? error.message : String(error);
     // N13 (a nonlinear function with no parenthesized argument) is a hard,
     // no-exceptions rule like N9 — never degrade it to inert math, so both
     // `Diagram` (which turns `degraded` into a build error anyway, but with
@@ -417,11 +446,28 @@ export function renderNotationFormula(
     degraded = true;
   }
 
+  const why = reason === undefined ? {} : { reason };
   try {
-    return { nodes: renderNotationMath(bound), unresolved, degraded };
-  } catch {
+    return {
+      nodes: renderNotationMath(bound),
+      latex: bound,
+      unresolved,
+      degraded,
+      ...why,
+      derived,
+      indices,
+    };
+  } catch (error) {
     // A marker that KaTeX or the sanitizer rejects must not cost the reader
     // the equation itself.
-    return { nodes: renderNotationMath(formula), unresolved, degraded: true };
+    return {
+      nodes: renderNotationMath(formula),
+      latex: formula,
+      unresolved,
+      degraded: true,
+      reason: reason ?? (error instanceof Error ? error.message : String(error)),
+      derived: [],
+      indices: [],
+    };
   }
 }

package/src/components/readable-text.ts

@@ -0,0 +1,25 @@
+/**
+ * An element's text as a reader sees it. KaTeX writes each formula three ways
+ * — MathML, its LaTeX `<annotation>` and its `aria-hidden` glyphs — so a
+ * heading's `textContent` reads `R\explain{motion.range}{R}R`; this reads the
+ * formula once, from its MathML, as `rehype-heading-anchors.mjs` does for the
+ * heading link's label.
+ */
+export function readableText(element: Element): string {
+  let text = '';
+  const walk = (node: Node): void => {
+    if (node.nodeType === Node.TEXT_NODE) {
+      text += node.textContent ?? '';
+      return;
+    }
+    if (node.nodeType !== Node.ELEMENT_NODE) return;
+    const child = node as Element;
+    if (child.localName === 'annotation' || child.classList.contains('katex-html')) return;
+    child.childNodes.forEach(walk);
+  };
+  walk(element);
+  return text
+    .replace(/[​⁡-⁤]/g, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+}

package/src/components/reference/FloatRefLayer.astro

@@ -22,7 +22,10 @@
  *  - otherwise a card floats near the reference showing its number,
  *    caption (table/figure), content, and a "Go to …" link, whose arrow
  *    says where it lands (`../card-jump.ts`): ↑ / ↓ on this page, → with the
- *    lesson's name on another one. A click on the
+ *    lesson's name on another one. The float's number heads the card's
+ *    title, "Equation (1.1.3)", "Figure 2.1.1", and the link then says only
+ *    "Go to the figure". A figure's picture is 80% of its width in the
+ *    article. A click on the
  *    reference pins the card, a second one closes it (the card manager's
  *    contract, `../card-manager.ts`); the card's own links navigate.
  *
@@ -60,7 +63,8 @@
  *
  * One card per referenced float, several at once; the card manager places
  * them clear of every other open card, and a symbol inside a card opens its
- * notation card as a child of it.
+ * notation card as a child of it — in a card from another page, as that
+ * page explains it (`markForeign`), even a symbol this page never uses.
  */
 import HoverPanel from '../HoverPanel.astro';
 ---
@@ -68,23 +72,30 @@ import HoverPanel from '../HoverPanel.astro';
 <HoverPanel id="float-ref-panel" label="Reference preview" data-float-ref-panel>
   <p class="float-ref-panel-title" slot="heading">
     <span class="float-ref-panel-kind" data-panel-kind></span>
+    <a class="float-ref-panel-number" data-panel-number></a>
     <span class="float-ref-panel-heading" data-panel-heading hidden></span>
   </p>
   <div class="float-ref-panel-body">
-    <div class="float-ref-panel-main">
-      <div class="float-ref-panel-content" data-panel-content></div>
-      <a class="float-ref-panel-number" data-panel-number></a>
-    </div>
+    <div class="float-ref-panel-content" data-panel-content></div>
     <p class="float-ref-panel-caption" data-panel-caption></p>
-    <a class="float-ref-panel-jump" data-panel-jump
-      >Go to <span data-panel-jump-label></span
-      ><span aria-hidden="true" data-jump-arrow> →</span></a
-    >
+    <p class="float-ref-panel-links">
+      <a class="float-ref-panel-jump hover-panel-action" data-panel-jump
+        >Go to <span data-panel-jump-label></span
+        ><span aria-hidden="true" data-jump-arrow> →</span></a
+      >
+    </p>
   </div>
 </HoverPanel>
 
 <script>
   import { cloneCardShell, isKept, registerCardSource } from '../card-manager';
+  import {
+    ensureKatexStylesheet,
+    fetchDoc,
+    isThisPage,
+    markForeign,
+    pageTitleOf,
+  } from '../card-fetch';
   import { wireJumpArrow } from '../card-jump';
 
   interface KindConfig {
@@ -120,6 +131,7 @@ import HoverPanel from '../HoverPanel.astro';
     // equation, not a hover preview of it — same principle as the table
     // preview below never offering its live pagination/expand controls.
     clone.querySelector('.keyed-equation__controls')?.remove();
+    clone.querySelector('[data-eq-copy]')?.remove();
     return clone;
   }
 
@@ -234,8 +246,8 @@ import HoverPanel from '../HoverPanel.astro';
    * decision 12). The body is the picture alone — a lab's tools sit in a tray
    * outside it. A hydrated island in it (a lab's plot) becomes plain markup,
    * so it never hydrates a second time inside the card: its plot is copied as
-   * drawn. A picture with nothing drawn yet — a plot the browser has not
-   * drawn, or one on a fetched page, where only the server markup exists —
+   * drawn, or, before the island has drawn and on a fetched page, the
+   * picture the build drew (rule V3). A picture with nothing drawn at all
    * gives no copy, and the card shows the caption alone.
    */
   function cloneFigureBody(target: HTMLElement): HTMLElement | null {
@@ -248,7 +260,21 @@ import HoverPanel from '../HoverPanel.astro';
       still.append(...island.childNodes);
       island.replaceWith(still);
     }
-    clone.querySelectorAll('script, template, astro-slot').forEach((node) => node.remove());
+    clone.querySelectorAll('script, template').forEach((node) => node.remove());
+    // What an island was given as children sits in an `<astro-slot>`: a
+    // lab's build-time picture, the one a fetched page or a figure not yet
+    // drawn has (rule V3). Keep it, without the wrapper, unless the island
+    // has already drawn its own picture beside it.
+    for (const slot of clone.querySelectorAll('astro-slot, astro-static-slot')) {
+      const drawnBeside = Array.from(slot.parentElement?.children ?? []).some(
+        (sibling) =>
+          sibling !== slot &&
+          !sibling.matches('astro-slot, astro-static-slot') &&
+          sibling.querySelector('svg, img, picture, canvas, video') !== null,
+      );
+      if (drawnBeside) slot.remove();
+      else slot.replaceWith(...Array.from(slot.childNodes));
+    }
     const drawn = clone.querySelector('svg, img, picture, canvas, video, table');
     if (islands.length > 0 && !drawn) return null;
     for (const control of clone.querySelectorAll<HTMLElement>('input, select, textarea, button')) {
@@ -259,6 +285,35 @@ import HoverPanel from '../HoverPanel.astro';
     return clone;
   }
 
+  /**
+   * A figure's picture in a card is 80% of its width in the article. On this
+   * page that width is measured on the figure. A fetched page has no layout,
+   * so its copy is laid out unseen in this page's article, where every
+   * lesson's figures take the same width, and measured there.
+   */
+  const FIGURE_CARD_SCALE = 0.8;
+  const PICTURE = ':is(svg:not(.katex *), img, canvas, video)';
+
+  function figureCardWidth(target: HTMLElement, clone: HTMLElement): number | null {
+    let width = 0;
+    if (target.ownerDocument === document) {
+      width =
+        target.querySelector(`.keyed-figure__body ${PICTURE}`)?.getBoundingClientRect().width ?? 0;
+    }
+    if (!(width > 0)) {
+      const article = document.querySelector<HTMLElement>('.main-pane .sl-markdown-content');
+      if (article) {
+        const probe = document.createElement('div');
+        probe.style.cssText = 'height:0;overflow:hidden;visibility:hidden';
+        probe.append(clone);
+        article.append(probe);
+        width = clone.querySelector(PICTURE)?.getBoundingClientRect().width ?? 0;
+        probe.remove();
+      }
+    }
+    return width > 0 ? Math.round(width * FIGURE_CARD_SCALE) : null;
+  }
+
   /** A copy with no ids, so a preview never collides with the page. */
   function importWithoutIds(node: Node): Node {
     const clone = document.importNode(node, true);
@@ -359,6 +414,11 @@ import HoverPanel from '../HoverPanel.astro';
       fillContent(target, contentEl) {
         const previewable = target.dataset.figPreviewable !== 'false';
         const clone = previewable ? cloneFigureBody(target) : null;
+        const width = clone ? figureCardWidth(target, clone) : null;
+        if (clone && width) {
+          clone.style.width = `${width}px`;
+          clone.style.maxWidth = '100%';
+        }
         contentEl.replaceChildren(...(clone ? [clone] : []));
       },
       captionFor(target) {
@@ -469,9 +529,35 @@ import HoverPanel from '../HoverPanel.astro';
     return node instanceof Element ? node.closest<HTMLElement>(selector) : null;
   }
 
+  /**
+   * A reference's kind, or the kind of a float whose own number this is (the
+   * number's toolbar hangs the float's card from it, `float-toolbar.ts`).
+   */
   function kindOf(trigger: HTMLElement): KindConfig | undefined {
-    return Object.values(KINDS).find((kind) =>
-      trigger.classList.contains(kind.triggerClass),
+    return Object.values(KINDS).find(
+      (kind) =>
+        trigger.classList.contains(kind.triggerClass) ||
+        (kind.numberClass !== '' && trigger.classList.contains(kind.numberClass)),
+    );
+  }
+
+  /** The kind an anchor names: by its prefix, else a section's heading. */
+  function kindOfId(id: string): KindConfig {
+    return (
+      Object.values(KINDS).find(
+        (kind) => kind.hrefPrefix !== '#' && id.startsWith(kind.hrefPrefix.slice(1)),
+      ) ?? KINDS.section
+    );
+  }
+
+  /** A float's own number on this page, for `item` (`eq-range`, `fig-…`). */
+  function ownNumber(item: string): HTMLElement | null {
+    const kind = Object.values(KINDS).find(
+      (candidate) => candidate.numberClass !== '' && item.startsWith(candidate.hrefPrefix.slice(1)),
+    );
+    if (!kind) return null;
+    return (
+      document.getElementById(item)?.querySelector<HTMLElement>(`a.${kind.numberClass}`) ?? null
     );
   }
 
@@ -494,61 +580,23 @@ import HoverPanel from '../HoverPanel.astro';
     return { page: href.slice(0, hash), id };
   }
 
-  /**
-   * Parsed target pages, keyed by path. A cross-page preview fetches the
-   * referenced lesson once and reuses it for every later hover on this page.
-   * A failed fetch drops its entry so a later hover can retry.
-   */
-  const pageCache = new Map<string, Promise<Document>>();
-
   /** A standalone lesson deliberately has no other course pages to fetch. */
   const standalone = document.documentElement.hasAttribute(
     'data-explico-standalone',
   );
 
-  function fetchDoc(page: string): Promise<Document> {
-    let pending = pageCache.get(page);
-    if (!pending) {
-      pending = fetch(page, { credentials: 'same-origin' })
-        .then((response) => {
-          if (!response.ok) throw new Error(`${response.status} for ${page}`);
-          return response.text();
-        })
-        .then((html) => new DOMParser().parseFromString(html, 'text/html'))
-        .catch((error) => {
-          pageCache.delete(page);
-          throw error;
-        });
-      pageCache.set(page, pending);
-    }
-    return pending;
-  }
-
-  /**
-   * A cloned equation preview needs KaTeX's stylesheet to render. Every page
-   * that *authors* math already loads it; this only matters for a page whose
-   * sole math is a cross-page reference, so copy the `<link>` from the fetched
-   * document when this one has none.
-   */
-  function ensureKatexStylesheet(sourceDoc: Document): void {
-    const selector = 'link[rel="stylesheet"][href*="katex"]';
-    if (document.querySelector(selector)) return;
-    const link = sourceDoc.querySelector<HTMLLinkElement>(selector);
-    if (link) document.head.appendChild(document.importNode(link, true));
-  }
-
   const capitalized = (text: string) =>
     `${text.charAt(0).toUpperCase()}${text.slice(1)}`;
 
-  /** The number link's text: `(2.1)` for an equation, else `Table 2.1`, `§ 1.1.2`, …; empty hides it. */
+  /** The number link's text: `Equation (2.1)`, `Table 2.1`, `§ 1.1.2`, …; empty hides it. */
   function numberText(kind: KindConfig, number: string): string {
     if (kind.numberLabel) return kind.numberLabel(number);
     return kind.jumpLabel === 'equation'
-      ? `(${number})`
+      ? `Equation (${number})`
       : `${capitalized(kind.jumpLabel)} ${number}`;
   }
 
-  /** What the card's "Go to …" link names (C15): `equation (1.4)`, `table 2.1`, `the section`. */
+  /** What the card previews, for its label (C15): `equation (1.4)`, `table 2.1`, `the section`. */
   function goToLabel(kind: KindConfig, number: string): string {
     if (!number) return `the ${kind.jumpLabel}`;
     return kind.jumpLabel === 'equation'
@@ -584,8 +632,9 @@ import HoverPanel from '../HoverPanel.astro';
       return targetFor(trigger, kind) || crossPageHref(trigger, kind) ? trigger : null;
     };
 
-    const refs = Array.from(document.querySelectorAll<HTMLElement>(TRIGGER_SELECTOR));
-    if (!refs.some((ref) => refFrom(ref))) return;
+    // Every page registers, with references or none: its floats' numbers
+    // pin and dock their own cards (`float-toolbar.ts`), and a card carried
+    // in from another page is built here (rule K5).
     shell.dataset.cardSourceReady = 'true';
 
     /**
@@ -680,19 +729,26 @@ import HoverPanel from '../HoverPanel.astro';
 
       const number = target.dataset[kind.numberDataKey] ?? '';
       const href = trigger.getAttribute('href') ?? '';
-      const goTo = goToLabel(kind, number);
+      const named = goToLabel(kind, number);
       kindEl.textContent = capitalized(kind.jumpLabel);
       headingEl.textContent = kind.shortDataKey
         ? (target.dataset[kind.shortDataKey] ?? '')
         : '';
       headingEl.hidden = headingEl.textContent.length === 0;
-      // The number sits to the right of the content and is itself a link to
-      // the float — for an equation just "(2.1)", else the labelled form.
+      // The float is named by its number in the card's title, "Equation
+      // (2.1)", "Figure 2.1", in place of its kind, so the link below need
+      // not repeat it. The number is itself a link to the float.
       numberEl.textContent = numberText(kind, number);
       numberEl.hidden = numberEl.textContent.length === 0;
       numberEl.href = href;
       numberEl.title = `Go to the ${kind.jumpLabel}`;
+      kindEl.hidden = !numberEl.hidden;
+      const goTo = `the ${kind.jumpLabel}`;
       kind.fillContent(target, contentEl);
+      el.toggleAttribute(
+        'data-panel-picture',
+        kind.jumpLabel === 'figure' && !!contentEl.querySelector('svg, img, picture, canvas, video'),
+      );
       // A term cloned from another page still carries its no-JS tooltip.
       for (const term of contentEl.querySelectorAll('a.notation-term[title]')) {
         term.removeAttribute('title');
@@ -702,7 +758,7 @@ import HoverPanel from '../HoverPanel.astro';
       jumpLabelEl.textContent = lesson ? `${goTo} in ${lesson}` : goTo;
       jumpEl.href = href;
       wireJumpArrow(jumpEl);
-      el.setAttribute('aria-label', `Preview of ${goTo}`);
+      el.setAttribute('aria-label', `Preview of ${named}`);
       return el;
     };
 
@@ -734,9 +790,8 @@ import HoverPanel from '../HoverPanel.astro';
         const target = sourceDoc.getElementById(crossPage.id);
         if (!target) return null;
         ensureKatexStylesheet(sourceDoc);
-        const lesson = sourceDoc.getElementById('_top')?.textContent?.trim() || undefined;
-        const el = buildCard(trigger, target, kind, lesson);
-        el?.setAttribute('data-card-foreign', '');
+        const el = buildCard(trigger, target, kind, pageTitleOf(sourceDoc));
+        if (el) markForeign(el, sourceDoc, crossPage.page);
         return el;
       });
     };
@@ -761,6 +816,27 @@ import HoverPanel from '../HoverPanel.astro';
         return !!target && !isFullyVisible(target);
       },
       render,
+      ownAnchor: ownNumber,
+      // K5: `eq-range` names this page's equation; elsewhere it is
+      // `/its/page/#eq-range`, the name a cross-page reference gives it.
+      awayItem: (item, page) => (item.includes('#') ? item : `${page}#${item}`),
+      build: (item, page) => {
+        const hash = item.indexOf('#');
+        const targetPage = hash === -1 ? page : item.slice(0, hash);
+        const id = hash === -1 ? item : item.slice(hash + 1);
+        const kind = kindOfId(id);
+        return fetchDoc(targetPage).then((sourceDoc) => {
+          const target = sourceDoc.getElementById(id);
+          if (!target) return null;
+          ensureKatexStylesheet(sourceDoc);
+          const here = isThisPage(targetPage);
+          const link = document.createElement('a');
+          link.setAttribute('href', here ? `#${id}` : `${targetPage}#${id}`);
+          const el = buildCard(link, target, kind, here ? undefined : pageTitleOf(sourceDoc));
+          if (el && !here) markForeign(el, sourceDoc, targetPage);
+          return el;
+        });
+      },
       onChange: (open) => {
         for (const [item, bar] of foldMarks) {
           if (open.has(item)) continue;
@@ -825,23 +901,11 @@ import HoverPanel from '../HoverPanel.astro';
       gap: 0.6rem;
     }
 
-    .float-ref-panel-main {
-      display: flex;
-      min-width: 0;
-      /* Center, not baseline: a tall equation's own baseline sits wherever
-         its glyphs put it, which for a fraction or multi-row expression can
-         be well above center — baseline-aligning the number to that point
-         would leave it looking pinned near the top of the card, seemingly
-         above the equation, instead of beside it. */
-      align-items: center;
-      justify-content: space-between;
-      gap: 0.75rem;
-    }
-
+    /* A float's number in the title, in place of its kind: "Equation
+       (1.1.3)", "Figure 2.1.1". */
     .float-ref-panel-number {
-      flex: none;
-      margin: 0;
-      color: var(--sl-color-gray-3);
+      color: var(--sl-color-gray-2);
+      font-size: var(--sl-text-xs);
       font-weight: 600;
       font-variant-numeric: tabular-nums;
       text-decoration: none;
@@ -857,7 +921,6 @@ import HoverPanel from '../HoverPanel.astro';
        `viewBox` alone, or a table in its scroll clip, has no width of its
        own to give a card that sizes itself to its content. */
     .float-ref-panel-content {
-      flex: 1 1 auto;
       min-width: 0;
       overflow-x: auto;
       /* `overflow-x: auto` alone makes the block axis compute to `auto` too
@@ -877,10 +940,6 @@ import HoverPanel from '../HoverPanel.astro';
       min-inline-size: min(22rem, 70vw);
     }
 
-    .float-ref-panel-content :global(.katex-display) {
-      margin-block: 0;
-    }
-
     .float-ref-panel-content :global(table) {
       margin: 0;
       /* 60% of the real table's own font-size (`global.css`'s
@@ -920,6 +979,12 @@ import HoverPanel from '../HoverPanel.astro';
       font-size: var(--sl-text-xs);
     }
 
+    /* A figure card is as wide as its picture: the caption wraps under it
+       rather than widening the card to fit its own line. */
+    :global(.hover-panel[data-panel-picture]) .float-ref-panel-caption {
+      contain: inline-size;
+    }
+
     .float-ref-panel-heading {
       font-weight: 600;
       font-size: var(--sl-text-sm);
@@ -943,9 +1008,17 @@ import HoverPanel from '../HoverPanel.astro';
       font-size: var(--sl-text-sm);
     }
 
-    .float-ref-panel-jump {
-      justify-self: start;
-      font-size: var(--sl-text-xs);
+    /* The card's links in one row: "Go to …", and a kept card's "Opened
+       at …" beside it (rule K7, `card-manager.ts`). */
+    .float-ref-panel-links {
+      margin: 0;
     }
   }
+
+  /* Outside the layer: `katex.css` is unlayered, and its
+     `.katex-display { margin: 1em 0 }` beats any layered rule, so inside
+     `@layer` this left the equation 1em of air above and below. */
+  .float-ref-panel-content :global(.katex-display) {
+    margin-block: 0;
+  }
 </style>

package/src/components/starlight/HeadingAnchorEnhancer.astro

@@ -23,11 +23,12 @@
  *    still navigates, so the hash and the highlight below follow as before;
  *    a clipboard that is missing or refuses leaves exactly that navigation.
  *    On hover the icon says "Copy link", a title this script sets, since
- *    only with it does a click copy. A float's chain icon in its caption
- *    line (`a[data-copy-link]`, `FloatCaption.astro`) copies the same way,
- *    named by its number and short caption — "Link copied · Figure 2.2.1 ·
- *    Projectile trajectory explorer", pasted as "Figure 2.2.1, Projectile
- *    trajectory explorer"; its landing is `KeyedFloatEnhancer`'s;
+ *    only with it does a click copy. A float's Copy link, in the toolbar
+ *    its number shows (`a[data-copy-link]`, `float-toolbar.ts`), copies the
+ *    same way, named by its number and short caption — "Link copied ·
+ *    Figure 2.2.1 · Projectile trajectory explorer", pasted as "Figure
+ *    2.2.1, Projectile trajectory explorer"; its landing is
+ *    `KeyedFloatEnhancer`'s;
  *  - a smooth, header-aware scroll on an in-page jump;
  *  - a brief highlight of the section body (the heading's following siblings up
  *    to the next heading of equal or higher rank), so a deep link lands the
@@ -57,6 +58,7 @@
   import { HEADINGS, sectionParts } from './section-parts';
   import { animatedScrollIntoView } from '../scroll-animation';
   import { floatOf } from '../float-name';
+  import { readableText } from '../readable-text';
 
   (() => {
     const root = document.querySelector('.sl-markdown-content');
@@ -161,15 +163,18 @@
       const titled = heading.querySelector('.block-heading__title') ?? heading;
       return {
         label,
-        title: short || (titled.textContent?.replace(/\s+/g, ' ').trim() ?? ''),
+        title: short || readableText(titled),
       };
     };
 
+    // A float's copy link (its number's toolbar, `float-toolbar.ts`): named
+    // by its number, then its short caption, an equation's `\caption{}` too.
     const floatName = (link: HTMLElement): LinkName => {
       const root = link.closest('figure');
+      const equation = link.closest<HTMLElement>('.keyed-equation');
       return {
         label: link.dataset.copyLink ?? '',
-        title: (root && floatOf(root)?.short) || '',
+        title: (root && floatOf(root)?.short) || equation?.dataset.eqShort || '',
       };
     };
 
@@ -258,7 +263,7 @@
     root.addEventListener('click', (event) => {
       const origin = event.target instanceof Element ? event.target : null;
 
-      // A float's chain icon: copy, confirm, and let the click navigate.
+      // A float's copy link: copy, confirm, and let the click navigate.
       const floatLink = origin?.closest<HTMLElement>('a[data-copy-link]');
       const floatHref = floatLink?.getAttribute('href') || '';
       if (floatLink && floatHref.startsWith('#')) {