explico 0.1.0

package/src/components/notation/render-notation-math.ts

@@ -0,0 +1,223 @@
+import rehypeKatex from 'rehype-katex';
+import { createNotationKatexOptions } from '../../reference/katex-options.mjs';
+
+interface HastText {
+  type: 'text';
+  value: string;
+}
+
+interface HastElement {
+  type: 'element';
+  tagName: string;
+  properties: Record<string, unknown>;
+  children: HastNode[];
+}
+
+type HastNode = HastText | HastElement;
+
+interface HastRoot {
+  type: 'root';
+  children: HastNode[];
+}
+
+export type SafeMathNode =
+  | { type: 'text'; value: string }
+  | {
+      type: 'element';
+      tagName: string;
+      properties: Readonly<Record<string, string>>;
+      children: readonly SafeMathNode[];
+    };
+
+const allowedTags = new Set([
+  'annotation',
+  'math',
+  'menclose',
+  'mfrac',
+  'mi',
+  'mn',
+  'mo',
+  'mover',
+  'mpadded',
+  'mphantom',
+  'mroot',
+  'mrow',
+  'mspace',
+  'msqrt',
+  'mstyle',
+  'msub',
+  'msubsup',
+  'msup',
+  'mtable',
+  'mtd',
+  'mtext',
+  'mtr',
+  'munder',
+  'munderover',
+  'semantics',
+  'span',
+  'svg',
+  'path',
+  'line',
+]);
+
+const simpleAttributeNames = new Set([
+  'accent',
+  'accentunder',
+  'columnalign',
+  'columnspacing',
+  'displaystyle',
+  'fence',
+  'height',
+  'lspace',
+  'mathvariant',
+  'preserveaspectratio',
+  'rowspacing',
+  'rspace',
+  'scriptlevel',
+  'separator',
+  'stretchy',
+  'viewbox',
+  'width',
+]);
+
+const safeAttributeValue = /^[ A-Za-z0-9+.,()\-/%]*$/;
+const safeClassName = /^[A-Za-z0-9_-]+$/;
+const safeStyle = /^(?:[a-z-]+:[ A-Za-z0-9+.,()\-/%]*;)*$/;
+const safePathData = /^[\sA-Za-z0-9+.,\-]*$/;
+const unsafeExtensionCommand =
+  /\\(?:href|url|includegraphics|htmlClass|htmlData|htmlId|htmlStyle)\b/;
+
+function attributeValue(value: unknown, propertyName: string): string {
+  if (typeof value === 'boolean') return String(value);
+  if (typeof value === 'number' && Number.isFinite(value)) return String(value);
+  if (typeof value !== 'string' || !safeAttributeValue.test(value)) {
+    throw new Error(`Unsafe KaTeX ${propertyName} value.`);
+  }
+  return value;
+}
+
+function safeProperties(
+  element: HastElement,
+): Readonly<Record<string, string>> {
+  const properties: Record<string, string> = {};
+
+  for (const [name, value] of Object.entries(element.properties)) {
+    if (name === 'className') {
+      if (
+        !Array.isArray(value) ||
+        !value.every(
+          (className) =>
+            typeof className === 'string' && safeClassName.test(className),
+        )
+      ) {
+        throw new Error('Unsafe KaTeX class list.');
+      }
+      properties.class = value.join(' ');
+      continue;
+    }
+
+    if (name === 'ariaHidden' && value === 'true') {
+      properties['aria-hidden'] = 'true';
+      continue;
+    }
+
+    if (name === 'encoding' && value === 'application/x-tex') {
+      properties.encoding = value;
+      continue;
+    }
+
+    if (
+      name === 'xmlns' &&
+      (value === 'http://www.w3.org/1998/Math/MathML' ||
+        value === 'http://www.w3.org/2000/svg')
+    ) {
+      properties.xmlns = value;
+      continue;
+    }
+
+    if (
+      name === 'style' &&
+      typeof value === 'string' &&
+      safeStyle.test(value) &&
+      !/(?:expression|url)\s*\(/i.test(value)
+    ) {
+      properties.style = value;
+      continue;
+    }
+
+    if (name === 'd' && typeof value === 'string' && safePathData.test(value)) {
+      properties.d = value;
+      continue;
+    }
+
+    const normalizedName = name.toLowerCase();
+    if (simpleAttributeNames.has(normalizedName)) {
+      const outputName =
+        normalizedName === 'viewbox'
+          ? 'viewBox'
+          : normalizedName === 'preserveaspectratio'
+            ? 'preserveAspectRatio'
+            : normalizedName;
+      properties[outputName] = attributeValue(value, name);
+      continue;
+    }
+
+    throw new Error(`Unexpected KaTeX property: ${name}.`);
+  }
+
+  return Object.freeze(properties);
+}
+
+function sanitizeNode(node: HastNode): SafeMathNode {
+  if (node.type === 'text') {
+    return Object.freeze({ type: 'text', value: node.value });
+  }
+
+  if (node.type !== 'element' || !allowedTags.has(node.tagName)) {
+    throw new Error(`Unexpected KaTeX node: ${node.type}.`);
+  }
+
+  return Object.freeze({
+    type: 'element',
+    tagName: node.tagName,
+    properties: safeProperties(node),
+    children: Object.freeze(node.children.map(sanitizeNode)),
+  });
+}
+
+/**
+ * Render repository-authored LaTeX through the same build-time KaTeX adapter
+ * as lesson math, then expose a constrained structured tree to Astro. No HTML
+ * string crosses the component boundary.
+ */
+export function renderNotationMath(latex: string): readonly SafeMathNode[] {
+  if (latex.trim().length === 0) {
+    throw new Error('Notation LaTeX must not be empty.');
+  }
+  if (unsafeExtensionCommand.test(latex)) {
+    throw new Error('Notation LaTeX cannot use a trust-requiring extension.');
+  }
+
+  const root: HastRoot = {
+    type: 'root',
+    children: [
+      {
+        type: 'element',
+        tagName: 'code',
+        properties: { className: ['math-inline'] },
+        children: [{ type: 'text', value: latex }],
+      },
+    ],
+  };
+
+  const transform = rehypeKatex(createNotationKatexOptions());
+  const file = {
+    message(message: unknown): never {
+      throw new Error(String(message));
+    },
+  } as unknown as Parameters<typeof transform>[1];
+
+  transform(root as unknown as Parameters<typeof transform>[0], file);
+  return Object.freeze(root.children.map(sanitizeNode));
+}

package/src/components/starlight/EquationEnhancer.astro

@@ -0,0 +1,72 @@
+---
+/**
+ * Progressive enhancement for keyed equations (Step D7).
+ *
+ * The no-JS baseline is complete: `remark-notation` emits a real `id="eq-<key>"`
+ * container, a focusable number `<a>`, and `[[eq:key]]` 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:
+ *  - re-triggering the highlight when the same `#eq-…` is activated again;
+ *  - a smooth, header-aware scroll on an in-page jump;
+ *  - moving keyboard focus onto the equation so screen-reader users land on it.
+ *
+ * Everything here is gated on `prefers-reduced-motion` and degrades to the
+ * native anchor behaviour if it throws.
+ */
+---
+
+<script>
+  (() => {
+    const root = document.querySelector('.sl-markdown-content');
+    if (!root) return;
+
+    const reduce = window.matchMedia('(prefers-reduced-motion: reduce)');
+
+    const activate = (target: HTMLElement | null, doScroll: boolean) => {
+      if (!target) return;
+      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('a.equation-ref, a.keyed-equation__number');
+      if (!link) return;
+      const href = link.getAttribute('href') || '';
+      if (!href.startsWith('#eq-')) return; // cross-page: let the browser navigate
+      const target = document.getElementById(href.slice(1));
+      if (!target) return;
+      event.preventDefault();
+      if (location.hash !== href) history.pushState(null, '', href);
+      activate(target, true);
+    });
+
+    window.addEventListener('hashchange', () => {
+      if (!location.hash.startsWith('#eq-')) return;
+      activate(document.getElementById(location.hash.slice(1)), false);
+    });
+
+    if (location.hash.startsWith('#eq-')) {
+      activate(document.getElementById(location.hash.slice(1)), true);
+    }
+  })();
+</script>

package/src/components/starlight/LayoutHeader.astro

@@ -0,0 +1,102 @@
+---
+import DefaultHeader from '@astrojs/starlight/components/Header.astro';
+---
+
+<DefaultHeader />
+
+<script>
+  import { createBrowserPreferenceStore } from '../../session/PreferenceStore';
+
+  type LayoutRegion = 'navigation' | 'contents';
+
+  const regions: Record<
+    LayoutRegion,
+    {
+      attribute: string;
+      storageKey: string;
+      peekSuppressedAttribute: string;
+      panelSelector: string;
+      shownLabel: string;
+      hiddenLabel: string;
+    }
+  > = {
+    navigation: {
+      attribute: 'data-navigation-hidden',
+      storageKey: 'credit-playground:layout:navigation-hidden',
+      peekSuppressedAttribute: 'data-navigation-peek-suppressed',
+      panelSelector: '.sidebar-pane',
+      shownLabel: 'Hide navigation',
+      hiddenLabel: 'Show navigation',
+    },
+    contents: {
+      attribute: 'data-page-sidebar-hidden',
+      storageKey: 'credit-playground:layout:contents-hidden',
+      peekSuppressedAttribute: 'data-page-sidebar-peek-suppressed',
+      panelSelector: '.right-sidebar',
+      shownLabel: 'Hide page contents',
+      hiddenLabel: 'Show page contents',
+    },
+  };
+
+  const root = document.documentElement;
+
+  // 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.
+  const preferences = createBrowserPreferenceStore();
+
+  function readPreference(storageKey: string): boolean {
+    return preferences.get(storageKey) === 'true';
+  }
+
+  function writePreference(storageKey: string, hidden: boolean): void {
+    preferences.set(storageKey, String(hidden));
+  }
+
+  function applyState(
+    button: HTMLButtonElement,
+    region: LayoutRegion,
+    hidden: boolean,
+  ): void {
+    const settings = regions[region];
+    const label = hidden ? settings.hiddenLabel : settings.shownLabel;
+    root.toggleAttribute(settings.attribute, hidden);
+    if (!hidden) root.removeAttribute(settings.peekSuppressedAttribute);
+    button.setAttribute('aria-expanded', String(!hidden));
+    button.setAttribute('aria-label', label);
+    button.title = label;
+  }
+
+  document
+    .querySelectorAll<HTMLButtonElement>('[data-layout-toggle]')
+    .forEach((button) => {
+      const region = button.dataset.layoutToggle as LayoutRegion;
+      const settings = regions[region];
+      if (!settings) return;
+
+      applyState(button, region, readPreference(settings.storageKey));
+      button.removeAttribute('hidden');
+      button.addEventListener('click', (event) => {
+        const hidden = !root.hasAttribute(settings.attribute);
+        applyState(button, region, hidden);
+        writePreference(settings.storageKey, hidden);
+
+        // A pointer click should leave a newly collapsed rail collapsed even
+        // though the pointer was inside the full-width panel when clicked.
+        if (hidden && event.detail > 0) {
+          root.setAttribute(settings.peekSuppressedAttribute, '');
+          button.blur();
+
+          const panel = document.querySelector(settings.panelSelector);
+          const clearSuppression = () =>
+            root.removeAttribute(settings.peekSuppressedAttribute);
+          panel?.addEventListener('pointerleave', clearSuppression, {
+            once: true,
+          });
+          window.setTimeout(() => {
+            if (!panel?.matches(':hover')) clearSuppression();
+          }, 180);
+        }
+      });
+    });
+</script>

package/src/components/starlight/LayoutPageSidebar.astro

@@ -0,0 +1,33 @@
+---
+import { Icon } from '@astrojs/starlight/components';
+import DefaultPageSidebar from '@astrojs/starlight/components/PageSidebar.astro';
+---
+
+<div
+  id="starlight__page-sidebar"
+  class="layout-page-sidebar"
+  data-layout-panel="contents"
+>
+  <button
+    class="layout-edge-toggle layout-contents-toggle"
+    type="button"
+    aria-controls="starlight__page-sidebar-content"
+    aria-expanded="true"
+    data-layout-toggle="contents"
+    hidden
+  >
+    <Icon
+      name="right-caret"
+      class="layout-edge-icon layout-edge-icon-hide"
+      size="1rem"
+    />
+    <Icon
+      name="left-caret"
+      class="layout-edge-icon layout-edge-icon-restore"
+      size="1rem"
+    />
+  </button>
+  <div id="starlight__page-sidebar-content" class="layout-page-sidebar-content">
+    <DefaultPageSidebar />
+  </div>
+</div>

package/src/components/starlight/LayoutSidebar.astro

@@ -0,0 +1,29 @@
+---
+import { Icon } from '@astrojs/starlight/components';
+import DefaultSidebar from '@astrojs/starlight/components/Sidebar.astro';
+---
+
+<div class="layout-navigation-panel" data-layout-panel="navigation">
+  <button
+    class="layout-edge-toggle layout-navigation-toggle"
+    type="button"
+    aria-controls="starlight__navigation-content"
+    aria-expanded="true"
+    data-layout-toggle="navigation"
+    hidden
+  >
+    <Icon
+      name="left-caret"
+      class="layout-edge-icon layout-edge-icon-hide"
+      size="1rem"
+    />
+    <Icon
+      name="right-caret"
+      class="layout-edge-icon layout-edge-icon-restore"
+      size="1rem"
+    />
+  </button>
+  <div id="starlight__navigation-content" class="layout-navigation-content">
+    <DefaultSidebar />
+  </div>
+</div>

package/src/components/starlight/LessonFooter.astro

@@ -0,0 +1,58 @@
+---
+/**
+ * Starlight only allows one `Footer` override, so this component composes the
+ * page-notation layer and the source-citation layer ahead of Starlight's own
+ * footer. Both layers are optional progressive enhancements over static
+ * markup that the remark adapters and the content collections already emit.
+ *
+ * The resolved notation bundle comes from the one compiler manifest (Phase
+ * D5); this component never rebuilds the registry.
+ */
+import DefaultFooter from '@astrojs/starlight/components/Footer.astro';
+import { loadManifest } from '../../compiler/manifest';
+import {
+  isLessonSlug,
+  lessonIdFromSlug,
+} from '../../compiler/lesson-derivation';
+import NotationLayer, {
+  type NotationLayerDefinition,
+} from '../notation/NotationLayer.astro';
+import CitationLayer from '../citation/CitationLayer.astro';
+import EquationEnhancer from './EquationEnhancer.astro';
+
+// `lessonId` is no longer authored (Phase C2); derive it from the route.
+const routeSlug = Astro.locals.starlightRoute.entry.id;
+const lessonId = isLessonSlug(routeSlug)
+  ? lessonIdFromSlug(routeSlug)
+  : undefined;
+
+const glossaryBase = `${import.meta.env.BASE_URL.replace(/\/$/, '')}/glossary/`;
+
+const definitions: NotationLayerDefinition[] = [];
+if (lessonId) {
+  const manifest = await loadManifest();
+  const lesson = manifest.lessons.find((entry) => entry.id === lessonId);
+  for (const definition of lesson?.notation.definitions ?? []) {
+    definitions.push({
+      key: definition.key,
+      notation: definition.notation,
+      label: definition.label,
+      summary: definition.summary,
+      formula: definition.formula,
+      units: definition.units,
+      seeAlso: definition.seeAlso,
+      editorialStatus: definition.editorialStatus,
+      scope: definition.scope,
+      href:
+        definition.scope === 'shared'
+          ? `${glossaryBase}#notation-${definition.key}`
+          : `#notation-${definition.key}`,
+    });
+  }
+}
+---
+
+<NotationLayer definitions={definitions} />
+{lessonId && <CitationLayer />}
+{lessonId && <EquationEnhancer />}
+<DefaultFooter />