explico 0.3.0 → 0.5.0

package/src/components/disclosure/hover-preview.ts

@@ -0,0 +1,202 @@
+/**
+ * A lightweight "peek" overlay: hovering or focusing a collapsed trigger
+ * shows a preview of its content floating over the page below it, dismissed
+ * once the pointer/focus leaves. See `docs/plans/collapsible-disclosure.md`
+ * Part 0.
+ *
+ * This is deliberately not built on `../hover-panel.ts`'s `createHoverPanel`
+ * — that engine is a single *reference* card with pin/jump semantics and a
+ * cross-group exclusivity arbiter (`claimActiveSurface`); a collapsed-content
+ * peek has no pin state and doesn't need to coordinate with the
+ * notation/citation/float-ref panel group. It does reuse that group's
+ * `requestAnimationFrame`-scheduled leave check (see `scheduleLeave` in
+ * `FloatRefLayer.astro`) so a pointer move from the trigger onto the peek
+ * itself doesn't cause a flicker-close.
+ *
+ * One peek panel is created lazily and shared across every trigger wired
+ * with `attachHoverPeek` — only one can be hovered at a time, so reusing a
+ * single element avoids paying DOM-churn cost per hover.
+ */
+
+export interface HoverPeekOptions {
+  /**
+   * Produce the node to show in the peek. Called fresh each time the peek
+   * opens. Must return a node safe to insert into the peek panel — a clone —
+   * never a live node the document still needs in its original place, since
+   * inserting it here would move it out from there.
+   */
+  getContent(): Node;
+  /** Cap on the peek's own scroll height, in `em`. Default: 16. */
+  maxHeightEm?: number;
+  /** Accessible label for the peek region. Default: `"Preview"`. */
+  label?: string;
+}
+
+let panel: HTMLElement | null = null;
+let scroller: HTMLElement | null = null;
+let activeTrigger: HTMLElement | null = null;
+let leaveTimer: number | null = null;
+let globalListenersReady = false;
+
+function cancelLeave(): void {
+  if (leaveTimer !== null) {
+    window.cancelAnimationFrame(leaveTimer);
+    leaveTimer = null;
+  }
+}
+
+function close(): void {
+  if (!panel) return;
+  panel.hidden = true;
+  scroller?.replaceChildren();
+  activeTrigger = null;
+}
+
+/**
+ * Force-close the peek if `trigger` is the one currently showing it.
+ * For callers whose trigger can become "not worth peeking at" without a
+ * pointer/focus leave — e.g. a collapsed `<details>` expanded by clicking
+ * its still-hovered `<summary>`, where the real content is now on screen
+ * and the peek would just be a stale duplicate floating over it.
+ */
+export function closeHoverPeek(trigger: HTMLElement): void {
+  if (activeTrigger === trigger) close();
+}
+
+function scheduleLeave(): void {
+  cancelLeave();
+  leaveTimer = window.requestAnimationFrame(() => {
+    leaveTimer = null;
+    if (!activeTrigger || !panel) return;
+    // `:focus-visible`, not `=== document.activeElement` / `:focus`: the
+    // trigger is very often something like a `<summary>` that a *click*
+    // also focuses as a side effect (e.g. clicking it to toggle a
+    // `<details>`) — a plain focus check would then treat that leftover,
+    // non-keyboard focus as "still viewing it" forever, since nothing else
+    // ever takes focus to fire `blur`. `:focus-visible` is only true for
+    // focus a browser considers keyboard/keyboard-equivalent, so a mouse
+    // click doesn't leave the peek stuck open after the pointer leaves.
+    const stillActive =
+      activeTrigger.matches(':hover') ||
+      activeTrigger.matches(':focus-visible') ||
+      panel.matches(':hover') ||
+      panel.matches(':focus-within');
+    if (!stillActive) close();
+  });
+}
+
+function position(trigger: HTMLElement, target: HTMLElement): void {
+  const edge = 12;
+  const gap = 6;
+  const anchorRect = trigger.getBoundingClientRect();
+
+  target.style.visibility = 'hidden';
+  target.hidden = false;
+  const rect = target.getBoundingClientRect();
+
+  const spaceBelow = window.innerHeight - edge - anchorRect.bottom - gap;
+  const spaceAbove = anchorRect.top - edge - gap;
+  const placeBelow = spaceBelow >= rect.height || spaceBelow >= spaceAbove;
+
+  let top = placeBelow
+    ? anchorRect.bottom + gap
+    : anchorRect.top - gap - rect.height;
+  top = Math.max(edge, Math.min(top, window.innerHeight - edge - rect.height));
+
+  let left = anchorRect.left;
+  left = Math.max(edge, Math.min(left, window.innerWidth - edge - rect.width));
+
+  target.style.top = `${Math.round(top)}px`;
+  target.style.left = `${Math.round(left)}px`;
+  target.style.visibility = 'visible';
+}
+
+function ensurePanel(): { panel: HTMLElement; scroller: HTMLElement } {
+  if (panel && scroller) return { panel, scroller };
+
+  panel = document.createElement('div');
+  panel.dataset.hoverPeekPanel = 'true';
+  panel.hidden = true;
+  panel.style.cssText = [
+    'position: fixed',
+    'z-index: 95',
+    'overflow: hidden',
+    'width: min(26rem, calc(100vw - 1.5rem))',
+    'border: 1px solid var(--sl-color-gray-5, #888)',
+    'border-radius: 0.65rem',
+    'background: var(--sl-color-bg, Canvas)',
+    'box-shadow: var(--sl-shadow-lg, 0 10px 30px rgba(0, 0, 0, 0.25))',
+    'color: var(--sl-color-text, CanvasText)',
+    'font-size: var(--sl-text-sm, 0.875rem)',
+    'line-height: 1.5',
+  ].join(';');
+
+  scroller = document.createElement('div');
+  scroller.style.cssText =
+    'overflow: auto; max-height: var(--hover-peek-max-height, 16em); padding: 0.75rem 1rem;';
+  panel.append(scroller);
+  document.body.append(panel);
+
+  panel.addEventListener('pointerenter', cancelLeave);
+  panel.addEventListener('pointerleave', scheduleLeave);
+
+  if (!globalListenersReady) {
+    globalListenersReady = true;
+    document.addEventListener('keydown', (event) => {
+      if (event.key === 'Escape' && activeTrigger) close();
+    });
+    document.addEventListener('pointerdown', (event) => {
+      if (!activeTrigger || !panel) return;
+      const target = event.target instanceof Node ? event.target : null;
+      const insideTrigger = !!target && activeTrigger.contains(target);
+      const insidePanel = !!target && panel.contains(target);
+      if (!insideTrigger && !insidePanel) close();
+    });
+  }
+
+  return { panel, scroller };
+}
+
+/**
+ * Wire `trigger` so hovering or focusing it shows a peek of
+ * `options.getContent()`. Idempotent — calling it again on the same trigger
+ * (e.g. a re-run enhancer walking the DOM again) is a no-op.
+ */
+export function attachHoverPeek(
+  trigger: HTMLElement,
+  options: HoverPeekOptions,
+): void {
+  if (trigger.dataset.hoverPeekWired === 'true') return;
+  trigger.dataset.hoverPeekWired = 'true';
+
+  const maxHeightEm = options.maxHeightEm ?? 16;
+  const label = options.label ?? 'Preview';
+
+  const show = () => {
+    const { panel: el, scroller: scrollEl } = ensurePanel();
+    if (activeTrigger === trigger) {
+      cancelLeave();
+      return;
+    }
+    activeTrigger = trigger;
+    el.setAttribute('aria-label', label);
+    el.style.setProperty('--hover-peek-max-height', `${maxHeightEm}em`);
+    scrollEl.replaceChildren(options.getContent());
+    position(trigger, el);
+  };
+
+  const leave = () => {
+    if (activeTrigger === trigger) scheduleLeave();
+  };
+
+  trigger.addEventListener('pointerenter', (event) => {
+    if (event.pointerType === 'touch') return;
+    show();
+  });
+  trigger.addEventListener('pointerleave', (event) => {
+    if (event.pointerType === 'touch') return;
+    leave();
+  });
+  trigger.addEventListener('focus', show);
+  trigger.addEventListener('blur', leave);
+}

package/src/components/disclosure/persisted-disclosure.ts

@@ -0,0 +1,66 @@
+/**
+ * Shared open/closed persistence for a native `<details>` disclosure.
+ *
+ * Every collapsible built on top of this (figures, sections, tables) wants
+ * the same three behaviors: restore the reader's last choice before the
+ * element paints, save reader-triggered native `toggle`s, and degrade to the
+ * author's `defaultOpen` when nothing is saved yet or storage is unavailable.
+ * This module is the one place that logic lives — see
+ * `docs/plans/collapsible-disclosure.md` Part 0.
+ *
+ * Storage goes through `PreferenceStore` only (never `localStorage`
+ * directly — `tests/unit/seams.test.ts` enforces that boundary). The key is
+ * scoped by `location.pathname` so the same figure/section/table `id` can
+ * repeat across pages without one page's saved state leaking into another's.
+ *
+ * **Wiring**: call this from a plain top-level `<script>` in the consuming
+ * Astro component — not from inside an `astro:page-load` listener — the same
+ * way `LayoutSidebar.astro` restores its sidebar-group compact state. A
+ * module script still runs deferred, but well before the reader can see the
+ * element; wrapping it in `astro:page-load` instead would visibly flash the
+ * `defaultOpen` state first on every navigation.
+ */
+import { createBrowserPreferenceStore } from '../../session/PreferenceStore';
+
+const store = createBrowserPreferenceStore();
+
+function storageKey(key: string): string {
+  return `disclosure:${location.pathname}:${key}`;
+}
+
+/**
+ * Apply the reader's saved open/closed state to `details` (falling back to
+ * `defaultOpen`) and persist future changes.
+ *
+ * Callers that don't want persistence at all (an author-set
+ * `rememberState={false}`) should simply not call this — set
+ * `details.open = defaultOpen` directly instead.
+ */
+export function wirePersistedDetails(
+  details: HTMLDetailsElement,
+  key: string,
+  defaultOpen: boolean,
+): void {
+  const fullKey = storageKey(key);
+  const saved = store.get(fullKey);
+  details.open = saved === null ? defaultOpen : saved === 'true';
+
+  details.addEventListener('toggle', () => {
+    if (details.hasAttribute('data-explico-temporary-open')) return;
+    store.set(fullKey, String(details.open));
+  });
+}
+
+/**
+ * Save an open/closed choice directly, bypassing the `toggle`-event
+ * listener above. For a caller that animates its own collapse (a custom
+ * shrink-then-`details.open = false`, say) and so can't rely on reading
+ * `details.open` at `toggle` time — the attribute has to stay `true` for
+ * the whole animation (the browser refuses to render a closed `<details>`'s
+ * content at all, animated or not), so the boolean this function is told to
+ * save is necessarily the caller's own *intended* end state, not whatever
+ * `details.open` happens to read at the moment of the call.
+ */
+export function savePersistedOpenState(key: string, open: boolean): void {
+  store.set(storageKey(key), String(open));
+}

package/src/components/examples/CompactExamples.astro

@@ -227,11 +227,13 @@ const {
 
       let openBeforePrint: boolean | undefined;
       const enterPrintMode = () => {
+        if (document.querySelector('[data-explico-print-controller]')) return;
         if (openBeforePrint !== undefined) return;
         openBeforePrint = details.open;
         details.open = true;
       };
       const leavePrintMode = () => {
+        if (document.querySelector('[data-explico-print-controller]')) return;
         if (openBeforePrint === undefined) return;
         details.open = openBeforePrint;
         openBeforePrint = undefined;

package/src/components/figure/Figure.astro

@@ -13,21 +13,75 @@
  * interactive content — a hydrated `client:*` island cloned into a floating
  * card would be an inert, non-hydrated, id-colliding duplicate, not a
  * working preview.
+ *
+ * Collapsible + persistent (docs/plans/collapsible-disclosure.md Part 1): the
+ * figure body sits in a native `<details>` whose `<summary>` is a persistent
+ * title bar showing `title` (a short label, distinct from the longer
+ * `caption`) — reading as an OS-window minimize/restore control while
+ * staying entirely native `<details>` semantics (`aria-expanded`, keyboard
+ * toggle, no bespoke ARIA needed). The rotating chevron itself isn't
+ * authored here: `@astrojs/starlight`'s own `markdown.css` already gives
+ * every `.sl-markdown-content summary` a disclosure-triangle `::before`
+ * marker that rotates 90° on `[open]` — reproducing that ourselves would
+ * just draw two.
+ *
+ * The caption + permalink number live in a `<figcaption>` *inside*
+ * `<details>`, after `.keyed-figure__body` — the pre-collapsible reading
+ * position (caption below the figure), but now part of the disclosure
+ * content: a native closed `<details>` hides it along with the body, since
+ * hovering the (collapsed) summary already surfaces the caption via the
+ * hover-peek card — showing it twice would be redundant. `textContent`
+ * reads on a `display: none` element still work, so `FloatRefLayer`'s
+ * preview card (`captionFor` in `FloatRefLayer.astro`) can read it
+ * regardless of the source figure's collapse state.
+ *
+ * The title-bar anchor link (`.keyed-figure__title-anchor`) sits next to the
+ * title text but, like the permalink number, is a DOM sibling of `<summary>`
+ * rather than a child of it — positioned onto the same line with CSS
+ * (mirroring Starlight's own heading-wrapper anchor trick in
+ * `anchor-links.css`, adapted since our "heading" is an interactive
+ * `<summary>` rather than inert text). A focusable `<a>` nested *inside* a
+ * `<summary>` trips axe's `nested-interactive` check (two independently
+ * activatable controls, unclear which one wins on click/Enter) — the
+ * `figures.spec.ts` axe test enforces this. Keeping it a sibling, wrapped
+ * together in `.keyed-figure__titlebar` with `position: relative` +
+ * `position: absolute`, avoids that while still reading as "next to the
+ * title".
+ *
+ * `defaultOpen` sets the first-visit state; `rememberState` (default `true`)
+ * persists the reader's later choice per-page via
+ * `../disclosure/persisted-disclosure`.
  */
+
 export interface Props {
   /** Stable key, e.g. `id="projectile-trajectory"`. Omit for a positional-only figure. */
   id?: string;
-  /** Visible caption, shown below the figure and in the hover-preview card. */
+  /** Short label for the title bar / anchor. Falls back to `caption` when omitted. */
+  title?: string;
+  /** Full caption, shown below the figure (with its number) and in the hover-preview card. */
   caption: string;
   /** `false` for interactive content the hover-preview must not clone. */
   previewable?: boolean;
+  /** Author-chosen state for a reader with nothing saved yet. Default: `true`. */
+  defaultOpen?: boolean;
+  /** Persist the reader's open/closed choice across visits, per page. Default: `true`. */
+  rememberState?: boolean;
   /** Computed by `remark-notation.mjs` — never author this directly. */
   number?: string;
   /** Computed by `remark-notation.mjs` — never author this directly. */
   anchorId?: string;
 }
 
-const { id, caption, previewable = true, number, anchorId } = Astro.props;
+const {
+  id,
+  title,
+  caption,
+  previewable = true,
+  defaultOpen = true,
+  rememberState = true,
+  number,
+  anchorId,
+} = Astro.props;
 
 if (typeof caption !== 'string' || !caption.trim()) {
   throw new Error('Figure requires a non-empty `caption` prop.');
@@ -37,6 +91,8 @@ if (!number || !anchorId) {
     'Figure is missing its computed `number`/`anchorId` — this page must run remark-notation with a `figures` cross-page table configured (see astro.config.mjs).',
   );
 }
+
+const titleText = typeof title === 'string' && title.trim() ? title : caption;
 ---
 
 <figure
@@ -46,17 +102,44 @@ if (!number || !anchorId) {
   data-fig-key={id}
   data-fig-previewable={String(previewable)}
 >
-  <div class="keyed-figure__body">
-    <slot />
-  </div>
-  <figcaption class="keyed-figure__caption">
+  <div class="keyed-figure__titlebar">
+    <details
+      class="keyed-figure__details"
+      data-remember-state={String(rememberState)}
+      open={defaultOpen}
+    >
+      <summary class="keyed-figure__summary">
+        <span class="keyed-figure__title-text">{titleText}</span>
+      </summary>
+      <div class="keyed-figure__body">
+        <slot />
+      </div>
+      <figcaption class="keyed-figure__caption">
+        <a
+          class="keyed-figure__number"
+          href={`#${anchorId}`}
+          aria-label={`Figure ${number}`}>Figure {number}</a
+        >
+        <span class="keyed-figure__caption-text">{caption}</span>
+      </figcaption>
+    </details>
     <a
-      class="keyed-figure__number"
+      class="keyed-figure__title-anchor"
       href={`#${anchorId}`}
-      aria-label={`Figure ${number}`}>Figure {number}</a
+      aria-label={`Figure ${number} titled “${titleText}”`}
     >
-    <span class="keyed-figure__caption-text">{caption}</span>
-  </figcaption>
+      <svg
+        aria-hidden="true"
+        width="16"
+        height="16"
+        viewBox="0 0 24 24"
+        fill="currentColor"
+        ><path
+          d="m12.11 15.39-3.88 3.88a2.52 2.52 0 0 1-3.5 0 2.47 2.47 0 0 1 0-3.5l3.88-3.88a1 1 0 1 0-1.42-1.42l-3.88 3.89a4.48 4.48 0 0 0 6.33 6.33l3.89-3.88a1 1 0 0 0-1.42-1.42m8.58-12.08a4.49 4.49 0 0 0-6.33 0l-3.89 3.88a1 1 0 1 0 1.42 1.42l3.88-3.88a2.52 2.52 0 0 1 3.5 0 2.47 2.47 0 0 1 0 3.5l-3.88 3.88a1 1 0 0 0 0 1.42 1 1 0 0 0 1.42 0l3.88-3.89a4.49 4.49 0 0 0 0-6.33M8.83 15.17a1 1 0 0 0 .71.29 1 1 0 0 0 .71-.29l4.92-4.92a1 1 0 1 0-1.42-1.42l-4.92 4.92a1 1 0 0 0 0 1.42"
+        ></path></svg
+      >
+    </a>
+  </div>
 </figure>
 
 <style>
@@ -65,6 +148,96 @@ if (!number || !anchorId) {
     padding: 0;
   }
 
+  /* One card for the whole figure — title bar and body together — rather
+     than a separate title strip on top of a second bordered box (the
+     `.lab-shell` a wrapped lab already draws around itself): the title now
+     lives *inside* this card, so `.lab-shell` gets its own border/background
+     stripped back to plain spacing when nested here (see `global.css`,
+     `.keyed-figure__body .lab-shell`) to avoid drawing that second box.
+     Same treatment as `.lab-shell` itself, for one consistent "card"
+     language sitewide — overrides Starlight's own default `<details>`
+     accent rule (`markdown.css`, a rule down the left side) entirely. */
+  .keyed-figure__details {
+    border: 1px solid var(--sl-color-gray-5);
+    border-block-start: 4px solid var(--sl-color-accent);
+    border-radius: 0.2rem;
+    background: color-mix(in srgb, var(--sl-color-bg) 94%, var(--sl-color-accent) 6%);
+    box-shadow: 0 1rem 2.6rem rgba(0, 0, 0, 0.13);
+    padding: clamp(1rem, 3vw, 1.5rem);
+  }
+
+  .keyed-figure__titlebar {
+    position: relative;
+    /* A custom property, not `font-size` itself: `font-size` is inherited
+       CSS, and `.keyed-figure__body` (the slotted figure content) is a
+       *descendant* of this wrapper too — setting `font-size` here directly
+       would inflate the figure's real content, not just the title. Read
+       this back explicitly on just the summary and the anchor icon below. */
+    --keyed-figure-title-size: var(--sl-text-h3);
+  }
+
+  .keyed-figure__summary {
+    /* This is a title, not a caption — size it like the headings labs
+       already use internally (e.g. LaunchAngleExplorer's own <h3>), not
+       like the muted `.keyed-figure__caption-text` below. */
+    font-size: var(--keyed-figure-title-size);
+    line-height: var(--sl-line-height-headings, 1.2);
+    /* Room for the absolutely-positioned anchor icon so title text never
+       runs under it. */
+    padding-inline-end: 1.5em;
+  }
+
+  .keyed-figure__title-text {
+    font-weight: 600;
+    color: var(--sl-color-white);
+  }
+
+  .keyed-figure__title-anchor {
+    position: absolute;
+    top: 0.15em;
+    inset-inline-end: 0;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    font-size: var(--keyed-figure-title-size);
+    width: 1em;
+    height: 1em;
+    color: var(--sl-color-gray-3);
+    text-decoration: none;
+    /* Prevent double/triple clicks from selecting the icon's a11y text. */
+    -webkit-user-select: none;
+    user-select: none;
+  }
+
+  .keyed-figure__title-anchor svg {
+    width: 0.7em;
+    height: 0.7em;
+  }
+
+  .keyed-figure__title-anchor:hover,
+  .keyed-figure__title-anchor:focus-visible {
+    color: var(--sl-color-text-accent);
+  }
+
+  .keyed-figure__title-anchor:focus-visible {
+    outline: 2px solid var(--sl-color-accent);
+    outline-offset: 0.15rem;
+  }
+
+  /* Hidden at rest, revealed on hover/focus of the title bar — same
+     "hover/focus to reveal" treatment as Starlight's own heading anchors
+     (`anchor-links.css`). */
+  @media (hover: hover) {
+    .keyed-figure__title-anchor {
+      opacity: 0;
+    }
+
+    .keyed-figure__title-anchor:focus-visible,
+    .keyed-figure__titlebar:hover .keyed-figure__title-anchor {
+      opacity: 1;
+    }
+  }
+
   .keyed-figure__body {
     overflow-x: auto;
   }
@@ -100,5 +273,101 @@ if (!number || !anchorId) {
     .keyed-figure__number {
       color: inherit;
     }
+
+    .keyed-figure__title-anchor {
+      display: none;
+    }
+
+    /* The disclosure triangle (Starlight's summary::before) is meaningless
+       once printed content is forced open below. */
+    .keyed-figure__summary::before {
+      display: none !important;
+    }
+
+    /* A closed <details> hides its non-summary children via the UA
+       stylesheet; force the body and caption visible regardless of
+       on-screen state so a collapsed figure still prints its content. */
+    .keyed-figure__body,
+    .keyed-figure__caption {
+      display: block !important;
+    }
   }
 </style>
+
+<script>
+  import { wirePersistedDetails } from '../disclosure/persisted-disclosure';
+  import { attachHoverPeek, closeHoverPeek } from '../disclosure/hover-preview';
+
+  document
+    .querySelectorAll<HTMLDetailsElement>(
+      '.keyed-figure__details:not([data-figure-wired])',
+    )
+    .forEach((details) => {
+      details.dataset.figureWired = 'true';
+      const figure = details.closest<HTMLElement>('.keyed-figure');
+      if (!figure || !figure.id) return;
+
+      // The SSR-rendered `open` attribute already carries the author's
+      // `defaultOpen` prop verbatim — read it before anything below mutates
+      // `.open`, rather than threading the prop value through a second data
+      // attribute.
+      const defaultOpen = details.open;
+      if (details.dataset.rememberState === 'true') {
+        wirePersistedDetails(details, `figure:${figure.id}`, defaultOpen);
+      }
+
+      const summary = details.querySelector<HTMLElement>(
+        ':scope > summary',
+      );
+
+      // Deep-linking to this figure (from a `[[fig-key]]` jump or a shared
+      // URL) must reveal it even if a reader had left it collapsed — the
+      // figure's id lives on the always-visible <figure>, not on the
+      // <details> itself, so the browser's native :target reveal doesn't
+      // apply here and this has to be done by hand.
+      const openIfTargeted = () => {
+        if (location.hash === `#${figure.id}`) details.open = true;
+      };
+      openIfTargeted();
+      window.addEventListener('hashchange', openIfTargeted);
+
+      if (!summary) return;
+
+      // The peek is only useful while collapsed — once expanded, the real
+      // content is already on screen right below the title bar, and duping
+      // it into a floating box would just be noise. `attachHoverPeek` itself
+      // doesn't know about "collapsed", so gate it here: a capture-order
+      // listener added *before* the wiring call runs first on the same
+      // element and can suppress the event before `attachHoverPeek`'s own
+      // handler sees it.
+      const suppressWhenOpen = (event: Event) => {
+        if (details.open) event.stopImmediatePropagation();
+      };
+      summary.addEventListener('pointerenter', suppressWhenOpen);
+      summary.addEventListener('focus', suppressWhenOpen);
+
+      // Expanding while the peek is still showing (hover, then click to
+      // open without the pointer ever leaving) would otherwise leave a now-
+      // redundant preview floating over the real content that just
+      // appeared underneath it.
+      details.addEventListener('toggle', () => {
+        if (details.open) closeHoverPeek(summary);
+      });
+
+      // The caption now lives in the <figcaption> after <details>, not
+      // inside the summary — query it from the figure, not the summary.
+      const captionText =
+        figure.querySelector('.keyed-figure__caption-text')?.textContent ??
+        '';
+      attachHoverPeek(summary, {
+        label: `Figure ${figure.dataset.figNumber ?? ''} preview`,
+        getContent: () => {
+          const wrap = document.createElement('div');
+          const strong = document.createElement('strong');
+          strong.textContent = `Figure ${figure.dataset.figNumber ?? ''}`;
+          wrap.append(strong, document.createTextNode(` — ${captionText}`));
+          return wrap;
+        },
+      });
+    });
+</script>