explico 0.1.0

package/src/compiler/resolution-report.ts

@@ -0,0 +1,150 @@
+/**
+ * The committed per-lesson resolution report (Step D6 (d)).
+ *
+ * `compileManifest()` already resolves every `[[key]]` / `\explain{key}`
+ * occurrence to a definition, scope, and source span
+ * (`manifest.lessons[].notation.resolution`). That lives in the git-ignored
+ * `.generated/manifest.json`, so this module projects it into
+ * `resolution/<lessonId>.notation.json` — one small, diff-checkable file per
+ * lesson — plus `resolution/consistency-report.json` for the Tier-3 corpus
+ * checks. `pnpm validate:content` regenerates them and **fails if a committed
+ * file is stale**, so a drift between content and the checked-in report cannot
+ * pass CI unnoticed.
+ *
+ * The reports are deterministic: keys are sorted recursively, rows follow the
+ * manifest's stable ordering, and nothing records a timestamp or a content
+ * hash — a file changes only when a resolution or a finding changes.
+ */
+
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { join } from 'node:path';
+
+import {
+  consistencyCounts,
+  type ConsistencyDiagnostic,
+} from '../reference/consistency';
+import { MANIFEST_SCHEMA_VERSION, type Manifest } from './manifest';
+
+const REPOSITORY_ROOT = process.cwd();
+const RESOLUTION_DIR = join(REPOSITORY_ROOT, 'build', 'resolution');
+/** Repo-relative prefix for the map keys and the stale-path messages (Phase F). */
+const RESOLUTION_PREFIX = 'build/resolution/';
+const CONSISTENCY_FILE = 'consistency-report.json';
+
+/** JSON with recursively sorted object keys and a trailing newline. */
+function stableJson(value: unknown): string {
+  const sortKeys = (node: unknown): unknown => {
+    if (Array.isArray(node)) return node.map(sortKeys);
+    if (node && typeof node === 'object') {
+      return Object.fromEntries(
+        Object.keys(node as Record<string, unknown>)
+          .sort()
+          .map((key) => [
+            key,
+            sortKeys((node as Record<string, unknown>)[key]),
+          ]),
+      );
+    }
+    return node;
+  };
+  return `${JSON.stringify(sortKeys(value), null, 2)}\n`;
+}
+
+/** `{ 'build/resolution/foo.notation.json': '…', … }` — the full expected tree. */
+export function buildResolutionReports(
+  manifest: Manifest,
+): Map<string, string> {
+  const files = new Map<string, string>();
+
+  const localKeysByLesson = new Map<string, string[]>();
+  for (const definition of manifest.notation.definitions) {
+    if (definition.kind !== 'local') continue;
+    const list = localKeysByLesson.get(definition.lessonId) ?? [];
+    list.push(definition.key);
+    localKeysByLesson.set(definition.lessonId, list);
+  }
+
+  for (const lesson of manifest.lessons) {
+    files.set(
+      `${RESOLUTION_PREFIX}${lesson.id}.notation.json`,
+      stableJson({
+        schemaVersion: MANIFEST_SCHEMA_VERSION,
+        lesson: lesson.id,
+        file: lesson.file,
+        localKeys: [...(localKeysByLesson.get(lesson.id) ?? [])].sort(),
+        references: lesson.notation.resolution,
+      }),
+    );
+  }
+
+  files.set(
+    `${RESOLUTION_PREFIX}${CONSISTENCY_FILE}`,
+    stableJson({
+      schemaVersion: MANIFEST_SCHEMA_VERSION,
+      generatedBy: 'pnpm validate:content',
+      counts: consistencyCounts(manifest.diagnostics.consistency),
+      diagnostics: manifest.diagnostics
+        .consistency as readonly ConsistencyDiagnostic[],
+    }),
+  );
+
+  return files;
+}
+
+export interface ResolutionReportSync {
+  readonly written: number;
+  /** Repo-relative paths that were out of date (created, changed, or removed). */
+  readonly stale: readonly string[];
+}
+
+/**
+ * Write every expected report and prune orphans. Returns the paths that did not
+ * already match on disk — the caller turns a non-empty list into a build
+ * failure so the checked-in reports stay honest.
+ */
+export function syncResolutionReports(
+  manifest: Manifest,
+): ResolutionReportSync {
+  const expected = buildResolutionReports(manifest);
+  mkdirSync(RESOLUTION_DIR, { recursive: true });
+
+  const onDisk = new Set(
+    existsSync(RESOLUTION_DIR)
+      ? readdirSync(RESOLUTION_DIR).filter((name) => name.endsWith('.json'))
+      : [],
+  );
+  const stale: string[] = [];
+
+  for (const [relPath, content] of [...expected].sort(([a], [b]) =>
+    a.localeCompare(b),
+  )) {
+    const name = relPath.slice(RESOLUTION_PREFIX.length);
+    const absolute = join(RESOLUTION_DIR, name);
+    onDisk.delete(name);
+    const current = existsSync(absolute)
+      ? readFileSync(absolute, 'utf8')
+      : undefined;
+    if (current !== content) {
+      writeFileSync(absolute, content);
+      stale.push(
+        `${relPath} (${current === undefined ? 'missing' : 'changed'})`,
+      );
+    }
+  }
+
+  for (const orphan of [...onDisk].sort()) {
+    rmSync(join(RESOLUTION_DIR, orphan));
+    stale.push(`${RESOLUTION_PREFIX}${orphan} (stale, removed)`);
+  }
+
+  return { written: expected.size, stale };
+}
+
+export { RESOLUTION_DIR };

package/src/components/CurriculumMap.astro

@@ -0,0 +1,208 @@
+---
+import { getCollection } from 'astro:content';
+import { loadManifest } from '../compiler/manifest';
+import { isLessonSlug, lessonIdFromSlug } from '../compiler/lesson-derivation';
+
+const [tracks, docs, competencies, manifest] = await Promise.all([
+  getCollection('tracks'),
+  getCollection('docs'),
+  getCollection('competencies'),
+  loadManifest(),
+]);
+// `requires` / `assessments` are derived (Phase C2); read them from the one
+// compiler manifest, and the doc entry for title / description / slug.
+const docEntryById = new Map(
+  docs
+    .filter((entry) => isLessonSlug(entry.id))
+    .map((entry) => [lessonIdFromSlug(entry.id), entry]),
+);
+const lessonById = new Map(
+  manifest.lessons.map((lesson) => [lesson.id, lesson]),
+);
+const competencyById = new Map(
+  competencies.map((entry) => [entry.data.id, entry.data]),
+);
+---
+
+{
+  tracks.map(({ data: track }) => (
+    <section class="track" aria-labelledby={`track-${track.id}`}>
+      <header>
+        <h2 id={`track-${track.id}`}>{track.title}</h2>
+        <p>{track.description}</p>
+        <p>
+          <strong>Audience:</strong> {track.audience}
+        </p>
+        <div class="entry-assumptions">
+          <strong>Entry assumptions:</strong>
+          <ul>
+            {track.entryAssumptions.map((assumption) => (
+              <li>{assumption}</li>
+            ))}
+          </ul>
+        </div>
+      </header>
+
+      <ol class="lesson-sequence">
+        {track.lessons.map((lessonId, index) => {
+          const lesson = lessonById.get(lessonId);
+          const entry = docEntryById.get(lessonId);
+          if (!lesson || !entry) return null;
+          return (
+            <li>
+              <article>
+                <p class="step">Lesson {index + 1}</p>
+                <h3>
+                  <a
+                    href={`${import.meta.env.BASE_URL.replace(/\/$/, '')}/${entry.id}/`}
+                  >
+                    {entry.data.title}
+                  </a>
+                </h3>
+                <code>{lessonId}</code>
+                <p>{entry.data.description}</p>
+
+                <dl>
+                  <div>
+                    <dt>Requires</dt>
+                    <dd>
+                      {lesson.requires.length > 0
+                        ? lesson.requires.map((id) => (
+                            <span title={competencyById.get(id)?.title}>
+                              <code>{id}</code>
+                            </span>
+                          ))
+                        : 'Track entry assumptions only'}
+                    </dd>
+                  </div>
+                  <div>
+                    <dt>Teaches</dt>
+                    <dd>
+                      {lesson.teaches.map((id) => (
+                        <span title={competencyById.get(id)?.title}>
+                          <code>{id}</code>
+                        </span>
+                      ))}
+                    </dd>
+                  </div>
+                  <div>
+                    <dt>Evidence</dt>
+                    <dd>
+                      {lesson.assessments.map((id) => (
+                        <code>{id}</code>
+                      ))}
+                    </dd>
+                  </div>
+                </dl>
+              </article>
+            </li>
+          );
+        })}
+      </ol>
+    </section>
+  ))
+}
+
+<section aria-labelledby="competency-catalog">
+  <h2 id="competency-catalog">Atomic competency catalog</h2>
+  <p>
+    Each competency has an explicit prerequisite list and an evidence policy.
+    The build rejects unknown references, cycles, invalid lesson ordering, and
+    insufficient assessment coverage.
+  </p>
+  <ol class="competency-map">
+    {
+      competencies
+        .sort((left, right) => left.data.id.localeCompare(right.data.id))
+        .map(({ data }) => (
+          <li>
+            <strong>{data.title}</strong>
+            <br />
+            <code>{data.id}</code>
+            <p>{data.outcome}</p>
+            {data.prerequisites.length > 0 ? (
+              <small>
+                Requires: <code>{data.prerequisites.join(', ')}</code>
+              </small>
+            ) : (
+              <small>Entry competency: no declared prerequisites.</small>
+            )}
+          </li>
+        ))
+    }
+  </ol>
+</section>
+
+<style>
+  .track > header {
+    margin-block-end: 1.25rem;
+  }
+
+  .entry-assumptions ul {
+    margin-block: 0.35rem 0;
+  }
+
+  .lesson-sequence,
+  .competency-map {
+    display: grid;
+    gap: 1rem;
+    padding-inline-start: 1.5rem;
+  }
+
+  .lesson-sequence > li::marker {
+    color: var(--sl-color-accent-high);
+    font-weight: 700;
+  }
+
+  .lesson-sequence article,
+  .competency-map li {
+    padding: 1rem;
+    border: 1px solid var(--sl-color-gray-5);
+    border-radius: 0.55rem;
+    background: var(--sl-color-gray-7);
+  }
+
+  .lesson-sequence h3,
+  .lesson-sequence p,
+  .competency-map p {
+    margin-block: 0.4rem;
+  }
+
+  .step {
+    color: var(--sl-color-gray-3);
+    font-size: var(--sl-text-sm);
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.04em;
+  }
+
+  .lesson-sequence dl {
+    display: grid;
+    gap: 0.7rem;
+    margin-block: 1rem 0;
+  }
+
+  .lesson-sequence dl div {
+    display: grid;
+    grid-template-columns: minmax(5rem, 0.25fr) 1fr;
+    gap: 0.75rem;
+  }
+
+  .lesson-sequence dt {
+    font-weight: 700;
+  }
+
+  .lesson-sequence dd {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.35rem 0.6rem;
+    margin: 0;
+  }
+
+  @media (max-width: 36rem) {
+    .lesson-sequence dl div {
+      grid-template-columns: 1fr;
+      gap: 0.1rem;
+    }
+  }
+</style>

package/src/components/HoverPanel.astro

@@ -0,0 +1,67 @@
+---
+/**
+ * Shared hover/pin panel shell for the notation and citation layers.
+ *
+ * This component contributes only the fixed-position `<aside>` container and
+ * its base styling. The interaction engine — side selection, the sticky-header
+ * and article-column clamps, pin, Escape, and outside-close — lives once in
+ * `./hover-panel.ts` and is wired from each layer's island script. The panel's
+ * inner fields are slotted by the layer that owns them.
+ *
+ * Extra attributes (e.g. `data-notation-panel`, `data-citation-panel`) are
+ * forwarded to the `<aside>` so each layer keeps the hook its tests and pin
+ * controls already reference.
+ */
+export interface Props {
+  /** Element id — pin controls point `aria-controls` at it. */
+  id: string;
+  /** Accessible name for the region. */
+  label: string;
+  class?: string;
+}
+
+const { id, label, class: className, ...rest } = Astro.props;
+---
+
+<aside
+  class:list={['hover-panel', className]}
+  id={id}
+  role="region"
+  aria-label={label}
+  aria-live="polite"
+  aria-atomic="true"
+  hidden
+  {...rest}
+>
+  <slot />
+</aside>
+
+<style>
+  @layer starlight.components {
+    .hover-panel {
+      position: fixed;
+      z-index: 100;
+      /* The panel is an <aside> in the content flow; a stray cascade margin
+         would offset a position:fixed box from its computed `top`, so the
+         JS placement (which clears display equations) must start from zero. */
+      margin: 0;
+      width: min(23rem, calc(100vw - 1.5rem));
+      overflow: 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-sm);
+    }
+
+    /* Slotted fields carry the owning layer's scope, not this component's, so
+       the descendant match must be global. */
+    .hover-panel :global(:focus-visible) {
+      outline: 3px solid var(--sl-color-accent);
+      outline-offset: 2px;
+    }
+  }
+</style>