npm - explico - Versions diffs - 0.3.0 → 0.5.0 - Mend

explico 0.3.0 → 0.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (151) hide show

package/CHANGELOG.md +344 -1
package/README.md +117 -3
package/dist/compiler/astro.d.ts +38 -0
package/dist/compiler/astro.js +258 -0
package/dist/compiler/cli.d.ts +13 -0
package/dist/compiler/cli.js +32 -12
package/dist/compiler/collections.d.ts +3 -2
package/dist/compiler/collections.js +28 -1
package/dist/compiler/course-config.d.ts +86 -4
package/dist/compiler/course-config.js +39 -0
package/dist/compiler/exports/standalone-html.d.ts +34 -0
package/dist/compiler/exports/standalone-html.js +803 -0
package/dist/compiler/lesson-derivation.d.ts +1 -1
package/dist/compiler/lesson-derivation.js +2 -2
package/dist/compiler/manifest.d.ts +112 -7
package/dist/compiler/manifest.js +205 -40
package/dist/compiler/resolution-report.d.ts +4 -0
package/dist/reference/base-abbreviations.d.mts +30 -0
package/dist/reference/base-abbreviations.mjs +60 -0
package/dist/reference/base-operators.d.mts +15 -0
package/dist/reference/base-operators.mjs +40 -0
package/dist/reference/base-roman-labels.d.mts +35 -0
package/dist/reference/base-roman-labels.mjs +43 -0
package/dist/reference/consistency.d.ts +8 -2
package/dist/reference/consistency.js +50 -3
package/dist/reference/diagrams-validate.d.ts +21 -0
package/dist/reference/diagrams-validate.js +13 -0
package/dist/reference/equations-validate.d.ts +8 -3
package/dist/reference/equations-validate.js +1 -1
package/dist/reference/equations.d.mts +66 -35
package/dist/reference/equations.mjs +142 -40
package/dist/reference/gate-abbreviations.d.ts +17 -0
package/dist/reference/gate-abbreviations.js +64 -0
package/dist/reference/gate-math.d.ts +28 -5
package/dist/reference/gate-math.js +5 -2
package/dist/reference/gate-prose-notation.d.ts +60 -0
package/dist/reference/gate-prose-notation.js +125 -0
package/dist/reference/keyed-float-validate.d.ts +14 -8
package/dist/reference/keyed-float-validate.js +1 -1
package/dist/reference/keyed-jsx-floats.d.mts +24 -21
package/dist/reference/keyed-jsx-floats.mjs +90 -41
package/dist/reference/knowledge-checks-validate.d.ts +35 -0
package/dist/reference/knowledge-checks-validate.js +78 -0
package/dist/reference/knowledge-checks.d.mts +25 -0
package/dist/reference/knowledge-checks.mjs +45 -0
package/dist/reference/lab-math-scope.d.ts +9 -1
package/dist/reference/lab-math-scope.js +32 -4
package/dist/reference/math-glyphs.d.mts +30 -0
package/dist/reference/math-glyphs.mjs +367 -0
package/dist/reference/mdx-attributes.d.mts +13 -0
package/dist/reference/mdx-attributes.mjs +38 -0
package/dist/reference/mixed-content.d.ts +17 -0
package/dist/reference/mixed-content.js +29 -0
package/dist/reference/page-notation.d.ts +52 -0
package/dist/reference/page-notation.js +171 -0
package/dist/reference/raw-floats-validate.d.ts +18 -0
package/dist/reference/raw-floats-validate.js +53 -0
package/dist/reference/raw-floats.d.mts +18 -0
package/dist/reference/raw-floats.mjs +129 -0
package/dist/reference/rehype-heading-anchors.d.mts +1 -1
package/dist/reference/rehype-heading-anchors.mjs +107 -1
package/dist/reference/rehype-table-header-labels.d.mts +26 -0
package/dist/reference/rehype-table-header-labels.mjs +152 -0
package/dist/reference/remark-abbreviations.d.mts +7 -0
package/dist/reference/remark-abbreviations.mjs +174 -0
package/dist/reference/remark-memo.d.mts +16 -0
package/dist/reference/remark-memo.mjs +339 -0
package/dist/reference/remark-notation.d.mts +102 -5
package/dist/reference/remark-notation.mjs +506 -50
package/dist/reference/remark-short-note.d.mts +4 -0
package/dist/reference/remark-short-note.mjs +237 -0
package/dist/reference/types.d.ts +16 -1
package/dist/reference/units-vocab.js +4 -0
package/docs/VERSIONING.md +33 -4
package/docs/authoring/README.md +12 -0
package/docs/authoring/agents.md +17 -2
package/docs/authoring/components.md +135 -0
package/docs/authoring/migrating.md +154 -7
package/docs/authoring/notation.md +568 -8
package/docs/authoring/structure.md +251 -0
package/docs/authoring/visualizations.md +36 -3
package/package.json +5 -2
package/src/compiler/astro.ts +332 -0
package/src/compiler/cli.ts +33 -10
package/src/compiler/collections.ts +45 -4
package/src/compiler/course-config.ts +131 -3
package/src/compiler/exports/standalone-html.ts +963 -0
package/src/compiler/lesson-derivation.ts +2 -2
package/src/compiler/manifest.ts +367 -49
package/src/components/HoverPanel.astro +45 -4
package/src/components/abbreviation/AbbreviationGlossary.astro +70 -0
package/src/components/abbreviation/AbbreviationLayer.astro +127 -0
package/src/components/assessments/AssessmentRunner.tsx +52 -17
package/src/components/assessments/AssessmentSet.astro +98 -14
package/src/components/assessments/RenderedContent.tsx +55 -0
package/src/components/assessments/assessment-randomization.ts +16 -0
package/src/components/diagram/Diagram.astro +444 -83
package/src/components/disclosure/hover-preview.ts +202 -0
package/src/components/disclosure/persisted-disclosure.ts +66 -0
package/src/components/examples/CompactExamples.astro +2 -0
package/src/components/figure/Figure.astro +279 -10
package/src/components/memo/Memo.astro +453 -0
package/src/components/memo/ShortNote.astro +223 -0
package/src/components/notation/NotationFormula.astro +18 -1
package/src/components/notation/NotationLayer.astro +116 -8
package/src/components/notation/render-notation-math.ts +39 -2
package/src/components/notation/safe-math-to-react.ts +50 -0
package/src/components/reference/FloatRefLayer.astro +233 -15
package/src/components/starlight/CollapsibleSections.astro +461 -0
package/src/components/starlight/DiagramEnhancer.astro +385 -0
package/src/components/starlight/HeadingAnchorEnhancer.astro +5 -17
package/src/components/starlight/KeyedFloatEnhancer.astro +81 -3
package/src/components/starlight/LayoutHeader.astro +50 -0
package/src/components/starlight/LayoutSidebar.astro +62 -1
package/src/components/starlight/LayoutSocialIcons.astro +41 -2
package/src/components/starlight/LessonExportActions.astro +436 -0
package/src/components/starlight/LessonFooter.astro +38 -2
package/src/components/starlight/section-parts.ts +31 -0
package/src/components/table/Table.astro +296 -9
package/src/components/table/TableOverflowExpander.astro +489 -0
package/src/content-config.ts +20 -0
package/src/reference/base-abbreviations.mjs +60 -0
package/src/reference/base-operators.mjs +40 -0
package/src/reference/base-roman-labels.mjs +43 -0
package/src/reference/consistency.ts +73 -2
package/src/reference/diagrams-validate.ts +40 -0
package/src/reference/equations-validate.ts +6 -4
package/src/reference/equations.mjs +142 -40
package/src/reference/gate-abbreviations.ts +128 -0
package/src/reference/gate-math.ts +27 -7
package/src/reference/gate-prose-notation.ts +224 -0
package/src/reference/keyed-float-validate.ts +12 -9
package/src/reference/keyed-jsx-floats.mjs +90 -41
package/src/reference/knowledge-checks-validate.ts +130 -0
package/src/reference/knowledge-checks.mjs +45 -0
package/src/reference/lab-math-scope.ts +45 -3
package/src/reference/math-glyphs.mjs +367 -0
package/src/reference/mdx-attributes.mjs +38 -0
package/src/reference/mixed-content.ts +69 -0
package/src/reference/page-notation.ts +252 -0
package/src/reference/raw-floats-validate.ts +103 -0
package/src/reference/raw-floats.mjs +129 -0
package/src/reference/rehype-heading-anchors.mjs +107 -1
package/src/reference/rehype-table-header-labels.mjs +152 -0
package/src/reference/remark-abbreviations.mjs +174 -0
package/src/reference/remark-memo.mjs +339 -0
package/src/reference/remark-notation.mjs +506 -50
package/src/reference/remark-short-note.mjs +237 -0
package/src/reference/types.ts +16 -0
package/src/reference/units-vocab.ts +4 -0
package/src/styles/global.css +1125 -50

package/src/components/starlight/DiagramEnhancer.astro ADDED Viewed

@@ -0,0 +1,385 @@
+---
+/**
+ * Progressive behavior for `<Diagram>`:
+ *
+ * - a persistent, animated title disclosure;
+ * - a compact horizontal expand control shown only when the canvas overflows;
+ * - an in-page expanded surface that moves the real figure (never a clone) to
+ *   `<body>`, overlays its placeholder, and follows that placeholder while the
+ *   page scrolls — the same spatial model as `TableOverflowExpander.astro`.
+ *
+ * Expansion is deliberately non-modal: there is no backdrop, page scrolling
+ * remains available, and the diagram closes only through its own shrink button
+ * or Escape. Tall expanded content scrolls vertically inside its viewport-
+ * capped surface.
+ */
+---
+<script>
+  import {
+    savePersistedOpenState,
+    wirePersistedDetails,
+  } from '../disclosure/persisted-disclosure';
+  import { claimActiveSurface, releaseActiveSurface } from '../hover-panel';
+  const GROUP = 'diagram-overflow';
+  const EDGE_PX = 16;
+  const ANIMATION_MS = 220;
+  interface Expansion {
+    readonly figure: HTMLElement;
+    readonly placeholder: HTMLElement;
+    readonly spoofWrapper: HTMLElement;
+    readonly button: HTMLButtonElement;
+    readonly scroll: HTMLElement;
+    readonly reposition: () => void;
+    readonly evaluate: () => void;
+  }
+  let active: Expansion | null = null;
+  function sidebarLeftBound(): number {
+    const sidebar = document.querySelector<HTMLElement>('.sidebar-pane');
+    const visible = !!sidebar && getComputedStyle(sidebar).visibility !== 'hidden';
+    return visible ? sidebar!.getBoundingClientRect().right + EDGE_PX : EDGE_PX;
+  }
+  function tocLeftBound(): number | null {
+    const toc = document.querySelector<HTMLElement>('.right-sidebar');
+    if (!toc) return null;
+    if (document.documentElement.hasAttribute('data-page-sidebar-hidden')) {
+      return null;
+    }
+    if (!window.matchMedia('(min-width: 72rem)').matches) return null;
+    return toc.getBoundingClientRect().left;
+  }
+  function captionFor(figure: HTMLElement): string {
+    return (
+      figure.querySelector<HTMLElement>('.diagram__summary')?.textContent?.trim() ??
+      'this diagram'
+    );
+  }
+  function updateExpandButton(
+    figure: HTMLElement,
+    button: HTMLButtonElement,
+    expanded: boolean,
+  ): void {
+    button.setAttribute('aria-expanded', String(expanded));
+    button.setAttribute(
+      'aria-label',
+      expanded
+        ? `Shrink ${captionFor(figure)}`
+        : `Expand ${captionFor(figure)} horizontally`,
+    );
+    button.title = expanded ? 'Shrink diagram' : 'Expand diagram horizontally';
+    const srText = button.querySelector<HTMLElement>('.sr-only');
+    if (srText) srText.textContent = expanded ? 'Shrink diagram' : 'Expand diagram';
+  }
+  function updateScrollFocusability(scroll: HTMLElement, figure: HTMLElement): void {
+    if (scroll.scrollWidth > scroll.clientWidth + 1) {
+      scroll.tabIndex = 0;
+      scroll.setAttribute('aria-label', `Scrollable ${captionFor(figure)}`);
+    } else {
+      scroll.removeAttribute('tabindex');
+      scroll.removeAttribute('aria-label');
+    }
+  }
+  function evaluateOverflow(
+    figure: HTMLElement,
+    details: HTMLDetailsElement,
+    toolbar: HTMLElement,
+    button: HTMLButtonElement,
+    scroll: HTMLElement,
+  ): void {
+    if (active?.figure === figure) return;
+    const overflows = details.open && scroll.scrollWidth > scroll.clientWidth + 1;
+    figure.dataset.diagramOverflow = String(overflows);
+    toolbar.hidden = !overflows;
+    button.hidden = !overflows;
+    updateScrollFocusability(scroll, figure);
+  }
+  function collapseExpansion({ restoreFocus = true } = {}): void {
+    if (!active) return;
+    const state = active;
+    active = null;
+    window.removeEventListener('scroll', state.reposition, true);
+    window.removeEventListener('resize', state.reposition);
+    state.figure.classList.remove('diagram-is-expanded');
+    state.figure.style.cssText = '';
+    state.placeholder.replaceWith(state.figure);
+    state.spoofWrapper.remove();
+    updateExpandButton(state.figure, state.button, false);
+    state.evaluate();
+    if (restoreFocus) state.button.focus({ preventScroll: true });
+  }
+  function expand(
+    figure: HTMLElement,
+    button: HTMLButtonElement,
+    scroll: HTMLElement,
+    evaluate: () => void,
+  ): void {
+    // An expanded diagram is dismissed only by its own shrink control or
+    // Escape. Ignore another diagram's expand control until the current one is
+    // restored.
+    if (active && active.figure !== figure) return;
+    claimActiveSurface(GROUP, () => {});
+    releaseActiveSurface(GROUP);
+    const neededWidth = scroll.scrollWidth;
+    const rect = figure.getBoundingClientRect();
+    const placeholder = document.createElement('div');
+    placeholder.className = 'diagram-expand-placeholder';
+    placeholder.style.height = `${rect.height}px`;
+    figure.replaceWith(placeholder);
+    // Retain every `.sl-markdown-content …` descendant rule after moving the
+    // original figure to `<body>`, without creating a layout box of its own.
+    const spoofWrapper = document.createElement('div');
+    spoofWrapper.className = 'sl-markdown-content';
+    spoofWrapper.style.display = 'contents';
+    document.body.append(spoofWrapper);
+    spoofWrapper.append(figure);
+    figure.classList.add('diagram-is-expanded');
+    const reposition = () => {
+      const headerBottom =
+        document.querySelector<HTMLElement>('.header')?.getBoundingClientRect()
+          .bottom ?? 0;
+      const verticalStart = Math.max(EDGE_PX, headerBottom + EDGE_PX);
+      const placeholderRect = placeholder.getBoundingClientRect();
+      const sidebarEdge = sidebarLeftBound();
+      const viewportEdge = window.innerWidth - EDGE_PX;
+      const tocBoundary = tocLeftBound();
+      const rightBound = Math.min(
+        viewportEdge,
+        Math.max(
+          tocBoundary !== null ? tocBoundary - EDGE_PX : viewportEdge,
+          sidebarEdge + neededWidth,
+        ),
+      );
+      const availableWidth = Math.max(rightBound - sidebarEdge, 80);
+      const width = Math.min(neededWidth, availableWidth);
+      const left = sidebarEdge + (availableWidth - width) / 2;
+      // Exact placeholder tracking makes this an overlay at the diagram's
+      // document position, not a sticky/modal surface. It naturally moves
+      // above or below the viewport as the reader scrolls past it.
+      const top = placeholderRect.top;
+      figure.style.position = 'fixed';
+      figure.style.top = `${top}px`;
+      figure.style.left = `${left}px`;
+      figure.style.width = `${width}px`;
+      const visibleTop = Math.max(verticalStart, top);
+      const maxHeight = Math.max(
+        window.innerHeight - visibleTop - EDGE_PX,
+        80,
+      );
+      figure.style.maxHeight = `${maxHeight}px`;
+      const titleHeight =
+        figure
+          .querySelector<HTMLElement>('.diagram__summary')
+          ?.getBoundingClientRect().height ?? 0;
+      figure.style.setProperty(
+        '--diagram-expanded-body-height',
+        `${Math.max(maxHeight - titleHeight, 40)}px`,
+      );
+      updateScrollFocusability(scroll, figure);
+    };
+    active = {
+      figure,
+      placeholder,
+      spoofWrapper,
+      button,
+      scroll,
+      reposition,
+      evaluate,
+    };
+    updateExpandButton(figure, button, true);
+    reposition();
+    window.addEventListener('scroll', reposition, {
+      passive: true,
+      capture: true,
+    });
+    window.addEventListener('resize', reposition, { passive: true });
+  }
+  function wireDisclosure(
+    figure: HTMLElement,
+    details: HTMLDetailsElement,
+    body: HTMLElement,
+    evaluate: () => void,
+  ): void {
+    const summary = details.querySelector<HTMLElement>(':scope > summary');
+    if (!summary) return;
+    const defaultOpen = details.open;
+    const remember = details.dataset.rememberState === 'true';
+    if (remember) {
+      wirePersistedDetails(details, `diagram:${figure.id}`, defaultOpen);
+    }
+    details.dataset.state = details.open ? 'open' : 'closed';
+    // An external/bookmarked deep link reveals the complete diagram. Later
+    // in-page jumps retain the reader's persisted minimized state.
+    if (location.hash === `#${figure.id}`) {
+      details.open = true;
+      details.dataset.state = 'open';
+    }
+    const reduceMotion = window.matchMedia('(prefers-reduced-motion: reduce)');
+    let finishTimer: number | null = null;
+    let transitionEnd: ((event: TransitionEvent) => void) | null = null;
+    const cancelAnimation = () => {
+      if (finishTimer !== null) window.clearTimeout(finishTimer);
+      finishTimer = null;
+      if (transitionEnd) body.removeEventListener('transitionend', transitionEnd);
+      transitionEnd = null;
+      body.style.removeProperty('transition');
+      body.style.removeProperty('overflow');
+    };
+    const setOpen = (open: boolean) => {
+      cancelAnimation();
+      const current = body.getBoundingClientRect().height;
+      if (open) details.open = true;
+      details.dataset.state = open ? 'open' : 'closed';
+      if (remember) savePersistedOpenState(`diagram:${figure.id}`, open);
+      if (reduceMotion.matches) {
+        details.open = open;
+        body.style.maxHeight = open ? '' : '0px';
+        if (active?.figure === figure) {
+          active.placeholder.style.height = `${figure.getBoundingClientRect().height}px`;
+        }
+        evaluate();
+        active?.reposition();
+        return;
+      }
+      body.style.transition = 'none';
+      body.style.maxHeight = `${current}px`;
+      body.style.overflow = 'hidden';
+      void body.offsetHeight;
+      body.style.removeProperty('transition');
+      const expandedLimit = Number.parseFloat(
+        getComputedStyle(figure).getPropertyValue(
+          '--diagram-expanded-body-height',
+        ),
+      );
+      const target = open
+        ? Math.min(
+            body.scrollHeight,
+            Number.isFinite(expandedLimit) ? expandedLimit : Number.POSITIVE_INFINITY,
+          )
+        : 0;
+      const finish = () => {
+        cancelAnimation();
+        details.open = open;
+        body.style.maxHeight = open ? '' : '0px';
+        if (active?.figure === figure) {
+          active.placeholder.style.height = `${figure.getBoundingClientRect().height}px`;
+        }
+        evaluate();
+        active?.reposition();
+      };
+      transitionEnd = (event) => {
+        if (event.target === body && event.propertyName === 'max-height') finish();
+      };
+      body.addEventListener('transitionend', transitionEnd);
+      finishTimer = window.setTimeout(finish, ANIMATION_MS + 60);
+      requestAnimationFrame(() => {
+        body.style.maxHeight = `${target}px`;
+      });
+    };
+    summary.addEventListener('click', (event) => {
+      event.preventDefault();
+      setOpen(details.dataset.state !== 'open');
+    });
+  }
+  function setup(): void {
+    for (const figure of document.querySelectorAll<HTMLElement>(
+      '.diagram[data-diagram-expandable]',
+    )) {
+      if (figure.dataset.diagramExpandReady === 'true') continue;
+      const details = figure.querySelector<HTMLDetailsElement>(
+        '[data-diagram-details]',
+      );
+      const body = figure.querySelector<HTMLElement>('[data-diagram-body]');
+      const toolbar = figure.querySelector<HTMLElement>('[data-diagram-toolbar]');
+      const button = figure.querySelector<HTMLButtonElement>('[data-diagram-expand]');
+      const scroll = figure.querySelector<HTMLElement>('.diagram-scroll');
+      if (!details || !body || !toolbar || !button || !scroll) continue;
+      figure.dataset.diagramExpandReady = 'true';
+      const evaluate = () =>
+        evaluateOverflow(figure, details, toolbar, button, scroll);
+      button.addEventListener('click', () => {
+        if (active?.figure === figure) collapseExpansion();
+        else expand(figure, button, scroll, evaluate);
+      });
+      new ResizeObserver(evaluate).observe(scroll);
+      details.addEventListener('toggle', evaluate);
+      wireDisclosure(figure, details, body, evaluate);
+      updateExpandButton(figure, button, false);
+      evaluate();
+    }
+  }
+  setup();
+  window.addEventListener('explico:prepare-static-export', () => {
+    collapseExpansion({ restoreFocus: false });
+  });
+  document.addEventListener('astro:page-load', setup);
+  document.addEventListener('keydown', (event) => {
+    if (event.key === 'Escape' && active) collapseExpansion();
+  });
+</script>
+<style is:global>
+  .diagram-is-expanded {
+    /* Above the side rails, but below Starlight's sticky site header. */
+    z-index: calc(var(--sl-z-index-navbar) - 1);
+    margin: 0 !important;
+    max-width: none !important;
+    contain: none !important;
+    overflow-y: hidden;
+    background: var(--sl-color-bg);
+    box-shadow: var(--sl-shadow-lg);
+  }
+  .diagram-is-expanded .diagram__titlebar,
+  .diagram-is-expanded .diagram__details {
+    max-height: inherit;
+  }
+  .diagram-is-expanded .diagram__details {
+    display: flex;
+    flex-direction: column;
+  }
+  .diagram-is-expanded .diagram__body {
+    min-height: 0;
+    max-height: var(--diagram-expanded-body-height);
+    flex: 1 1 auto;
+    overflow-x: hidden;
+    overflow-y: auto;
+  }
+  @media print {
+    .diagram-expand-placeholder {
+      display: none;
+    }
+  }
+</style>

package/src/components/starlight/HeadingAnchorEnhancer.astro CHANGED Viewed

@@ -19,6 +19,9 @@
  *    won't navigate to a fragment that's already current;
  *  - moving keyboard focus onto the heading so screen-reader users land on it.
  *
+ * `sectionParts()` (the section-boundary walk) lives in `./section-parts.ts`,
+ * shared with `CollapsibleSections.astro`.
+ *
  * 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
@@ -33,11 +36,12 @@
 ---
 <script>
+  import { HEADINGS, sectionParts } from './section-parts';
   (() => {
     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 =>
@@ -70,22 +74,6 @@
       );
     };
-    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);

package/src/components/starlight/KeyedFloatEnhancer.astro CHANGED Viewed

@@ -1,13 +1,14 @@
 ---
 /**
  * Progressive enhancement for keyed floats — equations (Step D7), extended
- * to `<Table>`/`<Figure>` (F-tables-figures). Generalizes the original
+ * to `<Table>`/`<Figure>`/`<Diagram>`. Generalizes the original
  * equation-only `EquationEnhancer`: the scroll/focus/flash mechanics are
  * unchanged, parameterized over `KINDS` below so a deep-link to `#eq-`,
- * `#tab-`, or `#fig-` is handled the same way.
+ * `#tab-`, `#fig-`, or `#dia-` is handled the same way.
  *
  * The no-JS baseline is complete: `remark-notation` emits a real
- * `id="eq-<key>"` / `id="tab-<key>"` / `id="fig-<key>"` container, a
+ * `id="eq-<key>"` / `id="tab-<key>"` / `id="fig-<key>"` /
+ * `id="dia-<key>"` container, a
  * focusable number `<a>`, and a `[[…]]` reference renders a plain anchor;
  * `global.css` does the `:target` deep-link highlight (with a
  * `prefers-reduced-motion` fallback) and the sticky-header scroll offset via
@@ -69,6 +70,12 @@
         numberSelector: '.keyed-figure__number',
         reveal: false,
       },
+      {
+        prefix: '#dia-',
+        triggerSelector: 'a.diagram-ref, a.diagram__title-anchor',
+        numberSelector: '.diagram__number',
+        reveal: false,
+      },
     ];
     const TRIGGER_SELECTOR = KINDS.map((kind) => kind.triggerSelector).join(', ');
     const kindForHash = (hash: string) =>
@@ -123,6 +130,77 @@
       }
     });
+    // "Copy LaTeX" for an equation, two ways: its own button (only a numbered
+    // display equation has one — `data-eq-copy`, `remark-notation.mjs`'s
+    // `equationNode`), or a click anywhere else in the equation that isn't a
+    // symbol with its own notation card (an operator, a bare number, a
+    // parenthesis, …) — the same gesture works on an inline equation too
+    // (`inlineEquationNode`), which has no room for a persistent button of
+    // its own without breaking the reading line. A notation-registry symbol
+    // keeps its existing click-to-pin behavior either way
+    // (`NotationLayer.astro`), so this skips anything under `[data-notation-key]`.
+    root.addEventListener('click', (event) => {
+      const origin = event.target instanceof Element ? event.target : null;
+      if (!origin) return;
+      if (origin.closest('a.keyed-equation__number, [data-notation-key]')) {
+        return;
+      }
+      const ownButton = origin.closest<HTMLButtonElement>('[data-eq-copy]');
+      const container = ownButton
+        ? null
+        : origin.closest<HTMLElement>('.keyed-equation, .inline-equation');
+      if (!ownButton && (!container || !origin.closest('.katex-html'))) {
+        return;
+      }
+      const feedbackTarget =
+        ownButton ??
+        container?.querySelector<HTMLElement>('.keyed-equation__copy') ??
+        container;
+      const latex =
+        ownButton?.dataset.latex ?? feedbackTarget?.dataset.latex ?? '';
+      if (!feedbackTarget || latex.length === 0 || !navigator.clipboard) {
+        return;
+      }
+      navigator.clipboard.writeText(latex).then(
+        () => {
+          feedbackTarget.dataset.copied = 'true';
+          window.setTimeout(() => {
+            delete feedbackTarget.dataset.copied;
+          }, 1200);
+        },
+        () => {
+          /* Clipboard blocked: nothing more we can do here. */
+        },
+      );
+    });
+    // A tooltip for the gesture above, and only for the part of the equation
+    // it actually applies to — an explained symbol has its own hover card
+    // (`NotationLayer.astro`) and needs no tooltip layered on top of it.
+    // `mouseover`/`mouseout` (not `mouseenter`/`mouseleave`) because they
+    // bubble, which delegation on `root` needs.
+    root.addEventListener('mouseover', (event) => {
+      const origin = event.target instanceof Element ? event.target : null;
+      if (!origin || origin.getAttribute('title') === 'Copy LaTeX') return;
+      if (origin.closest('[data-notation-key], [data-eq-copy]')) return;
+      if (
+        !origin.closest('.keyed-equation .katex-html, .inline-equation .katex-html')
+      ) {
+        return;
+      }
+      origin.setAttribute('title', 'Copy LaTeX');
+    });
+    root.addEventListener('mouseout', (event) => {
+      const origin = event.target instanceof Element ? event.target : null;
+      if (origin?.getAttribute('title') === 'Copy LaTeX') {
+        origin.removeAttribute('title');
+      }
+    });
     window.addEventListener('hashchange', () => {
       const kind = kindForHash(location.hash);
       if (!kind) return;

package/src/components/starlight/LayoutHeader.astro CHANGED Viewed

@@ -40,6 +40,39 @@ import DefaultHeader from '@astrojs/starlight/components/Header.astro';
   const root = document.documentElement;
+  /**
+   * `.main-pane`'s width formula (`global.css`) caps itself against
+   * `var(--toc-actual-width, ...)` so it never grows into the "On this
+   * page" rail — `.right-sidebar` is edge-anchored (`inset-inline-end: 0`)
+   * rather than positioned relative to `.main-pane`, so nothing else
+   * guarantees that any more. A worst-case CSS estimate alone would have
+   * to assume the rail's own 80ch cap at all times, which is far wider
+   * than any actual page's headings need and would cap `.main-pane`
+   * well short of where it could safely go. Measuring the rail's real
+   * rendered width here and writing it to `--toc-actual-width` lets the
+   * cap match reality instead — on a typical page of short headings this
+   * ends up nowhere near binding, so `.main-pane` keeps the same width
+   * Starlight's own formula already gave it.
+   *
+   * This doesn't close a loop back on itself: `.right-sidebar`'s own width
+   * is edge-anchored and shrink-to-fit against its own content, not
+   * against how much room `.main-pane` leaves it (that dependency is
+   * exactly what the edge anchor removed), so measuring it here doesn't
+   * need to react to anything this function itself changes.
+   */
+  function updateTocReservation(): void {
+    const panel = document.querySelector<HTMLElement>('.right-sidebar');
+    if (!panel) return;
+    // Only meaningful for the open, two-column desktop layout — collapsed
+    // (`data-page-sidebar-hidden`) uses its own edge-rail width formula
+    // that never reads this variable, and below the breakpoint there's no
+    // `.right-sidebar` column to cap `.main-pane` against at all.
+    if (root.hasAttribute('data-page-sidebar-hidden')) return;
+    if (!window.matchMedia('(min-width: 72rem)').matches) return;
+    const width = panel.getBoundingClientRect().width;
+    if (width > 0) root.style.setProperty('--toc-actual-width', `${width}px`);
+  }
   // The one seam for per-viewer UI preferences (Phase H1). This component never
   // touches browser storage directly; a future SSR host swaps in a different
   // PreferenceStore and nothing here changes.
@@ -80,6 +113,10 @@ import DefaultHeader from '@astrojs/starlight/components/Header.astro';
         const hidden = !root.hasAttribute(settings.attribute);
         applyState(button, region, hidden);
         writePreference(settings.storageKey, hidden);
+        // The initial measurement below skips a rail that starts collapsed
+        // (there's nothing on screen yet to measure); catch it here the
+        // first time it actually opens.
+        if (region === 'contents' && !hidden) updateTocReservation();
         // A pointer click should leave a newly collapsed rail collapsed even
         // though the pointer was inside the full-width panel when clicked.
@@ -99,4 +136,17 @@ import DefaultHeader from '@astrojs/starlight/components/Header.astro';
         }
       });
     });
+  updateTocReservation();
+  let tocReservationResizeTimer: number | null = null;
+  window.addEventListener(
+    'resize',
+    () => {
+      if (tocReservationResizeTimer !== null) {
+        window.clearTimeout(tocReservationResizeTimer);
+      }
+      tocReservationResizeTimer = window.setTimeout(updateTocReservation, 150);
+    },
+    { passive: true },
+  );
 </script>

package/src/components/starlight/LayoutSidebar.astro CHANGED Viewed

@@ -23,7 +23,68 @@ import DefaultSidebar from '@astrojs/starlight/components/Sidebar.astro';
       size="1rem"
     />
   </button>
-  <div id="starlight__navigation-content" class="layout-navigation-content">
+  <div
+    id="starlight__navigation-content"
+    class="layout-navigation-content layout-compact-sidebar"
+  >
     <DefaultSidebar />
+    <script>
+      import { createBrowserPreferenceStore } from '../../session/PreferenceStore';
+      (() => {
+        if (!matchMedia('(min-width: 50rem)').matches) return;
+        const root = document.querySelector('#starlight__navigation-content');
+        const stateRoot = root?.querySelector('sl-sidebar-state-persist');
+        if (!stateRoot) return;
+        const groups = [
+          ...stateRoot.querySelectorAll(':scope > ul > li > details'),
+        ];
+        const storageKey = 'explico-sidebar-groups';
+        const preferences = createBrowserPreferenceStore();
+        let compact = groups.map(() => true);
+        try {
+          const saved = JSON.parse(preferences.get(storageKey) || 'null');
+          if (
+            saved?.hash === stateRoot.dataset.hash &&
+            Array.isArray(saved.compact)
+          ) {
+            compact = groups.map((_, index) => saved.compact[index] !== false);
+          }
+        } catch {}
+        const save = () => {
+          try {
+            preferences.set(
+              storageKey,
+              JSON.stringify({
+                hash: stateRoot.dataset.hash,
+                compact: groups.map((group) => group.hasAttribute('data-compact')),
+              }),
+            );
+          } catch {}
+        };
+        groups.forEach((group, index) => {
+          // The links remain rendered and operable in compact mode; only their
+          // labels collapse. Keep <details> open so this stays true for assistive
+          // technology as well as pointer users.
+          group.setAttribute('open', '');
+          group.toggleAttribute('data-compact', compact[index]);
+          const summary = group.querySelector(':scope > summary');
+          summary?.setAttribute('aria-expanded', String(!compact[index]));
+          summary?.addEventListener('click', (event) => {
+            event.preventDefault();
+            group.toggleAttribute('data-compact');
+            group.setAttribute('open', '');
+            summary.setAttribute(
+              'aria-expanded',
+              String(!group.hasAttribute('data-compact')),
+            );
+            save();
+          });
+        });
+      })();
+    </script>
   </div>
 </div>