explico 0.13.1 → 0.14.0

package/docs/privacy.md

@@ -0,0 +1,59 @@
+# What an explico site keeps in a reader's browser
+
+An explico course sets **no cookies**, loads **nothing from another site**
+(fonts, KaTeX and search are served by the site itself), and sends nothing
+anywhere: there is no analytics. What it keeps lives in the reader's own
+browser storage (`localStorage` for what outlives the tab, `sessionStorage`
+for what does not), and is read only by the pages of the course.
+
+EU rules treat browser storage like cookies: storing something needs the
+reader's consent unless it is strictly necessary for what the reader asked
+for, such as a preference they set themselves (ePrivacy Directive Art. 5(3);
+EDPB Guidelines 2/2023 on its technical scope; Article 29 Working Party
+Opinion 04/2012 on the exemptions). explico is built so that one question
+covers everything that needs consent.
+
+## Settings: kept because the reader set them
+
+| What | Key | Written when |
+| --- | --- | --- |
+| Theme | `starlight-theme` (Starlight's own) | The reader picks one. Starlight also writes an empty value on each page load. |
+| Text size (phones) | `explico:display:text-size` | The reader picks one |
+| Panels folded away or resized | `explico:layout:*` | The reader folds or drags a panel |
+| A part shown compact or labelled | `explico-sidebar-groups` | The reader clicks the part |
+| Which edition a lesson opens as, and whether the other is listed | `explico-sidebar-editions` | The reader switches either in the sidebar's foot |
+| A section folded or opened | `disclosure:<page>:<section>` | The reader folds or opens it (never on a mere visit) |
+| "Carry cards" on or off; card width; article kept left | `explico:cards:carry`, `explico:layout:side-card-width*`, `explico:layout:keep-article-left` | The reader sets it |
+
+These need no answer: each one is a choice the reader made, kept so it stays
+made.
+
+## Reading memory: kept only with the reader's yes
+
+| What | Key | With a yes | Without one |
+| --- | --- | --- | --- |
+| The chapters a reader opened, as they were (the sidebar marks; the line under a changed page's title) | `explico-page-marks:<base>` | Recorded on each visit | Not recorded; no marks |
+| The cards kept open on a page | `explico:cards:<page>` | Kept in the browser | Kept for the tab only |
+| The cards carried from page to page | `explico:cards:carried:<base>` | Kept in the browser | Kept for the tab only |
+| The frame and step each deck stopped at, and the frames Present mode showed, as they were (each slide's "Shown" or "Not shown yet" on a deck's page, its slide map; "Continue at slide N") | `explico:decks:<base>` | Recorded as the reader presents; the frames the tab recorded before the yes are kept with it | Before an answer, kept and marked for the tab only; after a no, the stopping place alone, for the tab: the frames shown are cleared, and none is recorded |
+
+The course asks once ("Remember your reading?", `readingMemory: "ask"`, the
+default), at the bottom of the window, with two answers of equal weight. Until
+the reader answers, nothing of their reading outlives the tab. A no deletes
+any reading memory at once. The answer (`explico-reading-memory:<base>`) is
+the one thing kept without asking, as storing a consent choice is, and stands
+for 13 months. The `[?]` panel's "In this browser" section changes it, and
+"Forget what this course stored" deletes every key above for the course and
+asks again. `readingMemory: "off"` never asks and never keeps reading memory.
+
+## For the course's own privacy notice
+
+- The site's host sees each request, as any web server does: GitHub Pages,
+  Cloudflare Pages or the course's own server keeps its access logs under its
+  own privacy terms. Name the host.
+- Anything the course adds outside explico changes this page: an analytics
+  script, fonts or scripts from a CDN, an embedded video. Each sends the
+  reader's address to another site, and most need consent of their own.
+- `src/session/reading-memory.ts` is the source of truth for what counts as
+  reading memory; `tests/e2e/reading-memory.spec.ts` in the playground checks
+  that an unanswered browser keeps nothing of the reading.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "explico",
-  "version": "0.13.1",
+  "version": "0.14.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",
@@ -31,11 +31,15 @@
     "CHANGELOG.md",
     "docs/VERSIONING.md",
     "docs/katex-bracket-scaling.md",
-    "docs/authoring"
+    "docs/diagram-scaling.md",
+    "docs/privacy.md",
+    "docs/authoring",
+    "docs/course-agent"
   ],
   "dependencies": {
     "@dagrejs/dagre": "3.1.1",
     "esbuild": "0.27.7",
+    "github-slugger": "2.0.0",
     "mdast-util-gfm-table": "2.0.0",
     "mdast-util-math": "3.0.0",
     "mdast-util-to-markdown": "2.1.2",
@@ -70,7 +74,9 @@
   },
   "scripts": {
     "build": "tsup && node scripts/copy-assets.mjs && node scripts/fix-esm-extensions.mjs && tsc -p tsconfig.dts-mjs.json && node scripts/gen-rules-schema.mjs",
+    "check:dist-imports": "node scripts/check-dist-imports.mjs",
     "check:release-migration": "node scripts/check-release-migration.mjs",
+    "release": "node scripts/release.mjs",
     "test": "vitest run",
     "test:watch": "vitest"
   }

package/src/compiler/astro.ts

@@ -12,7 +12,11 @@ import {
   writeManifest,
 } from './manifest';
 import { missingNotationPayloadKeys } from '../reference/page-notation';
-import { assertFigureSymbolsBound } from '../reference/figure-symbols';
+import {
+  assertNoUnboundFigureSymbols,
+  unboundFigureSymbols,
+  type PageUnboundFigureSymbols,
+} from '../reference/figure-symbols';
 import { undrawnFigurePictures, undrawnFigureWarning } from '../reference/figure-pictures';
 import {
   pageRenderDiagnostics,
@@ -25,7 +29,8 @@ import { writeLatexExports } from './exports/latex-export';
 import { writeMarkdownExports } from './exports/markdown-export';
 import { prepareChapters } from './exports/export-chapters';
 import { writeDownloadIndex } from './exports/download-index';
-import { standaloneFilename, standalonePageSlugs } from './exports/export-pages';
+import { checkFrameFit } from './exports/deck-fit';
+import { standaloneDownloads, standaloneFilename } from './exports/export-pages';
 import remarkAbbreviations from '../reference/remark-abbreviations.mjs';
 import remarkCitation from '../reference/remark-citation.mjs';
 import remarkNotation from '../reference/remark-notation.mjs';
@@ -160,10 +165,11 @@ type MarkdownConfig = AstroConfig['markdown'];
 
 /**
  * Every configured remark plugin, regardless of which of Astro's two
- * mutually-exclusive wiring surfaces a course uses: the deprecated flat
- * `markdown.remarkPlugins` array, or a `markdown.processor` (e.g.
- * `unified({ remarkPlugins })`) whose own `options.remarkPlugins` a
- * non-`unified` processor (e.g. `satteri()`) may not have at all.
+ * mutually-exclusive wiring surfaces a course uses: a `markdown.processor`
+ * (e.g. `unified({ remarkPlugins })`, the form Astro 7.3 asks for) whose own
+ * `options.remarkPlugins` a non-`unified` processor (e.g. `satteri()`) may not
+ * have at all, or the flat `markdown.remarkPlugins` array Astro 7.3 deprecates
+ * and a course not yet moved still has.
  */
 function configuredRemarkPlugins(markdown: MarkdownConfig): readonly unknown[] {
   const direct = markdown?.remarkPlugins ?? [];
@@ -200,22 +206,24 @@ export function assertRemarkPluginsWired(
     !remarkPluginIsWired(remarkPlugins, remarkAbbreviations)
   ) {
     missing.push(
-      `remarkAbbreviations is missing from markdown.remarkPlugins, but ` +
+      `remarkAbbreviations is missing from the remark plugins of astro.config.mjs, but ` +
         `manifest.abbreviations has ${manifest.abbreviations.length} ` +
         `entr${manifest.abbreviations.length === 1 ? 'y' : 'ies'}. Import it from ` +
         `'explico/reference/remark-abbreviations.mjs' and add ` +
-        `[remarkAbbreviations, { abbreviations: manifest.abbreviations }] to ` +
-        `markdown.remarkPlugins — see docs/authoring/migrating.md#4-rule-n14.`,
+        `[remarkAbbreviations, { abbreviations: manifest.abbreviations }] to the ` +
+        `\`remarkPlugins\` of \`markdown.processor: unified({ … })\` — see ` +
+        `docs/authoring/migrating.md#4-rule-n14.`,
     );
   }
 
   if (manifest.sources.length > 0 && !remarkPluginIsWired(remarkPlugins, remarkCitation)) {
     missing.push(
-      `remarkCitation is missing from markdown.remarkPlugins, but ` +
+      `remarkCitation is missing from the remark plugins of astro.config.mjs, but ` +
         `manifest.sources has ${manifest.sources.length} ` +
         `entr${manifest.sources.length === 1 ? 'y' : 'ies'}. Import it from ` +
         `'explico/reference/remark-citation.mjs' and add ` +
-        `[remarkCitation, { sources: manifest.sources }] to markdown.remarkPlugins.`,
+        `[remarkCitation, { sources: manifest.sources }] to the \`remarkPlugins\` of ` +
+        `\`markdown.processor: unified({ … })\`.`,
     );
   }
 
@@ -224,11 +232,12 @@ export function assertRemarkPluginsWired(
     !remarkPluginIsWired(remarkPlugins, remarkNotation)
   ) {
     missing.push(
-      `remarkNotation is missing from markdown.remarkPlugins, but ` +
+      `remarkNotation is missing from the remark plugins of astro.config.mjs, but ` +
         `manifest.notation.raw has ${manifest.notation.raw.length} ` +
         `entr${manifest.notation.raw.length === 1 ? 'y' : 'ies'}. Import it from ` +
         `'explico/reference/remark-notation.mjs' and add ` +
-        `[remarkNotation, createRemarkNotationOptions(manifest)] to markdown.remarkPlugins.`,
+        `[remarkNotation, createRemarkNotationOptions(manifest)] to the \`remarkPlugins\` of ` +
+        `\`markdown.processor: unified({ … })\`.`,
     );
   }
 
@@ -243,25 +252,41 @@ export function assertRemarkPluginsWired(
 
 /**
  * Check every built page, and return the findings only a rendered page gives
- * (`render-diagnostics.ts`) for `content warnings`.
+ * (`render-diagnostics.ts`) for `content warnings`. A page that fails a check
+ * does not stop the walk: every page is read first, then the build throws once
+ * with the whole list, so it reports each page at once and not one per run.
+ * Exported for the test.
  */
-async function validateGeneratedPages(
+export async function validateGeneratedPages(
   directory: URL,
-  manifest: Manifest,
+  manifest: Pick<Manifest, 'lessons'>,
   warn: (message: string) => void,
 ): Promise<RenderDiagnostic[]> {
   const root = fileURLToPath(directory);
   const rendered: RenderDiagnostic[] = [];
+  const failures: string[] = [];
+  const unbound: PageUnboundFigureSymbols[] = [];
+  const messageOf = (error: unknown): string =>
+    error instanceof Error ? error.message : String(error);
   const walk = async (path: string): Promise<void> => {
-    for (const entry of await readdir(path, { withFileTypes: true })) {
+    // A fixed order, so the list a build prints is the same on every machine.
+    const entries = (await readdir(path, { withFileTypes: true })).sort((a, b) =>
+      a.name.localeCompare(b.name),
+    );
+    for (const entry of entries) {
       const child = join(path, entry.name);
       if (entry.isDirectory()) {
         await walk(child);
       } else if (entry.isFile() && entry.name.endsWith('.html')) {
         const html = await readFile(child, 'utf8');
         const page = relative(root, child);
-        assertNotationPayloadHtml(page, html);
-        assertFigureSymbolsBound(page, html);
+        try {
+          assertNotationPayloadHtml(page, html);
+        } catch (error) {
+          failures.push(messageOf(error));
+        }
+        const figures = unboundFigureSymbols(html);
+        if (figures.length > 0) unbound.push({ page, figures });
         const undrawn = undrawnFigurePictures(html);
         if (undrawn.length > 0) warn(undrawnFigureWarning(page, undrawn));
         rendered.push(...pageRenderDiagnostics(manifest, page, html));
@@ -269,6 +294,12 @@ async function validateGeneratedPages(
     }
   };
   await walk(root);
+  try {
+    assertNoUnboundFigureSymbols(unbound);
+  } catch (error) {
+    failures.push(messageOf(error));
+  }
+  if (failures.length > 0) throw new Error(failures.join('\n\n'));
   return rendered;
 }
 
@@ -407,7 +438,7 @@ export function explicoContentRefresh(
             const slug = matchStandaloneDownload(
               pathname,
               configuredDevelopment.base,
-              standalonePageSlugs(manifest),
+              standaloneDownloads(manifest).map(({ download }) => download),
             );
             if (!slug) return next();
 
@@ -419,7 +450,7 @@ export function explicoContentRefresh(
               );
               developmentDownloads ??= buildDevelopmentDownloads(
                 configuredDevelopment,
-                standalonePageSlugs(manifest),
+                standaloneDownloads(manifest).map(({ download }) => download),
               );
               const currentDownloads = developmentDownloads;
               currentDownloads.catch(() => {
@@ -456,6 +487,14 @@ export function explicoContentRefresh(
         for (const diagnostic of writeRenderDiagnostics(rendered)) {
           logger.warn(`[${diagnostic.code}] ${diagnostic.file}: ${diagnostic.message}`);
         }
+        // Rule D2: every frame of every deck fits its canvas, measured in a browser.
+        const overflowing = await checkFrameFit(fileURLToPath(dir), manifest, { logger });
+        if (overflowing.length > 0) {
+          throw new Error(
+            `${overflowing.length} deck frame(s) do not fit their canvas (rule D2, frame-overflow):\n` +
+              overflowing.map((finding) => `  - ${finding.message}`).join('\n'),
+          );
+        }
         await writeStandaloneLessonExports(dir, manifest);
         await writeCombinedExports(dir, manifest);
         // The print exports share one reading of the chapters and one