explico 0.8.0 → 0.11.1

package/src/components/reference/FloatRefLayer.astro

@@ -1,9 +1,9 @@
 ---
 /**
  * Progressive enhancement for `[[eq-key]]` / `[[tab-key]]` / `[[fig-key]]` /
- * `[[dia-key]]`
+ * `[[dia-key]]` / `[[sec-slug]]` / `[[ex-key]]` / `[[check-key]]`
  * references in prose (F4, extended F-tables-figures) — one hover/pin/jump
- * engine shared by all four keyed floats. This generalizes the original
+ * engine shared by the four keyed floats and sections. This generalizes the original
  * equation-only `EquationRefLayer`; the positioning, mutual-exclusion, and
  * pin/jump/Escape mechanics are unchanged, parameterized over `KIND_CONFIG`
  * below so a hover on any of the three trigger classes is handled the same
@@ -17,9 +17,19 @@
  * it points to:
  *
  *  - if the referenced float is on the current page and already fully on
- *    screen, it is highlighted in place instead of opening a card;
- *  - otherwise a small card floats near the reference showing its number,
- *    caption (table/figure), content, and a "Jump to …" link.
+ *    screen, it is highlighted in place instead of opening a card, and a
+ *    click navigates to it natively (highlight mode);
+ *  - 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
+ *    reference pins the card, a second one closes it (the card manager's
+ *    contract, `../card-manager.ts`); the card's own links navigate.
+ *
+ * A float with a short caption — an equation's `\caption{…}`, the `short`
+ * prop of a table, figure or diagram — heads the card with it
+ * (docs/plans/titles-and-containers.md Part 3), read off the target's
+ * `data-‹kind›-short`.
  *
  * What the card's content shows differs by kind:
  *  - equation: the KaTeX formula, cloned from the target (unchanged from the
@@ -30,27 +40,36 @@
  *    `previewable={false}` shows its caption and number only, since a
  *    cloned copy would be an inert, non-hydrated, id-colliding duplicate,
  *    not a working preview.
+ *  - section: the heading's title and the section's first paragraph, with
+ *    `§ 1.1.2` as the jump link when the heading shows a number.
+ *  - worked-example set and knowledge check (docs/plans/titles-and-containers.md
+ *    Part 6): the block's topical title — not its badge — and one line of
+ *    what it holds (the examples' names, the number of questions), with
+ *    `Example 1.1.1` / `Knowledge check 1.1.1` as the jump link when the
+ *    heading shows a number.
  *
  * Cross-page references (`[[lesson#eq-key]]` etc.) get the same card: their
- * `href` is a real path to another lesson page, so `showCrossPage` fetches
- * and parses that page once (cached), pulls the `#eq-…`/`#tab-…`/`#fig-…`
- * node out of it, and fills the card exactly as above (cloning across
- * documents via `importNode`). The card always opens — there is nothing in
- * this document to highlight in place — and clicking the reference navigates
- * to the other page, where `KeyedFloatEnhancer.astro` handles the landing.
+ * `href` is a real path to another lesson page, so the card's `render`
+ * fetches and parses that page once (cached), pulls the
+ * `#eq-…`/`#tab-…`/`#fig-…` node out of it, and fills the card exactly as
+ * above (cloning across documents via `importNode`). There is nothing in this
+ * document to highlight in place, so the card always opens; its link goes to
+ * the other page, where `KeyedFloatEnhancer.astro` handles the landing. A
+ * standalone export has no other pages to fetch: there a cross-page
+ * reference stays a plain link.
  *
- * This is a single-panel engine, not the notation layer's stack
- * (`popup-stack.ts`): only one card is ever open at a time — now shared
- * across all three kinds, not just equations — which is also why it's
- * hand-rolled here rather than built on `createHoverPanel`.
- * `claimActiveSurface`/`releaseActiveSurface` are still reused so an open
- * float card and an open citation or notation popup remain mutually
- * exclusive.
+ * 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.
  */
 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>
+    <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>
@@ -58,16 +77,15 @@ import HoverPanel from '../HoverPanel.astro';
     </div>
     <p class="float-ref-panel-caption" data-panel-caption></p>
     <a class="float-ref-panel-jump" data-panel-jump
-      >Jump to <span data-panel-jump-label></span
-      ><span aria-hidden="true"> ↗</span></a
+      >Go to <span data-panel-jump-label></span
+      ><span aria-hidden="true" data-jump-arrow> →</span></a
     >
   </div>
 </HoverPanel>
 
 <script>
-  import { claimActiveSurface, releaseActiveSurface } from '../hover-panel';
-
-  const GROUP = 'float-ref';
+  import { cloneCardShell, isKept, registerCardSource } from '../card-manager';
+  import { wireJumpArrow } from '../card-jump';
 
   interface KindConfig {
     readonly triggerClass: string;
@@ -82,6 +100,10 @@ import HoverPanel from '../HoverPanel.astro';
     readonly revealOnPin: boolean;
     fillContent(target: HTMLElement, contentEl: HTMLElement): void;
     captionFor(target: HTMLElement): string;
+    /** The target's `data-*` key holding its short caption, if the kind has one. */
+    readonly shortDataKey?: string;
+    /** The jump link's text, when not `(n)` / `‹Kind› n`; empty hides it. */
+    numberLabel?(number: string): string;
   }
 
   // `importNode`, not `cloneNode`: `target` may come from a *different*
@@ -154,22 +176,16 @@ import HoverPanel from '../HoverPanel.astro';
       .forEach((button) => button.remove());
   }
 
-  let diagramCloneSerial = 0;
+  let cloneSerial = 0;
 
   /**
-   * A diagram preview contains SVG fragment references (`url(#marker-id)`).
-   * Prefix every cloned id and rewrite those references so the preview cannot
-   * steal the moved/original diagram's arrow markers — or vice versa.
+   * A picture's copy keeps its SVG fragment references (`url(#marker-id)`, a
+   * clip path) working without stealing the original's: prefix every cloned
+   * id and rewrite the references to it, so neither the card nor the page
+   * resolves `#id` to the other's element.
    */
-  function cloneDiagramBody(target: HTMLElement): HTMLElement | null {
-    const clone = cloneBody(target, 'diagram-scroll');
-    if (!clone) return null;
-    clone.removeAttribute('id');
-    clone.removeAttribute('tabindex');
-    clone.removeAttribute('aria-labelledby');
-    clone.setAttribute('aria-label', 'Diagram preview');
-
-    const prefix = `float-ref-diagram-${++diagramCloneSerial}-`;
+  function isolateIds(clone: HTMLElement, kind: string): void {
+    const prefix = `float-ref-${kind}-${++cloneSerial}-`;
     const ids = new Map<string, string>();
     for (const element of clone.querySelectorAll<HTMLElement>('[id]')) {
       const oldId = element.id;
@@ -200,10 +216,101 @@ import HoverPanel from '../HoverPanel.astro';
         if (rewritten !== value) element.setAttribute(attribute, rewritten);
       }
     }
+  }
+
+  function cloneDiagramBody(target: HTMLElement): HTMLElement | null {
+    const clone = cloneBody(target, 'diagram-scroll');
+    if (!clone) return null;
+    clone.removeAttribute('id');
+    clone.removeAttribute('tabindex');
+    clone.removeAttribute('aria-labelledby');
+    clone.setAttribute('aria-label', 'Diagram preview');
+    isolateIds(clone, 'diagram');
+    return clone;
+  }
+
+  /**
+   * A figure's picture, as a still copy (docs/plans/figures-and-short-captions.md,
+   * 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 —
+   * gives no copy, and the card shows the caption alone.
+   */
+  function cloneFigureBody(target: HTMLElement): HTMLElement | null {
+    const clone = cloneBody(target, 'keyed-figure__body');
+    if (!clone) return null;
+    const islands = Array.from(clone.querySelectorAll('astro-island'));
+    for (const island of islands) {
+      const still = document.createElement('div');
+      still.className = 'float-ref-island';
+      still.append(...island.childNodes);
+      island.replaceWith(still);
+    }
+    clone.querySelectorAll('script, template, astro-slot').forEach((node) => node.remove());
+    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')) {
+      control.setAttribute('tabindex', '-1');
+      control.setAttribute('disabled', '');
+    }
+    isolateIds(clone, 'figure');
     return clone;
   }
 
-  const KINDS: Record<'equation' | 'table' | 'figure' | 'diagram', KindConfig> = {
+  /** A copy with no ids, so a preview never collides with the page. */
+  function importWithoutIds(node: Node): Node {
+    const clone = document.importNode(node, true);
+    if (clone instanceof Element) {
+      clone.removeAttribute('id');
+      clone.querySelectorAll('[id]').forEach((element) => element.removeAttribute('id'));
+    }
+    return clone;
+  }
+
+  /**
+   * The first paragraph of a heading's section. On this page a collapsible
+   * section's body sits in its `<details>` (`CollapsibleSections.astro`); on
+   * a fetched page, or an ordinary section, it is the paragraphs after the
+   * heading's wrapper, up to the next heading.
+   */
+  function sectionLead(heading: HTMLElement): HTMLElement | null {
+    const body = heading
+      .closest('summary')
+      ?.parentElement?.querySelector<HTMLElement>(':scope > .sl-section-body');
+    if (body) return body.querySelector<HTMLElement>(':scope > p');
+    let node = (heading.closest('.sl-heading-wrapper') ?? heading).nextElementSibling;
+    while (node && !node.matches('.sl-heading-wrapper, h1, h2, h3, h4, h5, h6')) {
+      if (node.tagName === 'P') return node as HTMLElement;
+      node = node.nextElementSibling;
+    }
+    return null;
+  }
+
+  /**
+   * A knowledge check's or an example set's heading (`BlockHeading.astro`):
+   * its topical title — not the badge or the number, which the card's jump
+   * link already names — then `detail`, one line of what the block holds.
+   */
+  function fillBlockPreview(target: HTMLElement, contentEl: HTMLElement, detail: string) {
+    const title = document.createElement('p');
+    title.className = 'float-ref-panel-section-title';
+    const source = target.querySelector('.block-heading__title') ?? target;
+    for (const child of source.childNodes) title.append(importWithoutIds(child));
+    const lead = document.createElement('p');
+    lead.className = 'float-ref-panel-section-lead';
+    lead.textContent = detail;
+    contentEl.replaceChildren(title, ...(detail ? [lead] : []));
+  }
+
+  const plural = (count: number, noun: string) =>
+    `${count} ${noun}${count === 1 ? '' : 's'}`;
+
+  const KINDS: Record<
+    'equation' | 'table' | 'figure' | 'diagram' | 'section' | 'example' | 'check',
+    KindConfig
+  > = {
     equation: {
       triggerClass: 'equation-ref',
       hrefPrefix: '#eq-',
@@ -211,6 +318,7 @@ import HoverPanel from '../HoverPanel.astro';
       numberDataKey: 'eqNumber',
       highlightClass: 'eq-ref-highlight',
       jumpLabel: 'equation',
+      shortDataKey: 'eqShort',
       revealOnPin: true,
       fillContent(target, contentEl) {
         contentEl.replaceChildren(cloneEquationFormula(target));
@@ -226,6 +334,7 @@ import HoverPanel from '../HoverPanel.astro';
       numberDataKey: 'tabNumber',
       highlightClass: 'tab-ref-highlight',
       jumpLabel: 'table',
+      shortDataKey: 'tabShort',
       revealOnPin: false,
       fillContent(target, contentEl) {
         const clone = cloneBody(target, 'keyed-table__body');
@@ -245,10 +354,11 @@ import HoverPanel from '../HoverPanel.astro';
       numberDataKey: 'figNumber',
       highlightClass: 'fig-ref-highlight',
       jumpLabel: 'figure',
+      shortDataKey: 'figShort',
       revealOnPin: false,
       fillContent(target, contentEl) {
         const previewable = target.dataset.figPreviewable !== 'false';
-        const clone = previewable ? cloneBody(target, 'keyed-figure__body') : null;
+        const clone = previewable ? cloneFigureBody(target) : null;
         contentEl.replaceChildren(...(clone ? [clone] : []));
       },
       captionFor(target) {
@@ -264,6 +374,7 @@ import HoverPanel from '../HoverPanel.astro';
       numberDataKey: 'diaNumber',
       highlightClass: 'dia-ref-highlight',
       jumpLabel: 'diagram',
+      shortDataKey: 'diaShort',
       revealOnPin: false,
       fillContent(target, contentEl) {
         const clone = cloneDiagramBody(target);
@@ -273,6 +384,81 @@ import HoverPanel from '../HoverPanel.astro';
         return target.querySelector('.diagram__caption-text')?.textContent ?? '';
       },
     },
+    section: {
+      triggerClass: 'section-ref',
+      // A section's anchor is its heading's slug, with no prefix of its own;
+      // only `a.section-ref` links are ever considered here.
+      hrefPrefix: '#',
+      numberClass: '',
+      numberDataKey: 'secNumber',
+      highlightClass: 'sec-ref-highlight',
+      jumpLabel: 'section',
+      revealOnPin: false,
+      fillContent(target, contentEl) {
+        const title = document.createElement('p');
+        title.className = 'float-ref-panel-section-title';
+        // The heading's own nodes, so a title with math keeps it rendered.
+        for (const child of target.childNodes) title.append(importWithoutIds(child));
+        const lead = sectionLead(target);
+        const leadClone = lead ? (importWithoutIds(lead) as HTMLElement) : null;
+        leadClone?.classList.add('float-ref-panel-section-lead');
+        contentEl.replaceChildren(title, ...(leadClone ? [leadClone] : []));
+      },
+      captionFor() {
+        return '';
+      },
+      numberLabel(number) {
+        return number ? `§\u00a0${number}` : '';
+      },
+    },
+    example: {
+      triggerClass: 'example-ref',
+      hrefPrefix: '#ex-',
+      numberClass: '',
+      numberDataKey: 'exNumber',
+      highlightClass: 'sec-ref-highlight',
+      jumpLabel: 'example',
+      revealOnPin: false,
+      fillContent(target, contentEl) {
+        // The examples' own names, as the set's tabs show them.
+        const labels = Array.from(
+          target.closest('compact-examples')?.querySelectorAll<HTMLElement>(
+            '[data-example-label]',
+          ) ?? [],
+          (panel) => panel.dataset.exampleLabel ?? '',
+        ).filter(Boolean);
+        fillBlockPreview(target, contentEl, labels.join(' · '));
+      },
+      captionFor() {
+        return '';
+      },
+      numberLabel(number) {
+        return number ? `Example\u00a0${number}` : '';
+      },
+    },
+    check: {
+      triggerClass: 'knowledge-check-ref',
+      hrefPrefix: '#check-',
+      numberClass: '',
+      numberDataKey: 'checkNumber',
+      highlightClass: 'sec-ref-highlight',
+      jumpLabel: 'knowledge check',
+      revealOnPin: false,
+      fillContent(target, contentEl) {
+        // The runner is labelled by the check's heading
+        // (`AssessmentRunner.tsx`), wherever the section has moved it.
+        const questions = target.ownerDocument
+          .querySelector(`.assessment-shell[aria-labelledby="${CSS.escape(target.id)}"]`)
+          ?.querySelectorAll('.assessment-item').length;
+        fillBlockPreview(target, contentEl, questions ? plural(questions, 'question') : '');
+      },
+      captionFor() {
+        return '';
+      },
+      numberLabel(number) {
+        return number ? `Knowledge check\u00a0${number}` : '';
+      },
+    },
   };
 
   const TRIGGER_SELECTOR = Object.values(KINDS)
@@ -351,57 +537,34 @@ import HoverPanel from '../HoverPanel.astro';
     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. */
+  function numberText(kind: KindConfig, number: string): string {
+    if (kind.numberLabel) return kind.numberLabel(number);
+    return kind.jumpLabel === 'equation'
+      ? `(${number})`
+      : `${capitalized(kind.jumpLabel)} ${number}`;
+  }
+
+  /** What the card's "Go to …" link names (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'
+      ? `equation (${number})`
+      : `${kind.jumpLabel} ${number}`;
+  }
+
   function setup() {
-    const panel = document.querySelector<HTMLElement>('[data-float-ref-panel]')!;
-    if (!panel || panel.dataset.floatRefReady === 'true') return;
-
-    // `.main-pane` (Starlight's `TwoColumnContent.astro`) sets
-    // `isolation: isolate`, which traps this panel's z-index inside it — the
-    // right "On this page" rail sits outside that isolation as a
-    // `position: fixed` sibling with no z-index of its own, and CSS still
-    // paints any positioned box ahead of a plain in-flow one regardless of
-    // z-index or DOM order. No z-index set here could ever win against that
-    // from inside `.main-pane`, so the panel is allowed to cover the rail
-    // (per its own design) by moving it out to `<body>` instead — the same
-    // fix the notation layer's popups already use for this exact trap (see
-    // `PopupStackConfig.container` in `popup-stack.ts`). `position: fixed`
-    // means the DOM parent doesn't affect its layout.
-    if (panel.parentElement !== document.body) {
-      document.body.appendChild(panel);
+    const template = document.getElementById('float-ref-panel');
+    if (
+      !(template instanceof HTMLTemplateElement) ||
+      template.dataset.cardSourceReady === 'true'
+    ) {
+      return;
     }
-
-    const refs = Array.from(
-      document.querySelectorAll<HTMLAnchorElement>(
-        Object.values(KINDS)
-          .map((kind) => `.sl-markdown-content a.${kind.triggerClass}`)
-          .join(', '),
-      ),
-    ).filter((a) => {
-      const kind = kindOf(a);
-      if (!kind) return false;
-      // Same-page (`#eq-…`) or a resolvable cross-page (`/lesson/#eq-…`) ref.
-      return (
-        (a.getAttribute('href') ?? '').startsWith(kind.hrefPrefix) ||
-        crossPageHref(a, kind) !== null
-      );
-    });
-    if (refs.length === 0) return;
-    panel.dataset.floatRefReady = 'true';
-
-    const refSet = new Set<HTMLElement>(refs);
-    const numberEl = panel.querySelector<HTMLAnchorElement>('[data-panel-number]')!;
-    const contentEl = panel.querySelector<HTMLElement>('[data-panel-content]')!;
-    const captionEl = panel.querySelector<HTMLElement>('[data-panel-caption]')!;
-    const jumpEl = panel.querySelector<HTMLAnchorElement>('[data-panel-jump]')!;
-    const jumpLabelEl = panel.querySelector<HTMLElement>('[data-panel-jump-label]')!;
-    const closeButton = panel.querySelector<HTMLElement>('[data-hover-panel-close]');
-
-    let activeTrigger: HTMLElement | null = null;
-    let activeTarget: HTMLElement | null = null;
-    let activeKind: KindConfig | null = null;
-    let mode: 'highlight' | 'panel' | null = null;
-    let pinned = false;
-    let leaveTimer: number | null = null;
+    const shell: HTMLTemplateElement = template;
 
     const targetFor = (trigger: HTMLElement, kind: KindConfig) => {
       const href = trigger.getAttribute('href') ?? '';
@@ -410,7 +573,51 @@ import HoverPanel from '../HoverPanel.astro';
         : null;
     };
 
+    // A reference this layer can preview: same-page with its target on this
+    // page, or a cross-page one. A card cloned from another page
+    // (`data-card-foreign`) holds references into that page, not this one.
+    const refFrom = (node: EventTarget | null) => {
+      const trigger = closestElement(node, TRIGGER_SELECTOR);
+      if (!trigger || trigger.closest('[data-card-foreign]')) return null;
+      const kind = kindOf(trigger);
+      if (!kind) return null;
+      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;
+    shell.dataset.cardSourceReady = 'true';
+
+    /**
+     * The outermost fold hiding `el`: a closed memo or section (its
+     * `<details>` stays laid out while closed, clipped, so its content still
+     * has an on-screen box), any other closed `<details>`, or a `hidden`
+     * ancestor. A reference to something in there previews it in a card, as
+     * if it were off screen, and marks the fold's bar while the card is open.
+     */
+    const foldHiding = (el: Element): HTMLElement | null => {
+      let hiding: HTMLElement | null = null;
+      for (let node = el.parentElement; node; node = node.parentElement) {
+        if (node instanceof HTMLDetailsElement) {
+          const state = node.dataset.state;
+          if (!node.open || (state !== undefined && state !== 'open' && state !== 'peeking')) {
+            hiding = node;
+          }
+        } else if (node.hidden) {
+          hiding = node;
+        }
+      }
+      return hiding;
+    };
+
+    /** The part of a fold a reader sees while it is closed: its bar. */
+    const foldBar = (fold: HTMLElement): HTMLElement =>
+      (fold instanceof HTMLDetailsElement
+        ? fold.querySelector<HTMLElement>(':scope > summary')
+        : null) ?? fold;
+
     const isFullyVisible = (el: HTMLElement) => {
+      if (foldHiding(el)) return false;
       const rect = el.getBoundingClientRect();
       const headerBottom =
         document
@@ -425,373 +632,182 @@ import HoverPanel from '../HoverPanel.astro';
       );
     };
 
-    const reveal = (target: HTMLElement | null, kind: KindConfig) => {
-      if (!target || !kind.revealOnPin) return;
-      target.querySelector(`.${kind.numberClass}`)?.classList.add('eq-number-revealed');
+    // Highlight mode: a same-page float already fully on screen is lit up in
+    // place, and its reference stays a plain link (the manager leaves a
+    // trigger the source does not claim alone).
+    let highlighted: { target: HTMLElement; className: string } | null = null;
+    const clearHighlight = () => {
+      highlighted?.target.classList.remove(highlighted.className);
+      highlighted = null;
+    };
+    const highlight = (trigger: HTMLElement) => {
+      const kind = kindOf(trigger);
+      const target = kind ? targetFor(trigger, kind) : null;
+      if (!kind || !target || !isFullyVisible(target)) return;
+      clearHighlight();
+      target.classList.add(kind.highlightClass);
+      highlighted = { target, className: kind.highlightClass };
     };
 
-    /**
-     * How much horizontal room the card may use: from the right edge of the
-     * left sidebar nav to the viewport edge. Unlike the old article-column
-     * clamp, this deliberately does not stop at the right "On this page"
-     * rail — a wide equation (e.g. an OLS estimator) needs the room more
-     * than the card needs to respect the ToC's column, and readers can
-     * still reach the ToC once the card closes.
-     *
-     * `.sidebar-pane` is `position: fixed` and reports its full-viewport
-     * geometry even while hidden below the sidebar breakpoint (Starlight
-     * hides it with `visibility`, not `display`), so that has to be checked
-     * explicitly rather than trusted from the rect alone.
-     */
-    function horizontalRegion(edge: number): { start: number; end: number } {
-      const sidebarPane = document.querySelector<HTMLElement>('.sidebar-pane');
-      const sidebarVisible =
-        !!sidebarPane && getComputedStyle(sidebarPane).visibility !== 'hidden';
-      const sidebarRect = sidebarVisible
-        ? sidebarPane!.getBoundingClientRect()
-        : null;
-      return {
-        start: Math.max(edge, sidebarRect?.right ?? edge),
-        end: window.innerWidth - edge,
-      };
-    }
-
-    function position(trigger: HTMLElement) {
-      const edge = 12;
-      const gap = 10;
-      const displayEquation = trigger.closest<HTMLElement>('.katex-display');
-      const safeRegion = displayEquation ?? trigger;
-      const regionRect = safeRegion.getBoundingClientRect();
-      const anchorRect = trigger.getBoundingClientRect();
-
-      // Set before any width-dependent measurement below so the card has
-      // already grown (or not) to its final width by the time its rect is
-      // read for placement.
-      const { start: horizontalStart, end: horizontalEnd } =
-        horizontalRegion(edge);
-      panel.style.setProperty(
-        '--float-ref-max-width',
-        `${Math.max(horizontalEnd - horizontalStart, 0)}px`,
-      );
-
-      const headerBottom =
-        document
-          .querySelector<HTMLElement>('.header')
-          ?.getBoundingClientRect().bottom ?? 0;
-      const verticalStart = Math.max(edge, headerBottom + edge);
-      const verticalEnd = window.innerHeight - edge;
-      const spaceAbove = regionRect.top - gap - verticalStart;
-      const spaceBelow = verticalEnd - regionRect.bottom - gap;
-
-      panel.style.maxHeight = `${Math.max(spaceAbove, spaceBelow, 0)}px`;
-      let rect = panel.getBoundingClientRect();
-      const placeBelow = spaceBelow >= rect.height || spaceBelow >= spaceAbove;
-      panel.style.maxHeight = `${Math.max(placeBelow ? spaceBelow : spaceAbove, 0)}px`;
-      rect = panel.getBoundingClientRect();
-
-      let top = placeBelow
-        ? regionRect.bottom + gap
-        : regionRect.top - gap - rect.height;
-      let left = anchorRect.left + anchorRect.width / 2 - rect.width / 2;
-
-      top = Math.max(verticalStart, Math.min(top, verticalEnd - rect.height));
-      left =
-        horizontalEnd - horizontalStart >= rect.width
-          ? Math.max(horizontalStart, Math.min(left, horizontalEnd - rect.width))
-          : Math.max(edge, Math.min(left, window.innerWidth - rect.width - edge));
-
-      panel.style.top = `${Math.round(top)}px`;
-      panel.style.left = `${Math.round(left)}px`;
-    }
+    /** `lesson` names the page a cross-page reference lands on. */
+    const buildCard = (
+      trigger: HTMLElement,
+      target: HTMLElement,
+      kind: KindConfig,
+      lesson?: string,
+    ) => {
+      const el = cloneCardShell(shell);
+      if (!el) return null;
+      const field = (name: string) => el.querySelector<HTMLElement>(`[data-panel-${name}]`);
+      const kindEl = field('kind');
+      const headingEl = field('heading');
+      const numberEl = el.querySelector<HTMLAnchorElement>('[data-panel-number]');
+      const contentEl = field('content');
+      const captionEl = field('caption');
+      const jumpEl = el.querySelector<HTMLAnchorElement>('[data-panel-jump]');
+      const jumpLabelEl = field('jump-label');
+      if (
+        !kindEl ||
+        !headingEl ||
+        !numberEl ||
+        !contentEl ||
+        !captionEl ||
+        !jumpEl ||
+        !jumpLabelEl
+      ) {
+        return null;
+      }
 
-    function fillPanel(trigger: HTMLElement, target: HTMLElement, kind: KindConfig) {
-      const number = (target.dataset[kind.numberDataKey] ?? '') as string;
-      const label = kind.jumpLabel;
+      const number = target.dataset[kind.numberDataKey] ?? '';
       const href = trigger.getAttribute('href') ?? '';
-      // The number sits to the right of the content and is itself the jump link
-      // — for an equation just "(2.1)", for a table/figure the labelled form.
-      numberEl.textContent =
-        kind.jumpLabel === 'equation'
-          ? `(${number})`
-          : `${label.charAt(0).toUpperCase()}${label.slice(1)} ${number}`;
+      const goTo = 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.
+      numberEl.textContent = numberText(kind, number);
+      numberEl.hidden = numberEl.textContent.length === 0;
       numberEl.href = href;
-      numberEl.title = `Jump to the ${label}`;
+      numberEl.title = `Go to the ${kind.jumpLabel}`;
       kind.fillContent(target, contentEl);
+      // 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');
+      }
       captionEl.textContent = kind.captionFor(target);
       captionEl.hidden = captionEl.textContent.length === 0;
-      jumpLabelEl.textContent = label;
+      jumpLabelEl.textContent = lesson ? `${goTo} in ${lesson}` : goTo;
       jumpEl.href = href;
-    }
-
-    function clearAll() {
-      if (activeTarget && activeKind) {
-        activeTarget.classList.remove(activeKind.highlightClass);
-      }
-      if (mode === 'panel') {
-        panel.hidden = true;
-        releaseActiveSurface(GROUP);
-      }
-      activeTrigger = null;
-      activeTarget = null;
-      activeKind = null;
-      mode = null;
-      pinned = false;
-    }
+      wireJumpArrow(jumpEl);
+      el.setAttribute('aria-label', `Preview of ${goTo}`);
+      return el;
+    };
 
     /**
-     * Pin the open card and hand the exclusivity group back: a pinned card is a
-     * little workspace the reader dwells in, so hovering a symbol *inside* it
-     * must be free to open its notation popup without the surface arbiter
-     * treating that as "attention moved elsewhere" and closing the card. The
-     * card still closes on its "×", on an outside click, or on Escape.
+     * A same-page reference fills its card from this document. A cross-page
+     * one fetches and parses its page once (`fetchDoc` caches it), pulls the
+     * `#eq-…`/`#tab-…`/`#fig-…` node out of it, and fills the same card —
+     * cloned across documents by the `importNode`-based helpers above.
      */
-    function pinPanel(target: HTMLElement | null, kind: KindConfig) {
-      pinned = true;
-      reveal(target, kind);
-      releaseActiveSurface(GROUP);
-    }
+    // Fold bars marked for an open card, by the card's item.
+    const foldMarks = new Map<string, HTMLElement>();
 
-    function show(trigger: HTMLElement, pin: boolean) {
+    const render = (item: string, trigger: HTMLElement) => {
       const kind = kindOf(trigger);
-      if (!kind) return;
-
+      if (!kind) return null;
       const crossPage = crossPageHref(trigger, kind);
-      if (crossPage) {
-        if (standalone) return;
-        void showCrossPage(trigger, kind, crossPage);
-        return;
-      }
-
-      const target = targetFor(trigger, kind);
-      if (!target) return;
-
-      if (pinned && trigger !== activeTrigger) return;
-
-      if (trigger === activeTrigger) {
-        if (pin) pinPanel(activeTarget, kind);
-        return;
-      }
-
-      clearAll();
-      activeTrigger = trigger;
-      activeTarget = target;
-      activeKind = kind;
-
-      if (isFullyVisible(target)) {
-        // Never reached with `pin: true` — the click handler only calls
-        // `show(trigger, true)` once it has already checked the float is
-        // off screen; an on-screen reference is left to navigate natively.
-        mode = 'highlight';
-        target.classList.add(kind.highlightClass);
-        return;
-      }
-
-      mode = 'panel';
-      fillPanel(trigger, target, kind);
-      claimActiveSurface(GROUP, clearAll);
-      panel.style.visibility = 'hidden';
-      panel.hidden = false;
-      position(trigger);
-      panel.style.visibility = 'visible';
-      if (pin) pinPanel(target, kind);
-    }
-
-    /**
-     * The cross-page counterpart of `show`: the target float lives on another
-     * lesson page, so there is nothing in this document to highlight in place.
-     * Fetch and parse that page once (`fetchDoc` caches it), pull the
-     * `#eq-…`/`#tab-…`/`#fig-…` node out of it, and fill the same card — the
-     * formula, table body, or (for a `previewable` figure) figure body, cloned
-     * across documents by `fillPanel`'s `importNode`-based helpers. A slow
-     * fetch that resolves after the pointer has moved on is discarded.
-     */
-    async function showCrossPage(
-      trigger: HTMLElement,
-      kind: KindConfig,
-      ref: { page: string; id: string },
-    ) {
-      if (pinned && trigger !== activeTrigger) return;
-      if (trigger === activeTrigger) return;
-
-      clearAll();
-      activeTrigger = trigger;
-      activeKind = kind;
-
-      let sourceDoc: Document;
-      try {
-        sourceDoc = await fetchDoc(ref.page);
-      } catch {
-        if (activeTrigger === trigger) clearAll();
-        return;
-      }
-      if (activeTrigger !== trigger) return;
-
-      const target = sourceDoc.getElementById(ref.id);
-      if (!target) {
-        clearAll();
-        return;
+      if (!crossPage) {
+        const target = targetFor(trigger, kind);
+        if (!target) return null;
+        const fold = foldHiding(target);
+        if (fold) {
+          const bar = foldBar(fold);
+          bar.classList.add('float-ref-fold-hint');
+          foldMarks.set(item, bar);
+        }
+        return buildCard(trigger, target, kind);
       }
-
-      activeTarget = target; // a detached node owned by `sourceDoc`
-      mode = 'panel';
-      ensureKatexStylesheet(sourceDoc);
-      fillPanel(trigger, target, kind);
-      claimActiveSurface(GROUP, clearAll);
-      panel.style.visibility = 'hidden';
-      panel.hidden = false;
-      position(trigger);
-      panel.style.visibility = 'visible';
-    }
-
-    function scheduleLeave() {
-      if (pinned) return;
-      if (leaveTimer !== null) window.cancelAnimationFrame(leaveTimer);
-      leaveTimer = window.requestAnimationFrame(() => {
-        leaveTimer = null;
-        if (pinned || !activeTrigger) return;
-        const stillActive =
-          activeTrigger.matches(':hover') ||
-          activeTrigger === document.activeElement ||
-          panel.matches(':hover') ||
-          panel.contains(document.activeElement);
-        if (!stillActive) clearAll();
+      return fetchDoc(crossPage.page).then((sourceDoc) => {
+        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', '');
+        return el;
       });
-    }
+    };
+
+    registerCardSource({
+      layer: 'reference',
+      triggerFrom: refFrom,
+      itemFor: (trigger) => {
+        const kind = kindOf(trigger);
+        if (!kind) return null;
+        const crossPage = crossPageHref(trigger, kind);
+        if (crossPage) return `${crossPage.page}#${crossPage.id}`;
+        return (trigger.getAttribute('href') ?? '').slice(1) || null;
+      },
+      claims: (trigger) => {
+        const kind = kindOf(trigger);
+        if (!kind) return false;
+        // The exporter rewrote a cross-page reference to the course's own
+        // URL; an offline copy must never fetch it.
+        if (crossPageHref(trigger, kind)) return !standalone;
+        const target = targetFor(trigger, kind);
+        return !!target && !isFullyVisible(target);
+      },
+      render,
+      onChange: (open) => {
+        for (const [item, bar] of foldMarks) {
+          if (open.has(item)) continue;
+          bar.classList.remove('float-ref-fold-hint');
+          foldMarks.delete(item);
+        }
+        // Keeping an equation's card, pinned or docked, reveals its faded
+        // number badge (F4).
+        for (const [item, mode] of open) {
+          if (!isKept(mode)) continue;
+          const kind = Object.values(KINDS).find(
+            (candidate) =>
+              candidate.revealOnPin && item.startsWith(candidate.hrefPrefix.slice(1)),
+          );
+          if (!kind) continue;
+          document
+            .getElementById(item)
+            ?.querySelector(`.${kind.numberClass}`)
+            ?.classList.add('eq-number-revealed');
+        }
+      },
+    });
 
     document.addEventListener('pointerover', (event) => {
       if (event.pointerType === 'touch') return;
-      const trigger = closestElement(event.target, TRIGGER_SELECTOR);
-      if (!trigger || !refSet.has(trigger)) return;
-      if (trigger === closestElement(event.relatedTarget, TRIGGER_SELECTOR)) return;
-      show(trigger, false);
+      const trigger = refFrom(event.target);
+      if (!trigger) return;
+      if (event.relatedTarget instanceof Node && trigger.contains(event.relatedTarget)) return;
+      highlight(trigger);
     });
 
     document.addEventListener('pointerout', (event) => {
       if (event.pointerType === 'touch') return;
-      const trigger = closestElement(event.target, TRIGGER_SELECTOR);
-      if (!trigger || !refSet.has(trigger)) return;
-      if (trigger === closestElement(event.relatedTarget, TRIGGER_SELECTOR)) return;
-      scheduleLeave();
+      const trigger = refFrom(event.target);
+      if (!trigger) return;
+      if (event.relatedTarget instanceof Node && trigger.contains(event.relatedTarget)) return;
+      clearHighlight();
     });
 
     document.addEventListener('focusin', (event) => {
-      const trigger = closestElement(event.target, TRIGGER_SELECTOR);
-      if (trigger && refSet.has(trigger)) show(trigger, false);
+      const trigger = refFrom(event.target);
+      if (trigger) highlight(trigger);
     });
 
     document.addEventListener('focusout', (event) => {
-      const trigger = closestElement(event.target, TRIGGER_SELECTOR);
-      if (trigger && refSet.has(trigger)) scheduleLeave();
-    });
-
-    panel.addEventListener('pointerleave', scheduleLeave);
-
-    document.addEventListener('click', (event) => {
-      if (closeButton && closestElement(event.target, '[data-hover-panel-close]')) {
-        event.preventDefault();
-        clearAll();
-        return;
-      }
-
-      const trigger = closestElement(event.target, TRIGGER_SELECTOR);
-      if (trigger && refSet.has(trigger)) {
-        const kind = kindOf(trigger);
-        if (!kind) return;
-
-        const isCrossPage = crossPageHref(trigger, kind) !== null;
-
-        // A diagram reference remains an ordinary navigation link. Hover may
-        // preview an off-screen diagram, but clicking must dismiss that card
-        // and take the reader to the real diagram in one gesture.
-        if (kind.jumpLabel === 'diagram' && !isCrossPage) {
-          clearAll();
-          return;
-        }
-
-        // A card that is already open for this trigger — same-page *or*
-        // cross-page — pins in place instead of navigating. The only way to
-        // the float itself is now the card's own number/"Jump to …" link.
-        if (mode === 'panel' && activeTrigger === trigger) {
-          event.preventDefault();
-          pinPanel(isCrossPage ? null : targetFor(trigger, kind), kind);
-          return;
-        }
-
-        if (isCrossPage) {
-          // The exporter rewrites this to the canonical course URL. Leave it
-          // as an ordinary link; an offline hover/click must never fetch it.
-          if (standalone) {
-            clearAll();
-            return;
-          }
-          // No card open yet (keyboard, or a click that beat the hover): open
-          // it — pinned — rather than leave the page.
-          event.preventDefault();
-          const ref = crossPageHref(trigger, kind)!;
-          void showCrossPage(trigger, kind, ref).then(() => {
-            if (activeTrigger === trigger && mode === 'panel') {
-              pinPanel(null, kind);
-            }
-          });
-          return;
-        }
-
-        const target = targetFor(trigger, kind);
-        if (target && !isFullyVisible(target)) {
-          event.preventDefault();
-          show(trigger, true);
-        }
-        // Already fully visible: let the native anchor navigation through —
-        // `KeyedFloatEnhancer.astro` picks up the `hashchange` it produces.
-        return;
-      }
-
-      if (closestElement(event.target, '[data-panel-jump], [data-panel-number]')) {
-        // Real navigation to the float is the point of these links; just drop
-        // our own state so a stray pointerout doesn't fight it.
-        clearAll();
-        return;
-      }
-
-      if (mode === 'panel' && event.target instanceof Node) {
-        // An outside click closes the card — but a click landing in a notation
-        // popup that a card symbol opened is "inside" as far as the reader is
-        // concerned.
-        if (
-          !panel.contains(event.target) &&
-          !closestElement(event.target, '.notation-popup')
-        ) {
-          clearAll();
-        }
-      }
+      if (refFrom(event.target)) clearHighlight();
     });
-
-    document.addEventListener('keydown', (event) => {
-      if (event.key === 'Escape' && mode) clearAll();
-    });
-
-    window.addEventListener(
-      'resize',
-      () => {
-        if (mode === 'panel' && activeTrigger) position(activeTrigger);
-      },
-      { passive: true },
-    );
-    window.addEventListener(
-      'scroll',
-      () => {
-        if (mode !== 'panel' || !activeTrigger) return;
-        if (
-          activeTarget?.ownerDocument === document &&
-          isFullyVisible(activeTarget)
-        ) {
-          clearAll();
-          return;
-        }
-        position(activeTrigger);
-      },
-      { passive: true, capture: true },
-    );
   }
 
   setup();
@@ -837,7 +853,11 @@ import HoverPanel from '../HoverPanel.astro';
       text-decoration: underline;
     }
 
+    /* The content takes the card's width: a figure's SVG sized by its
+       `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
@@ -853,6 +873,10 @@ import HoverPanel from '../HoverPanel.astro';
       display: none;
     }
 
+    .float-ref-panel-content :global(.keyed-figure__body) {
+      min-inline-size: min(22rem, 70vw);
+    }
+
     .float-ref-panel-content :global(.katex-display) {
       margin-block: 0;
     }
@@ -881,6 +905,44 @@ import HoverPanel from '../HoverPanel.astro';
       font-size: var(--sl-text-xs);
     }
 
+    /* The card's header: the kind of float, then its short caption when it
+       has one. */
+    .float-ref-panel-title {
+      display: flex;
+      flex-wrap: wrap;
+      align-items: baseline;
+      gap: 0.2rem 0.6rem;
+      margin: 0;
+    }
+
+    .float-ref-panel-kind {
+      color: var(--sl-color-gray-3);
+      font-size: var(--sl-text-xs);
+    }
+
+    .float-ref-panel-heading {
+      font-weight: 600;
+      font-size: var(--sl-text-sm);
+    }
+
+    /* A section preview: its title, then the start of its first paragraph —
+       enough to recognise the passage, not to read it here. */
+    .float-ref-panel-content :global(.float-ref-panel-section-title) {
+      margin: 0;
+      font-weight: 600;
+    }
+
+    .float-ref-panel-content :global(.float-ref-panel-section-lead) {
+      display: -webkit-box;
+      margin: 0.35rem 0 0;
+      overflow: hidden;
+      -webkit-box-orient: vertical;
+      -webkit-line-clamp: 4;
+      line-clamp: 4;
+      color: var(--sl-color-gray-2);
+      font-size: var(--sl-text-sm);
+    }
+
     .float-ref-panel-jump {
       justify-self: start;
       font-size: var(--sl-text-xs);