explico 0.1.1 → 0.2.0

package/src/components/popup-stack.ts

@@ -0,0 +1,345 @@
+/**
+ * Multi-popup engine for the notation layer (see `NotationLayer.astro`).
+ *
+ * Unlike the single shared hover panel (`./hover-panel.ts`, used by the
+ * citation layer, which never nests), notation cards nest: a card's formula
+ * can itself carry live symbols (D15), and pointing at one is the reader
+ * exploring outward, not navigating away — replacing the card they were just
+ * reading with a different one is the wrong response to that. So this module
+ * keeps a small stack of independent popup elements instead of one shared
+ * panel: each key gets at most one open popup, opening a symbol found inside
+ * an existing popup adds another popup beside it, closing a popup also
+ * closes whatever was opened from inside it (nothing is left pointing at a
+ * symbol that no longer exists), and every popup positions itself clear of
+ * its trigger and of every other currently open popup.
+ *
+ * Because each key's popup is a real, persistent DOM node — never replaced
+ * in place — this sidesteps the reentrancy problem an earlier "replace the
+ * panel's content" design ran into: a `:hover` check made once the dust
+ * settles is always accurate, there is no synthetic event fired by a node
+ * removing itself out from under the pointer.
+ */
+import { claimActiveSurface, releaseActiveSurface } from './hover-panel';
+
+export interface PopupStackConfig {
+  /** Where popup elements are appended. They are `position: fixed`, so the
+   *  parent's place in the document doesn't matter. */
+  container: HTMLElement;
+  /** Exclusivity group against other surfaces (e.g. the citation panel). */
+  groupId: string;
+  /**
+   * Nearest interactive trigger for an event target — must search the live
+   * document *and* the content of every currently open popup.
+   */
+  triggerFrom: (node: EventTarget | null) => HTMLElement | null;
+  /** Stable key identifying what a trigger points at. */
+  keyFor: (trigger: HTMLElement) => string | null;
+  /** A pin toggle outside the popups themselves (e.g. a list button). */
+  pinControlFrom?: (node: EventTarget | null) => HTMLElement | null;
+  /**
+   * Build a fresh, unattached popup element for `key`, opened from `trigger`.
+   * Return `null` to abort the open (unknown key).
+   */
+  createPopup: (key: string, trigger: HTMLElement) => HTMLElement | null;
+  /** Called after any popup opens, closes, or changes pin state. */
+  onChange?: (open: ReadonlySet<string>, pinned: ReadonlySet<string>) => void;
+}
+
+interface PopupRecord {
+  key: string;
+  el: HTMLElement;
+  trigger: HTMLElement;
+  parentKey: string | null;
+  pinned: boolean;
+  leaveTimer: number | null;
+}
+
+function closestElement(node: EventTarget | null, selector: string) {
+  return node instanceof Element ? node.closest<HTMLElement>(selector) : null;
+}
+
+export function createPopupStack(config: PopupStackConfig) {
+  const { container } = config;
+  const popups = new Map<string, PopupRecord>();
+  const order: string[] = []; // open order, oldest first — Escape closes the last.
+
+  const pinControlFrom = (node: EventTarget | null) =>
+    config.pinControlFrom?.(node) ?? null;
+
+  const notify = () => {
+    config.onChange?.(
+      new Set(popups.keys()),
+      new Set([...popups.values()].filter((p) => p.pinned).map((p) => p.key)),
+    );
+  };
+
+  const parentOf = (trigger: HTMLElement): string | null => {
+    const host = closestElement(trigger, '[data-popup-key]');
+    const key = host?.getAttribute('data-popup-key') ?? null;
+    return key && popups.has(key) ? key : null;
+  };
+
+  function position(record: PopupRecord) {
+    const edge = 12;
+    const gap = 10;
+    const { el, trigger } = record;
+    const displayEquation = trigger.closest<HTMLElement>('.katex-display');
+    const safeRegion = displayEquation ?? trigger;
+    const regionRect = safeRegion.getBoundingClientRect();
+    const anchorRect = trigger.getBoundingClientRect();
+
+    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;
+
+    el.style.maxHeight = `${Math.max(spaceAbove, spaceBelow, 0)}px`;
+    let rect = el.getBoundingClientRect();
+    const placeBelow = spaceBelow >= rect.height || spaceBelow >= spaceAbove;
+    el.style.maxHeight = `${Math.max(placeBelow ? spaceBelow : spaceAbove, 0)}px`;
+    rect = el.getBoundingClientRect();
+
+    let top = placeBelow
+      ? regionRect.bottom + gap
+      : regionRect.top - gap - rect.height;
+    let left = anchorRect.left + anchorRect.width / 2 - rect.width / 2;
+
+    const article = document.querySelector<HTMLElement>('.sl-markdown-content');
+    const articleRect = article?.getBoundingClientRect();
+    const horizontalStart = Math.max(edge, articleRect?.left ?? edge);
+    const horizontalEnd = Math.min(
+      window.innerWidth - edge,
+      articleRect?.right ?? window.innerWidth - edge,
+    );
+
+    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));
+
+    // Clear of every other open popup: cascade below whichever one this
+    // still overlaps, then re-clamp to the viewport. A handful of popups
+    // open at once is the realistic ceiling here, so a bounded scan is
+    // plenty — this does not need to be a general bin-packer.
+    const others = [...popups.values()]
+      .filter((other) => other.key !== record.key)
+      .map((other) => other.el.getBoundingClientRect());
+    for (let attempt = 0; attempt < others.length + 4; attempt++) {
+      const box = {
+        top,
+        left,
+        right: left + rect.width,
+        bottom: top + rect.height,
+      };
+      const hit = others.find(
+        (o) =>
+          box.left < o.right &&
+          box.right > o.left &&
+          box.top < o.bottom &&
+          box.bottom > o.top,
+      );
+      if (!hit) break;
+      top = hit.bottom + gap;
+      if (top + rect.height > verticalEnd) {
+        top = verticalStart;
+        left += rect.width * 0.35 + gap;
+      }
+    }
+    top = Math.max(verticalStart, Math.min(top, verticalEnd - rect.height));
+    left = Math.max(
+      edge,
+      Math.min(left, window.innerWidth - rect.width - edge),
+    );
+
+    el.style.top = `${Math.round(top)}px`;
+    el.style.left = `${Math.round(left)}px`;
+  }
+
+  function scheduleLeaveCheck(record: PopupRecord) {
+    if (record.pinned) return;
+    if (record.leaveTimer !== null) {
+      window.cancelAnimationFrame(record.leaveTimer);
+    }
+    record.leaveTimer = window.requestAnimationFrame(() => {
+      record.leaveTimer = null;
+      if (!popups.has(record.key) || record.pinned) return;
+      const staysOpen =
+        record.trigger.matches(':hover') ||
+        record.trigger === document.activeElement ||
+        record.el.matches(':hover') ||
+        record.el.contains(document.activeElement) ||
+        // A hovered or pinned CHILD keeps its parent alive too — moving from
+        // the trigger straight into a child popup (a real, legitimate path;
+        // the child is positioned right next to it) must not close this one
+        // out from under the reader mid-move.
+        [...popups.values()].some((other) => other.parentKey === record.key);
+      if (staysOpen) return;
+      closePopup(record.key);
+    });
+  }
+
+  function closePopup(key: string) {
+    const record = popups.get(key);
+    if (!record) return;
+    // Children first — a card opened from inside this one has nothing left
+    // to anchor to once it's gone.
+    for (const other of [...popups.values()]) {
+      if (other.parentKey === key) closePopup(other.key);
+    }
+    if (record.leaveTimer !== null) {
+      window.cancelAnimationFrame(record.leaveTimer);
+    }
+    popups.delete(key);
+    const at = order.indexOf(key);
+    if (at !== -1) order.splice(at, 1);
+    record.el.remove();
+    if (popups.size === 0) releaseActiveSurface(config.groupId);
+    notify();
+  }
+
+  function closeAll() {
+    for (const key of [...popups.keys()]) closePopup(key);
+  }
+
+  function openPopup(key: string, trigger: HTMLElement, pin: boolean): void {
+    const existing = popups.get(key);
+    if (existing) {
+      if (pin && !existing.pinned) {
+        existing.pinned = true;
+        notify();
+      }
+      return;
+    }
+
+    const el = config.createPopup(key, trigger);
+    if (!el) return;
+
+    if (popups.size === 0) claimActiveSurface(config.groupId, closeAll);
+
+    el.dataset.popupKey = key;
+    el.style.position = 'fixed';
+    el.style.visibility = 'hidden';
+    el.hidden = false;
+    container.appendChild(el);
+
+    const record: PopupRecord = {
+      key,
+      el,
+      trigger,
+      parentKey: parentOf(trigger),
+      pinned: pin,
+      leaveTimer: null,
+    };
+    popups.set(key, record);
+    order.push(key);
+
+    position(record);
+    el.style.visibility = 'visible';
+
+    el.addEventListener('pointerleave', () => scheduleLeaveCheck(record));
+    el.addEventListener('focusout', () => scheduleLeaveCheck(record));
+
+    notify();
+  }
+
+  document.addEventListener('pointerover', (event) => {
+    if (event.pointerType === 'touch') return;
+    const trigger = config.triggerFrom(event.target);
+    if (!trigger || trigger === config.triggerFrom(event.relatedTarget)) {
+      return;
+    }
+    const key = config.keyFor(trigger);
+    if (!key) return;
+    openPopup(key, trigger, false);
+  });
+
+  document.addEventListener('pointerout', (event) => {
+    if (event.pointerType === 'touch') return;
+    const trigger = config.triggerFrom(event.target);
+    if (!trigger || trigger === config.triggerFrom(event.relatedTarget)) {
+      return;
+    }
+    const key = config.keyFor(trigger);
+    const record = key ? popups.get(key) : undefined;
+    if (record) scheduleLeaveCheck(record);
+  });
+
+  document.addEventListener('focusin', (event) => {
+    const trigger = config.triggerFrom(event.target);
+    const key = trigger ? config.keyFor(trigger) : null;
+    if (trigger && key) openPopup(key, trigger, false);
+  });
+
+  document.addEventListener('focusout', (event) => {
+    const trigger = config.triggerFrom(event.target);
+    const key = trigger ? config.keyFor(trigger) : null;
+    const record = key ? popups.get(key) : undefined;
+    if (record) scheduleLeaveCheck(record);
+  });
+
+  document.addEventListener('click', (event) => {
+    const control = pinControlFrom(event.target);
+    if (control) {
+      const ownKey = config.keyFor(control);
+      if (ownKey) openPopup(ownKey, control, true);
+      return;
+    }
+
+    const trigger = config.triggerFrom(event.target);
+    if (trigger && !trigger.closest('a')) {
+      const key = config.keyFor(trigger);
+      if (key) {
+        event.preventDefault();
+        if (popups.get(key)?.pinned) {
+          closePopup(key);
+        } else {
+          openPopup(key, trigger, true);
+        }
+        return;
+      }
+    }
+    if (trigger) return; // a real link trigger: let it navigate.
+
+    // Anywhere else inside an open popup collapses just that one — its body
+    // is never a trigger, so a click there can only mean "I'm done with
+    // this." (The corner "×" falls under this same rule.) A real link
+    // inside it — "Open the full definition" — is excluded so it navigates.
+    const host = closestElement(event.target, '[data-popup-key]');
+    const hostKey = host?.getAttribute('data-popup-key');
+    if (
+      hostKey &&
+      event.target instanceof Node &&
+      !closestElement(event.target, 'a')
+    ) {
+      closePopup(hostKey);
+    }
+  });
+
+  // Deliberately no "click outside closes everything": the reader explicitly
+  // asked that clicking the equation itself — the unexplained parts included
+  // — never collapses a card. Closing is always a targeted gesture: the "×",
+  // a click on a card's own body, Escape, or (for a card that was only ever
+  // hovered, never pinned) the pointer simply leaving.
+
+  document.addEventListener('keydown', (event) => {
+    if (event.key !== 'Escape' || order.length === 0) return;
+    closePopup(order[order.length - 1]);
+  });
+
+  const repositionAll = () => {
+    for (const record of popups.values()) position(record);
+  };
+  window.addEventListener('resize', repositionAll, { passive: true });
+  window.addEventListener('scroll', repositionAll, {
+    passive: true,
+    capture: true,
+  });
+
+  return { closeAll };
+}
+
+export { closestElement };

package/src/components/starlight/EquationEnhancer.astro

@@ -9,10 +9,19 @@
  * `scroll-margin`.
  *
  * This script only adds what CSS and anchors cannot:
- *  - re-triggering the highlight when the same `#eq-…` is activated again;
  *  - a smooth, header-aware scroll on an in-page jump;
+ *  - re-triggering the highlight when the same `#eq-…` is activated again —
+ *    the one case a plain anchor click does nothing for, since the browser
+ *    won't navigate to a fragment that's already current;
  *  - moving keyboard focus onto the equation so screen-reader users land on it.
  *
+ * It deliberately does *not* intercept an ordinary click that changes the
+ * hash. `:target` is set only by a genuine same-document fragment
+ * navigation — never by `history.pushState` (a common trap: pushState
+ * updates the URL but leaves `:target`, and thus `eq-flash`, dark). Letting
+ * the click through and reacting to the `hashchange` it produces is what
+ * actually plays the highlight.
+ *
  * Everything here is gated on `prefers-reduced-motion` and degrades to the
  * native anchor behaviour if it throws.
  */
@@ -55,14 +64,20 @@
       if (!href.startsWith('#eq-')) return; // cross-page: let the browser navigate
       const target = document.getElementById(href.slice(1));
       if (!target) return;
-      event.preventDefault();
-      if (location.hash !== href) history.pushState(null, '', href);
-      activate(target, true);
+      // Only the already-on-this-anchor click needs handling here — the
+      // browser has nothing new to navigate to, so it won't fire `hashchange`
+      // and nothing else will re-trigger the flash. Every other click is left
+      // alone: its native navigation sets `:target` and fires `hashchange`,
+      // which the listener below turns into the same `activate()`.
+      if (location.hash === href) {
+        event.preventDefault();
+        activate(target, true);
+      }
     });
 
     window.addEventListener('hashchange', () => {
       if (!location.hash.startsWith('#eq-')) return;
-      activate(document.getElementById(location.hash.slice(1)), false);
+      activate(document.getElementById(location.hash.slice(1)), true);
     });
 
     if (location.hash.startsWith('#eq-')) {

package/src/components/starlight/HeadingAnchorEnhancer.astro

@@ -0,0 +1,131 @@
+---
+/**
+ * Progressive enhancement for content-heading deep links (Step F3), the sibling
+ * of `EquationEnhancer.astro`.
+ *
+ * The no-JS baseline is complete: `rehype-heading-anchors` emits Starlight's
+ * `.sl-heading-wrapper` + `a.sl-anchor-link` markup, its bundled
+ * `anchor-links.css` does the hover/focus reveal, and `global.css` does the
+ * `:target` flash (with a `prefers-reduced-motion` fallback) and the
+ * sticky-header `scroll-margin`.
+ *
+ * This script only adds what CSS and anchors cannot:
+ *  - 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
+ *    reader on the whole passage, not just the title;
+ *  - re-triggering the highlight when the same `#…` is activated again —
+ *    the one case a plain anchor click does nothing for, since the browser
+ *    won't navigate to a fragment that's already current;
+ *  - moving keyboard focus onto the heading so screen-reader users land on it.
+ *
+ * It deliberately does *not* intercept an ordinary click that changes the
+ * hash. `:target` is set only by a genuine same-document fragment
+ * navigation — never by `history.pushState` (a common trap: pushState
+ * updates the URL but leaves `:target`, and thus `heading-flash`, dark).
+ * Letting the click through and reacting to the `hashchange` it produces is
+ * what actually plays the highlight — see `EquationEnhancer.astro`, which
+ * this mirrors.
+ *
+ * Everything here is gated on `prefers-reduced-motion` and degrades to the
+ * native anchor behaviour if it throws.
+ */
+---
+
+<script>
+  (() => {
+    const root = document.querySelector('.sl-markdown-content');
+    if (!root) return;
+
+    const HEADINGS = 'h1, h2, h3, h4, h5, h6';
+    const reduce = window.matchMedia('(prefers-reduced-motion: reduce)');
+
+    const isContentHeading = (el: Element | null): el is HTMLElement =>
+      !!el && el.matches(HEADINGS) && root.contains(el);
+
+    const headingForId = (raw: string): HTMLElement | null => {
+      if (!raw) return null;
+      let id = raw;
+      try {
+        id = decodeURIComponent(raw);
+      } catch {
+        /* keep the raw value */
+      }
+      const el = document.getElementById(id);
+      return isContentHeading(el) ? el : null;
+    };
+
+    // Matches `global.css`'s `heading-flash` animation-duration; the buffer
+    // avoids clipping the CSS animation's own fade-out.
+    const FLASH_MS = 5200;
+
+    const flash = (el: Element | null) => {
+      if (!el || reduce.matches) return;
+      el.classList.remove('deep-link-section-flash');
+      void (el as HTMLElement).offsetWidth;
+      el.classList.add('deep-link-section-flash');
+      window.setTimeout(
+        () => el.classList.remove('deep-link-section-flash'),
+        FLASH_MS,
+      );
+    };
+
+    const sectionParts = (heading: HTMLElement): Element[] => {
+      const wrapper = heading.closest('.sl-heading-wrapper') ?? heading;
+      const rank = Number(heading.tagName[1]);
+      const parts: Element[] = [wrapper];
+      let node = wrapper.nextElementSibling;
+      while (node) {
+        const inner = node.matches(HEADINGS)
+          ? node
+          : node.querySelector(HEADINGS);
+        if (inner && Number(inner.tagName[1]) <= rank) break;
+        parts.push(node);
+        node = node.nextElementSibling;
+      }
+      return parts;
+    };
+
+    const activate = (heading: HTMLElement | null, doScroll: boolean) => {
+      if (!heading) return;
+      const parts = sectionParts(heading);
+      if (doScroll) {
+        parts[0].scrollIntoView({
+          behavior: reduce.matches ? 'auto' : 'smooth',
+          block: 'start',
+        });
+      }
+      for (const part of parts) flash(part);
+      heading.setAttribute('tabindex', '-1');
+      try {
+        heading.focus({ preventScroll: true });
+      } catch {
+        heading.focus();
+      }
+    };
+
+    root.addEventListener('click', (event) => {
+      const origin = event.target instanceof Element ? event.target : null;
+      const link = origin?.closest('a.sl-anchor-link');
+      if (!link) return;
+      const href = link.getAttribute('href') || '';
+      if (!href.startsWith('#')) return;
+      const heading = headingForId(href.slice(1));
+      if (!heading) return;
+      // Only the already-on-this-anchor click needs handling here — see
+      // `EquationEnhancer.astro`. Every other click is left to the browser's
+      // own fragment navigation, picked up below via `hashchange`.
+      if (location.hash === href) {
+        event.preventDefault();
+        activate(heading, true);
+      }
+    });
+
+    window.addEventListener('hashchange', () => {
+      activate(headingForId(location.hash.slice(1)), true);
+    });
+
+    const initial = headingForId(location.hash.slice(1));
+    if (initial) activate(initial, true);
+  })();
+</script>

package/src/components/starlight/LessonFooter.astro

@@ -19,6 +19,7 @@ import NotationLayer, {
 } from '../notation/NotationLayer.astro';
 import CitationLayer from '../citation/CitationLayer.astro';
 import EquationEnhancer from './EquationEnhancer.astro';
+import HeadingAnchorEnhancer from './HeadingAnchorEnhancer.astro';
 
 // `lessonId` is no longer authored (Phase C2); derive it from the route.
 const routeSlug = Astro.locals.starlightRoute.entry.id;
@@ -39,6 +40,8 @@ if (lessonId) {
       label: definition.label,
       summary: definition.summary,
       formula: definition.formula,
+      formulaScope: definition.formulaScope,
+      glosses: definition.glosses,
       units: definition.units,
       seeAlso: definition.seeAlso,
       editorialStatus: definition.editorialStatus,
@@ -55,4 +58,5 @@ if (lessonId) {
 <NotationLayer definitions={definitions} />
 {lessonId && <CitationLayer />}
 {lessonId && <EquationEnhancer />}
+{lessonId && <HeadingAnchorEnhancer />}
 <DefaultFooter />

package/src/content-config.ts

@@ -3,6 +3,7 @@ import { glob } from 'astro/loaders';
 import { z } from 'astro/zod';
 import { docsSchema } from '@astrojs/starlight/schema';
 import { isSubstantiveMeaning } from './reference/prose';
+import { glossKeySegment } from './reference/gloss';
 
 // Phase F: content lives in the top-level `content/` folder, not `src/content/`.
 // `docsLoader()` is hard-wired to `<srcDir>/content/docs`, so the `docs`
@@ -71,6 +72,42 @@ const notationSource = z.union([
  * `label` is authored only where that reads wrong. The `notationProse`
  * refinement rejects an under-specified `meaning`.
  */
+/**
+ * A **gloss** on a notation card: a symbol the card's own `formula` needs in
+ * order to be written down, carrying a name and nothing else (D15).
+ *
+ * A gloss is deliberately cheaper than a card. It has no description, no
+ * sources, no curriculum alignment, no review state, and no glossary card of
+ * its own; it is not a node in the curriculum graph and never creates a
+ * reference edge. Its key is derived, not authored — `<card key>.<slug(name)>`
+ * — so a gloss is scoped to the card that declares it and two cards may each
+ * gloss `T`. Because a formula spells LaTeX and never a key, **promoting** a
+ * gloss is exactly: delete this line, add `content/notation/<key>.md`.
+ *
+ * `units` is optional and stays a bare unit string: "T — time" is ambiguous in
+ * a corpus with several `T`s, "T — time, years from valuation" is not, and it
+ * is still one line. Prose belongs on a card.
+ */
+const notationGloss = z.object({
+  latex: z.string().min(1),
+  name: z
+    .string()
+    .min(1)
+    .refine((value) => glossKeySegment(value) !== undefined, {
+      message:
+        'A gloss name must contain letters or digits so a key can be derived from it.',
+    })
+    // The symbol goes in `latex`, the name names it. A name carrying LaTeX is
+    // the one unambiguous way to get this field wrong, so it blocks; a name
+    // that is merely long is a Tier-3 `gloss-name-shape` warning instead,
+    // because a complicated quantity may honestly need several words.
+    .refine((value) => !/[\\$`\n]/.test(value), {
+      message:
+        'A gloss name is a plain noun phrase; put the symbol in `latex`, not in the name.',
+    }),
+  units: z.string().min(1).optional(),
+});
+
 const notationEntryShape = z.object({
   key: id,
   latex: z.string().min(1),
@@ -82,6 +119,7 @@ const notationEntryShape = z.object({
   sources: z.array(notationSource).default([]),
   alignment: notationAlignmentDefault,
   label: z.string().min(1).optional(),
+  glosses: z.array(notationGloss).default([]),
 });
 
 const localNotationDefinition = notationEntryShape;