explico 0.3.0 → 0.5.0

package/src/components/HoverPanel.astro

@@ -50,7 +50,9 @@ const { id, label, class: className, ...rest } = Astro.props;
   >
     <span aria-hidden="true">&times;</span>
   </button>
-  <slot />
+  <div class="hover-panel-scroll">
+    <slot />
+  </div>
 </aside>
 
 <style>
@@ -63,9 +65,15 @@ const { id, label, class: className, ...rest } = Astro.props;
          JS placement (which clears display equations) must start from zero. */
       margin: 0;
       width: min(23rem, calc(100vw - 1.5rem));
-      overflow: auto;
-      padding: 1rem;
-      padding-inline-end: 2.4rem;
+      display: flex;
+      flex-direction: column;
+      /* The scrolling lives on `.hover-panel-scroll` below, not here — the
+         close button is an absolutely-positioned sibling of that scroller,
+         so it stays put when the content scrolls instead of scrolling away
+         with it (which is what happens to an absolutely-positioned child of
+         the scroll container itself). `hidden` also keeps the rounded
+         corners clean around the inner scroller. */
+      overflow: hidden;
       border: 1px solid var(--sl-color-gray-5);
       border-top: 0.25rem solid var(--sl-color-accent);
       border-radius: 0.65rem;
@@ -75,6 +83,39 @@ const { id, label, class: className, ...rest } = Astro.props;
       font-size: var(--sl-text-sm);
     }
 
+    /* `.hover-panel { display: flex }` above has the same specificity as the
+       UA stylesheet's `[hidden] { display: none }` and comes later in the
+       cascade, so it would otherwise win and defeat the `hidden` attribute
+       that every layer's JS relies on to actually hide the panel. */
+    .hover-panel[hidden] {
+      display: none;
+    }
+
+    /* The equation/table/figure preview card (`FloatRefLayer.astro`) is the
+       one panel whose content size varies wildly — a short reference vs. a
+       wide equation — so it grows to fit instead of staying pinned at the
+       default width. `--float-ref-max-width` is computed in JS from the live
+       layout (the room between the left sidebar and the viewport edge); the
+       notation and citation panels never set it and keep the fixed default. */
+    .hover-panel[data-float-ref-panel] {
+      width: fit-content;
+      min-width: min(23rem, var(--float-ref-max-width, 100vw));
+      max-width: var(--float-ref-max-width, min(23rem, calc(100vw - 1.5rem)));
+    }
+
+    .hover-panel-scroll {
+      overflow: auto;
+      /* Without these, this flex item's default `auto` minimum size is its
+         *content's* size, not the panel's — content wider or taller than the
+         panel would inflate the panel itself outward instead of scrolling
+         inside it (the same flexbox trap `.float-ref-panel-content` guards
+         against with its own `min-width: 0`). */
+      min-width: 0;
+      min-height: 0;
+      padding: 1rem;
+      padding-inline-end: 2.4rem;
+    }
+
     .hover-panel-close {
       position: absolute;
       top: 0.5rem;

package/src/components/abbreviation/AbbreviationGlossary.astro

@@ -0,0 +1,70 @@
+---
+/**
+ * A plain, alphabetical listing of the `abbreviations` collection (rule N14)
+ * — deliberately the simplest possible reader-facing view of this content.
+ * Unlike `NotationGlossary.astro`, there is no hover popup, no formula
+ * rendering, and no `NotationLayer`: an abbreviation card is a name
+ * resolution only, so a definition list is the whole job.
+ */
+import { getCollection } from 'astro:content';
+
+const entries = (await getCollection('abbreviations')).sort((left, right) =>
+  left.data.abbr.localeCompare(right.data.abbr),
+);
+---
+
+{
+  entries.length === 0 ? (
+    <p class="abbreviation-glossary-empty">
+      No abbreviations are catalogued yet.
+    </p>
+  ) : (
+    <dl class="abbreviation-glossary">
+      {entries.map((entry) => (
+        <div class="abbreviation-entry" id={`abbr-${entry.data.key}`}>
+          <dt>
+            {entry.data.abbr}
+            {entry.data.aliases.length > 0 && (
+              <span class="abbreviation-aliases">
+                {' '}
+                (also {entry.data.aliases.join(', ')})
+              </span>
+            )}
+          </dt>
+          <dd>{entry.data.expansion}</dd>
+        </div>
+      ))}
+    </dl>
+  )
+}
+
+<style>
+  .abbreviation-glossary {
+    display: grid;
+    grid-template-columns: max-content 1fr;
+    column-gap: 1rem;
+    row-gap: 0.75rem;
+  }
+
+  .abbreviation-entry {
+    display: contents;
+  }
+
+  .abbreviation-entry dt {
+    font-weight: 600;
+    white-space: nowrap;
+  }
+
+  .abbreviation-entry dd {
+    margin: 0;
+  }
+
+  .abbreviation-aliases {
+    font-weight: 400;
+    color: var(--sl-color-gray-3);
+  }
+
+  .abbreviation-glossary-empty {
+    color: var(--sl-color-gray-3);
+  }
+</style>

package/src/components/abbreviation/AbbreviationLayer.astro

@@ -0,0 +1,127 @@
+---
+/**
+ * Hover/pin panel for the inline abbreviation links `remarkAbbreviations`
+ * emits (N14, close sibling of `CitationLayer.astro`). The links are real
+ * anchors to the glossary's "Abbreviations" section and work with no
+ * JavaScript; this island only adds a quick look at the resolution without
+ * leaving the reader's place.
+ *
+ * The abbreviations table is small by nature (a name + one-line resolution
+ * each), so unlike the math-notation layer this renders every entry
+ * unconditionally on every lesson page — one hidden block per entry — rather
+ * than computing a per-page dependency closure. The panel reads its content
+ * from that static markup, never from a second serialized copy of the table.
+ * Positioning, pin, Escape, and outside-close come from the shared
+ * `HoverPanel` primitive.
+ */
+import { getCollection } from 'astro:content';
+import HoverPanel from '../HoverPanel.astro';
+
+const entries = await getCollection('abbreviations');
+---
+
+<HoverPanel id="abbreviation-panel" label="Abbreviation" data-abbreviation-panel>
+  <div class="abbreviation-panel-body">
+    <p class="abbreviation-panel-term" data-panel-term></p>
+    <p class="abbreviation-panel-expansion" data-panel-expansion></p>
+    <a class="abbreviation-panel-jump" data-panel-jump
+      >See it in the glossary</a
+    >
+  </div>
+</HoverPanel>
+
+{
+  entries.map((entry) => (
+    <p hidden data-abbr-entry={entry.data.key}>
+      {entry.data.expansion}
+    </p>
+  ))
+}
+
+<script>
+  import { createHoverPanel, closestElement } from '../hover-panel';
+
+  function setup() {
+    const panel = document.querySelector<HTMLElement>(
+      '[data-abbreviation-panel]',
+    );
+    if (!panel || panel.dataset.hoverPanelReady === 'true') return;
+
+    const markers = Array.from(
+      document.querySelectorAll<HTMLAnchorElement>(
+        '.sl-markdown-content a.abbreviation-term[data-abbr-key]',
+      ),
+    );
+    if (markers.length === 0) return;
+    const markerSet = new Set<HTMLElement>(markers);
+
+    const term = panel.querySelector<HTMLElement>('[data-panel-term]')!;
+    const expansion = panel.querySelector<HTMLElement>(
+      '[data-panel-expansion]',
+    )!;
+    const jump = panel.querySelector<HTMLAnchorElement>('[data-panel-jump]')!;
+
+    const markerFrom = (node: EventTarget | null) => {
+      const candidate = closestElement(
+        node,
+        'a.abbreviation-term[data-abbr-key]',
+      );
+      return candidate && markerSet.has(candidate) ? candidate : null;
+    };
+
+    // Fill the panel from the matching hidden `[data-abbr-entry]` block —
+    // never from a second serialized copy of the table.
+    const render = (marker: HTMLElement, key: string) => {
+      const entry = document.querySelector<HTMLElement>(
+        `[data-abbr-entry="${CSS.escape(key)}"]`,
+      );
+      if (!entry) return false;
+
+      term.textContent = marker.textContent ?? '';
+      expansion.textContent = entry.textContent ?? '';
+      jump.href = marker.getAttribute('href') ?? '#abbreviations';
+      return true;
+    };
+
+    createHoverPanel({
+      panel,
+      groupId: 'abbreviation',
+      triggerFrom: markerFrom,
+      keyFor: (element) => element.dataset.abbrKey ?? null,
+      render,
+    });
+  }
+
+  setup();
+  document.addEventListener('astro:page-load', setup);
+</script>
+
+<style>
+  @layer starlight.components {
+    :global(a.abbreviation-term) {
+      text-decoration: underline dotted;
+      text-underline-offset: 0.2em;
+      color: inherit;
+    }
+
+    :global(a.abbreviation-term:hover),
+    :global(a.abbreviation-term:focus-visible) {
+      background: var(--sl-color-accent-low);
+      color: var(--sl-color-text-accent);
+    }
+
+    .abbreviation-panel-body p {
+      margin: 0 0 0.5rem;
+      line-height: 1.5;
+    }
+
+    .abbreviation-panel-term {
+      font-weight: 600;
+    }
+
+    .abbreviation-panel-jump {
+      display: inline-block;
+      font-size: var(--sl-text-xs);
+    }
+  }
+</style>

package/src/components/assessments/AssessmentRunner.tsx

@@ -10,6 +10,9 @@ import {
   type ProgressRepository,
 } from '../../progress/ProgressRepository';
 import { useSessionUser } from '../../session/user-context';
+import type { MixedContentNode } from '../notation/render-notation-math';
+import RenderedContent from './RenderedContent';
+import { shuffled } from './assessment-randomization';
 
 interface ChoiceOption {
   id: string;
@@ -20,8 +23,14 @@ interface AssessmentItemBase {
   id: string;
   competencyId?: string;
   evidenceKind: 'direct' | 'transfer';
-  prompt: string;
-  explanation: string;
+  /**
+   * Pre-split and glyph-resolved by `AssessmentSet.astro` from
+   * `manifest.assessmentContent` (schema v8) — the same KaTeX pipeline
+   * lesson body math renders through, not the raw authored string. Render
+   * with {@link RenderedContent}, never as a plain string.
+   */
+  promptContent: readonly MixedContentNode[];
+  explanationContent: readonly MixedContentNode[];
 }
 
 interface ChoiceItem extends AssessmentItemBase {
@@ -42,7 +51,10 @@ type Outcome = 'correct' | 'incorrect';
 interface Props {
   /** Assessment collection id — scopes recorded attempts and analytics events. */
   assessmentId: string;
+  /** Assessment title; the set wrapper renders it, direct callers use it here. */
   title: string;
+  /** Stable id of the heading emitted by `AssessmentSet.astro`. */
+  labelledBy?: string;
   items: Item[];
   /**
    * Seams (Phase H1). Both default to the no-op implementations the static
@@ -70,18 +82,38 @@ function statusFor(outcome: Outcome | undefined): {
 interface QuestionProps {
   item: Item;
   index: number;
+  headingTag: 'h3' | 'h4';
   outcome: Outcome | undefined;
   onResult: (id: string, outcome: Outcome) => void;
   onReset: (id: string) => void;
 }
 
-function Question({ item, index, outcome, onResult, onReset }: QuestionProps) {
+function Question({
+  item,
+  index,
+  headingTag: Heading,
+  outcome,
+  onResult,
+  onReset,
+}: QuestionProps) {
   const panelId = useId();
   const groupName = useId();
   const inputId = useId();
   const [open, setOpen] = useState(false);
   const [choice, setChoice] = useState<string | null>(null);
   const [numeric, setNumeric] = useState('');
+  const [choiceOptions, setChoiceOptions] = useState<ChoiceOption[]>(() =>
+    item.type === 'single-choice' ? item.options : [],
+  );
+
+  // Keep the server-rendered authored order hydration-safe, then generate a
+  // fresh display order in the browser. It remains stable for this view and
+  // is regenerated by a full reload; correctness continues to use option ids.
+  useEffect(() => {
+    if (item.type === 'single-choice') {
+      setChoiceOptions(shuffled(item.options));
+    }
+  }, [item]);
 
   const checked = outcome !== undefined;
   const parsed = Number(numeric);
@@ -108,7 +140,7 @@ function Question({ item, index, outcome, onResult, onReset }: QuestionProps) {
 
   return (
     <li className="assessment-item">
-      <h4 className="assessment-item-heading">
+      <Heading className="assessment-item-heading">
         <button
           type="button"
           className="assessment-disclosure"
@@ -140,17 +172,19 @@ function Question({ item, index, outcome, onResult, onReset }: QuestionProps) {
             />
           </svg>
         </button>
-      </h4>
+      </Heading>
 
       <div id={panelId} className="assessment-panel" hidden={!open}>
-        <p className="assessment-prompt">{item.prompt}</p>
+        <p className="assessment-prompt">
+          <RenderedContent content={item.promptContent} />
+        </p>
 
         {item.type === 'single-choice' ? (
           <fieldset className="assessment-choices">
             <legend className="sr-only">
               Answer options for question {index}
             </legend>
-            {item.options.map((option) => (
+            {choiceOptions.map((option) => (
               <label key={option.id} className="assessment-option">
                 <input
                   type="radio"
@@ -203,7 +237,7 @@ function Question({ item, index, outcome, onResult, onReset }: QuestionProps) {
               <strong>
                 {outcome === 'correct' ? 'Correct.' : 'Not quite.'}
               </strong>{' '}
-              {item.explanation}
+              <RenderedContent content={item.explanationContent} />
             </>
           ) : (
             'Check your answer to reveal the explanation.'
@@ -217,11 +251,13 @@ function Question({ item, index, outcome, onResult, onReset }: QuestionProps) {
 export default function AssessmentRunner({
   assessmentId,
   title,
+  labelledBy,
   items,
   progress = noopProgressRepository,
   analytics = noopAnalyticsEmitter,
 }: Props) {
-  const headingId = useId();
+  const ownHeadingId = useId();
+  const headingId = labelledBy ?? ownHeadingId;
   const user = useSessionUser();
   const [results, setResults] = useState<Record<string, Outcome>>({});
 
@@ -295,20 +331,19 @@ export default function AssessmentRunner({
 
   return (
     <section className="assessment-shell" aria-labelledby={headingId}>
-      <div className="assessment-header">
-        <h3 id={headingId}>{title}</h3>
-        <p className="assessment-progress" aria-live="polite">
-          {answered === 0
-            ? `${items.length} question${items.length === 1 ? '' : 's'}`
-            : `${correct} of ${items.length} correct`}
-        </p>
-      </div>
+      {!labelledBy && <h3 id={headingId}>{title}</h3>}
+      <p className="assessment-progress" aria-live="polite">
+        {answered === 0
+          ? `${items.length} question${items.length === 1 ? '' : 's'}`
+          : `${correct} of ${items.length} correct`}
+      </p>
       <ol className="assessment-list">
         {items.map((item, position) => (
           <Question
             key={item.id}
             item={item}
             index={position + 1}
+            headingTag={labelledBy ? 'h3' : 'h4'}
             outcome={results[item.id]}
             onResult={report}
             onReset={clear}

package/src/components/assessments/AssessmentSet.astro

@@ -1,12 +1,18 @@
 ---
 import { getCollection } from 'astro:content';
 import { loadManifest } from '../../compiler/manifest';
+import type { ContentSegment } from '../../reference/mixed-content';
+import { renderNotationMath } from '../notation/render-notation-math';
+import type { MixedContentNode } from '../notation/render-notation-math';
+import { knowledgeCheckAnchorId } from '../../reference/knowledge-checks.mjs';
 import AssessmentRunner from './AssessmentRunner';
 
 interface Props {
   /**
    * Explicit assessment id. Omitted in lesson bodies (Phase C2): the set is
    * resolved from the route's colocated `<lesson>.checks.yml` via the manifest.
+   * Put an explicit id in that list as well to publish its part-wide number to
+   * `[[check-…]]` references; undeclared legacy embeds keep a local fallback.
    */
   id?: string;
 }
@@ -19,36 +25,114 @@ const lessonId = Astro.url.pathname
   .replace(/\/$/, '')
   .replace(/\//g, '.');
 
+const manifest = await loadManifest();
+const lesson = manifest.lessons.find((entry) => entry.id === lessonId);
+if (!lesson) {
+  throw new Error(
+    `AssessmentSet: route "${Astro.url.pathname}" does not resolve to a lesson in the manifest`,
+  );
+}
+
 let ids: string[];
 if (explicitId) {
   ids = [explicitId];
 } else {
-  const manifest = await loadManifest();
-  ids = [
-    ...(manifest.lessons.find((lesson) => lesson.id === lessonId)
-      ?.assessments ?? []),
-  ];
+  ids = [...lesson.assessments];
 }
 
 const assessments = await getCollection('assessments');
-const entries = ids.map((id) => {
+const entries = ids.map((id, index) => {
   const entry = assessments.find((candidate) => candidate.data.id === id);
   if (!entry) {
     throw new Error(
       `AssessmentSet: no assessment collection entry with id "${id}"`,
     );
   }
-  return entry;
+  const publishedNumber = lesson.knowledgeChecks.find(
+    (check) => check.key === id,
+  )?.number;
+  const localIndex =
+    lesson.numbering.checks + lesson.assessments.length + index + 1;
+  const number =
+    publishedNumber ??
+    (lesson.part > 0 ? `${lesson.part}.${localIndex}` : String(index + 1));
+  return { entry, number, anchorId: knowledgeCheckAnchorId(id) };
 });
+
+// `manifest.assessmentContent` (schema v8) already resolved every glyph in
+// every item's `prompt` / `explanation` against this page's lesson scope —
+// same `pageScope`, same relationship, as `gate-math.ts`'s assessment check.
+// Rendering the resolved LaTeX to a `SafeMathNode` tree happens here, in an
+// Astro component, not in `manifest.ts`: the compiler layer stays
+// framework-agnostic, and `renderNotationMath` already lives one directory
+// over for exactly this reason (`NotationMath.astro` calls it the same way).
+const contentByKey = new Map(
+  manifest.assessmentContent
+    .filter((item) => item.lessonId === lessonId)
+    .map((item) => [`${item.assessmentId}:${item.itemId}`, item]),
+);
+
+function renderedContent(
+  raw: string,
+  segments: readonly ContentSegment[] | undefined,
+): MixedContentNode[] {
+  if (!segments) return [{ type: 'text', value: raw }];
+  return segments.map((segment) =>
+    segment.type === 'text'
+      ? segment
+      : { type: 'math', nodes: renderNotationMath(segment.latex) },
+  );
+}
 ---
 
 {
-  entries.map((entry) => (
-    <AssessmentRunner
-      client:visible
-      assessmentId={entry.data.id}
-      title={entry.data.title}
-      items={entry.data.items}
-    />
+  entries.map(({ entry, number, anchorId }) => (
+    <>
+      <div
+        class="sl-heading-wrapper level-h2 assessment-heading-wrapper"
+        data-collapsible="true"
+        data-default-open="true"
+      >
+        <h2 id={anchorId}>
+          <span class="assessment-heading-number">Knowledge check {number}</span>
+          <span aria-hidden="true"> — </span>
+          {entry.data.title}
+        </h2>
+        <a
+          class="sl-anchor-link"
+          href={`#${anchorId}`}
+          aria-label={`Knowledge check ${number} titled “${entry.data.title}”`}
+        >
+          <span aria-hidden="true" class="sl-anchor-icon">
+            <svg width="16" height="16" viewBox="0 0 24 24" fill="currentColor">
+              <path d="m12.11 15.39-3.88 3.88a2.52 2.52 0 0 1-3.5 0 2.47 2.47 0 0 1 0-3.5l3.88-3.88a1 1 0 1 0-1.42-1.42l-3.88 3.89a4.48 4.48 0 0 0 6.33 6.33l3.89-3.88a1 1 0 0 0-1.42-1.42m8.58-12.08a4.49 4.49 0 0 0-6.33 0l-3.89 3.88a1 1 0 1 0 1.42 1.42l3.88-3.88a2.52 2.52 0 0 1 3.5 0 2.47 2.47 0 0 1 0 3.5l-3.88 3.88a1 1 0 0 0 0 1.42 1 1 0 0 0 1.42 0l3.88-3.89a4.49 4.49 0 0 0 0-6.33M8.83 15.17a1 1 0 0 0 .71.29 1 1 0 0 0 .71-.29l4.92-4.92a1 1 0 1 0-1.42-1.42l-4.92 4.92a1 1 0 0 0 0 1.42" />
+            </svg>
+          </span>
+          <span class="sr-only" data-pagefind-ignore="true">
+            Link to knowledge check {number}: {entry.data.title}
+          </span>
+        </a>
+      </div>
+      <AssessmentRunner
+        client:visible
+        assessmentId={entry.data.id}
+        title={entry.data.title}
+        labelledBy={anchorId}
+        items={entry.data.items.map((item: (typeof entry.data.items)[number]) => {
+          const content = contentByKey.get(`${entry.data.id}:${item.id}`);
+          return {
+            ...item,
+            promptContent: renderedContent(
+              item.prompt,
+              content?.promptSegments,
+            ),
+            explanationContent: renderedContent(
+              item.explanation,
+              content?.explanationSegments,
+            ),
+          };
+        })}
+      />
+    </>
   ))
 }

package/src/components/assessments/RenderedContent.tsx

@@ -0,0 +1,55 @@
+import { Fragment } from 'react';
+import type {
+  MixedContentNode,
+  SafeMathNode,
+} from '../notation/render-notation-math';
+import { toReactProps } from '../notation/safe-math-to-react';
+
+/**
+ * The React-side twin of `SafeMathNode.astro`: walk the same structured,
+ * pre-sanitized tree and emit real elements via `React.createElement`
+ * (`h`/JSX below), never `dangerouslySetInnerHTML` — no HTML string crosses
+ * into this island any more than it does into an Astro page.
+ */
+function SafeMath({ node }: { node: SafeMathNode }) {
+  if (node.type === 'text') return <>{node.value}</>;
+  const Tag = node.tagName as keyof JSX.IntrinsicElements;
+  return (
+    <Tag {...toReactProps(node.properties)}>
+      {node.children.map((child, index) => (
+        // eslint-disable-next-line react/no-array-index-key -- a static, sanitized render tree; index is stable across renders
+        <SafeMath key={index} node={child} />
+      ))}
+    </Tag>
+  );
+}
+
+/**
+ * Render an assessment `prompt` / `explanation` after `AssessmentSet.astro`
+ * has split, resolved, and rendered it (`manifest.assessmentContent` ->
+ * `renderNotationMath`): plain text runs verbatim, each math run through
+ * {@link SafeMath}.
+ */
+export default function RenderedContent({
+  content,
+}: {
+  content: readonly MixedContentNode[];
+}) {
+  return (
+    <>
+      {content.map((segment, index) =>
+        segment.type === 'text' ? (
+          // eslint-disable-next-line react/no-array-index-key -- a static, ordered segment list
+          <Fragment key={index}>{segment.value}</Fragment>
+        ) : (
+          <span key={index} className="notation-math">
+            {segment.nodes.map((node, nodeIndex) => (
+              // eslint-disable-next-line react/no-array-index-key -- a static, sanitized render tree
+              <SafeMath key={nodeIndex} node={node} />
+            ))}
+          </span>
+        ),
+      )}
+    </>
+  );
+}

package/src/components/assessments/assessment-randomization.ts

@@ -0,0 +1,16 @@
+/** Return a shuffled copy without changing the authored answer array. */
+export function shuffled<T>(
+  values: readonly T[],
+  random: () => number = Math.random,
+): T[] {
+  const result = [...values];
+  for (let index = result.length - 1; index > 0; index--) {
+    const draw = random();
+    const bounded = Number.isFinite(draw)
+      ? Math.min(Math.max(draw, 0), 1 - Number.EPSILON)
+      : 0;
+    const swapIndex = Math.floor(bounded * (index + 1));
+    [result[index], result[swapIndex]] = [result[swapIndex], result[index]];
+  }
+  return result;
+}