explico 0.2.0 → 0.3.0

package/src/components/starlight/AboutPanel.astro

@@ -0,0 +1,255 @@
+---
+/**
+ * The `[?]` "about this material" control, rendered top-right in the header next
+ * to the social icons (`LayoutSocialIcons.astro` composes both). It appears on
+ * every route — landing page and study-material pages alike.
+ *
+ * All of its data comes from the one compiler manifest (`manifest.about`): the
+ * engine identity from `explico`'s own `package.json`, the course's reader-facing
+ * `about` block, and the knowledge version resolved against
+ * `content/CHANGELOG.md`. This component never re-reads the filesystem.
+ *
+ * It is a plain `<details>` disclosure: the browser gives keyboard toggle and
+ * `aria-expanded` for free; the inline script only adds Escape-to-close and
+ * outside-click-to-close.
+ */
+import { loadManifest } from '../../compiler/manifest';
+
+const { about } = await loadManifest();
+const { engine, material, knowledge, authors, disclaimer, changelogHref } =
+  about;
+
+/** `mailto:` an email, pass through an http(s) URL, plain text otherwise. */
+function contactHref(contact: string): string | undefined {
+  if (/^https?:\/\//i.test(contact)) return contact;
+  if (/^[^@\s]+@[^@\s]+\.[^@\s]+$/.test(contact)) return `mailto:${contact}`;
+  return undefined;
+}
+
+const authorLabel = authors.length > 1 ? 'Authors' : 'Author';
+const knowledgeLine = knowledge.date
+  ? `${knowledge.version} · ${knowledge.date}`
+  : knowledge.version;
+---
+
+<details class="about" data-about-panel>
+  <summary
+    class="about-toggle"
+    aria-label={`About ${material.name}`}
+    title={`About ${material.name}`}
+  >
+    <span aria-hidden="true">?</span>
+  </summary>
+  <div class="about-body">
+    <p class="about-name">{material.name}</p>
+    {material.summary && <p class="about-summary">{material.summary}</p>}
+
+    <dl class="about-facts">
+      <div>
+        <dt>Knowledge version</dt>
+        <dd>{knowledgeLine}</dd>
+      </div>
+      <div>
+        <dt>Engine</dt>
+        <dd>
+          {
+            engine.homepage ? (
+              <a href={engine.homepage}>
+                {engine.name} {engine.version}
+              </a>
+            ) : (
+              <span>
+                {engine.name} {engine.version}
+              </span>
+            )
+          }
+        </dd>
+      </div>
+      {
+        authors.length > 0 && (
+          <div>
+            <dt>{authorLabel}</dt>
+            <dd>
+              {authors.map((author, index) => {
+                const href = author.contact
+                  ? contactHref(author.contact)
+                  : undefined;
+                return (
+                  <>
+                    {index > 0 && ', '}
+                    {author.name}
+                    {author.contact && (
+                      <>
+                        {' '}
+                        (
+                        {href ? (
+                          <a href={href}>{author.contact}</a>
+                        ) : (
+                          author.contact
+                        )}
+                        )
+                      </>
+                    )}
+                  </>
+                );
+              })}
+            </dd>
+          </div>
+        )
+      }
+    </dl>
+
+    {disclaimer && <p class="about-disclaimer">{disclaimer}</p>}
+
+    {
+      changelogHref && (
+        <p class="about-links">
+          <a href={changelogHref}>What changed in this material</a>
+        </p>
+      )
+    }
+  </div>
+</details>
+
+<style>
+  @layer starlight.components {
+    .about {
+      position: relative;
+      display: inline-flex;
+    }
+
+    .about-toggle {
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      width: 1.75rem;
+      height: 1.75rem;
+      border: 1px solid var(--sl-color-gray-5);
+      border-radius: 999px;
+      color: var(--sl-color-gray-1);
+      background: var(--sl-color-bg);
+      font-size: var(--sl-text-sm);
+      font-weight: 600;
+      line-height: 1;
+      cursor: pointer;
+      user-select: none;
+      list-style: none;
+    }
+
+    .about-toggle::-webkit-details-marker {
+      display: none;
+    }
+
+    .about-toggle:hover {
+      color: var(--sl-color-text);
+      border-color: var(--sl-color-gray-4);
+    }
+
+    .about[open] .about-toggle {
+      color: var(--sl-color-text);
+      border-color: var(--sl-color-accent);
+    }
+
+    .about-toggle:focus-visible {
+      outline: 2px solid var(--sl-color-accent);
+      outline-offset: 2px;
+    }
+
+    .about-body {
+      position: absolute;
+      inset-inline-end: 0;
+      top: calc(100% + 0.5rem);
+      z-index: 90;
+      width: min(21rem, calc(100vw - 1.5rem));
+      max-height: min(70vh, 34rem);
+      overflow-y: auto;
+      padding: 1rem;
+      border: 1px solid var(--sl-color-gray-5);
+      border-top: 0.25rem solid var(--sl-color-accent);
+      border-radius: 0.65rem;
+      color: var(--sl-color-text);
+      background: var(--sl-color-bg);
+      box-shadow: var(--sl-shadow-lg);
+      font-size: var(--sl-text-xs);
+      line-height: 1.5;
+    }
+
+    .about-name {
+      margin: 0;
+      font-size: var(--sl-text-sm);
+      font-weight: 600;
+    }
+
+    .about-summary {
+      margin: 0.35rem 0 0;
+      color: var(--sl-color-gray-2);
+    }
+
+    .about-facts {
+      margin: 0.75rem 0 0;
+      display: grid;
+      gap: 0.4rem;
+    }
+
+    .about-facts > div {
+      display: grid;
+      grid-template-columns: 8rem 1fr;
+      gap: 0.5rem;
+    }
+
+    .about-facts dt {
+      color: var(--sl-color-gray-3);
+      text-transform: uppercase;
+      letter-spacing: 0.03em;
+      font-size: 0.65rem;
+      line-height: 1.6;
+    }
+
+    .about-facts dd {
+      margin: 0;
+      overflow-wrap: anywhere;
+    }
+
+    .about-disclaimer {
+      margin: 0.85rem 0 0;
+      padding-top: 0.75rem;
+      border-top: 1px solid var(--sl-color-gray-6);
+      color: var(--sl-color-gray-2);
+    }
+
+    .about-links {
+      margin: 0.75rem 0 0;
+    }
+
+    .about-body a {
+      color: var(--sl-color-text-accent);
+    }
+  }
+</style>
+
+<script>
+  (() => {
+    const panels = Array.from(
+      document.querySelectorAll<HTMLDetailsElement>('details[data-about-panel]'),
+    );
+    if (panels.length === 0) return;
+
+    document.addEventListener('keydown', (event) => {
+      if (event.key !== 'Escape') return;
+      for (const details of panels) {
+        if (!details.open) continue;
+        details.open = false;
+        details.querySelector<HTMLElement>('summary')?.focus();
+      }
+    });
+
+    document.addEventListener('pointerdown', (event) => {
+      const target = event.target instanceof Node ? event.target : null;
+      for (const details of panels) {
+        if (details.open && (!target || !details.contains(target))) {
+          details.open = false;
+        }
+      }
+    });
+  })();
+</script>

package/src/components/starlight/HeadingAnchorEnhancer.astro

@@ -1,7 +1,7 @@
 ---
 /**
  * Progressive enhancement for content-heading deep links (Step F3), the sibling
- * of `EquationEnhancer.astro`.
+ * of `KeyedFloatEnhancer.astro`.
  *
  * The no-JS baseline is complete: `rehype-heading-anchors` emits Starlight's
  * `.sl-heading-wrapper` + `a.sl-anchor-link` markup, its bundled
@@ -24,7 +24,7 @@
  * 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
+ * what actually plays the highlight — see `KeyedFloatEnhancer.astro`, which
  * this mirrors.
  *
  * Everything here is gated on `prefers-reduced-motion` and degrades to the
@@ -113,7 +113,7 @@
       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
+      // `KeyedFloatEnhancer.astro`. Every other click is left to the browser's
       // own fragment navigation, picked up below via `hashchange`.
       if (location.hash === href) {
         event.preventDefault();

package/src/components/starlight/KeyedFloatEnhancer.astro

@@ -0,0 +1,137 @@
+---
+/**
+ * Progressive enhancement for keyed floats — equations (Step D7), extended
+ * to `<Table>`/`<Figure>` (F-tables-figures). 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.
+ *
+ * The no-JS baseline is complete: `remark-notation` emits a real
+ * `id="eq-<key>"` / `id="tab-<key>"` / `id="fig-<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
+ * `scroll-margin`.
+ *
+ * This script only adds what CSS and anchors cannot:
+ *  - a smooth, header-aware scroll on an in-page jump;
+ *  - re-triggering the highlight when the same `#eq-…`/`#tab-…`/`#fig-…` 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 float so screen-reader users land on it;
+ *  - for an equation only, marking its number permanently visible
+ *    (`.eq-number-revealed`, styled in `global.css`) once the reader has
+ *    actually arrived at it, so it doesn't fade back down once the
+ *    `:target`/`:hover` state ends — a table/figure number isn't faded to
+ *    begin with (it's part of the always-visible caption), so it has
+ *    nothing to reveal.
+ *
+ * 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 the 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.
+ */
+---
+
+<script>
+  (() => {
+    const root = document.querySelector('.sl-markdown-content');
+    if (!root) return;
+
+    interface Kind {
+      readonly prefix: string;
+      readonly triggerSelector: string;
+      readonly numberSelector: string;
+      readonly reveal: boolean;
+    }
+
+    const KINDS: readonly Kind[] = [
+      {
+        prefix: '#eq-',
+        triggerSelector: 'a.equation-ref, a.keyed-equation__number',
+        numberSelector: '.keyed-equation__number',
+        reveal: true,
+      },
+      {
+        prefix: '#tab-',
+        triggerSelector: 'a.table-ref, a.keyed-table__number',
+        numberSelector: '.keyed-table__number',
+        reveal: false,
+      },
+      {
+        prefix: '#fig-',
+        triggerSelector: 'a.figure-ref, a.keyed-figure__number',
+        numberSelector: '.keyed-figure__number',
+        reveal: false,
+      },
+    ];
+    const TRIGGER_SELECTOR = KINDS.map((kind) => kind.triggerSelector).join(', ');
+    const kindForHash = (hash: string) =>
+      KINDS.find((kind) => hash.startsWith(kind.prefix));
+
+    const reduce = window.matchMedia('(prefers-reduced-motion: reduce)');
+
+    const activate = (target: HTMLElement | null, doScroll: boolean, kind: Kind) => {
+      if (!target) return;
+      if (kind.reveal) {
+        target
+          .querySelector(kind.numberSelector)
+          ?.classList.add('eq-number-revealed');
+      }
+      if (!reduce.matches) {
+        // Restart the CSS `:target` animation even when the hash is unchanged.
+        target.style.animation = 'none';
+        void target.offsetWidth;
+        target.style.removeProperty('animation');
+      }
+      if (doScroll) {
+        target.scrollIntoView({
+          behavior: reduce.matches ? 'auto' : 'smooth',
+          block: 'start',
+        });
+      }
+      target.setAttribute('tabindex', '-1');
+      try {
+        target.focus({ preventScroll: true });
+      } catch {
+        target.focus();
+      }
+    };
+
+    root.addEventListener('click', (event) => {
+      const origin = event.target instanceof Element ? event.target : null;
+      const link = origin?.closest(TRIGGER_SELECTOR);
+      if (!link) return;
+      const href = link.getAttribute('href') || '';
+      const kind = kindForHash(href);
+      if (!kind) return; // cross-page or unrecognized: let the browser navigate
+      const target = document.getElementById(href.slice(1));
+      if (!target) return;
+      // 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, kind);
+      }
+    });
+
+    window.addEventListener('hashchange', () => {
+      const kind = kindForHash(location.hash);
+      if (!kind) return;
+      activate(document.getElementById(location.hash.slice(1)), true, kind);
+    });
+
+    const initialKind = kindForHash(location.hash);
+    if (initialKind) {
+      activate(document.getElementById(location.hash.slice(1)), true, initialKind);
+    }
+  })();
+</script>

package/src/components/starlight/LayoutSocialIcons.astro

@@ -0,0 +1,12 @@
+---
+/**
+ * Starlight allows one `SocialIcons` override, so this composes the stock
+ * social-link row with the `[?]` About control (`AboutPanel.astro`). Both sit in
+ * the header's right cluster; the About panel is present on every route.
+ */
+import DefaultSocialIcons from '@astrojs/starlight/components/SocialIcons.astro';
+import AboutPanel from './AboutPanel.astro';
+---
+
+<DefaultSocialIcons />
+<AboutPanel />

package/src/components/starlight/LessonFooter.astro

@@ -18,7 +18,8 @@ import NotationLayer, {
   type NotationLayerDefinition,
 } from '../notation/NotationLayer.astro';
 import CitationLayer from '../citation/CitationLayer.astro';
-import EquationEnhancer from './EquationEnhancer.astro';
+import KeyedFloatEnhancer from './KeyedFloatEnhancer.astro';
+import FloatRefLayer from '../reference/FloatRefLayer.astro';
 import HeadingAnchorEnhancer from './HeadingAnchorEnhancer.astro';
 
 // `lessonId` is no longer authored (Phase C2); derive it from the route.
@@ -57,6 +58,7 @@ if (lessonId) {
 
 <NotationLayer definitions={definitions} />
 {lessonId && <CitationLayer />}
-{lessonId && <EquationEnhancer />}
+{lessonId && <KeyedFloatEnhancer />}
+{lessonId && <FloatRefLayer />}
 {lessonId && <HeadingAnchorEnhancer />}
 <DefaultFooter />

package/src/components/table/Table.astro

@@ -0,0 +1,104 @@
+---
+/**
+ * A referenceable table (F-tables-figures) — the table equivalent of a
+ * keyed display equation. `remark-notation.mjs` numbers every `<Table>` on a
+ * lesson page `‹chapter›.‹n›` (chapter = the lesson's course ordinal, `n`
+ * sequential over the lesson), keyed or not, and injects the resulting
+ * `number`/`anchorId` as props; this component only renders what it's given
+ * — it never computes its own number, same as `equationNode()`'s output for
+ * equations.
+ *
+ * An author sets `id` to make the table referenceable by name with
+ * `[[tab-<id>]]` (same page) or `[[lesson-slug#tab-<id>]]` (cross page); a
+ * table without `id` is still numbered and deep-linkable, just not
+ * referenceable by name — the same rule an unkeyed equation follows.
+ */
+export interface Props {
+  /** Stable key, e.g. `id="kinematics-summary"`. Omit for a positional-only table. */
+  id?: string;
+  /** Visible caption, shown below the table and in the hover-preview card. */
+  caption: string;
+  /** Computed by `remark-notation.mjs` — never author this directly. */
+  number?: string;
+  /** Computed by `remark-notation.mjs` — never author this directly. */
+  anchorId?: string;
+}
+
+const { id, caption, number, anchorId } = Astro.props;
+
+if (typeof caption !== 'string' || !caption.trim()) {
+  throw new Error('Table requires a non-empty `caption` prop.');
+}
+if (!number || !anchorId) {
+  throw new Error(
+    'Table is missing its computed `number`/`anchorId` — this page must run remark-notation with a `tables` cross-page table configured (see astro.config.mjs).',
+  );
+}
+---
+
+<figure
+  class="keyed-table"
+  id={anchorId}
+  data-tab-number={number}
+  data-tab-key={id}
+>
+  <div class="keyed-table__body">
+    <slot />
+  </div>
+  <figcaption class="keyed-table__caption">
+    <a
+      class="keyed-table__number"
+      href={`#${anchorId}`}
+      aria-label={`Table ${number}`}>Table {number}</a
+    >
+    <span class="keyed-table__caption-text">{caption}</span>
+  </figcaption>
+</figure>
+
+<style>
+  .keyed-table {
+    margin-block: 1.5rem;
+    padding: 0;
+  }
+
+  .keyed-table__body {
+    overflow-x: auto;
+  }
+
+  .keyed-table__body :global(table) {
+    margin: 0;
+  }
+
+  .keyed-table__caption {
+    margin-block-start: 0.5rem;
+    font-size: var(--sl-text-sm);
+    color: var(--sl-color-gray-3);
+  }
+
+  .keyed-table__number {
+    font-weight: 600;
+    font-variant-numeric: tabular-nums;
+    color: var(--sl-color-text-accent);
+    text-decoration: none;
+  }
+
+  .keyed-table__number:hover,
+  .keyed-table__number:focus-visible {
+    text-decoration: underline;
+  }
+
+  .keyed-table__number:focus-visible {
+    outline: 2px solid var(--sl-color-accent);
+    outline-offset: 0.15rem;
+  }
+
+  .keyed-table__caption-text::before {
+    content: ' — ';
+  }
+
+  @media print {
+    .keyed-table__number {
+      color: inherit;
+    }
+  }
+</style>

package/src/reference/base-operators.mjs

@@ -0,0 +1,103 @@
+/**
+ * The base operator library: the named mathematical operators every reader is
+ * assumed to know, so a lesson never has to introduce them with a notation
+ * entry.
+ *
+ * Rationale (parallel to `base-library.mjs`): the completeness gate has no
+ * opinion about operators — KaTeX parses `\exp`, `\int`, `\sin`, … as operator
+ * nodes, and `\operatorname{Var}` as an `operatorname` node, none of which the
+ * glyph resolver treats as a bindable symbol. The `operator-explained`
+ * consistency check (rule N8) fills that gap: an operator 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. This set is the "everyone knows these"
+ * baseline — trig, the exponential and logarithms, limits, extrema, and the
+ * big operators — kept greppable and small like the base library.
+ *
+ * A domain operator (`Var`, `Cov`, `Corr`, `sgn`, `erf`, `Tr`, `argmax`, …) is
+ * written `\operatorname{…}` and is NOT here: it earns a card, a
+ * `notation.local` entry, or an explicit line in `course.config.ts`
+ * (`operators.allow`).
+ *
+ * Entries are the KaTeX command without its backslash (`exp`, not `\exp`) for
+ * `op` nodes, and the verbatim body for `\operatorname{…}` nodes (`Var`).
+ * Matching is case-sensitive.
+ */
+export const BASE_OPERATORS = 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',
+    // limits
+    'lim',
+    'limsup',
+    'liminf',
+    'injlim',
+    'projlim',
+    'varlimsup',
+    'varliminf',
+    'varinjlim',
+    'varprojlim',
+    // extrema
+    'max',
+    'min',
+    'sup',
+    'inf',
+    // linear algebra / number theory / misc
+    'arg',
+    'deg',
+    'det',
+    'dim',
+    'gcd',
+    'hom',
+    'ker',
+    'Pr',
+    'mod',
+    // big operators
+    'sum',
+    'prod',
+    'coprod',
+    'int',
+    'iint',
+    'iiint',
+    'oint',
+  ]),
+);
+
+/**
+ * The operators a course treats as common, given its `course.config.ts`
+ * `operators` block: the shipped baseline, plus `allow`, minus `deny`.
+ *
+ * @param {{ allow?: readonly string[], deny?: readonly string[] } | undefined} operators
+ * @returns {Set<string>}
+ */
+export function effectiveOperatorAllowlist(operators) {
+  const allow = operators?.allow ?? [];
+  const deny = new Set(operators?.deny ?? []);
+  const effective = new Set(BASE_OPERATORS);
+  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 isBaseOperator(name, operators) {
+  return effectiveOperatorAllowlist(operators).has(name);
+}