explico 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -14,6 +14,97 @@ under **Breaking** below; a PATCH never breaks.
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-09-16
+
+### Breaking
+
+- **New build-enforced authoring rule S1: no Markdown heading (`##` through
+  `######`) and no `<Figure title>` / `<Diagram label>` / `<Memo title>` /
+  `<ShortNote title>` may run past 65 characters.** A `<Figure>` with a long
+  `caption` and no explicit `title` was silently using the whole caption as
+  its always-visible collapsible title-bar text — the reader saw the full
+  sentence twice. `gate-heading-length.ts` scans every lesson body; a course
+  with an over-limit heading or float title anywhere will now fail
+  `pnpm validate:content` / `astro build`. `<Table>` is exempt — it has only
+  a `caption`, not a separate `title`. A lesson's own `frontmatter.title`
+  (the page `<h1>`) is Review-only, not build-enforced — the gate scans body
+  text and cannot see frontmatter. See
+  `docs/authoring/structure-rules.md#s1`.
+
+- **Removed the "Pin explanation" button from the "Page notation" panel**
+  (`.notation-pin`, `[data-notation-control]` — both gone from the DOM). Pin
+  a card from the list the same way an inline prose symbol always has: click
+  its glyph, now also Tab + Enter/Space-operable (`role="button"`,
+  `tabindex="0"`, `aria-pressed`) since it was the button's only remaining
+  job. A course's own CSS or tests targeting either selector need updating.
+
+- **`NotationLayer.astro`'s separate "Page notation" `<h2>` is gone** —
+  the panel had two headings back to back ("Page notation" over "Notation
+  used on this page (N)"), saying the same thing twice. The panel's
+  `<summary>` is now the only heading, and `.notation-layer-heading` no
+  longer exists.
+
+- **`Diagram`'s `description` prop and its collapsed "Diagram description"
+  fallback block are gone** (`.diagram-fallback` no longer exists in the
+  DOM). The caption (`label`) is the diagram's one authored piece of text,
+  matching how a LaTeX figure/table caption already tells the whole story —
+  a separate always-present description block was inventing a second text
+  category most courses never wanted and that only added visible chrome
+  under every diagram. Drop any `description="…"` passed to `<Diagram>`;
+  the build no longer accepts it (`astro check` fails on an excess prop).
+
+### Added
+
+- **`NotationLayer.astro`'s "Page notation" panel and `remark-citation.mjs`'s
+  generated "References" section are both properly collapsible now** — same
+  native, persisted, deep-linkable disclosure `Figure`/`CollapsibleSections`
+  already use, not the always-native-default `<details>` "Page notation" had
+  before (no persistence, no course-configurable default, no anchor).
+  - `NotationLayer` gains `defaultOpen`/`rememberState` props (mirroring
+    `Figure`'s) and a hover-reveal permalink anchor next to its title bar
+    (`#page-notation` by default).
+  - `remark-citation.mjs`'s generated References heading now carries the
+    same `[collapsible]`/`[collapsed]` marker an authored `##` heading uses,
+    via a new `defaultOpen` plugin option — so it rides the *same*
+    `rehypeHeadingAnchors` / `CollapsibleSections` machinery every other
+    heading does, with no engine changes needed on that side. This only
+    takes visible effect on a course whose `astro.config.mjs` wires
+    `rehypeHeadingAnchors` into its rehype pipeline.
+  - New `CourseConfig.disclosureDefaults` (the manifest schema is now v14,
+    additive):
+    `{ notation?, references? }`, each `true` = open, closed (the engine's
+    own default) when omitted or the whole block is absent. Both are
+    engine-authored sections, not written by a lesson, so they get their own
+    default independent of `defaultCollapsible.sections`/`.subsections` (an
+    author's own `##` headings). See `docs/authoring`,
+    `playground/astro.config.mjs` for the wiring convention.
+
+### Fixed
+
+- **A symbol explained once via `\explain{key}{…}` can now auto-resolve at
+  every later bare occurrence of the same declared `latex` on the page — this
+  previously failed silently (no tooltip, no build error) for several common
+  shapes.** A definition whose whole canonical form is a roman label
+  (`\mathrm{SSR}`, `\mathrm{SST}`) never entered the auto-annotator's
+  signature index at all, so a bare occurrence of such a symbol could never
+  resolve, anywhere on the page, independent of position. Also fixed: a bare
+  symbol sitting immediately next to an `\explain{…}{…}` call, a canonical
+  match found by seeing through an already-explicit call's own wrapping, and
+  a partial `\explain{key}{…}` wrap covering only part of a declared
+  multi-token form — all three previously either dropped the symbol silently
+  or produced malformed, unparseable output. All of these now resolve
+  correctly, or fail loudly as "Unresolved notation" (`resolveMathGlyphs`,
+  shared by lesson-body rendering and `gate-math.ts`'s `pnpm validate:content`
+  check — so a regression here fails the build immediately rather than
+  passing silently through to a render-time surprise). One side effect: the
+  fix also restores the `ambiguous-canonical-notation` check for
+  `\operatorname{…}`/`\mathrm{…}`-only glyphs, which the same bug had
+  silently disabled — a course with two different notation keys declaring
+  structurally identical LaTeX (e.g. two keys both `\operatorname{Var}`) will
+  now correctly fail `pnpm validate:content` where it previously built with a
+  silent, unresolvable ambiguity. See
+  [`docs/authoring/notation.md`](docs/authoring/notation.md).
+
 ## [0.5.0] - 2026-09-15
 
 ### Added
@@ -137,13 +228,16 @@ under **Breaking** below; a PATCH never breaks.
   UI. The change is additive, but consumers that validate
   `MANIFEST_SCHEMA_VERSION` must accept the new version.
 
-- **The compiler manifest schema is now v10.** Diagrams are first-class keyed
+- **The compiler manifest schema is now v10.** Numbered knowledge checks add
+  `manifest.checks`, `lessons[].knowledgeChecks`, `lessons[].numbering.checks`,
+  and `diagnostics.checks`. The change is additive, but consumers that
+  validate `MANIFEST_SCHEMA_VERSION` must accept the new version.
+
+- **The compiler manifest schema is now v9.** Diagrams are first-class keyed
   floats with their own `manifest.diagrams`, `lessons[].diagrams`,
-  `lessons[].numbering.diagrams`, and `diagnostics.diagrams` fields. Numbered
-  knowledge checks add `manifest.checks`, `lessons[].knowledgeChecks`,
-  `lessons[].numbering.checks`, and `diagnostics.checks`. The changes are
-  additive, but consumers that validate `MANIFEST_SCHEMA_VERSION` must accept
-  the new version.
+  `lessons[].numbering.diagrams`, and `diagnostics.diagrams` fields. The
+  change is additive, but consumers that validate `MANIFEST_SCHEMA_VERSION`
+  must accept the new version.
 
 - **New build-enforced authoring rule N9: a physical quantity, unit, or math
   operator must be typeset in `$…$`, never as plain text, anywhere on a
@@ -217,6 +311,20 @@ under **Breaking** below; a PATCH never breaks.
   with `\sin\theta`, `\log x`, `\exp t`, etc. anywhere in rendered math will
   now fail the build; see `docs/authoring/notation.md#n13`.
 
+- **New build-enforced authoring rule N15: a nested visible delimiter — `(`,
+  `[`, `\{`, or `|` inside another one of them — must use its `\left`/`\right`
+  sizing form, not the bare character.** The moment a second one of these four
+  glyphs sits inside the first — same type or mixed, e.g. `(a + [b])` — every
+  level of that nest switches to the sizing form: `\sin(2(90°-\theta))` is now
+  a hard error, `\sin\left(2\left(90°-\theta\right)\right)` is required.
+  `findNestedBareDelimiters` (`math-glyphs.mjs`) walks the same parsed KaTeX
+  tree `resolveMathGlyphs` and N13 already build; a violation fails
+  `pnpm validate:content` / `astro build` with no `lint-ignore.yml` escape
+  hatch, like N9/N13. A single, non-nested bare delimiter (`(x)`) is
+  untouched, and a delimiter inside `\text{…}` (a unit per N9) is unaffected.
+  A downstream course with a nested bare delimiter anywhere in rendered math
+  will now fail the build; see `docs/authoring/notation.md#n15`.
+
 ### Added
 
 - **Numbered, referenceable, collapsible knowledge checks.** Assessment ids in
@@ -436,7 +544,8 @@ under **Breaking** below; a PATCH never breaks.
   system with its completeness gate, the curriculum-graph validator, the
   Astro/Starlight UI, the LMS / session / analytics seams, and the `content` CLI.
 
-[Unreleased]: https://github.com/danieltuzes/explico/compare/v0.5.0...HEAD
+[Unreleased]: https://github.com/danieltuzes/explico/compare/v0.6.0...HEAD
+[0.6.0]: https://github.com/danieltuzes/explico/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/danieltuzes/explico/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/danieltuzes/explico/compare/v0.3.0...v0.4.0
 [0.3.0]: https://github.com/danieltuzes/explico/compare/v0.2.0...v0.3.0

package/dist/compiler/course-config.d.ts

@@ -107,6 +107,33 @@ interface CourseAbout {
     /** Link to the published content changelog (repo blob, docs page, …). */
     readonly changelogHref?: string;
 }
+/**
+ * A course's chosen initial open/closed state for the engine's own built-in
+ * collapsible sections — the "Page notation" panel (`NotationLayer.astro`)
+ * and the generated "References" section (`remark-citation.mjs`). Each is
+ * independent of `defaultCollapsible.sections`/`.subsections` (an author's
+ * own `##` headings): both of these are engine-authored, not written by a
+ * lesson, so they need their own default rather than inheriting the site's
+ * general heading default.
+ *
+ * `true` starts open, `false` (or omitted) starts closed — the engine's own
+ * default is closed either way, matching a long panel a reader usually
+ * doesn't need open on arrival.
+ */
+interface CourseDisclosureDefaults {
+    /** Initial state of the "Page notation" panel. Default: closed. */
+    readonly notation?: boolean;
+    /** Initial state of the generated "References" section. Default: closed. */
+    readonly references?: boolean;
+}
+/** The stable, non-optional form `NormalizedLessonExports` mirrors. */
+interface NormalizedDisclosureDefaults {
+    readonly notation: boolean;
+    readonly references: boolean;
+}
+/** Validate and canonicalize `CourseConfig.disclosureDefaults`. Absent (or
+ *  an absent sub-field) resolves to closed, the engine's own default. */
+declare function normalizeDisclosureDefaults(config: CourseConfig): NormalizedDisclosureDefaults;
 /** Optional, build-time lesson artifacts exposed to readers. */
 interface LessonExportsConfig {
     /** Emit one self-contained, offline-capable HTML file per lesson. */
@@ -151,6 +178,9 @@ interface CourseConfig {
     readonly abbreviations?: CourseAbbreviations;
     /** Per-lesson export actions and downloadable artifacts. Disabled when omitted. */
     readonly lessonExports?: LessonExportsConfig;
+    /** Initial open/closed state for the engine's own built-in collapsible
+     *  sections ("Page notation", "References"). Closed when omitted. */
+    readonly disclosureDefaults?: CourseDisclosureDefaults;
 }
 /** Validate and canonicalize the build-facing lesson-export configuration. */
 declare function normalizeLessonExports(config: CourseConfig): NormalizedLessonExports;
@@ -161,4 +191,4 @@ declare function normalizeLessonExports(config: CourseConfig): NormalizedLessonE
  */
 declare function coursePartsOf(config: CourseConfig): readonly CoursePart[];
 
-export { type CourseAbbreviations, type CourseAbout, type CourseAuthor, type CourseConfig, type CourseConventions, type CourseOperators, type CoursePart, type CourseRomanLabels, type CourseSection, type LessonExportsConfig, type NormalizedLessonExports, coursePartsOf, normalizeLessonExports };
+export { type CourseAbbreviations, type CourseAbout, type CourseAuthor, type CourseConfig, type CourseConventions, type CourseDisclosureDefaults, type CourseOperators, type CoursePart, type CourseRomanLabels, type CourseSection, type LessonExportsConfig, type NormalizedDisclosureDefaults, type NormalizedLessonExports, coursePartsOf, normalizeDisclosureDefaults, normalizeLessonExports };

package/dist/compiler/course-config.js

@@ -1,3 +1,9 @@
+function normalizeDisclosureDefaults(config) {
+  return {
+    notation: config.disclosureDefaults?.notation === true,
+    references: config.disclosureDefaults?.references === true
+  };
+}
 function normalizeLessonExports(config) {
   const standaloneHtml = config.lessonExports?.standaloneHtml === true;
   const print = config.lessonExports?.print === true;
@@ -35,5 +41,6 @@ function coursePartsOf(config) {
 }
 export {
   coursePartsOf,
+  normalizeDisclosureDefaults,
   normalizeLessonExports
 };

package/dist/compiler/manifest.d.ts

@@ -10,7 +10,7 @@ import { MathGateDiagnostic } from '../reference/gate-math.js';
 import { ContentSegment } from '../reference/mixed-content.js';
 import { GlyphScopeEntry } from '../reference/gloss.js';
 import { NotationDefinitionRecord, NotationPageBundle, NotationBacklink, NotationDiagnostic, EditorialStatus, NotationGlossEntry } from '../reference/types.js';
-import { NormalizedLessonExports, CourseConfig } from './course-config.js';
+import { NormalizedLessonExports, NormalizedDisclosureDefaults, CourseConfig } from './course-config.js';
 import { KnowledgeVersionDiagnostic } from './knowledge-version.js';
 import { SidebarGroup } from './lesson-derivation.js';
 import './collections.js';
@@ -90,8 +90,14 @@ import '../reference/keyed-float-validate.js';
  * validation and can never get a stable number or `[[…]]` reference; this
  * flags it (warning-only — the manifest shape a client already reads is
  * unchanged).
+ * v14 (disclosure defaults, additive): `disclosureDefaults` — the resolved
+ * initial open/closed state for the "Page notation" panel and the generated
+ * "References" section, from `CourseConfig.disclosureDefaults`. Both are
+ * engine-authored sections, not written by a lesson, so they get their own
+ * default independent of a course's `##` heading default; closed unless the
+ * course sets one.
  */
-declare const MANIFEST_SCHEMA_VERSION = 13;
+declare const MANIFEST_SCHEMA_VERSION = 14;
 declare const MANIFEST_PATH: string;
 interface ManifestCitation {
     readonly id: string;
@@ -256,6 +262,8 @@ interface Manifest {
     readonly schemaVersion: number;
     /** Normalized build/UI settings for opt-in per-lesson exports. */
     readonly lessonExports: NormalizedLessonExports;
+    /** Initial open/closed state for "Page notation" and "References". */
+    readonly disclosureDefaults: NormalizedDisclosureDefaults;
     /** Reader-facing identity + versions (the `[?]` About panel). */
     readonly about: ManifestAbout;
     readonly notation: {

package/dist/compiler/manifest.js

@@ -45,6 +45,7 @@ import {
   gateProseNotationInAssessments
 } from "../reference/gate-prose-notation.js";
 import { gateAbbreviations } from "../reference/gate-abbreviations.js";
+import { gateHeadingLength } from "../reference/gate-heading-length.js";
 import {
   splitMixedContent
 } from "../reference/mixed-content.js";
@@ -54,7 +55,8 @@ import { formulaGlyphScope } from "../reference/gloss.js";
 import { resolveReferenceId } from "../reference/references.js";
 import {
   coursePartsOf,
-  normalizeLessonExports
+  normalizeLessonExports,
+  normalizeDisclosureDefaults
 } from "./course-config.js";
 import {
   resolveKnowledgeVersion
@@ -73,7 +75,7 @@ import {
   isLessonSlug,
   lessonIdFromSlug
 } from "./lesson-derivation.js";
-const MANIFEST_SCHEMA_VERSION = 13;
+const MANIFEST_SCHEMA_VERSION = 14;
 const REPOSITORY_ROOT = process.cwd();
 const CONTENT_ROOT = join(REPOSITORY_ROOT, "content");
 const MANIFEST_PATH = join(REPOSITORY_ROOT, "build", "manifest.json");
@@ -243,7 +245,8 @@ async function compileManifest(courseConfig) {
       notationInput,
       abbreviations: abbreviationsInput,
       courseAbbreviations: courseConfig.abbreviations
-    })
+    }),
+    ...gateHeadingLength(notationInput.lessons)
   ];
   const notationLessonById = new Map(
     notationInput.lessons.map((lesson) => [lesson.lessonId, lesson])
@@ -517,6 +520,7 @@ async function compileManifest(courseConfig) {
   return {
     schemaVersion: MANIFEST_SCHEMA_VERSION,
     lessonExports: normalizeLessonExports(courseConfig),
+    disclosureDefaults: normalizeDisclosureDefaults(courseConfig),
     about,
     notation: {
       definitions: registry.definitions,

package/dist/reference/gate-heading-length.d.ts

@@ -0,0 +1,12 @@
+import { MathGateDiagnostic } from './gate-math.js';
+import { NotationLessonInput } from './types.js';
+
+declare const HEADING_LENGTH_LIMIT = 65;
+/**
+ * Scan every lesson body for a heading or a keyed float's title running past
+ * `HEADING_LENGTH_LIMIT` characters. Returns one `MathGateDiagnostic`
+ * (context `'structure'`, always an error) per finding.
+ */
+declare function gateHeadingLength(lessons: readonly NotationLessonInput[]): MathGateDiagnostic[];
+
+export { HEADING_LENGTH_LIMIT, gateHeadingLength };

package/dist/reference/gate-heading-length.js

@@ -0,0 +1,79 @@
+import { stripFencedCode } from "./equations.mjs";
+import { lineOf } from "./gate-prose-notation.js";
+const HEADING_LENGTH_LIMIT = 65;
+const HEADING_LINE = /^[ \t]{0,3}(#{1,6})[ \t]+(.+?)[ \t]*#*[ \t]*$/gm;
+const TITLE_ATTRIBUTE_BY_TAG = {
+  Figure: "title",
+  Diagram: "label",
+  Memo: "title",
+  ShortNote: "title"
+};
+function readAttribute(attributesSource, name) {
+  const pattern = new RegExp(`\\b${name}\\s*=\\s*(["'])([^"']*)\\1`);
+  const match = pattern.exec(attributesSource);
+  return match ? match[2] : void 0;
+}
+function overLimitMessage(kind, text) {
+  return `${kind} ${JSON.stringify(text)} is ${text.length} characters, over the ${HEADING_LENGTH_LIMIT}-character limit (rule S1). Shorten it and move the rest into the paragraph or caption that follows.`;
+}
+function headingFindings(text) {
+  const out = [];
+  const re = new RegExp(HEADING_LINE.source, HEADING_LINE.flags);
+  let match;
+  while (match = re.exec(text)) {
+    const level = match[1]?.length ?? 1;
+    const title = (match[2] ?? "").trim();
+    if (title.length > HEADING_LENGTH_LIMIT) {
+      out.push({
+        index: match.index,
+        token: title,
+        message: overLimitMessage(`${"#".repeat(level)} heading`, title)
+      });
+    }
+  }
+  return out;
+}
+function floatTitleFindings(text) {
+  const out = [];
+  for (const [tagName, attribute] of Object.entries(TITLE_ATTRIBUTE_BY_TAG)) {
+    const opening = new RegExp(`<${tagName}\\b([^>]*)>`, "g");
+    let match;
+    while (match = opening.exec(text)) {
+      const value = readAttribute(match[1] ?? "", attribute)?.trim();
+      if (value && value.length > HEADING_LENGTH_LIMIT) {
+        out.push({
+          index: match.index,
+          token: value,
+          message: overLimitMessage(`<${tagName} ${attribute}>`, value)
+        });
+      }
+    }
+  }
+  return out;
+}
+function findingsIn(text) {
+  return [...headingFindings(text), ...floatTitleFindings(text)].sort(
+    (a, b) => a.index - b.index
+  );
+}
+function gateHeadingLength(lessons) {
+  const diagnostics = [];
+  for (const lesson of lessons) {
+    const text = stripFencedCode(lesson.body);
+    for (const finding of findingsIn(text)) {
+      diagnostics.push({
+        context: "structure",
+        severity: "error",
+        file: lesson.source.file,
+        line: lineOf(lesson.body, finding.index),
+        token: finding.token,
+        message: finding.message
+      });
+    }
+  }
+  return diagnostics;
+}
+export {
+  HEADING_LENGTH_LIMIT,
+  gateHeadingLength
+};

package/dist/reference/gate-math.d.ts

@@ -1,7 +1,7 @@
 import { NotationRegistryInput, NotationLessonInput } from './types.js';
 
 interface MathGateDiagnostic {
-    readonly context: 'body' | 'formula' | 'assessment' | 'prose' | 'abbreviation';
+    readonly context: 'body' | 'formula' | 'assessment' | 'prose' | 'abbreviation' | 'structure';
     /**
      * Body / component-slot math blocks the build (the render path needs every
      * glyph resolved for the KaTeX trust callback). `formula` joined it at D15:
@@ -19,7 +19,11 @@ interface MathGateDiagnostic {
      * same change that introduced the check. `abbreviation` (N14,
      * `gate-abbreviations.ts`) is the same "ships straight as an error" story
      * for a different shape of plain-text token — an unexplained acronym or
-     * dotted abbreviation, rather than a mis-typed quantity/unit.
+     * dotted abbreviation, rather than a mis-typed quantity/unit. `structure`
+     * (S1, `gate-heading-length.ts`) is unrelated to notation — it caps how
+     * long a heading or a keyed float's title may run — but reuses this same
+     * diagnostic shape and the one `manifest.diagnostics.math` array rather
+     * than adding a second array the CLI has to know about.
      */
     readonly severity: 'error' | 'warning';
     readonly file: string;

package/dist/reference/gate-math.js

@@ -6,7 +6,8 @@ const SEVERITY = {
   formula: "error",
   assessment: "error",
   prose: "error",
-  abbreviation: "error"
+  abbreviation: "error",
+  structure: "error"
 };
 const TERM_KEY = /\[\[\s*([a-z0-9]+(?:[.-][a-z0-9]+)*)\s*\]\]/g;
 const EXPLAIN_KEY = /\\explain\s*\{([a-z0-9]+(?:[.-][a-z0-9]+)*)\}/g;

package/dist/reference/math-glyphs.d.mts

@@ -42,6 +42,14 @@ export function resolveMathGlyphs(latex: string, definitions: Array<{
  * Used by the `operator-explained` consistency check (rule N8); the glyph
  * resolver still skips operator bodies whole.
  *
+ * The span handed in is raw lesson source, so it may still carry
+ * `\explain{key}{…}` / `\slot{key}{…}` markers around other symbols in the
+ * same expression — `\explain` is not valid KaTeX, so parsing it unstripped
+ * throws and this function used to swallow that as "no operators here" for
+ * the whole span, silently hiding any `\operatorname{…}` alongside the
+ * marker. `stripNotationMarkers` removes just the marker wrapper first so
+ * the scan sees plain, parseable math.
+ *
  * @param {string} latex
  * @returns {Array<{ name: string, source: 'named' | 'operatorname' }>}
  */
@@ -60,6 +68,10 @@ export function collectOperators(latex: string): Array<{
  * `roman-label-explained` consistency check (rule N10); the glyph resolver
  * still skips `\mathrm{…}` bodies whole ([N3](../../docs/authoring/notation.md#n3)).
  *
+ * Same `stripNotationMarkers` preprocessing as {@link collectOperators}, and
+ * for the same reason: an unstripped `\explain{…}{…}` elsewhere in the span
+ * fails the raw KaTeX parse and used to silently drop every label in it.
+ *
  * @param {string} latex
  * @returns {Array<{ name: string }>}
  */