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/table/TableOverflowExpander.astro ADDED Viewed

@@ -0,0 +1,489 @@
+---
+/**
+ * Table column narrowing + expand-on-overflow
+ * (docs/plans/collapsible-disclosure.md Part 4) — a runtime enhancer, wired
+ * from `LessonFooter.astro` alongside the other lesson-page enhancers, the
+ * same progressive-enhancement approach `CollapsibleSections.astro` and
+ * `HeadingAnchorEnhancer.astro` already use.
+ *
+ * **Structure**: each candidate container (`.keyed-table__body` from
+ * `Table.astro`, or `.table-overflow-body` — created at runtime around a
+ * bare markdown table that has none) is turned into a flex row. Normally
+ * that row is `[.table-overflow-scroll, .table-overflow-expand-btn]` — the
+ * button, present only once the table actually overflows
+ * (`evaluateOverflow` toggles `hidden`), is a plain flex sibling rather than
+ * an overlay, so `align-items: stretch` (the flex default) makes it exactly
+ * as tall as the table for free, and it can never sit on top of table
+ * content. While expanded, a second button is prepended — the row becomes
+ * `[collapse, .table-overflow-scroll, collapse]`, the "0th and n+1th
+ * column" — so *both* collapse affordances are real layout columns the
+ * table's own content is pushed clear of, never floating overlays that
+ * could cover a cell. `.table-overflow-expand-btn:first-child`/`:last-child`
+ * in `global.css` flip which side gets the divider border; the two buttons
+ * otherwise share one class. Row striping/hover-highlight
+ * (`tbody tr:nth-child(even)`/`:hover`) is a separate, unconditional rule in
+ * `global.css` — plain CSS, so it applies with or without this script.
+ *
+ * **Why a dedicated `.table-overflow-scroll` wrapper**: Starlight's own
+ * `markdown.css` gives *every* `<table>` under `.sl-markdown-content` its
+ * own `display: block; overflow: auto` — its own independent scroll
+ * container. Left in place inside `.table-overflow-scroll`, that inner rule
+ * would win first and clip/scroll the table before this wrapper ever saw
+ * overflow, leaving `scrollWidth > clientWidth` on it permanently false.
+ * `global.css` undoes that per-table rule specifically *inside*
+ * `.table-overflow-scroll`, so there is exactly one real scroll surface —
+ * the one this component measures and, on click, enlarges. A table with no
+ * JS at all never gets this wrapper and keeps Starlight's default per-table
+ * scroll as its fallback, unmodified. Column *sizing* was never the bug —
+ * `table-layout` is `auto` either way, so columns already size to content —
+ * the bug was only about which element ends up owning the scrollbar.
+ *
+ * A bare markdown table gets the same `.table-overflow-scroll` treatment
+ * inside a runtime-created `.table-overflow-body`, skipping anything
+ * already inside a `<Table>` or a lab island's own `.lab-data-table`
+ * (`ProjectileRangeExplorer.tsx` and friends already give that a dedicated,
+ * deliberately-always-scrolling container; wrapping it again would nest two
+ * independent scroll containers around the same rows).
+ *
+ * **Expand**: on click, the actual node that moves to `<body>` and becomes
+ * `position: fixed` is `target` — the whole `<figure class="keyed-table">`
+ * when there is one (so its `<figcaption>` travels with the expanded view
+ * instead of being left behind, orphaned, in the narrow column), or the
+ * flex-row container itself for a bare table with no figure. `target`'s
+ * left edge lands at the live `.sidebar-pane` edge — not the
+ * `--sl-sidebar-width`/`--__toc-width` CSS vars, which don't reflect the
+ * sidebar's real, responsive visibility, per `FloatRefLayer.astro`'s
+ * `horizontalRegion()`. Its width is only as wide as the table and its two
+ * button columns actually need (`.table-overflow-scroll`'s `scrollWidth`,
+ * measured before anything moves — that reports the full unclipped content
+ * width regardless of how narrow the wrapper currently renders it, plus
+ * both `SIDE_COLUMN_PX` button widths). Unlike `FloatRefLayer.astro`'s own
+ * card, which deliberately ignores the "On this page" rail's column
+ * entirely, this prefers *not* claiming that space (`tocLeftBound()`):
+ * offered the choice, it centers itself between the left nav and the
+ * rail's left edge, and only spills past that edge — as far as the
+ * viewport edge, if it must — once the table genuinely doesn't fit without
+ * doing so. That handoff is a continuous function of window width, not a
+ * branch between two different layouts: see the comment on `rightBound` in
+ * `reposition()` for why nothing jumps at the point where the table starts
+ * spilling past the rail. A zero-height placeholder left behind at
+ * the original DOM position keeps
+ * the page from reflowing, and is swapped back in on collapse
+ * (`placeholder.replaceWith(target)`), restoring the exact original spot.
+ * Moving the real node rather than `position: fixed`-ing it in place is
+ * required, not stylistic: `.main-pane` sets `isolation: isolate`
+ * (`TwoColumnContent.astro`), which traps any z-index attempt to paint over
+ * the "On this page" rail — `FloatRefLayer.astro` hit the identical trap
+ * and documents the same escape.
+ *
+ * Moving `target` out to `<body>` also moves it out of `.sl-markdown-content`
+ * — which is where every bit of Starlight's own table styling (row-line
+ * borders, header color) and this file's own zebra-stripe/hover rule live,
+ * since they're all written as `.sl-markdown-content …` descendant
+ * selectors. Rather than duplicate that styling, `target` is wrapped in a
+ * throwaway `<div class="sl-markdown-content">` (itself `display: contents`,
+ * so it never generates a box of its own or affects layout) before being
+ * appended to `<body>` — a genuine ancestor for CSS purposes, torn down
+ * again on collapse.
+ *
+ * The expanded table tracks the *placeholder's* live position on
+ * scroll/resize (where the table would be, were it still in flow) exactly,
+ * unclamped — it scrolls with the page the same as the in-flow element it
+ * stands in for, sliding up past the header and out the top of the
+ * viewport rather than sticking there. Only once that position has
+ * scrolled entirely out of the visible band does the expanded table hide
+ * (`visibility: hidden`) outright — there is no reason to keep any part of
+ * it rendered once the reader has scrolled past it.
+ *
+ * Only one table is ever expanded at a time, and expanding one closes
+ * whichever other overlay — a hover-preview card, a notation popup — was
+ * open, via the same `claimActiveSurface`/`releaseActiveSurface` arbiter
+ * `FloatRefLayer.astro` and the citation/notation layers already share. That
+ * claim is released again immediately rather than held, though: unlike
+ * those layers, the table doesn't stay registered as the arbiter's active
+ * surface while expanded, so a hover card opening *afterward* — over an
+ * explainable quantity inside the table itself, say — can't turn around and
+ * force the table closed the way claiming the arbiter normally would. The
+ * table closes only through its own explicit gestures — the collapse
+ * buttons or Escape — and deliberately *not* an outside click: a reader
+ * following a link in the "On this page" rail, or clicking anywhere else to
+ * keep reading, should find the table exactly as they left it, not
+ * collapsed back to its normal size out from under them.
+ *
+ * No persisted state here (unlike Parts 1/3): expand/collapse is transient
+ * per-view UI, not a reader preference worth remembering across visits.
+ */
+---
+<script>
+  import { claimActiveSurface, releaseActiveSurface } from "../hover-panel";
+  const GROUP = "table-overflow";
+  const EDGE_PX = 16; // ~1em at the default root font size
+  const WIDTH_BUFFER_PX = 2; // rounding slack so the minimal width never re-triggers a scrollbar
+  const SIDE_COLUMN_PX = 24; // must match `.table-overflow-expand-btn`'s `width: 1.5rem`
+  interface Expansion {
+    container: HTMLElement;
+    target: HTMLElement;
+    scroll: HTMLElement;
+    placeholder: HTMLElement;
+    spoofWrapper: HTMLElement;
+    button: HTMLButtonElement;
+    leadingButton: HTMLButtonElement;
+    reposition: () => 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;
+  }
+  // Left edge of the "On this page" rail's own rendered box (not
+  // `.right-sidebar-container`, the flex row's reserved-but-empty column
+  // for it — `.right-sidebar` is `position: fixed`, so its real box can sit
+  // narrower than that reservation, and it's the real box this needs to
+  // stay clear of), but only while it's actually shown — not the desktop
+  // breakpoint's collapsed edge rail (`data-page-sidebar-hidden`, mirroring
+  // the left nav's own collapsed-rail affordance) and not the narrow-
+  // viewport layout, where there's no real right column at all. `null`
+  // means "no rail to avoid" — the table may use the full
+  // sidebar-to-viewport-edge region, same as before.
+  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(container: HTMLElement): string {
+    const figure = container.closest<HTMLElement>(".keyed-table");
+    const text = figure
+      ?.querySelector(".keyed-table__caption-text")
+      ?.textContent?.trim();
+    const number = figure?.dataset.tabNumber;
+    if (number && text) return `Table ${number} — ${text}`;
+    return text || "this table";
+  }
+  function updateButtonLabel(
+    container: HTMLElement,
+    button: HTMLButtonElement,
+    expanded: boolean,
+  ) {
+    button.textContent = expanded ? "⟨" : "⇔";
+    button.setAttribute(
+      "aria-label",
+      expanded
+        ? `Collapse ${captionFor(container)}`
+        : `Expand ${captionFor(container)} to full width`,
+    );
+    button.title = expanded ? "Collapse" : "Expand to full width";
+    button.setAttribute("aria-expanded", String(expanded));
+  }
+  // A scrollable region must itself be reachable by keyboard (WCAG 2.1.1 —
+  // axe's `scrollable-region-focusable`), so arrow keys can scroll it once
+  // focused; a `tabindex` is only added while it is actually scrollable, not
+  // unconditionally.
+  function updateScrollFocusability(
+    scroll: HTMLElement,
+    container: HTMLElement,
+  ) {
+    if (scroll.scrollWidth > scroll.clientWidth + 1) {
+      scroll.tabIndex = 0;
+      scroll.setAttribute(
+        "aria-label",
+        `Scrollable table: ${captionFor(container)}`,
+      );
+    } else {
+      scroll.removeAttribute("tabindex");
+      scroll.removeAttribute("aria-label");
+    }
+  }
+  function evaluateOverflow(
+    scroll: HTMLElement,
+    button: HTMLButtonElement,
+    container: HTMLElement,
+  ) {
+    if (active?.scroll === scroll) return; // never hide the one currently expanded
+    button.hidden = scroll.scrollWidth <= scroll.clientWidth + 1;
+    updateScrollFocusability(scroll, container);
+  }
+  function collapse() {
+    if (!active) return;
+    const {
+      container,
+      target,
+      scroll,
+      placeholder,
+      spoofWrapper,
+      button,
+      leadingButton,
+      reposition,
+    } = active;
+    window.removeEventListener("scroll", reposition, true);
+    window.removeEventListener("resize", reposition);
+    target.classList.remove("table-overflow-expanded");
+    target.style.cssText = "";
+    leadingButton.remove();
+    placeholder.replaceWith(target);
+    spoofWrapper.remove();
+    active = null;
+    updateButtonLabel(container, button, false);
+    evaluateOverflow(scroll, button, container);
+  }
+  function expand(
+    container: HTMLElement,
+    button: HTMLButtonElement,
+    scroll: HTMLElement,
+  ) {
+    if (active) collapse();
+    // Close whatever other overlay (a hover-preview card, a notation popup)
+    // was open, via the same shared arbiter every layer uses — but
+    // immediately release the claim rather than leaving the table
+    // registered as the arbiter's active surface. If it stayed registered,
+    // a hover card opening *afterward* over the table's own content (an
+    // explainable quantity inside it, say) would claim the arbiter in turn
+    // and force this table closed the same way a genuinely different
+    // overlay replacing it would — which is exactly backwards: the card
+    // should simply float above the still-open table (it already
+    // out-ranks it on z-index), and the table should close only through
+    // its own explicit gestures (the collapse buttons, an outside click, or
+    // Escape — all wired below, independent of this arbiter).
+    claimActiveSurface(GROUP, () => {});
+    releaseActiveSurface(GROUP);
+    // Measured *before* anything moves: `scrollWidth` reports the table's
+    // full, unclipped content width regardless of how narrow this wrapper
+    // currently renders it. Expanded, the row gains *two* button columns —
+    // the always-present trailing one plus the prepended leading one — so
+    // both must be budgeted for, not just one; short-changing this by even
+    // one column leaves `.table-overflow-scroll` a hair narrower than its
+    // content, which forces a needless horizontal scrollbar — and that
+    // scrollbar's own thickness then eats into the row's height, which can
+    // in turn push the whole figure past `maxHeight` and trigger a needless
+    // *vertical* scrollbar too.
+    const neededWidth =
+      scroll.scrollWidth + WIDTH_BUFFER_PX + SIDE_COLUMN_PX * 2;
+    // The whole referenceable figure (table + caption) moves together, not
+    // just its scrolling body — otherwise the caption is left behind,
+    // orphaned, in the narrow column while the table pops out beside it.
+    const target = container.closest<HTMLElement>(".keyed-table") ?? container;
+    const rect = target.getBoundingClientRect();
+    const placeholder = document.createElement("div");
+    placeholder.className = "table-overflow-placeholder";
+    placeholder.style.height = `${rect.height}px`;
+    target.replaceWith(placeholder);
+    // A genuine CSS ancestor (not a clone/relabel of `target` itself) so
+    // every `.sl-markdown-content …` rule — Starlight's row/border styling,
+    // this file's own zebra-stripe/hover rule — still applies once `target`
+    // is no longer a real descendant of the page's actual
+    // `.sl-markdown-content`. `display: contents` keeps it from generating
+    // any box of its own or affecting layout.
+    const spoofWrapper = document.createElement("div");
+    spoofWrapper.className = "sl-markdown-content";
+    spoofWrapper.setAttribute("role", "region");
+    spoofWrapper.setAttribute("aria-label", `Expanded ${captionFor(container)}`);
+    spoofWrapper.style.display = "contents";
+    document.body.appendChild(spoofWrapper);
+    spoofWrapper.appendChild(target);
+    target.classList.add("table-overflow-expanded");
+    // Preserve the target's native semantics while it is moved. The generated
+    // ancestor above supplies the landmark axe expects outside `<main>`;
+    // applying `role="region"` directly to a keyed table's `<figure>` would be
+    // invalid ARIA. Its `<figcaption>` continues to name the figure itself.
+    // The "0th column" — a second collapse button, prepended so the row
+    // reads as `[collapse, scroll, collapse]`, exactly mirroring the
+    // always-present trailing button. Both are real flex items, so table
+    // content is pushed clear of them rather than floating an overlay on
+    // top of it.
+    const leadingButton = document.createElement("button");
+    leadingButton.type = "button";
+    leadingButton.className = "table-overflow-expand-btn";
+    leadingButton.textContent = "⟩";
+    leadingButton.setAttribute(
+      "aria-label",
+      `Collapse ${captionFor(container)}`,
+    );
+    leadingButton.title = "Collapse";
+    leadingButton.addEventListener("click", collapse);
+    container.prepend(leadingButton);
+    const reposition = () => {
+      const headerBottom =
+        document.querySelector<HTMLElement>("header.header")?.getBoundingClientRect()
+          .bottom ?? 0;
+      const verticalStart = Math.max(EDGE_PX, headerBottom + EDGE_PX);
+      const placeholderRect = placeholder.getBoundingClientRect();
+      // Track where the table would be in normal flow; once that position
+      // has scrolled entirely past the visible band, there is nothing to
+      // keep on screen — hide rather than cling to the viewport edge.
+      const inView =
+        placeholderRect.bottom > verticalStart &&
+        placeholderRect.top < window.innerHeight;
+      target.style.visibility = inView ? "" : "hidden";
+      if (!inView) return;
+      // Tracks the placeholder's own top exactly, unclamped — the table
+      // scrolls with the page like the in-flow element it stands in for,
+      // sliding up and off the top edge as the reader scrolls past, rather
+      // than sticking at `verticalStart` and then vanishing outright once
+      // `inView` above finally goes false.
+      const top = placeholderRect.top;
+      const sidebarEdge = sidebarLeftBound();
+      const viewportEdge = window.innerWidth - EDGE_PX;
+      // The "On this page" rail's left edge is a *soft* boundary, not a hard
+      // one: the table would rather stay clear of it, but is willing to
+      // spill past it, as far as `viewportEdge`, if `neededWidth` doesn't
+      // fit before it. `Math.max(tocBoundary, sidebarEdge + neededWidth)`
+      // is what makes that soft — as the window narrows and `tocBoundary`
+      // creeps left of `sidebarEdge + neededWidth`, this expression stops
+      // tracking `tocBoundary` and holds steady at `sidebarEdge +
+      // neededWidth` instead (the table's own width doesn't change), so the
+      // handoff between "centered before the rail" and "spilling past it"
+      // has no seam to jump across — `left`/`width` below vary continuously
+      // with window size the whole way through, never snapping between two
+      // different formulas.
+      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);
+      // Only as wide as the table (and its two button columns) needs, up to
+      // `rightBound` — never wider just because the room is there.
+      const width = Math.min(neededWidth, availableWidth);
+      // Centered between `sidebarEdge` and `rightBound`. While the table
+      // fits before the rail, that's a true center within the sidebar-to-
+      // rail gap. Once it doesn't, `rightBound` above has already opened up
+      // to exactly `sidebarEdge + neededWidth` (or `viewportEdge`, if even
+      // that overflows), so `availableWidth` equals `width` and this
+      // reduces to `sidebarEdge` — flush against the nav, extending only as
+      // far right as it has to, rather than centered across room it isn't
+      // using.
+      const left = sidebarEdge + (availableWidth - width) / 2;
+      target.style.position = "fixed";
+      target.style.top = `${top}px`;
+      target.style.left = `${left}px`;
+      target.style.width = `${width}px`;
+      // Sized against the visible top of the band (never above
+      // `verticalStart`, however far off-screen `top` itself has scrolled)
+      // so this stays a sane ceiling on the box's own height rather than
+      // ballooning once the table starts sliding above the header.
+      const visibleTop = Math.max(verticalStart, top);
+      target.style.maxHeight = `${Math.max(window.innerHeight - visibleTop - EDGE_PX, 80)}px`;
+      // Re-check: at its (possibly capped) expanded width the table may or
+      // may not still need to scroll internally.
+      updateScrollFocusability(scroll, container);
+    };
+    reposition();
+    window.addEventListener("scroll", reposition, {
+      passive: true,
+      capture: true,
+    });
+    window.addEventListener("resize", reposition, { passive: true });
+    active = {
+      container,
+      target,
+      scroll,
+      placeholder,
+      spoofWrapper,
+      button,
+      leadingButton,
+      reposition,
+    };
+    updateButtonLabel(container, button, true);
+  }
+  function wrapBareTable(table: HTMLTableElement): HTMLElement {
+    const wrapper = document.createElement("div");
+    wrapper.className = "table-overflow-body";
+    table.replaceWith(wrapper);
+    wrapper.append(table);
+    return wrapper;
+  }
+  function wire(container: HTMLElement) {
+    // The table itself moves into a dedicated scroll clip, freeing the
+    // button to be a full-height flex sibling instead of an overlay
+    // floating on top of table content.
+    const scroll = document.createElement("div");
+    scroll.className = "table-overflow-scroll";
+    while (container.firstChild) scroll.append(container.firstChild);
+    container.append(scroll);
+    const button = document.createElement("button");
+    button.type = "button";
+    button.className = "table-overflow-expand-btn";
+    button.hidden = true;
+    updateButtonLabel(container, button, false);
+    container.append(button);
+    button.addEventListener("click", () => {
+      if (active?.container === container) collapse();
+      else expand(container, button, scroll);
+    });
+    evaluateOverflow(scroll, button, container);
+    let resizeTimer: number | null = null;
+    window.addEventListener("resize", () => {
+      if (resizeTimer !== null) window.clearTimeout(resizeTimer);
+      resizeTimer = window.setTimeout(
+        () => evaluateOverflow(scroll, button, container),
+        150,
+      );
+    });
+  }
+  function setup() {
+    const root = document.querySelector(".sl-markdown-content");
+    if (!root) return;
+    const containers = new Set<HTMLElement>();
+    root
+      .querySelectorAll<HTMLElement>(".keyed-table__body")
+      .forEach((el) => containers.add(el));
+    root
+      .querySelectorAll<HTMLTableElement>(
+        "table:not(.keyed-table__body table):not(.lab-shell table)",
+      )
+      .forEach((table) => containers.add(wrapBareTable(table)));
+    if (containers.size === 0) return;
+    containers.forEach(wire);
+    document.addEventListener("keydown", (event) => {
+      if (event.key === "Escape" && active) collapse();
+    });
+    // Deliberately no "click outside collapses it": a reader following a
+    // link in the "On this page" rail, or clicking anywhere else on the
+    // page to keep reading, is not asking for the table back at its normal
+    // size — only Escape or the collapse buttons themselves are.
+  }
+  setup();
+  window.addEventListener("explico:prepare-static-export", collapse);
+</script>

package/src/content-config.ts CHANGED Viewed

@@ -287,6 +287,25 @@ const notation = defineCollection({
   }),
 });
+/**
+ * Abbreviations table (rule N14) — deliberately a lighter tier than a
+ * `notation` card: just a name resolution, no `formula`, `units`, or
+ * curriculum `alignment`. `abbr` is the canonical written form (`OLS`);
+ * `aliases` are other written forms of the same abbreviation that should
+ * resolve the same way (`w.r.t.` might alias `wrt`).
+ */
+const abbreviations = defineCollection({
+  loader: glob({ pattern: '**/*.md', base: './content/abbreviations' }),
+  schema: z.object({
+    key: id,
+    abbr: z.string().min(1),
+    expansion: notationProse,
+    aliases: z.array(z.string().min(1)).default([]),
+    domain: id.optional(),
+    editorialStatus: editorialStatus.default('draft'),
+  }),
+});
 export const collections = {
   docs,
   competencies,
@@ -294,4 +313,5 @@ export const collections = {
   tracks,
   sources,
   notation,
+  abbreviations,
 };

package/src/reference/base-abbreviations.mjs ADDED Viewed

@@ -0,0 +1,60 @@
+/**
+ * The base abbreviation baseline: acronyms and dotted abbreviations every
+ * reader is assumed to know, so a lesson never has to introduce them with an
+ * abbreviations-table entry. The `\operatorname{…}` / `\mathrm{…}` twins are
+ * `base-operators.mjs` (rule N8) / `base-roman-labels.mjs` (rule N10); this is
+ * the plain-prose equivalent for rule N14.
+ *
+ * Kept intentionally small, same rationale as `BASE_ROMAN_LABELS`: a
+ * course-specific acronym (`OLS`, `SSR`, `MSE`) is exactly the thing a reader
+ * benefits from having spelled out, so it belongs in the course's own
+ * `content/abbreviations/*.md` table, not here. This baseline only holds
+ * abbreviations so common in ordinary English/academic writing that spelling
+ * them out on every course would be noise, not help. A course adds a real
+ * one via `abbreviations.allow` in `course.config.ts`, the same shape as
+ * `operators.allow` / `romanLabels.allow`.
+ */
+export const BASE_ABBREVIATIONS = Object.freeze(
+  new Set([
+    // dotted Latin/English abbreviations
+    'e.g.',
+    'i.e.',
+    'etc.',
+    'cf.',
+    'vs.',
+    'a.m.',
+    'p.m.',
+    'a.k.a.',
+    'et al.',
+    // generic acronyms with no domain-specific meaning in this engine
+    'AI',
+    'ID',
+    'OK',
+    'URL',
+    'FAQ',
+    'US',
+    'UK',
+    'EU',
+  ]),
+);
+/**
+ * The abbreviations a course treats as common, given its `course.config.ts`
+ * `abbreviations` block: the shipped baseline, plus `allow`, minus `deny`.
+ *
+ * @param {{ allow?: readonly string[], deny?: readonly string[] } | undefined} abbreviations
+ * @returns {Set<string>}
+ */
+export function effectiveAbbreviationAllowlist(abbreviations) {
+  const allow = abbreviations?.allow ?? [];
+  const deny = new Set(abbreviations?.deny ?? []);
+  const effective = new Set(BASE_ABBREVIATIONS);
+  for (const name of allow) effective.add(name);
+  for (const name of deny) effective.delete(name);
+  return effective;
+}
+/** True when `token` needs no abbreviations-table entry for this course. */
+export function isBaseAbbreviation(token, abbreviations) {
+  return effectiveAbbreviationAllowlist(abbreviations).has(token);
+}

package/src/reference/base-operators.mjs CHANGED Viewed

@@ -81,6 +81,46 @@ export const BASE_OPERATORS = Object.freeze(
   ]),
 );
+/**
+ * The subset of {@link BASE_OPERATORS} that must never appear with a bare
+ * (unparenthesized) argument: every trigonometric, inverse-trigonometric, and
+ * hyperbolic function, plus the exponential and logarithms (N13). `\sin x`
+ * leaves how far the argument extends ambiguous the moment anything follows
+ * it (`\sin x + 1` — is the `+1` inside or outside the sine?); `\sin(x)`
+ * never does, even for a single-symbol argument. Kept separate from
+ * `BASE_OPERATORS`: this is a formatting rule layered on top of the "does it
+ * need a notation card" question that set answers, so an operator can be
+ * universal (N8) and still owe a parenthesized argument. Enforced by
+ * `resolveMathGlyphs` in `math-glyphs.mjs`, which every rendered-math context
+ * (lesson body, notation `formula`, assessments, `Diagram` nodes, lab math)
+ * already calls.
+ */
+export const PARENTHESIZED_FUNCTIONS = Object.freeze(
+  new Set([
+    // exponential / logarithms
+    'exp',
+    'log',
+    'ln',
+    'lg',
+    // trigonometric
+    'sin',
+    'cos',
+    'tan',
+    'cot',
+    'sec',
+    'csc',
+    // inverse trigonometric
+    'arcsin',
+    'arccos',
+    'arctan',
+    // hyperbolic
+    'sinh',
+    'cosh',
+    'tanh',
+    'coth',
+  ]),
+);
 /**
  * The operators a course treats as common, given its `course.config.ts`
  * `operators` block: the shipped baseline, plus `allow`, minus `deny`.

package/src/reference/base-roman-labels.mjs ADDED Viewed

@@ -0,0 +1,43 @@
+/**
+ * The base roman-label baseline: `\mathrm{…}` multi-letter labels every
+ * reader is assumed to know, so a lesson never has to introduce them with a
+ * notation entry. The `\operatorname{…}` counterpart is `base-operators.mjs`
+ * (rule N8); this is its `\mathrm{…}` twin (rule N10).
+ *
+ * Rationale: the completeness gate has no opinion about `\mathrm{…}` bodies —
+ * they are a typographic label to KaTeX, not a bindable symbol, and N3
+ * requires the format without asking whether the label is ever explained.
+ * The `roman-label-explained` consistency check fills that gap: a label a
+ * lesson uses is either on this list (or the course's additions to it) or it
+ * carries a notation entry the reader can hover.
+ *
+ * Kept intentionally small — unlike `sin`/`exp`, an upright label is almost
+ * always a course-specific named quantity (`KE`, `PV`, `Var`-as-a-label) that
+ * genuinely benefits from a hover card, so the shipped baseline holds only
+ * the qualifiers that function like an operator's extremum subscript
+ * (`x_{\mathrm{opt}}`) rather than naming a quantity of their own. A course
+ * adds a real one via `romanLabels.allow` in `course.config.ts`, the same
+ * shape as `operators.allow`.
+ */
+export const BASE_ROMAN_LABELS = Object.freeze(new Set(['opt']));
+/**
+ * The roman labels a course treats as common, given its `course.config.ts`
+ * `romanLabels` block: the shipped baseline, plus `allow`, minus `deny`.
+ *
+ * @param {{ allow?: readonly string[], deny?: readonly string[] } | undefined} romanLabels
+ * @returns {Set<string>}
+ */
+export function effectiveRomanLabelAllowlist(romanLabels) {
+  const allow = romanLabels?.allow ?? [];
+  const deny = new Set(romanLabels?.deny ?? []);
+  const effective = new Set(BASE_ROMAN_LABELS);
+  for (const name of allow) effective.add(name);
+  for (const name of deny) effective.delete(name);
+  return effective;
+}
+/** True when `name` needs no notation entry for this course. */
+export function isBaseRomanLabel(name, romanLabels) {
+  return effectiveRomanLabelAllowlist(romanLabels).has(name);
+}