explico 0.12.0 → 0.13.1

package/dist/compiler/exports/latex/explico.cls

@@ -0,0 +1,415 @@
+%% explico.cls — the book class of a course's LaTeX source.
+%%
+%% explico writes this file next to every LaTeX download, and builds the PDF
+%% it offers from that same folder. Edit it freely in a download: it only sets
+%% the layout and defines the commands the chapter files use.
+%%
+%% Engines: LuaLaTeX (preferred) or pdfLaTeX, TeX Live 2025 or later.
+%%
+%% Numbering follows the course website: parts and chapters are numbered
+%% ‹part›.‹chapter›, sections ‹part›.‹chapter›.‹section›, and equations,
+%% figures, tables, diagrams, worked examples and knowledge checks run per
+%% chapter (‹part›.‹chapter›.‹n›) or, with \ExplicoFloatsByPart, per part
+%% (‹part›.‹n›). LaTeX does the counting; explico checks every number against
+%% the website when it builds the PDF.
+\NeedsTeXFormat{LaTeX2e}
+\ProvidesClass{explico}[2026/10/04 explico course book class]
+
+%% `scripts`: the document holds Greek, Cyrillic, CJK or emoji (the exporter
+%% sets it when it does), so LuaLaTeX loads the fallback fonts below.
+\newif\ifexplico@scripts
+\DeclareOption{scripts}{\explico@scriptstrue}
+\DeclareOption*{\PassOptionsToClass{\CurrentOption}{book}}
+\ProcessOptions\relax
+\LoadClass[11pt,oneside,openany]{book}
+
+%% --- Engine and fonts ------------------------------------------------------
+\RequirePackage{iftex}
+\RequirePackage{amsmath,amssymb,mathtools}
+%% Rule N17's engine half, as on the website (src/reference/katex-delimiters.mjs):
+%% a negative \delimitershortfall makes every \left...\right pair strictly taller
+%% than its content, so a nest grows outward at each level. TeX's default (5pt)
+%% lets nested pairs round to the same glyph.
+\delimitershortfall=-1pt
+%% Whether a text font sets Greek; if none does, a Greek letter in prose is
+%% set as its math symbol (below, with the other Unicode characters).
+\newif\ifexplico@greek
+\ifPDFTeX
+  \RequirePackage[T1]{fontenc}
+  \RequirePackage{lmodern}
+  \RequirePackage{textcomp}
+  \RequirePackage{bm}
+  %% A character no pdfTeX font sets (accented Greek, Chinese, an emoji) stays
+  %% blank instead of stopping the compile, and the log says so in LuaLaTeX's
+  %% words, which the export turns into its warning about blank characters.
+  \def\UTFviii@undefined@err#1{%
+    \typeout{Missing character: There is no
+      \expandafter\UTFviii@splitcsname\string#1\relax\space in font pdftex!}}
+\else
+  %% Latin Modern for text and math. unicode-math is also what lets a tagged
+  %% PDF carry MathML for every formula (luamml needs it); bm does not work
+  %% with it, so \bm becomes \boldsymbol.
+  \RequirePackage{unicode-math}
+  \providecommand{\bm}{\boldsymbol}
+  %% Latin Modern has no Greek, Cyrillic, Chinese, Japanese, Korean or emoji.
+  %% With `scripts`, prose in those scripts comes from fallback fonts: for each
+  %% script, the first of the fonts below this machine has (CMU Serif, from
+  %% TeX Live's cm-unicode, matches Latin Modern). A script none of them
+  %% covers stays blank, and the export warns about it.
+  \ifexplico@scripts
+  \def\explico@fallbacks{}
+  \def\explico@fallback#1#2{%
+    \let\explico@found\@empty
+    \@for\explico@candidate:=#1\do{%
+      \ifx\explico@found\@empty
+        \IfFontExistsTF{\explico@candidate}{%
+          \edef\explico@fallbacks{\explico@fallbacks"\explico@candidate:mode=harf;",}%
+          \let\explico@found\explico@candidate}{}%
+      \fi}%
+    \ifx\explico@found\@empty\else#2\fi}
+  \explico@fallback{CMU Serif,Noto Serif,DejaVu Serif,FreeSerif}{\explico@greektrue}
+  \explico@fallback{Noto Serif CJK SC,Noto Sans CJK SC,FandolSong,Source Han Serif SC}{}
+  \explico@fallback{Noto Color Emoji,Twemoji Mozilla,Symbola}{}
+  \ifx\explico@fallbacks\@empty\else
+    \directlua{luaotfload.add_fallback("explico", {\explico@fallbacks})}%
+    \setmainfont{Latin Modern Roman}[RawFeature={fallback=explico}]%
+  \fi
+  \fi
+\fi
+\RequirePackage{microtype}
+
+%% --- Page and colour --------------------------------------------------------
+\RequirePackage[margin=1in]{geometry}
+\RequirePackage{xcolor}
+\definecolor{explicoaccent}{HTML}{12775C}
+\definecolor{explicoframe}{HTML}{9DB8AD}
+\definecolor{explicoback}{HTML}{F3F8F6}
+\definecolor{explicoasidecaution}{HTML}{B5651D}
+\definecolor{explicoasidecautionback}{HTML}{FBF3EA}
+\definecolor{explicorule}{HTML}{8A9A93}
+
+%% --- Floats, tables and captions -------------------------------------------
+\RequirePackage{graphicx}
+\RequirePackage{array,booktabs,tabularx,longtable}
+\RequirePackage[export]{adjustbox}
+\RequirePackage{caption}
+\RequirePackage{newfloat}
+\DeclareFloatingEnvironment[
+  name=Diagram,
+  listname={List of Diagrams},
+  fileext=lod,
+  placement=htbp,
+]{diagram}
+%% Tagging names each float type's structures from TeX Live 2026 on, and a
+%% caption in a type it was not told about stops LuaLaTeX. TeX Live 2025 has
+%% no such key and tags every float alike.
+\ExplSyntaxOn
+\keys_if_exist:nnT { __tag/setup } { float/new }
+  { \tagpdfsetup { float/new = diagram } }
+\ExplSyntaxOff
+%% Contents and lists: room for explico's numbers (`2.1`, `2.1.10`), wider
+%% than the book class's one-level chapter numbers.
+\RequirePackage{etoolbox}
+\patchcmd{\l@chapter}{1.5em}{2.6em}{}{}
+\renewcommand*{\l@section}{\@dottedtocline{1}{2.6em}{3.4em}}
+\renewcommand*{\l@subsection}{\@dottedtocline{2}{6.0em}{4.2em}}
+\renewcommand*{\l@figure}{\@dottedtocline{1}{0em}{3.4em}}
+\let\l@table\l@figure
+\let\l@diagram\l@figure
+\captionsetup{font=small,labelsep=quad,format=plain,justification=justified,singlelinecheck=true}
+\captionsetup[table]{position=top}
+%% With \DocumentMetadata, which every export's main.tex has, the kernel's
+%% tagging code sets a caption itself (latex-lab's \@makecaption, installed at
+%% begin document) and none of the \captionsetup above applies. Its caption is
+%% the kernel's: \abovecaptionskip above, \belowcaptionskip below, "Table 2.1:"
+%% before the text. A table's caption stands above the table, so it gets the
+%% same space on both sides, whichever code sets it (the caption package swaps
+%% the two for `position=top`); and the label and the size are the ones the
+%% caption package would give, and the web page shows: "Table 2.1", a quad,
+%% the caption in small type.
+\AtBeginEnvironment{table}{%
+  \setlength{\abovecaptionskip}{8pt}\setlength{\belowcaptionskip}{8pt}}
+\ExplSyntaxOn
+\socket_if_exist:nT { caption/label }
+  {
+    \NewSocketPlug { caption/label } { explico } { #1 \quad }
+    \AssignSocketPlug { caption/label } { explico }
+    \AddToHookWithArguments { cmd/@makecaption/before } { \small }
+  }
+\ExplSyntaxOff
+%% A float set where it stands, inside a memo or a worked example, which a
+%% float cannot leave: the float package's [H]. Tagging then gives the float
+%% its caption, as PDF/UA-2 asks. (TeX Live 2026 tags a minipage as a Div,
+%% which a validator looks through, so a \captionof caption in one sits in
+%% the middle of the box's text.) Without the float package: a minipage whose
+%% \caption is the float's, as \captionof does it.
+\newif\ifexplico@float
+\IfFileExists{float.sty}{\RequirePackage{float}\explico@floattrue}{}
+\ifexplico@float
+  \newenvironment{ExplicoHere}[1]{%
+    \def\explico@herekind{#1}\begin{#1}[H]\centering
+  }{\expandafter\end\expandafter{\explico@herekind}}
+\else
+  \newenvironment{ExplicoHere}[1]{%
+    \par\medskip\noindent\begin{minipage}{\linewidth}\centering
+    \captionsetup{type=#1}%
+  }{\end{minipage}\par\medskip}
+\fi
+%% explico's short caption, run in bold before the long one.
+\newcommand*{\ExplicoCaptionTitle}[1]{\textbf{#1}}
+
+%% --- Diagrams ---------------------------------------------------------------
+\RequirePackage{tikz}
+\usetikzlibrary{arrows.meta}
+\tikzset{
+  explico diagram node/.style={
+    draw=explicorule, fill=explicoback, rounded corners=3pt, line width=0.5pt,
+    align=center, inner sep=3pt, font=\small,
+  },
+  explico diagram edge/.style={
+    draw=explicorule, line width=0.6pt, -{Stealth[length=5pt,width=4pt]},
+  },
+}
+
+%% --- Boxes: memos, notes, asides, worked examples, checks ------------------
+\RequirePackage[most]{tcolorbox}
+\tcbset{
+  explico/.style={
+    enhanced, breakable, colback=explicoback, colframe=explicoframe,
+    boxrule=0.5pt, arc=2pt, left=6pt, right=6pt, top=4pt, bottom=4pt,
+    fonttitle=\bfseries\small, coltitle=black, colbacktitle=explicoback!60!white,
+    titlerule=0.4pt, before skip=10pt plus 2pt, after skip=10pt plus 2pt,
+  },
+}
+\RequirePackage{alphalph}
+\RequirePackage{enumitem}
+
+%% --- Unicode in text that the default fonts lack ---------------------------
+\RequirePackage{newunicodechar}
+\newunicodechar{°}{\ifmmode^\circ\else\textdegree\fi}
+\newunicodechar{−}{\ensuremath{-}}
+\newunicodechar{×}{\ensuremath{\times}}
+\newunicodechar{±}{\ensuremath{\pm}}
+\newunicodechar{≤}{\ensuremath{\le}}
+\newunicodechar{≥}{\ensuremath{\ge}}
+\newunicodechar{≈}{\ensuremath{\approx}}
+\newunicodechar{≠}{\ensuremath{\neq}}
+\newunicodechar{→}{\ensuremath{\rightarrow}}
+\newunicodechar{←}{\ensuremath{\leftarrow}}
+\newunicodechar{↑}{\ensuremath{\uparrow}}
+\newunicodechar{↓}{\ensuremath{\downarrow}}
+\newunicodechar{⟨}{\ensuremath{\langle}}
+\newunicodechar{⟩}{\ensuremath{\rangle}}
+\newunicodechar{⋮}{\ensuremath{\vdots}}
+\newunicodechar{√}{\ensuremath{\surd}}
+\newunicodechar{∞}{\ensuremath{\infty}}
+\newunicodechar{′}{\ensuremath{'}}
+\newunicodechar{𝒩}{\ensuremath{\mathcal{N}}}
+\newunicodechar{①}{\textcircled{\scriptsize 1}}
+\newunicodechar{②}{\textcircled{\scriptsize 2}}
+\newunicodechar{③}{\textcircled{\scriptsize 3}}
+\newunicodechar{④}{\textcircled{\scriptsize 4}}
+\newunicodechar{⑤}{\textcircled{\scriptsize 5}}
+\newunicodechar{₀}{\textsubscript{0}}
+\newunicodechar{₁}{\textsubscript{1}}
+\newunicodechar{₂}{\textsubscript{2}}
+\newunicodechar{₃}{\textsubscript{3}}
+\newunicodechar{¹}{\textsuperscript{1}}
+\newunicodechar{²}{\textsuperscript{2}}
+\newunicodechar{³}{\textsuperscript{3}}
+%% A Greek letter on its own is a symbol (the polar coordinates ρ and φ in a
+%% caption, which holds no math): it is set as its math symbol. Inside a Greek
+%% word, which the exporter marks \ExplicoGreekWord{…}, it is a letter, set
+%% from the text font's Greek where one is loaded (`scripts`).
+\newif\ifexplico@word
+\DeclareRobustCommand{\ExplicoGreekWord}[1]{{\explico@wordtrue#1}}
+%% Protected, as \ensuremath is: the text of an equation is expanded for its
+%% tagging (alt text, MathML), and an expandable body breaks it there.
+\protected\def\explico@greekletter#1#2{%
+  \ifmmode#2\else
+    \ifexplico@word
+      \ifexplico@greek\char#1\relax\else\ensuremath{#2}\fi
+    \else\ensuremath{#2}\fi
+  \fi}
+\newunicodechar{α}{\explico@greekletter{"03B1}{\alpha}}
+\newunicodechar{β}{\explico@greekletter{"03B2}{\beta}}
+\newunicodechar{γ}{\explico@greekletter{"03B3}{\gamma}}
+\newunicodechar{δ}{\explico@greekletter{"03B4}{\delta}}
+\newunicodechar{ε}{\explico@greekletter{"03B5}{\varepsilon}}
+\newunicodechar{θ}{\explico@greekletter{"03B8}{\theta}}
+\newunicodechar{λ}{\explico@greekletter{"03BB}{\lambda}}
+\newunicodechar{μ}{\explico@greekletter{"03BC}{\mu}}
+\newunicodechar{π}{\explico@greekletter{"03C0}{\pi}}
+\newunicodechar{ρ}{\explico@greekletter{"03C1}{\rho}}
+\newunicodechar{σ}{\explico@greekletter{"03C3}{\sigma}}
+\newunicodechar{τ}{\explico@greekletter{"03C4}{\tau}}
+\newunicodechar{φ}{\explico@greekletter{"03C6}{\varphi}}
+\newunicodechar{ω}{\explico@greekletter{"03C9}{\omega}}
+\newunicodechar{Γ}{\explico@greekletter{"0393}{\Gamma}}
+\newunicodechar{Δ}{\explico@greekletter{"0394}{\Delta}}
+\newunicodechar{Θ}{\explico@greekletter{"0398}{\Theta}}
+\newunicodechar{Λ}{\explico@greekletter{"039B}{\Lambda}}
+\newunicodechar{Π}{\explico@greekletter{"03A0}{\Pi}}
+\newunicodechar{Σ}{\explico@greekletter{"03A3}{\Sigma}}
+\newunicodechar{Φ}{\explico@greekletter{"03A6}{\Phi}}
+\newunicodechar{Ω}{\explico@greekletter{"03A9}{\Omega}}
+
+%% --- Links ------------------------------------------------------------------
+\RequirePackage[colorlinks,linkcolor=explicoaccent,urlcolor=explicoaccent,citecolor=explicoaccent,bookmarksnumbered]{hyperref}
+\pdfstringdefDisableCommands{\let\ExplicoGreekWord\@firstofone}
+
+%% --- Numbering --------------------------------------------------------------
+\renewcommand{\thepart}{\arabic{part}}
+\counterwithin*{chapter}{part}
+\renewcommand{\thechapter}{\thepart.\arabic{chapter}}
+\newcounter{explicoexample}
+\newcounter{explicocheck}
+\newcounter{explicomemo}[chapter]
+\renewcommand{\theexplicomemo}{\alphalph{\value{explicomemo}}}
+\counterwithin{equation}{chapter}
+\counterwithin{figure}{chapter}
+\counterwithin{table}{chapter}
+\counterwithin{diagram}{chapter}
+\counterwithin{explicoexample}{chapter}
+\counterwithin{explicocheck}{chapter}
+%% Floats, examples and checks run on across each part's chapters.
+\newcommand{\ExplicoFloatsByPart}{%
+  \@for\explico@kind:=equation,figure,table,diagram,explicoexample,explicocheck\do{%
+    \expandafter\counterwithout\expandafter{\explico@kind}{chapter}%
+    \expandafter\counterwithin\expandafter{\explico@kind}{part}%
+  }%
+}
+%% Outline numbering down to explico's `numbering.sections.depth`
+%% (2 = ## … 6 = ######); 1 numbers no sections.
+\newcommand{\ExplicoSectionDepth}[1]{%
+  \setcounter{secnumdepth}{\numexpr#1-1\relax}%
+  \setcounter{tocdepth}{\numexpr#1-1\relax}%
+}
+\ExplicoSectionDepth{4}
+%% A chapter on its own starts where the course leaves it: part and chapter
+%% number, and how many floats of each kind come earlier in the part.
+%% #1 part, #2 chapter, #3 equations, #4 tables, #5 figures, #6 diagrams,
+%% #7 checks, #8 examples.
+\newcommand{\ExplicoStartChapterAt}[8]{%
+  \setcounter{part}{#1}%
+  \setcounter{chapter}{\numexpr#2-1\relax}%
+  \gdef\explico@offsets{{#3}{#4}{#5}{#6}{#7}{#8}}%
+}
+\gdef\explico@offsets{}
+%% After \chapter, so a chapter's own reset cannot undo them.
+\newcommand{\ExplicoApplyOffsets}{%
+  \ifx\explico@offsets\@empty\else
+    \expandafter\explico@applyoffsets\explico@offsets
+    \gdef\explico@offsets{}%
+  \fi
+}
+\newcommand{\explico@applyoffsets}[6]{%
+  \setcounter{equation}{#1}\setcounter{table}{#2}\setcounter{figure}{#3}%
+  \setcounter{diagram}{#4}\setcounter{explicocheck}{#5}\setcounter{explicoexample}{#6}%
+}
+
+%% --- Chapter front line -----------------------------------------------------
+%% Under a chapter's title: where it comes from and where its live version is.
+\newcommand{\ExplicoSource}[3]{%
+  \begingroup\small\color{black!65}%
+  \noindent From \emph{#1}%
+  \if\relax\detokenize{#2}\relax\else, version~#2\fi.%
+  \if\relax\detokenize{#3}\relax\else\ Interactive version: \url{#3}\fi
+  \par\endgroup\medskip
+}
+
+%% --- Books: a part's or the course's PDF ------------------------------------
+%% The title page. #1 title, #2 what it belongs to (empty for the course),
+%% #3 content version, #4 authors, #5 website.
+\newcommand{\ExplicoTitlePage}[5]{%
+  %% The title page shares page number i with the contents: no anchor of its own.
+  \hypersetup{pageanchor=false}%
+  \begin{titlepage}
+    \centering
+    \vspace*{0.18\textheight}
+    {\Huge\bfseries #1\par}
+    \if\relax\detokenize{#2}\relax\else\vspace{0.8em}{\Large #2\par}\fi
+    \if\relax\detokenize{#4}\relax\else\vspace{2.5em}{\large #4\par}\fi
+    \vfill
+    {Content version~#3\par}
+    \if\relax\detokenize{#5}\relax\else\vspace{0.4em}{\small\url{#5}\par}\fi
+  \end{titlepage}%
+  \hypersetup{pageanchor=true}%
+}
+%% Under a chapter's title in a book: its live version. The title page names
+%% the course and its version once.
+\newcommand{\ExplicoInteractive}[1]{%
+  \begingroup\small\color{black!65}%
+  \noindent Interactive version: \url{#1}\par\endgroup\medskip
+}
+%% A part opens on its own page, numbered as on the website.
+\newcommand{\ExplicoPart}[2]{\setcounter{part}{\numexpr#1-1\relax}\part{#2}}
+
+%% --- Notation ---------------------------------------------------------------
+%% \explain{key}{tex} and \slot{key}{tex} are explico's markers in math: the
+%% website opens a card for the key; on paper they print their content.
+\providecommand{\explain}[2]{#2}
+\providecommand{\slot}[2]{#2}
+%% \ExplicoNotation{target}{tex}: a formula's symbol that links to its notation entry
+%% (the serializer writes it only where the book has that entry).
+\providecommand{\ExplicoNotation}[2]{\hyperlink{#1}{#2}}
+%% A term in prose with a notation card on the website.
+\newcommand{\ExplicoTerm}[2]{#2}
+
+%% --- Cross-references ---------------------------------------------------------
+%% #1 label, #2 text before the number, #3 text after it.
+\newcommand{\ExplicoRef}[3]{\hyperref[#1]{#2\ref*{#1}#3}}
+\newcommand{\ExplicoEqRef}[1]{\hyperref[#1]{(\ref*{#1})}}
+
+%% --- Memos --------------------------------------------------------------------
+\newenvironment{ExplicoMemo}[1]{%
+  \refstepcounter{explicomemo}%
+  \begin{tcolorbox}[explico,title={Memo~\theexplicomemo:\enspace #1}]%
+}{\end{tcolorbox}}
+\newcommand{\ExplicoMemoMark}[1]{\textsuperscript{\hyperref[#1]{\ref*{#1}}}}
+
+%% --- Short notes ----------------------------------------------------------------
+\newenvironment{ExplicoNote}[2]{%
+  \begin{tcolorbox}[explico,colback=white,title={#2}]%
+  \hypertarget{#1}{}%
+}{\end{tcolorbox}}
+\newcommand{\ExplicoNoteMark}[2]{\hyperlink{#1}{#2}}
+
+%% --- Starlight asides -------------------------------------------------------------
+\newenvironment{ExplicoAside}[2]{%
+  \def\explico@variant{#1}\def\explico@caution{caution}\def\explico@danger{danger}%
+  \ifx\explico@variant\explico@caution
+    \tcbset{explico/.append style={colframe=explicoasidecaution,colback=explicoasidecautionback}}%
+  \else\ifx\explico@variant\explico@danger
+    \tcbset{explico/.append style={colframe=explicoasidecaution,colback=explicoasidecautionback}}%
+  \fi\fi
+  \begin{tcolorbox}[explico,title={#2}]%
+}{\end{tcolorbox}}
+
+%% --- Worked examples ---------------------------------------------------------------
+\newenvironment{ExplicoExamples}[1]{%
+  \refstepcounter{explicoexample}%
+  \begin{tcolorbox}[explico,title={Example~\theexplicoexample:\enspace #1}]%
+}{\end{tcolorbox}}
+\newcommand{\ExplicoExample}[1]{\par\medskip\noindent\textbf{#1}\par\nopagebreak\smallskip}
+
+%% --- Knowledge checks -----------------------------------------------------------
+\newenvironment{ExplicoCheck}[1]{%
+  \refstepcounter{explicocheck}%
+  \begin{tcolorbox}[explico,colback=white,title={Knowledge check~\theexplicocheck:\enspace #1}]%
+}{\end{tcolorbox}}
+\newcommand{\ExplicoCheckAnswerNote}[1]{\par\smallskip{\small\itshape Answers: \hyperlink{#1}{end of the chapter}.}\par}
+
+%% --- References ---------------------------------------------------------------------
+%% The chapter's reference list, numbered as on the website.
+\newenvironment{ExplicoReferences}[1]{%
+  \section*{References}%
+  \list{\@biblabel{\@arabic\c@enumiv}}{%
+    \settowidth\labelwidth{\@biblabel{#1}}%
+    \leftmargin\labelwidth\advance\leftmargin\labelsep
+    \@openbib@code\usecounter{enumiv}\let\p@enumiv\@empty
+    \renewcommand\theenumiv{\@arabic\c@enumiv}}%
+  \sloppy\clubpenalty4000\@clubpenalty\clubpenalty\widowpenalty4000\sfcode`\.\@m
+}{\def\@noitemerr{\@latex@warning{Empty `ExplicoReferences' environment}}\endlist}
+
+\endinput

package/dist/compiler/exports/latex/numbering.d.ts

@@ -0,0 +1,18 @@
+import { StaticPage } from '../static-tree.js';
+import '../html-tree.js';
+import 'parse5';
+
+/**
+ * The LaTeX source counts its own numbers (`\label`, `\ref`), so an edited
+ * download renumbers itself. When explico compiles the source unchanged,
+ * every number LaTeX prints must be the number the website prints: this
+ * module reads both and lists any disagreement, which fails the build.
+ */
+/** The number the website gives each labelled anchor of a page, by LaTeX label. */
+declare function websiteNumbers(page: StaticPage, chapterNumber: string): Map<string, string>;
+/** `\newlabel{label}{{number}{page}…}` lines of a LaTeX `.aux` file. */
+declare function auxLabels(aux: string): Map<string, string>;
+/** Every label whose LaTeX number differs from the website's, or that LaTeX never set. */
+declare function numberingMismatches(website: ReadonlyMap<string, string>, latex: ReadonlyMap<string, string>): string[];
+
+export { auxLabels, numberingMismatches, websiteNumbers };

package/dist/compiler/exports/latex/numbering.js

@@ -0,0 +1,57 @@
+import { labelOf } from "./serialize.js";
+function websiteNumbers(page, chapterNumber) {
+  const numbers = /* @__PURE__ */ new Map([[labelOf(page.route, "_top"), chapterNumber]]);
+  const add = (anchor, number) => {
+    if (anchor && number) numbers.set(labelOf(page.route, anchor), number);
+  };
+  const visit = (blocks) => {
+    for (const block of blocks) {
+      switch (block.kind) {
+        case "heading":
+          add(block.anchor, block.number);
+          break;
+        case "equation":
+        case "figure":
+        case "table":
+        case "diagram":
+        case "examples":
+        case "check":
+          add(block.anchor, block.number);
+          break;
+        case "memo":
+          add(block.anchor, block.label);
+          break;
+        default:
+          break;
+      }
+      if (block.kind === "list") block.items.forEach(visit);
+      if (block.kind === "examples") block.items.forEach((item) => visit(item.children));
+      if ("children" in block && block.kind !== "paragraph" && block.kind !== "heading" && Array.isArray(block.children)) {
+        visit(block.children);
+      }
+    }
+  };
+  visit(page.blocks);
+  return numbers;
+}
+function auxLabels(aux) {
+  const labels = /* @__PURE__ */ new Map();
+  for (const match of aux.matchAll(/^\\newlabel\{([^}]*)\}\{\{([^}]*)\}/gmu)) {
+    labels.set(match[1], match[2]);
+  }
+  return labels;
+}
+function numberingMismatches(website, latex) {
+  const problems = [];
+  for (const [label, expected] of website) {
+    const actual = latex.get(label);
+    if (actual === void 0) problems.push(`${label}: no number in LaTeX (website: ${expected})`);
+    else if (actual !== expected) problems.push(`${label}: LaTeX ${actual}, website ${expected}`);
+  }
+  return problems;
+}
+export {
+  auxLabels,
+  numberingMismatches,
+  websiteNumbers
+};

package/dist/compiler/exports/latex/serialize.d.ts

@@ -0,0 +1,112 @@
+import { ContentSegment } from '../../../reference/mixed-content.js';
+import { NotationEntry, StaticPage, DiagramGeometry, Inline } from '../static-tree.js';
+import '../../../reference/gate-math.js';
+import '../../../reference/types.js';
+import '../html-tree.js';
+import 'parse5';
+
+/**
+ * Serialize explico's static reading tree to the LaTeX of one chapter, written
+ * against `explico.cls`. The output is source a person can read and edit:
+ * explico's blocks are named environments, cross-references are `\ref`s to
+ * labels, and numbers are LaTeX's own (checked against the website after
+ * compiling, see `numbering.ts`).
+ */
+/** What the serializer needs to know beyond the page itself. */
+interface ChapterContext {
+    readonly page: StaticPage;
+    /** Routes of every page in this document; a reference to one becomes a `\ref`. */
+    readonly documentRoutes: ReadonlySet<string>;
+    /** Published course root, for links that leave the document. */
+    readonly canonicalBaseUrl?: string;
+    /** Picture files written for this chapter, by float anchor (`fig-…`), relative to the document. */
+    readonly pictures: ReadonlyMap<string, string>;
+    /** Answers of this chapter's checks, by assessment id, in authored order. */
+    readonly checkItems: ReadonlyMap<string, readonly CheckItem[]>;
+    /** Course title, version and the chapter's live URL for the front line. */
+    readonly source?: {
+        readonly course: string;
+        readonly version?: string;
+        readonly url?: string;
+    };
+    /**
+     * A chapter of a part's or the course's book: its citation keys gain the
+     * chapter (`projectiles/projectile-range/openstax`), since each chapter
+     * keeps its own reference list numbered as on its page; its notation is in
+     * the book's appendix, not after the chapter; and under its title is only
+     * the link to its live version, the title page naming the course.
+     */
+    readonly inBook?: boolean;
+    /**
+     * Keys with an entry in the document's notation appendix, so a formula's
+     * `\explain{key}{…}` can link to it. Absent for a chapter's own document,
+     * which has no appendix: its markers print their TeX, as the class does.
+     */
+    readonly notationTargets?: ReadonlySet<string>;
+}
+interface CheckItem {
+    readonly itemId: string;
+    readonly type: 'single-choice' | 'numeric';
+    readonly promptSegments: readonly ContentSegment[];
+    readonly explanationSegments: readonly ContentSegment[];
+    readonly options?: readonly {
+        readonly id: string;
+        readonly label: string;
+        /** The label as text and math (manifest v30); without it, the label is text. */
+        readonly labelSegments?: readonly ContentSegment[];
+    }[];
+    readonly correctOptionId?: string;
+    readonly answer?: {
+        readonly value: number;
+        readonly tolerance: number;
+    };
+}
+/** A LaTeX label for an anchor on a page: unique across a whole book. */
+declare function labelOf(route: string, anchor: string): string;
+declare function escapeText(text: string): string;
+/**
+ * Rewrites each `\explain{key}{tex}` whose key `linkTo` names as
+ * `\ExplicoNotation{target}{tex}`, a link to the notation entry; any other
+ * marker stays, and the class prints its TeX. Brace-aware, so a body with
+ * nested groups is kept whole. A link cannot hold another, so the outermost
+ * linked marker wins: `\dot{x}` links to the time derivative, and the markers
+ * inside it print their TeX.
+ */
+declare function linkExplains(tex: string, linkTo: (key: string) => string | undefined): string;
+/**
+ * explico's `<Diagram>` in TikZ, from the layout Dagre gave it at build time:
+ * the same boxes and edges as the website, with LaTeX setting the text and the
+ * math. Coordinates are scaled to the text width; type keeps its size.
+ */
+declare function diagramTikz(geometry: DiagramGeometry, writer: {
+    inlines(inlines: readonly Inline[]): string;
+}): string;
+/** The LaTeX of one chapter: `\chapter`, its body, references, notation and answers. */
+declare function serializeChapter(context: ChapterContext): string;
+/**
+ * A part's opener in a book: `\ExplicoPart`, numbered as on the website, then
+ * the text of the part's own page (its introduction, scope and objectives).
+ */
+declare function serializePartOpener(context: ChapterContext, part: {
+    readonly ordinal: number;
+    readonly label: string;
+}): string;
+/** A symbol in a book's notation appendix: its entry, the page that defines it, and the chapter it is local to. */
+interface AppendixNotation {
+    readonly entry: NotationEntry;
+    readonly page: StaticPage;
+    /** `2.2` for a symbol only one chapter defines; none for a shared one. */
+    readonly chapter?: string;
+}
+/**
+ * The book's notation appendix: every symbol its chapters use, in the order
+ * they first appear, each with its meaning, units and defining formula.
+ */
+declare function serializeNotationAppendix(entries: readonly AppendixNotation[], context: Omit<ChapterContext, 'page'>): string;
+/** The book's abbreviation appendix: each abbreviation and what it stands for. */
+declare function serializeAbbreviationAppendix(abbreviations: readonly {
+    readonly abbr: string;
+    readonly expansion: string;
+}[]): string;
+
+export { type AppendixNotation, type ChapterContext, type CheckItem, diagramTikz, escapeText, labelOf, linkExplains, serializeAbbreviationAppendix, serializeChapter, serializeNotationAppendix, serializePartOpener };