explico 0.1.0

package/dist/reference/render-lab-math.d.ts

@@ -0,0 +1,21 @@
+interface LabMathScopeDefinition {
+    readonly key: string;
+    readonly notation: string;
+}
+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[];
+}
+/**
+ * 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.
+ */
+declare function renderLabMath(template: string, scope: readonly LabMathScopeDefinition[]): RenderedLabMath;
+
+export { type LabMathScopeDefinition, type RenderedLabMath, renderLabMath };

package/dist/reference/render-lab-math.js

@@ -0,0 +1,58 @@
+import katex from "katex";
+import { resolveMathGlyphs } from "./math-glyphs.mjs";
+import { createNotationKatexOptions } from "./katex-options.mjs";
+const SLOT_PATTERN = /\\slot\{([a-z][a-z0-9]*)\}\{((?:[^{}]|\{[^{}]*\})*)\}/g;
+const sentinelFor = (index) => `909909${index}.909909`;
+function renderLabMath(template, scope) {
+  const slots = [];
+  const forBinding = template.replace(
+    SLOT_PATTERN,
+    (_match, name, fallback) => {
+      const sentinel = sentinelFor(slots.length);
+      slots.push({ name, fallback });
+      return ` ${sentinel} `;
+    }
+  );
+  let result;
+  try {
+    result = resolveMathGlyphs(forBinding, [...scope]);
+  } catch (error) {
+    throw new Error(
+      `Lab math failed to compile: ${error instanceof Error ? error.message : String(error)}
+  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).
+  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.
+  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))]
+  };
+}
+export {
+  renderLabMath
+};

package/dist/reference/types.d.ts

@@ -0,0 +1,151 @@
+type EditorialStatus = 'draft' | 'in-review' | 'reviewed';
+interface SourceSpan {
+    readonly file: string;
+    readonly line?: number;
+    readonly column?: number;
+    readonly endLine?: number;
+    readonly endColumn?: number;
+}
+type NotationAlignment = {
+    readonly kind: 'competency';
+    readonly introducedByCompetency: string;
+    readonly introducedInLesson: string;
+} | {
+    readonly kind: 'general';
+    readonly rationale: string;
+};
+type NotationReferenceKind = 'prose' | 'math' | 'definition';
+interface NotationReferenceInput {
+    readonly key: string;
+    readonly kind: NotationReferenceKind;
+    readonly source: SourceSpan;
+}
+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;
+}
+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;
+}
+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;
+}
+interface NotationRegistryInput {
+    readonly sharedDefinitions: readonly SharedNotationDefinitionInput[];
+    readonly lessons: readonly NotationLessonInput[];
+}
+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';
+type DiagnosticSeverity = 'error' | 'warning';
+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[];
+}
+type NotationDefinitionScope = {
+    readonly kind: 'shared';
+} | {
+    readonly kind: 'page';
+    readonly lessonId: string;
+};
+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[];
+}
+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;
+}
+interface LocalNotationDefinitionRecord extends NotationDefinitionRecordBase {
+    readonly kind: 'local';
+    readonly lessonId: string;
+    readonly summary: string;
+    readonly formula?: string;
+    readonly units?: string;
+    readonly sources: readonly string[];
+}
+type NotationDefinitionRecord = SharedNotationDefinitionRecord | LocalNotationDefinitionRecord;
+interface NotationBinding {
+    readonly key: string;
+    readonly definitionId: string;
+}
+interface NotationPageBundle {
+    readonly lessonId: string;
+    readonly status: EditorialStatus;
+    readonly source: SourceSpan;
+    readonly bindings: readonly NotationBinding[];
+    readonly definitionIds: readonly string[];
+}
+interface NotationBacklink {
+    readonly definitionId: string;
+    readonly key: string;
+    readonly lessonId: string;
+    readonly direct: boolean;
+}
+interface NotationRegistry {
+    readonly definitions: readonly NotationDefinitionRecord[];
+    readonly bundles: readonly NotationPageBundle[];
+    readonly backlinks: readonly NotationBacklink[];
+    readonly diagnostics: readonly NotationDiagnostic[];
+}
+
+export type { DiagnosticSeverity, EditorialStatus, LocalNotationDefinitionInput, LocalNotationDefinitionRecord, NotationAlignment, NotationBacklink, NotationBinding, NotationDefinitionRecord, NotationDefinitionScope, NotationDiagnostic, NotationDiagnosticCode, NotationLessonInput, NotationPageBundle, NotationReferenceInput, NotationReferenceKind, NotationRegistry, NotationRegistryInput, ResolvedNotationReference, SharedNotationDefinitionInput, SharedNotationDefinitionRecord, SourceSpan };

package/dist/reference/units-vocab.d.ts

@@ -0,0 +1,26 @@
+/**
+ * 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.
+ */
+declare const UNITS_VOCAB: ReadonlySet<string>;
+/** Lowercase word tokens of a `units` string (split on whitespace and hyphens). */
+declare function unitsTokens(units: string): string[];
+/** Tokens of `units` that are not in the controlled vocabulary, in order, deduped. */
+declare function offVocabularyTokens(units: string): string[];
+
+export { UNITS_VOCAB, offVocabularyTokens, unitsTokens };

package/dist/reference/units-vocab.js

@@ -0,0 +1,119 @@
+const UNITS_VOCAB = /* @__PURE__ */ 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"
+]);
+function unitsTokens(units) {
+  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));
+}
+function offVocabularyTokens(units) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const token of unitsTokens(units)) {
+    if (UNITS_VOCAB.has(token) || seen.has(token)) continue;
+    seen.add(token);
+    out.push(token);
+  }
+  return out;
+}
+export {
+  UNITS_VOCAB,
+  offVocabularyTokens,
+  unitsTokens
+};

package/dist/session/PreferenceStore.d.ts

@@ -0,0 +1,28 @@
+/**
+ * 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.
+ */
+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.
+ */
+declare function createBrowserPreferenceStore(): PreferenceStore;
+/** An in-memory store — the no-op-equivalent seam for SSR or tests. */
+declare function createMemoryPreferenceStore(): PreferenceStore;
+
+export { type PreferenceStore, createBrowserPreferenceStore, createMemoryPreferenceStore };

package/dist/session/PreferenceStore.js

@@ -0,0 +1,30 @@
+function createBrowserPreferenceStore() {
+  return {
+    get(key) {
+      try {
+        return window.localStorage.getItem(key);
+      } catch {
+        return null;
+      }
+    },
+    set(key, value) {
+      try {
+        window.localStorage.setItem(key, value);
+      } catch {
+      }
+    }
+  };
+}
+function createMemoryPreferenceStore() {
+  const map = /* @__PURE__ */ new Map();
+  return {
+    get: (key) => map.get(key) ?? null,
+    set: (key, value) => {
+      map.set(key, value);
+    }
+  };
+}
+export {
+  createBrowserPreferenceStore,
+  createMemoryPreferenceStore
+};

package/dist/session/user-context.d.ts

@@ -0,0 +1,7 @@
+import * as react from 'react';
+import { SessionUser } from './user.js';
+
+declare const SessionUserContext: react.Context<SessionUser>;
+declare function useSessionUser(): SessionUser;
+
+export { SessionUserContext, useSessionUser };

package/dist/session/user-context.js

@@ -0,0 +1,10 @@
+import { createContext, useContext } from "react";
+import { anonymousUser } from "./user";
+const SessionUserContext = createContext(anonymousUser);
+function useSessionUser() {
+  return useContext(SessionUserContext);
+}
+export {
+  SessionUserContext,
+  useSessionUser
+};

package/dist/session/user.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 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.
+ */
+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. */
+declare const anonymousUser: SessionUser;
+declare function isAnonymous(user: SessionUser): boolean;
+
+export { type SessionUser, anonymousUser, isAnonymous };

package/dist/session/user.js

@@ -0,0 +1,8 @@
+const anonymousUser = { kind: "anonymous", id: null };
+function isAnonymous(user) {
+  return user.kind === "anonymous" || user.id === null;
+}
+export {
+  anonymousUser,
+  isAnonymous
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "explico",
+  "version": "0.1.0",
+  "description": "Build-time engine for prerequisite-aware, notation-rigorous course content: one validated content model, a semantic notation/citation/equation system with a completeness gate, and a deterministic JSON manifest.",
+  "type": "module",
+  "license": "UNLICENSED",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/danieltuzes/explico.git"
+  },
+  "homepage": "https://github.com/danieltuzes/explico#readme",
+  "bugs": "https://github.com/danieltuzes/explico/issues",
+  "sideEffects": [
+    "*.css"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    "./content-config": "./src/content-config.ts",
+    "./components/*": "./src/components/*",
+    "./styles/*": "./src/styles/*",
+    "./reference/*.mjs": "./dist/reference/*.mjs",
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "@astrojs/markdown-remark": "7.2.4",
+    "@astrojs/react": "6.0.4",
+    "@astrojs/starlight": "0.41.9",
+    "astro": "7.2.7",
+    "katex": "0.16.47",
+    "react": "19.2.8",
+    "react-dom": "19.2.8",
+    "rehype-katex": "7.0.1",
+    "remark-math": "6.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "24.13.3",
+    "@types/react": "19.2.18",
+    "@types/react-dom": "19.2.5",
+    "tsup": "8.5.1",
+    "typescript": "6.0.2"
+  },
+  "scripts": {
+    "build": "tsup && node scripts/copy-assets.mjs"
+  }
+}

package/src/analytics/AnalyticsEmitter.ts

@@ -0,0 +1,23 @@
+/**
+ * The analytics seam (Phase H1).
+ *
+ * `noopAnalyticsEmitter` is the only sink the static site ships — `emit` does
+ * nothing. Stateful components call it alongside the {@link ProgressRepository}
+ * so a future host can route interaction events somewhere real without touching
+ * a component. Framework-free: no React, Astro, content, or browser API, and no
+ * network call.
+ */
+
+export interface AnalyticsEvent {
+  readonly name: string;
+  /** Epoch milliseconds, supplied by the caller so this stays side-effect-free. */
+  readonly at: number;
+  readonly props?: Readonly<Record<string, string | number | boolean | null>>;
+}
+
+export interface AnalyticsEmitter {
+  emit(event: AnalyticsEvent): void;
+}
+
+/** The only sink in the static build. */
+export const noopAnalyticsEmitter: AnalyticsEmitter = { emit: () => {} };