explico 0.1.0

package/src/reference/render-lab-math.ts

@@ -0,0 +1,99 @@
+import katex from 'katex';
+import { resolveMathGlyphs } from './math-glyphs.mjs';
+import { createNotationKatexOptions } from './katex-options.mjs';
+
+export interface LabMathScopeDefinition {
+  readonly key: string;
+  readonly notation: string;
+}
+
+export interface RenderedLabMath {
+  /** KaTeX HTML+MathML with `data-notation-key` and `data-lab-slot` spans. */
+  readonly html: string;
+  /** Slot names, in template order, the island must supply at runtime. */
+  readonly slots: readonly string[];
+  /** Notation keys the template resolved to, for diagnostics. */
+  readonly keys: readonly string[];
+}
+
+interface BindResult {
+  latex: string;
+  bindings: ReadonlyArray<{ key: string }>;
+  unresolved: ReadonlyArray<{ token: string; start: number }>;
+}
+
+// `\slot{name}{fallback}` — `name` is a lab-slot id, `fallback` may contain one
+// level of nested braces (for KaTeX digit grouping such as `1{,}000`).
+const SLOT_PATTERN = /\\slot\{([a-z][a-z0-9]*)\}\{((?:[^{}]|\{[^{}]*\})*)\}/g;
+
+// A decimal literal is invisible to the notation binder (a number is never an
+// identifier), survives `injectScopeBindings` verbatim, and will not collide
+// with authored content.
+const sentinelFor = (index: number): string => `909909${index}.909909`;
+
+/**
+ * Compile a developer-authored lab math template the same way lesson `$$`
+ * math is compiled: every identifier must resolve to a notation key in the
+ * page's scope or this throws. Slots are set aside during binding and restored
+ * as inert `data-lab-slot` spans the interactive island rewrites at runtime.
+ */
+export function renderLabMath(
+  template: string,
+  scope: readonly LabMathScopeDefinition[],
+): RenderedLabMath {
+  const slots: Array<{ name: string; fallback: string }> = [];
+  const forBinding = template.replace(
+    SLOT_PATTERN,
+    (_match: string, name: string, fallback: string) => {
+      const sentinel = sentinelFor(slots.length);
+      slots.push({ name, fallback });
+      return ` ${sentinel} `;
+    },
+  );
+
+  let result: BindResult;
+  try {
+    result = resolveMathGlyphs(forBinding, [...scope]) as BindResult;
+  } catch (error) {
+    throw new Error(
+      `Lab math failed to compile: ${
+        error instanceof Error ? error.message : String(error)
+      }\n  template: ${template.trim()}`,
+    );
+  }
+
+  if (result.unresolved.length > 0) {
+    const list = result.unresolved.map(({ token }) => `"${token}"`).join(', ');
+    throw new Error(
+      `Lab math uses undefined notation ${list}. Every symbol must resolve to ` +
+        `a notation entry in this page's glyph scope (a [[key]] reference or ` +
+        `notation.local).\n  template: ${template.trim()}`,
+    );
+  }
+
+  let bound = result.latex;
+  slots.forEach(({ name, fallback }, index) => {
+    const sentinel = sentinelFor(index);
+    if (!bound.includes(sentinel)) {
+      throw new Error(
+        `Lab math slot "${name}" was lost during notation binding; keep slots ` +
+          `out of subscripts and other reindexed positions.\n  template: ${template.trim()}`,
+      );
+    }
+    bound = bound.replace(
+      sentinel,
+      `\\htmlData{lab-slot=${name}}{${fallback}}`,
+    );
+  });
+
+  const html = katex.renderToString(
+    bound,
+    createNotationKatexOptions({ displayMode: true }),
+  );
+
+  return {
+    html,
+    slots: slots.map(({ name }) => name),
+    keys: [...new Set(result.bindings.map(({ key }) => key))],
+  };
+}

package/src/reference/types.ts

@@ -0,0 +1,182 @@
+export type EditorialStatus = 'draft' | 'in-review' | 'reviewed';
+
+export interface SourceSpan {
+  readonly file: string;
+  readonly line?: number;
+  readonly column?: number;
+  readonly endLine?: number;
+  readonly endColumn?: number;
+}
+
+export type NotationAlignment =
+  | {
+      readonly kind: 'competency';
+      readonly introducedByCompetency: string;
+      readonly introducedInLesson: string;
+    }
+  | {
+      readonly kind: 'general';
+      readonly rationale: string;
+    };
+
+export type NotationReferenceKind = 'prose' | 'math' | 'definition';
+
+export interface NotationReferenceInput {
+  readonly key: string;
+  readonly kind: NotationReferenceKind;
+  readonly source: SourceSpan;
+}
+
+export interface SharedNotationDefinitionInput {
+  readonly key: string;
+  readonly notation: string;
+  readonly label: string;
+  readonly summary: string;
+  readonly aliases: readonly string[];
+  readonly domain: string;
+  readonly formula?: string;
+  readonly units?: string;
+  readonly sources: readonly string[];
+  readonly seeAlso: readonly string[];
+  readonly alignment: NotationAlignment;
+  readonly status: EditorialStatus;
+  readonly aiAssisted: boolean;
+  readonly body: string;
+  /** References harvested from the Markdown body. */
+  readonly references: readonly NotationReferenceInput[];
+  readonly source: SourceSpan;
+}
+
+export interface LocalNotationDefinitionInput {
+  readonly key: string;
+  readonly notation: string;
+  readonly label: string;
+  readonly summary: string;
+  readonly formula?: string;
+  readonly units?: string;
+  readonly sources: readonly string[];
+  readonly seeAlso: readonly string[];
+  readonly alignment: NotationAlignment;
+  /** References harvested from summary content. */
+  readonly references: readonly NotationReferenceInput[];
+  readonly source: SourceSpan;
+}
+
+export interface NotationLessonInput {
+  readonly lessonId: string;
+  readonly status: EditorialStatus;
+  readonly localDefinitions: readonly LocalNotationDefinitionInput[];
+  /** References harvested from lesson prose and equations, excluding definitions. */
+  readonly references: readonly NotationReferenceInput[];
+  /** Original lesson body, retained for lossless loader adapters. */
+  readonly body: string;
+  readonly source: SourceSpan;
+}
+
+export interface NotationRegistryInput {
+  readonly sharedDefinitions: readonly SharedNotationDefinitionInput[];
+  readonly lessons: readonly NotationLessonInput[];
+}
+
+export type NotationDiagnosticCode =
+  | 'invalid-key'
+  | 'duplicate-page'
+  | 'duplicate-definition'
+  | 'conflicting-definition'
+  | 'undefined-reference'
+  | 'reference-cycle'
+  | 'unused-definition'
+  | 'alignment-unknown-competency'
+  | 'alignment-unknown-lesson'
+  | 'alignment-introduction'
+  | 'alignment-unavailable'
+  | 'alignment-review-state';
+
+export type DiagnosticSeverity = 'error' | 'warning';
+
+export interface NotationDiagnostic {
+  readonly code: NotationDiagnosticCode;
+  readonly severity: DiagnosticSeverity;
+  readonly message: string;
+  readonly key?: string;
+  readonly lessonId?: string;
+  readonly definitionId?: string;
+  readonly source?: SourceSpan;
+  readonly relatedSources?: readonly SourceSpan[];
+  readonly path?: readonly string[];
+}
+
+export type NotationDefinitionScope =
+  | { readonly kind: 'shared' }
+  | { readonly kind: 'page'; readonly lessonId: string };
+
+export interface ResolvedNotationReference {
+  readonly key: string;
+  readonly kind: NotationReferenceKind;
+  readonly definitionId: string;
+  readonly source: SourceSpan;
+}
+
+interface NotationDefinitionRecordBase {
+  readonly id: string;
+  readonly key: string;
+  readonly scope: NotationDefinitionScope;
+  readonly notation: string;
+  readonly label: string;
+  readonly seeAlso: readonly string[];
+  readonly alignment: NotationAlignment;
+  readonly status: EditorialStatus;
+  readonly source: SourceSpan;
+  readonly resolvedReferences: readonly ResolvedNotationReference[];
+}
+
+export interface SharedNotationDefinitionRecord extends NotationDefinitionRecordBase {
+  readonly kind: 'shared';
+  readonly summary: string;
+  readonly aliases: readonly string[];
+  readonly domain: string;
+  readonly formula?: string;
+  readonly units?: string;
+  readonly sources: readonly string[];
+  readonly aiAssisted: boolean;
+  readonly body: string;
+}
+
+export interface LocalNotationDefinitionRecord extends NotationDefinitionRecordBase {
+  readonly kind: 'local';
+  readonly lessonId: string;
+  readonly summary: string;
+  readonly formula?: string;
+  readonly units?: string;
+  readonly sources: readonly string[];
+}
+
+export type NotationDefinitionRecord =
+  SharedNotationDefinitionRecord | LocalNotationDefinitionRecord;
+
+export interface NotationBinding {
+  readonly key: string;
+  readonly definitionId: string;
+}
+
+export interface NotationPageBundle {
+  readonly lessonId: string;
+  readonly status: EditorialStatus;
+  readonly source: SourceSpan;
+  readonly bindings: readonly NotationBinding[];
+  readonly definitionIds: readonly string[];
+}
+
+export interface NotationBacklink {
+  readonly definitionId: string;
+  readonly key: string;
+  readonly lessonId: string;
+  readonly direct: boolean;
+}
+
+export interface NotationRegistry {
+  readonly definitions: readonly NotationDefinitionRecord[];
+  readonly bundles: readonly NotationPageBundle[];
+  readonly backlinks: readonly NotationBacklink[];
+  readonly diagnostics: readonly NotationDiagnostic[];
+}

package/src/reference/units-vocab.ts

@@ -0,0 +1,143 @@
+/**
+ * Controlled vocabulary for notation `units` strings (Step D6, check `units-vocab`).
+ *
+ * A `units` string is a short English phrase (`stated currency at valuation
+ * time`, `model-years from valuation time`, `probability between zero and one`).
+ * There is no fixed enum of whole phrases — the corpus composes them — so the
+ * vocabulary is a **word list**: every whitespace/hyphen-separated token of a
+ * `units` string must already be established in the corpus.
+ *
+ * The list below is the set of tokens that appear in two or more distinct
+ * `units` strings today, plus a small set of function words and morphological
+ * variants. A token outside it is either a typo or unreviewed divergence
+ * (`USD` vs `stated currency`, `valuation date` vs `valuation time`,
+ * `synthetic` / `simplified` framing, multi-clause `code; … prose and UI`
+ * strings) — surfaced as a Tier-3 warning, never auto-corrected.
+ *
+ * Extend deliberately: add a token here only when a reviewer has accepted the
+ * phrasing that introduces it.
+ */
+
+export const UNITS_VOCAB: ReadonlySet<string> = new Set([
+  // structure / function words
+  'a',
+  'and',
+  'as',
+  'at',
+  'between',
+  'by',
+  'for',
+  'from',
+  'in',
+  'of',
+  'or',
+  'per',
+  'the',
+  'this',
+  'to',
+  'under',
+  'when',
+  'after',
+  // currency / value
+  'currency',
+  'currencies',
+  'currency-unit',
+  'currency-units',
+  'unit',
+  'units',
+  'stated',
+  'value',
+  'present',
+  'notional',
+  'cash',
+  // time
+  'time',
+  'times',
+  'year',
+  'years',
+  'model',
+  'model-year',
+  'model-years',
+  'valuation',
+  'date',
+  'dates',
+  'day',
+  'days',
+  'horizon',
+  'current',
+  'future',
+  'next',
+  'node',
+  'successor',
+  'settlement',
+  'expiry',
+  'expiration',
+  'delivery',
+  'forward',
+  'maturity',
+  'payment',
+  'payments',
+  'coupon',
+  'premium',
+  'accrual',
+  'scheduled',
+  'schedule',
+  'period',
+  'periods',
+  // rates / dimensionless
+  'decimal',
+  'rate',
+  'nominal',
+  'annual',
+  'compounded',
+  'compounding',
+  'frequency',
+  'intensity',
+  'basis',
+  'point',
+  'points',
+  'percent',
+  'fraction',
+  'probability',
+  'probabilities',
+  'weight',
+  'weights',
+  'dimensionless',
+  'integer',
+  'index',
+  'count',
+  'zero',
+  'one',
+  // instruments / quantities
+  'bond',
+  'option',
+  'claim',
+  'security',
+  'underlying',
+  'quantity',
+  'quoted',
+  'explicitly',
+  'calculations',
+]);
+
+/** Lowercase word tokens of a `units` string (split on whitespace and hyphens). */
+export function unitsTokens(units: string): string[] {
+  return units
+    .toLowerCase()
+    .split(/[\s]+/)
+    .flatMap((word) => word.split(/(?<=[a-z0-9])-(?=[a-z])/))
+    .map((word) => word.replace(/^[^a-z0-9_]+|[^a-z0-9_]+$/g, ''))
+    .filter((word) => word.length > 0 && !/^\d+$/.test(word));
+}
+
+/** Tokens of `units` that are not in the controlled vocabulary, in order, deduped. */
+export function offVocabularyTokens(units: string): string[] {
+  const seen = new Set<string>();
+  const out: string[] = [];
+  for (const token of unitsTokens(units)) {
+    if (UNITS_VOCAB.has(token) || seen.has(token)) continue;
+    seen.add(token);
+    out.push(token);
+  }
+  return out;
+}

package/src/session/PreferenceStore.ts

@@ -0,0 +1,54 @@
+/**
+ * The per-viewer UI-preference seam (Phase H1).
+ *
+ * A "preference" is a small, non-authoritative bit of view state — which layout
+ * rails a viewer collapsed, say. It is **not** learning progress (that is the
+ * {@link ProgressRepository} seam) and never carries content or identity.
+ *
+ * This is the single module in the codebase allowed to touch browser storage.
+ * Components import a `PreferenceStore`; they never call `localStorage`
+ * directly, so a future SSR host can pass `memoryPreferenceStore` (or a
+ * cookie-backed store) and nothing else changes. `createBrowserPreferenceStore`
+ * is the "versioned local-storage adapter" the architecture doc anticipates —
+ * kept deliberately tiny, and the only place `git grep localStorage` matches.
+ */
+
+export interface PreferenceStore {
+  get(key: string): string | null;
+  set(key: string, value: string): void;
+}
+
+/**
+ * A `localStorage`-backed store. Every call is wrapped: storage can be absent
+ * (SSR), disabled, or full, and the caller must degrade gracefully — the UI
+ * controls still work, they just do not persist.
+ */
+export function createBrowserPreferenceStore(): PreferenceStore {
+  return {
+    get(key) {
+      try {
+        return window.localStorage.getItem(key);
+      } catch {
+        return null;
+      }
+    },
+    set(key, value) {
+      try {
+        window.localStorage.setItem(key, value);
+      } catch {
+        // Storage unavailable or full — the control still works this session.
+      }
+    },
+  };
+}
+
+/** An in-memory store — the no-op-equivalent seam for SSR or tests. */
+export function createMemoryPreferenceStore(): PreferenceStore {
+  const map = new Map<string, string>();
+  return {
+    get: (key) => map.get(key) ?? null,
+    set: (key, value) => {
+      map.set(key, value);
+    },
+  };
+}

package/src/session/user-context.ts

@@ -0,0 +1,18 @@
+/**
+ * React binding for the viewer identity seam (Phase H1).
+ *
+ * `SessionUserContext` defaults to {@link anonymousUser}. The static site never
+ * wraps a provider around it, so `useSessionUser()` always returns the
+ * anonymous user; a future SSR/LMS host injects a real identity here without
+ * touching any consumer.
+ */
+
+import { createContext, useContext } from 'react';
+
+import { anonymousUser, type SessionUser } from './user';
+
+export const SessionUserContext = createContext<SessionUser>(anonymousUser);
+
+export function useSessionUser(): SessionUser {
+  return useContext(SessionUserContext);
+}

package/src/session/user.ts

@@ -0,0 +1,24 @@
+/**
+ * The viewer identity seam (Phase H1).
+ *
+ * The static site has no accounts and no sign-in: every viewer is anonymous.
+ * A future SSR app or LMS host is the only thing that would ever supply a real
+ * identity, and it would do so by wrapping the React tree in a provider over
+ * {@link SessionUserContext} (see `./user-context`). Nothing in this repository
+ * produces a non-anonymous user, and nothing here reads a cookie, a token, or
+ * browser storage.
+ */
+
+export interface SessionUser {
+  /** Always `'anonymous'` in the static build. */
+  readonly kind: 'anonymous';
+  /** A stable id for a signed-in viewer; always `null` here. */
+  readonly id: string | null;
+}
+
+/** The only user the static site ever has. */
+export const anonymousUser: SessionUser = { kind: 'anonymous', id: null };
+
+export function isAnonymous(user: SessionUser): boolean {
+  return user.kind === 'anonymous' || user.id === null;
+}