marginalreader.cls

%%
%% marginalreader.cls
%% A LuaLaTeX class for graded readers with marginal glosses
%%
%% Copyright (C) 2026 Dino Sepúlveda
%%
%% This work may be distributed and/or modified under the conditions
%% of the LaTeX Project Public License, either version 1.3c of this
%% license or (at your option) any later version. The latest version
%% of this license is in
%%   https://www.latex-project.org/lppl.txt
%% and version 1.3c or later is part of all distributions of LaTeX
%% version 2008-05-04 or later.
%%
%% This work has the LPPL maintenance status `maintained'.
%% The Current Maintainer of this work is Dino Sepúlveda.
%%
%% This work consists of the files marginalreader.cls,
%% marginalreader-margin.lua and marginalreader-linenums.lua, the
%% documentation in doc/, and the example and test documents
%% distributed with it.
%%
\NeedsTeXFormat{LaTeX2e}
\ProvidesClass{marginalreader}[2026/08/22 v0.1 Graded reader with marginal glosses]

%% --- Engine check ---
\RequirePackage{iftex}
\ifluatex\else
  \ClassError{marginalreader}{LuaLaTeX is required}
    {This class must be compiled with lualatex.}
\fi

%% --- Option declarations ---
\RequirePackage{xkeyval}

% Paper and layout
\DeclareOptionX{paper}[b5]{\def\mr@paper{#1}}
\DeclareOptionX{twoside}[true]{\def\mr@twoside{#1}}
\DeclareOptionX{chapteralibi}[any]{\def\mr@chapteralibi{#1}}

% Fonts
\DeclareOptionX{fonts}[ebgaramond]{\def\mr@fonts{#1}}
% Base font size, handed to scrbook (any size KOMA accepts, WITH its
% unit: fontsize=9.5pt, fontsize=11pt, ...). The value is also used
% to derive \headheight, so a unit is required.
\DeclareOptionX{fontsize}[10pt]{\def\mr@fontsize{#1}}
% Interlinear spacing, so students can mark the text between the
% lines: single (default), 1.5, 2, 2.5 or 3 -- word-processor
% semantics, multiplying the normal leading (at 10pt/12pt, 2 means a
% 24pt baseline grid). Any other numeric value is accepted as a raw
% \linespread factor. Applies to the body text; the margin apparatus
% and footnotes deliberately stay single-spaced (see the line-spacing
% section below).
\DeclareOptionX{linespacing}[single]{\def\mr@linespacing{#1}}

% Rules
\DeclareOptionX{toprule}[solid]{\def\mr@toprule{#1}}
\DeclareOptionX{columnrule}[solid]{\def\mr@columnrule{#1}}
% Umbrella: rules=<style> sets toprule and columnrule together --
% rules=none removes both at once. Options are processed in the order
% given, so a later toprule=/columnrule= still overrides one of the
% pair (and vice versa).
\DeclareOptionX{rules}[solid]{\def\mr@toprule{#1}\def\mr@columnrule{#1}}
\DeclareOptionX{rulecolor}[black]{\def\mr@rulecolor{#1}}
\DeclareOptionX{rulewidth}[0.4pt]{\def\mr@rulewidth{#1}}
\DeclareOptionX{ruledash}[2pt/2pt]{\def\mr@ruledash{#1}}

% Line numbering
\DeclareOptionX{linenumbers}[false]{\def\mr@linenumbers{#1}}
\DeclareOptionX{linenumincrement}[5]{\def\mr@linenumincrement{#1}}
\DeclareOptionX{firstlinenum}[1]{\def\mr@firstlinenum{#1}}

% Marginalia
\DeclareOptionX{numberedmargin}[false]{\def\mr@numberedmargin{#1}}
\DeclareOptionX{glosssep}[\space\space]{\def\mr@glosssep{#1}}

% Spacing
\DeclareOptionX{marginpush}[4pt]{\def\mr@marginpush{#1}}

% Table of contents: by default each page number is set just after
% its entry (a fixed 1.5em gap, ragged line end); dottedtoc restores
% dotted leaders with flush-right numbers instead.
\def\mr@dottedtoc{false}
\DeclareOptionX{dottedtoc}[true]{\def\mr@dottedtoc{#1}}

% Drafting: date + time + version string in the centre foot of every
% page, implemented with the class's own scrlayer-scrpage footers
% rather than prelim2e. \myVersion can be defined by the document;
% \finalVersionString is provided for colophons either way.
\def\mr@drafting{false}
\DeclareOptionX{drafting}[true]{\def\mr@drafting{#1}}

\ExecuteOptionsX{paper,twoside,chapteralibi,fonts,fontsize,linespacing,
  toprule,columnrule,rulecolor,rulewidth,ruledash,linenumbers,
  linenumincrement,firstlinenum,numberedmargin,glosssep,marginpush}
\ProcessOptionsX\relax

%% --- Load base class ---
% NO paper option is passed to scrbook here: the geometry package owns
% the final page size (paperwidth/paperheight from the presets below),
% exactly as it already owns every margin. Two findings forced this
% design, both confirmed with minimal probe classes:
%   * a paper=<w>:<h> value routed through \PassOptionsToClass +
%     \LoadClass arrives at scrbook with its VALUE STRIPPED on this
%     kernel (the log's unused-option list shows a bare "paper"), so
%     the dimension pair silently never applied -- KOMA stayed at A4;
%   * the named sizes (b5, a5, letter...) only ever worked because
%     \documentclass options leak through to \LoadClass-loaded classes
%     as GLOBAL options, which KOMA's own parser does understand.
% That leak still happens and is harmless: for a name KOMA knows it
% pre-sets the same size the preset then re-asserts; for one it does
% not (6x9, 5.5x8.5...) it stays at its default until geometry sets
% the real size. A paper value with NO preset below (e.g. an explicit
% paper=17cm:24cm) is honoured the same way: KOMA parses the leaked
% global -- the w:h form does work at \documentclass level -- and the
% preset dispatcher's fallback keeps geometry's paperwidth/paperheight
% at whatever KOMA concluded.
\edef\mr@twoside@opt{%
  \ifx\mr@twoside\@empty twoside=true\else twoside=\mr@twoside\fi
}
\PassOptionsToClass{\mr@twoside@opt,headinclude=true,footinclude=false,fontsize=\mr@fontsize}{scrbook}
\LoadClass{scrbook}

%% --- Line spacing ---
% linespacing class option (see its declaration above): named values
% map to \linespread factors; anything else is taken as a raw numeric
% factor. \linespread multiplies \baselineskip at the next size-
% selecting \selectfont, i.e. from \begin{document}'s \normalsize
% onwards. Places that must STAY single-spaced regardless -- the
% margin apparatus (\mr@marginitem's parbox) and the footnote block
% (KOMA's `footnote' font element, below) -- locally reset the factor
% to 1: a doubled body is for students' pens, a doubled 8pt gloss
% column would only thrash the margin overflow machinery, and more
% gloss lines then fit beside each opened-up body line.
\@namedef{mr@lsp@single}{1}
\@namedef{mr@lsp@1}{1}
\@namedef{mr@lsp@1.5}{1.5}
\@namedef{mr@lsp@2}{2}
\@namedef{mr@lsp@2.5}{2.5}
\@namedef{mr@lsp@3}{3}
\@ifundefined{mr@lsp@\mr@linespacing}{%
  \edef\mr@lsp@factor{\mr@linespacing}%
}{%
  \edef\mr@lsp@factor{\@nameuse{mr@lsp@\mr@linespacing}}%
}
\linespread{\mr@lsp@factor}
% Footnotes single-spaced: KOMA applies the `footnote' font element
% inside the footnote insert's own group, which is exactly the scope
% needed. The element REPLACES the default, so \footnotesize must be
% restated.
\setkomafont{footnote}{\linespread{1}\footnotesize}

%% --- Required packages ---
\RequirePackage{fontspec}
\RequirePackage[tracking=true]{microtype}
\RequirePackage{xcolor}
\RequirePackage{graphicx}
\RequirePackage{ragged2e}
\RequirePackage{textcase}
\RequirePackage{scrlayer-scrpage}
\RequirePackage{luacode}
\RequirePackage{booktabs}

%% --- Geometry ---
% Define class lengths
\newlength{\mr@marginsep}
\setlength{\mr@marginsep}{5mm}
\newlength{\marginwidth}
\newlength{\fullwidth}
\newlength{\mr@outermargin}
\newlength{\mr@innermargin}
% Vertical dimensions, preset-overridable (defaults are the b5
% values): top/bottom page margins and the footskip used both by the
% reader geometry below and by \mr@plainmattergeometry (front/back
% matter). Scaled per paper so a pocket 4.5x6.5 page is not carrying
% letter-sized margins and vice versa.
\newlength{\mr@topmargin}
\setlength{\mr@topmargin}{14mm}
\newlength{\mr@bottommargin}
\setlength{\mr@bottommargin}{14mm}
\newlength{\mr@footskip}
\setlength{\mr@footskip}{8mm}
% Head height: just over one REAL \baselineskip -- i.e. after both
% fontsize= (KOMA's per-size leading table) and linespacing= (the
% \linespread factor) have taken effect; the \normalsize forces
% \baselineskip current before it is read. scrlayer-scrpage checks
% \headheight against exactly this spaced \baselineskip at
% \begin{document} and, when found short, silently enlarges it --
% AFTER geometry laid the page out but BEFORE the Lua margin manager
% reads \headheight for its text-top derivation, skewing every rule
% and carried-item position by the difference (up to ~15pt at
% linespacing=2; observed). Meeting the check up front keeps the
% whole chain consistent.
\normalsize
\newlength{\mr@headheight}
\setlength{\mr@headheight}{\dimexpr1.05\baselineskip\relax}
% Physical page size, set by the presets and handed to the geometry
% package (see the paper-option note above \LoadClass for why KOMA is
% not trusted with it). Initialised from whatever KOMA concluded, so a
% paper value with no preset (a KOMA name like a3, or an explicit
% w:h pair, both parsed from the leaked \documentclass option) keeps
% its size.
\newlength{\mr@paperwidth}
\setlength{\mr@paperwidth}{\paperwidth}
\newlength{\mr@paperheight}
\setlength{\mr@paperheight}{\paperheight}

% Paper-specific geometry presets. Proportions follow the b5 reference
% design (paper 176mm wide: inner ~7%, text ~60%, gloss column ~21%,
% outer edge ~9%; top/bottom ~5.6% of the paper height), rounded to
% whole millimetres; the remaining outer-edge gap is
% paperwidth - inner - textwidth - marginsep - marginwidth, and stays
% between ~10mm (pocket) and ~23mm (letter) across the presets.
% Declared with \@namedef -- see the paper-size mapping note above for
% why \def cannot spell these names.
\@namedef{mr@setup@geometry@b5}{%      176mm x 250mm; edge gap 16mm
  \setlength{\mr@paperwidth}{176mm}%
  \setlength{\mr@paperheight}{250mm}%
  \setlength{\mr@innermargin}{12mm}%
  \setlength{\textwidth}{105mm}%
  \setlength{\marginwidth}{38mm}%
}
\@namedef{mr@setup@geometry@a5}{%      148mm x 210mm; edge gap 15mm
  \setlength{\mr@paperwidth}{148mm}%
  \setlength{\mr@paperheight}{210mm}%
  \setlength{\mr@innermargin}{10mm}%
  \setlength{\textwidth}{88mm}%
  \setlength{\marginwidth}{30mm}%
  \setlength{\mr@topmargin}{12mm}%
  \setlength{\mr@bottommargin}{12mm}%
  \setlength{\mr@footskip}{7mm}%
}
\@namedef{mr@setup@geometry@a4}{%      210mm x 297mm; edge gap 20mm
  \setlength{\mr@paperwidth}{210mm}%
  \setlength{\mr@paperheight}{297mm}%
  \setlength{\mr@innermargin}{15mm}%
  \setlength{\textwidth}{120mm}%
  \setlength{\marginwidth}{50mm}%
  \setlength{\mr@topmargin}{16mm}%
  \setlength{\mr@bottommargin}{16mm}%
}
\@namedef{mr@setup@geometry@letter}{%  8.5in x 11in; edge gap ~23mm
  \setlength{\mr@paperwidth}{8.5in}%
  \setlength{\mr@paperheight}{11in}%
  \setlength{\mr@innermargin}{15mm}%
  \setlength{\textwidth}{125mm}%
  \setlength{\marginwidth}{48mm}%
  \setlength{\mr@topmargin}{16mm}%
  \setlength{\mr@bottommargin}{16mm}%
}
\@namedef{mr@setup@geometry@halfletter}{% 5.5in x 8.5in; edge gap ~13mm
  \setlength{\mr@paperwidth}{5.5in}%
  \setlength{\mr@paperheight}{8.5in}%
  \setlength{\mr@innermargin}{10mm}%
  \setlength{\textwidth}{83mm}%
  \setlength{\marginwidth}{29mm}%
  \setlength{\mr@topmargin}{12mm}%
  \setlength{\mr@bottommargin}{12mm}%
  \setlength{\mr@footskip}{7mm}%
}
% "5.5x8.5" is the same trim as half letter -- one geometry, two names.
\@namedef{mr@setup@geometry@5.5x8.5}{%
  \@nameuse{mr@setup@geometry@halfletter}%
}
\@namedef{mr@setup@geometry@6x9}{%     6in x 9in; edge gap ~14mm
  \setlength{\mr@paperwidth}{6in}%
  \setlength{\mr@paperheight}{9in}%
  \setlength{\mr@innermargin}{11mm}%
  \setlength{\textwidth}{90mm}%
  \setlength{\marginwidth}{32mm}%
  \setlength{\mr@topmargin}{13mm}%
  \setlength{\mr@bottommargin}{13mm}%
}
\@namedef{mr@setup@geometry@7x10}{%    7in x 10in; edge gap ~16mm
  \setlength{\mr@paperwidth}{7in}%
  \setlength{\mr@paperheight}{10in}%
  \setlength{\mr@innermargin}{12mm}%
  \setlength{\textwidth}{106mm}%
  \setlength{\marginwidth}{39mm}%
}
\@namedef{mr@setup@geometry@4.5x6.5}{% 4.5in x 6.5in; edge gap ~10mm
  \setlength{\mr@paperwidth}{4.5in}%
  \setlength{\mr@paperheight}{6.5in}%
  \setlength{\mr@innermargin}{8mm}%
  \setlength{\textwidth}{68mm}%
  \setlength{\marginwidth}{24mm}%
  \setlength{\mr@marginsep}{4mm}%
  \setlength{\mr@topmargin}{10mm}%
  \setlength{\mr@bottommargin}{12mm}%
  \setlength{\mr@footskip}{7mm}%
}

\@ifundefined{mr@setup@geometry@\mr@paper}{%
  \@nameuse{mr@setup@geometry@b5}%
}{%
  \csname mr@setup@geometry@\mr@paper\endcsname
}

% Compute derived lengths. \mr@outermargin is derived from
% \mr@paperwidth, NOT \paperwidth: until geometry (below) applies the
% preset, \paperwidth still holds whatever KOMA concluded, which for a
% preset KOMA does not know by name is its A4 default.
\setlength{\fullwidth}{\dimexpr\textwidth + \mr@marginsep + \marginwidth\relax}
\setlength{\mr@outermargin}{\dimexpr\mr@paperwidth - \mr@innermargin - \textwidth\relax}

% Apply geometry via geometry package
\RequirePackage{geometry}
\geometry{
  paperwidth=\mr@paperwidth,
  paperheight=\mr@paperheight,
  inner=\mr@innermargin,
  outer=\mr@outermargin,
  textwidth=\textwidth,
  top=\mr@topmargin,
  bottom=\mr@bottommargin,
  % One \baselineskip of head height: the running head is a full
  % \small text line (title small caps + page number),
  % and scrlayer-scrpage warns below \baselineskip -- then silently
  % enlarges \headheight itself, which would skew the Lua margin
  % manager's text-top derivation (it reads \headheight at
  % \AtBeginDocument, AFTER that enlargement, while geometry laid the
  % page out with the smaller value). Scaled with fontsize= via
  % \mr@headheight.
  headheight=\mr@headheight,
  headsep=3mm,
  footskip=\mr@footskip,
  marginparsep=\mr@marginsep,
  marginparwidth=\marginwidth,
  nofoot=false,
}

%% --- Font presets ---
\def\mr@setup@fonts@ebgaramond{%
  \setmainfont{EB Garamond}[
    Ligatures=TeX,
    Numbers=OldStyle,
  ]%
  \setsansfont{TeX Gyre Heros}[
    Ligatures=TeX,
    Scale=MatchLowercase,
  ]%
}
\def\mr@setup@fonts@palatino{%
  \setmainfont{TeX Gyre Pagella}[
    Ligatures=TeX,
    Numbers=OldStyle,
  ]%
  \setsansfont{TeX Gyre Heros}[
    Ligatures=TeX,
    Scale=MatchLowercase,
  ]%
}
\def\mr@setup@fonts@quadraat{%
  \setmainfont{FF Quadraat}[
    Ligatures=TeX,
    Numbers=OldStyle,
  ]%
  \setsansfont{FF Scala Sans}[
    Ligatures=TeX,
    Scale=MatchLowercase,
  ]%
}
\def\mr@setup@fonts@none{}

\@ifundefined{mr@setup@fonts@\mr@fonts}{%
  \ClassWarning{marginalreader}{Unknown font preset '\mr@fonts', using ebgaramond}%
  \mr@setup@fonts@ebgaramond
}{%
  \csname mr@setup@fonts@\mr@fonts\endcsname
}

%% --- Small caps commands ---
\newcommand{\spacedlowsmallcaps}[1]{%
  \textls[80]{\textsc{\MakeTextLowercase{#1}}}%
}
\newcommand{\spacedallcaps}[1]{%
  \textls[160]{\textsc{\MakeTextUppercase{#1}}}%
}
% Declarative variant of the above: a font SWITCH for places that
% cannot take an argument-form command --
% KOMA font elements, tocbasic entry formats. fontspec's LetterSpace=8
% tracks by 0.08em, the same amount \spacedlowsmallcaps applies via
% \textls[80]. Titles are not lowercased by it (no declarative
% \MakeTextLowercase exists); capital initials render as full caps
% within the small caps.
\DeclareRobustCommand{\spacedlowsmallcapsstyle}{%
  \scshape\addfontfeature{LetterSpace=8.0}%
}

%% --- Margin font setup ---
\newcommand{\mr@glossstyle}{\itshape}
\newcommand{\mr@glossdefstyle}{\upshape}
\newcommand{\mr@marginfontsetup}{\footnotesize\RaggedRight}
\newcommand{\glossstyle}[1]{\renewcommand{\mr@glossstyle}{#1}}
\newcommand{\glossdefstyle}[1]{\renewcommand{\mr@glossdefstyle}{#1}}
\newcommand{\marginfontsetup}[1]{\renewcommand{\mr@marginfontsetup}{#1}}
% Public name for this font slot (design spec sec. 8: \rmfamily,
% \sffamily, \glossfont, \linenumfont) -- \mr@marginfontsetup already
% supplies \glossfont's actual role (see \linenumfont's own comment,
% below); this just gives it the user-facing name the spec promises.
\let\glossfont\mr@marginfontsetup

%% --- Chapter formatting ---
% KOMA's default heading font ("disposition", inherited by chapter,
% section and subsection alike) is \sffamily\bfseries (see \sectfont in
% scrbook.cls). That is the wrong base for this class's small-caps
% headings, which should sit in the body serif at
% normal weight -- \spacedlowsmallcaps and \itshape below add the actual
% distinguishing style. Reset it once here for all heading levels.
\addtokomafont{disposition}{\normalfont}

% chapteralibi: control where chapters can start
% (KOMA's real 'open' key toggles \if@openright, consulted by \chapter
%  itself as \if@openright\cleardoublepage\else\clearpage\fi -- this is
%  the only mechanism needed here.)
\def\mr@chapteralibi@any{%
  \KOMAoptions{open=any}%
}
\def\mr@chapteralibi@recto{%
  \KOMAoptions{open=right}%
}
\def\mr@chapteralibi@newpage{%
  \KOMAoptions{open=any}%
}

\@ifundefined{mr@chapteralibi@\mr@chapteralibi}{%
  \mr@chapteralibi@any
}{%
  \csname mr@chapteralibi@\mr@chapteralibi\endcsname
}

% Blank pages inserted by \cleardoublepage (before part pages and
% part-opening chapters, and wherever the document uses it) carry no
% header or folio.
\KOMAoptions{cleardoublepage=empty}

% Chapter: spaced low small caps, Large, flush left, no number prefix
\setcounter{secnumdepth}{-1}
\RedeclareSectionCommand[
  beforeskip=2\baselineskip,
  afterskip=1\baselineskip,
  font=\Large,
  prefixfont=\Large,
  afterindent=false,
]{chapter}
\renewcommand*{\chapterformat}{}
\renewcommand*{\raggedchapter}{\raggedright}

% Small caps are applied to the chapter title itself in
% \chapterlinesformat below (via \spacedlowsmallcaps); the family/weight
% reset happens once, above, via \addtokomafont{disposition}{\normalfont}.
\renewcommand{\chapterlinesformat}[3]{%
  \@hangfrom{#2}{\spacedlowsmallcaps{#3}}%
}

% Section: spaced low small caps, large, flush left
\RedeclareSectionCommand[
  beforeskip=1\baselineskip,
  afterskip=0.5\baselineskip,
  font=\large,
  afterindent=false,
]{section}
% Blank the number prefix so sections stay unnumbered in print even
% while secnumdepth permits numbering (see below) -- mirrors chapter.
\renewcommand*{\sectionformat}{}
% \sectionmarkformat is a separate hook (used by \automark for the
% running header, see below) that defaults to \thesection\autodot\enskip
% independently of \sectionformat -- blank it too, or section numbers
% leak into the recto running head even though the printed heading and
% \sectionformat are unnumbered.
\renewcommand*{\sectionmarkformat}{}
% \sectionlinesformat is KOMA's shared formatting hook for every
% "section-style" heading level (section, subsection, ...) -- #1 here is
% the level name. Small caps are only wanted for \section itself; without
% discriminating on #1, \subsection below would incorrectly inherit them
% too (it only wants italic, per spec).
\renewcommand{\sectionlinesformat}[4]{%
  \Ifstr{#1}{section}{%
    \@hangfrom{#3}{\spacedlowsmallcaps{#4}}%
  }{%
    \@hangfrom{#3}{#4}%
  }%
}

% Subsection: italic, normal size
\RedeclareSectionCommand[
  beforeskip=0.75\baselineskip,
  afterskip=0.25\baselineskip,
  font=\normalsize\itshape,
  afterindent=false,
]{subsection}
% Same rationale as \sectionformat above.
\renewcommand*{\subsectionformat}{}

% Subsubsection: italic, normal size, styled the same as subsection.
% Unnumbered in print like every other level.
\RedeclareSectionCommand[
  beforeskip=0.75\baselineskip,
  afterskip=0.25\baselineskip,
  font=\normalsize\itshape,
  afterindent=false,
]{subsubsection}
\renewcommand*{\subsubsectionformat}{}

% Paragraph: run-in, spaced low small caps, with the body text
% following on the same line. runin=true must be EXPLICIT: KOMA's
% default for the level is runin=bysign (negative afterskip means
% run-in), so a plain positive afterskip here silently turned the
% level into a display heading. With runin=true, afterskip is the
% HORIZONTAL gap between title and text. Run-in levels format their
% title through \sectioncatchphraseformat, not \sectionlinesformat;
% #1 is the level name, #4 the title text.
\RedeclareSectionCommand[
  runin=true,
  beforeskip=1\baselineskip,
  afterskip=1em,
  font=\normalsize,
]{paragraph}
\renewcommand*{\paragraphformat}{}
\renewcommand{\sectioncatchphraseformat}[4]{%
  \hskip #2#3\spacedlowsmallcaps{#4}%
}

% Description labels: spaced low small caps.
\renewcommand*{\descriptionlabel}[1]{%
  \hspace{\labelsep}\spacedlowsmallcaps{#1}%
}

% Part: the division above chapters (hierarchy PART > CHAPTER >
% SECTION > subsection). A part gets its own page:
% centred (KOMA's \raggedpart default), no header or footer
% (\partpagestyle empty), label line "pars i" (\partname under babel's
% main language) in spaced small caps above the title in larger spaced
% small caps. Rules and margin apparatus are switched off around the
% part page by the \part wrapper defined further down, next to
% \mr@flushmargins, which it reuses.
%
% \mr@scspaced: internal alias of the public declarative switch
% \spacedlowsmallcapsstyle (defined in the small-caps section above);
% kept so the KOMA font elements and TOC formats below read the same
% as before the public name existed.
\newcommand*{\mr@scspaced}{\spacedlowsmallcapsstyle}
\renewcommand*{\thepart}{\roman{part}}
\renewcommand*{\partformat}{\MakeTextLowercase{\partname}~\thepart}
\renewcommand*{\partpagestyle}{empty}
\setkomafont{partprefix}{\large\mr@scspaced}
\setkomafont{part}{\LARGE\mr@scspaced}

% \parttext{...} -- a short text (an argumentum, a quotation) set
% under the NEXT part's title on the part page. Implemented on KOMA's
% own \setpartpreamble: position [u] = under the title, in a narrower
% centred measure. Line counting
% is suspended around the text (the part page carries no reader
% apparatus; without the push/pop the preamble's lines would be
% counted and numbered as body text). Like \ctparttext, it applies to
% the next \part only -- KOMA clears the preamble after use.
\newcommand{\parttext}[1]{%
  % [uc]: under the title, box centred on the text block. Inside:
  % justified at 3/4 measure, one blank line below the title -- a
  % quotation-block look, without the quote environment's asymmetric
  % indents.
  \setpartpreamble[uc][.75\textwidth]{%
    \directlua{marginalreader_linenums.display_push()}%
    \vspace*{\baselineskip}%
    \normalfont\normalsize
    #1\par
    \directlua{marginalreader_linenums.display_pop()}%
  }%
}

% Table of contents:
%   * part entries: spaced small caps, no page number (tocbasic's
%     pagenumberformat with a one-argument gobble);
%   * chapter entries: spaced small caps, entry number in small caps;
%   * section/subsection entries: normal font, entry number in
%     lowercase small caps;
%   * page numbers sit just after their entry, separated by a fixed
%     1.5em gap, unless the
%     dottedtoc class option asks for dotted leaders with flush-right
%     numbers -- then tocbasic's default fill is left alone.
\newcommand{\mr@tocpartformat}[1]{\large\mr@scspaced #1}
\newcommand{\mr@tocpartnopage}[1]{}
\newcommand{\mr@tocchapformat}[1]{\mr@scspaced #1}
% Small-caps entry numbers. No \MakeTextLowercase here, twice over:
% the numbers are digits and lowercase roman already, and textcase's
% case scan breaks inside a tocbasic entrynumberformat once hyperref
% wraps the entry in its link anchors (probed: 8 errors per TOC with
% it, none without).
\newcommand{\mr@tocscnum}[1]{\textsc{#1}}
\DeclareTOCStyleEntry[
  entryformat=\mr@tocpartformat,
  pagenumberformat=\mr@tocpartnopage,
]{tocline}{part}
\DeclareTOCStyleEntry[
  entryformat=\mr@tocchapformat,
  entrynumberformat=\mr@tocscnum,
  pagenumberformat=\normalfont,
]{tocline}{chapter}
\DeclareTOCStyleEntry[
  entrynumberformat=\mr@tocscnum,
]{tocline}{section}
\DeclareTOCStyleEntry[
  entrynumberformat=\mr@tocscnum,
]{tocline}{subsection}
\Ifstr{\mr@dottedtoc}{true}{}{%
  \DeclareTOCStyleEntries[
    linefill=\hspace*{1.5em},
    raggedpagenumber=true,
  ]{tocline}{chapter,section,subsection}%
}

%% --- Running headers ---
% Headlines: the page number lives IN the header, hanging into the outer
% margin past the text block with a 2em separation; verso carries the
% chapter title, recto the section title, both in spaced low small
% caps; regular pages have no footer at all, and chapter-opening pages
% (KOMA's `plain.scrheadings`) carry only a small page number in the
% outer footer.
\pagestyle{scrheadings}
\clearpairofpagestyles

\automark[section]{chapter}
% The "cap. N" prefix hooks are unused under this layout (marks carry
% the bare title); blanked so nothing re-adds a number.
\renewcommand*{\chaptermarkformat}{}

% \automark (above) redefines \chaptermark/\sectionmark itself -- via
% \def, deep inside scrlayer.sty's \automark@leftlow/
% \automark@righthigh -- to \markboth/\markright the title text (#1)
% UNSTYLED. The stored mark itself must be in spaced low small caps,
% so both commands are overridden again here. This MUST come AFTER
% \automark, not before --
% \automark's own \def would otherwise silently clobber a
% \renewcommand* placed earlier, discarding this fix (confirmed against
% this installation's scrlayer.sty). \chaptermark sets BOTH marks, so
% a recto page in a section-less chapter still shows the chapter title
% instead of an empty header. Sections print unnumbered in this class
% (see \sectionformat above), so the section mark carries the bare
% title, with no number prefix.
\renewcommand*{\chaptermark}[1]{%
  \markboth{\spacedlowsmallcaps{#1}}{\spacedlowsmallcaps{#1}}%
}
\renewcommand*{\sectionmark}[1]{%
  \markright{\spacedlowsmallcaps{#1}}%
}

% KOMA's default running-head font is slanted (\slshape); the header
% titles here are already spaced small caps and must stay upright,
% one size down from the body.
\setkomafont{pageheadfoot}{\normalfont\small}

% Verso (even): number hangs left of the text block into the outer
% margin; head flush left. Recto (odd): mirrored. \llap/\rlap keep the
% number outside the header's own width, so the title always aligns
% with the text block edge.
\lehead{\mbox{\llap{\small\pagemark\kern2em}\headmark}}
\rohead{\mbox{\headmark\rlap{\kern2em\small\pagemark}}}

% Chapter-opening (plain) pages: small page number in the outer footer,
% nothing else. Regular pages get no footer (the number is in the
% header).
\ofoot[\small\pagemark]{}

%% --- Drafting stamp ---
% drafting=true: every scrheadings/
% plain page carries a small centre-foot stamp with the date, time and
% version -- implemented with the class's own footers rather than
% prelim2e, which would fight scrlayer-scrpage for the foot line.
% (Pages set with \thispagestyle{empty} -- the part pages, title
% pages -- carry no stamp; a draft circulating for comment does not
% need its display pages stamped.) \myVersion may be defined by the
% document before or after loading; \finalVersionString is provided
% either way, for colophons.
\RequirePackage{scrtime}
% The fallback \myVersion is only provided at \begin{document}, so a
% document's own preamble \newcommand{\myVersion}{...} still works
% (providing it at class-load time made that a "Command already
% defined" error; the footer and \finalVersionString expand it at use
% time, well after this hook).
\AddToHook{begindocument}{\providecommand{\myVersion}{}}
\newcommand{\finalVersionString}{%
  \emph{Final version} as of \today\ (\myVersion).%
}
\Ifstr{\mr@drafting}{true}{%
  \renewcommand{\finalVersionString}{}%
  \cfoot[{\footnotesize[\,\today\ at \thistime\ -- \myVersion\,]}]%
        {\footnotesize[\,\today\ at \thistime\ -- \myVersion\,]}%
}{}

% Re-enable section numbering in internal counters (but not in print)
\setcounter{secnumdepth}{2}
\RedeclareSectionCommand[counterwithout={}]{chapter}

%% --- Lua margin manager ---
\RequirePackage{luatexbase}
\directlua{marginalreader_margin = require("marginalreader-margin")}

% Pass final geometry to the Lua module and register its page-processing
% callback (collision avoidance / cross-page flow -- see
% marginalreader-margin.lua). Deferred to \AtBeginDocument so every
% length below has its final, geometry-package-adjusted value.
% The rule geometry (text_top / text_left_recto / text_left_verso /
% paper_height, added to the table below) is resolved from this
% document's FINAL, post-geometry-package layout parameters (\topmargin,
% \headheight, \headsep, \oddsidemargin, \evensidemargin, \voffset,
% \hoffset, \paperheight), via the standard LaTeX invariant "distance
% from a paper edge to the text block = 1in + offset + margin" -- NOT
% recomputed from headheight/headsep/margin lengths in Lua the way the
% an early draft did (that code hardcoded "18mm"/"6mm"/
% "14pt" magic numbers, which do not track this class's real,
% overridable geometry). Both this formula and the coordinate convention
% it feeds into (marginalreader-margin.lua's M.draw_rules) were checked
% against this class's own rendered output before being relied on here:
% compiled a probe document with running text spanning several pages,
% and cross-checked the formula's predicted text-block top/left
% positions against `pdftotext -bbox` measurements of the actual first
% line of body text on non-chapter-opening recto and verso pages --
% agreement was within ~0.1mm (a font glyph-ink-vs-typeset-box-edge
% level discrepancy), on both axes, for both page parities. See
% the development notes for the full derivation and measurements.
\AtBeginDocument{%
  \directlua{
    marginalreader_margin.configure({
      margin_width = tex.sp("\the\marginwidth"),
      margin_sep   = tex.sp("\the\mr@marginsep"),
      inner_margin = tex.sp("\the\mr@innermargin"),
      text_width   = tex.sp("\the\textwidth"),
      margin_push  = tex.sp("\mr@marginpush"),
      page_height  = tex.sp("\the\textheight"),
      is_twoside   = \if@twoside true\else false\fi,
      text_top        = tex.sp("\the\dimexpr 1in+\voffset+\topmargin+\headheight+\headsep\relax"),
      text_left_recto = tex.sp("\the\dimexpr 1in+\hoffset+\oddsidemargin\relax"),
      text_left_verso = tex.sp("\the\dimexpr 1in+\hoffset+\evensidemargin\relax"),
      paper_height    = tex.sp("\the\paperheight"),
      topskip         = tex.sp("\the\topskip"),
      overlay_box     = \number\mr@overlaybox,
    })
    marginalreader_margin.register()
  }%
  % read back the PREVIOUS compile's recorded anchor positions
  % (marginalreader-margin.lua's side file, written at that run's Lua
  % `stop_run` callback) and run the collision-avoidance/cross-page-flow
  % pre-pass over them, BEFORE the document body below is typeset --
  % every \mr@marginitem call after this point consults the result via
  % M.get_correction. Must run after M.configure, just above (the
  % pre-pass needs the geometry fields set there), which is why this is
  % a separate \directlua call rather than folded into the one above --
  % and is safe to call unconditionally, even on a first compile with no
  % side file yet (degrades to the original uncorrected placement, with no
  % correction applied -- see marginalreader-margin.lua's "Pre-pass
  % status" note, at the top of that file, for the full two-pass
  % rationale).
  %
  % NOTE for future maintainers: keep Lua source passed through
  % \directlua{...} free of `--` comments. \directlua's argument is
  % scanned under ordinary TeX catcodes, which collapse end-of-line
  % characters to spaces -- so a Lua `--` line comment does not stop at
  % the next visual line the way it would in a real .lua file, it runs
  % to the true end of the WHOLE \directlua argument, silently eating
  % any real code after it. Confirmed empirically (a `pre_output_filter`
  % callback registration silently failed to compile this way, with a
  % misleading-looking "'end' expected near <eof>" Lua error) while
  % implementing this task -- see the development notes. `--[[ ... ]]` block
  % comments do not have this problem (they are delimited, not
  % newline-terminated), but the simplest fix, used throughout this
  % class, is what these two paragraphs are doing right now: put the
  % explanation in ordinary `%`-comments OUTSIDE the \directlua argument,
  % and keep the argument itself a short, comment-free function call.
  \directlua{marginalreader_margin.load_positions()}%
  % Rule style/colour/dash configuration, resolved into plain Lua-side
  % numbers. Colour needs xcolor's own machinery to reduce an arbitrary
  % colour NAME (\mr@rulecolor -- "black" by default, but any colour
  % xcolor knows about, in any of its native models) to plain r,g,b
  % floats: \extractcolorspec gets the colour's native model+spec,
  % \convertcolorspec converts that to the "rgb" model specifically
  % (decimal 0-1 floats -- exactly what the PDF `RG` operator wants, see
  % M.draw_rules). Done here, TeX-side, with xcolor's own tools, rather
  % than reimplementing colour-model conversion in Lua.
  %
  % The resulting "r,g,b" string, and the raw \mr@ruledash spec text,
  % are passed to Lua as plain strings and parsed INSIDE
  % marginalreader-margin.lua (M.configure_rules), not inline in this
  % \directlua block: Lua's pattern-matching syntax uses `%`
  % (`%d`/`%a`/`%s`/`%.`/...), and \directlua's argument is macro-
  % expanded under ordinary TeX catcodes, where `%` starts a comment --
  % confirmed empirically that inline `%d`/`%s`-using Lua written
  % directly in a \directlua{...} argument gets silently truncated
  % mid-line by TeX's comment scanning before Lua ever sees it. Passing
  % the plain, `%`-free spec strings across and parsing them on the Lua
  % side (ordinary Lua source, read from a file, unaffected by TeX
  % catcodes) avoids that trap entirely.
  \extractcolorspec{\mr@rulecolor}\mr@rc@tmp
  \expandafter\convertcolorspec\mr@rc@tmp{rgb}\mr@rc@rgb
  \directlua{
    marginalreader_margin.configure_rules({
      top_rule_style  = "\mr@toprule",
      col_rule_style  = "\mr@columnrule",
      rule_width      = tex.sp("\mr@rulewidth"),
      rule_color_spec = "\mr@rc@rgb",
      rule_dash_spec  = "\mr@ruledash",
    })
  }%
}

% Rerun warning: tell the user when this compile's margin
% layout is not (yet) fully corrected. The two-pass mechanism set up in
% \AtBeginDocument above only applies corrections computed from the
% PREVIOUS compile's recorded data -- a single compile (or any compile
% after the document itself changed) therefore ships uncorrected margin
% placement with nothing in the log to say so. \ifmr@positionschanged is
% set by marginalreader-margin.lua's M.get_positions_changed (see that
% function, and the "Rerun-needed detection" section above it, for the
% comparison itself). Mirrors the LaTeX kernel's own "Label(s) may have
% changed. Rerun to get cross-references right." idiom: same purpose
% (tell the user a rerun will change the output), same shape (compare
% this run's recorded data against what was read back at the start of
% the run).
%
% Deliberately NOT \AtEndDocument (despite that being the obvious first
% choice, and how this was drafted initially): the kernel's own
% \enddocument runs \@enddocumenthook -- i.e. every \AtEndDocument block
% -- BEFORE its own final \clearpage (confirmed directly in this
% installation's latex.ltx: \@kernel@after@enddocument ... \clearpage
% ... \UseOneTimeHook{enddocument/afterlastpage} ... -- the exact reason
% packages like lastpage.sty force their OWN \clearpage inside
% \AtEndDocument, to learn the true last page number early). A first
% draft of this fix used \AtEndDocument directly and, on testing,
% silently never warned on any single-page document whose margin items
% all sit on that one (and therefore also LAST, not-yet-shipped) page --
% confirmed against tests/test-gloss.tex and tests/test-margin-basic.tex,
% both single-page, both exercising \gloss -- a real gap, not a
% theoretical one, and a common case for a short document or any chapter
% that does not happen to force a page break right at the end.
% `enddocument/afterlastpage` is the kernel's own, purpose-built hook for
% exactly this: it fires once, AFTER the true final \clearpage (see the
% kernel excerpt above), so every item's anchor -- including any on the
% last page -- has already been recorded by the time this code runs.
% Available unconditionally on this kernel (\NewHook{enddocument/
% afterlastpage} in latex.ltx) -- the same hook-management mechanism this
% class already relies on for \AddToHook{shipout/background} below, so
% this introduces no new version assumption.
\newif\ifmr@positionschanged
\AddToHook{enddocument/afterlastpage}{%
  \directlua{marginalreader_margin.get_positions_changed()}%
  \ifmr@positionschanged
    \ClassWarningNoLine{marginalreader}{Margin positions have changed. Rerun lualatex to get correct margin layout.}%
  \fi
}%

% Flush pending margin overflow onto real reader pages. The layout
% pre-pass may have decided (from the previous run's data) that some
% margin items carry onto pages at or beyond the current one. That
% carry is delivered at shipout of the target page -- but the target
% page must (a) EXIST and (b) still be a READER page. Two observed
% failure modes motivate this command:
%   * the document simply ends before the target page -- the carried
%     items silently vanish (a crowded final page whose overflowing
%     glosses, margin table and margin figure disappeared);
%   * a matter switch reaches the target page first -- the carry then
%     paints on top of a front/back-matter page with centred, rule-free
%     geometry (observed: chapter 2's margin spill painted across the
%     back-matter Notae page whenever page parity did not happen to
%     insert a blank verso in between).
% Same job as marginfix's \dumpmargins: emit as many (otherwise empty)
% reader pages as the pending carry needs -- rules, running headers
% and all. Called at \backmatter (before the geometry switches) and on
% the `enddocument` hook, which the kernel fires BEFORE its own final
% \clearpage (see the note above).
% Absolute page counter: incremented once per \shipout, BEFORE the
% shipout hooks run, so during any given page's shipout -- background
% hook, rules, and the page's own \latelua whatsits alike -- it reads
% as that page's unique, document-wide number. The margin system keys
% ALL its per-page data (position records, blocked regions, carry,
% flush) on THIS counter, never on the page counter: \pagenumbering
% resets (front matter i, ii, iii... then main matter 1, 2, 3...)
% make c@page ambiguous, and that ambiguity was a live bug -- carry
% destined for main-matter page 3 was consumed when TITLE PAGE iii
% shipped, silently losing the carried items and leaving their
% ghost-reserved gap at the top of the real page's margin column.
\newcount\mr@abspage
\mr@abspage=0
\AddToHook{shipout/before}{\global\advance\mr@abspage\@ne}

\newcommand{\mr@flushmargins}{%
  % (In the Lua below: the page currently under construction is one
  % past the last shipped page, hence the +1.)
  \directlua{
    local M = marginalreader_margin
    local cur = tex.count["mr@abspage"] + 1
    local highest = -1
    for pg, list in pairs(M.carry_in) do
      if list and \string##list > 0 and pg >= cur and pg > highest then
        highest = pg
      end
    end
    if highest >= cur then
      for i = cur, highest do
        tex.print("\string\\null\string\\clearpage")
      end
    end
  }%
}
\AddToHook{enddocument}{\mr@flushmargins}%

% Draw the top rule + column rule on every page. Registered on the
% LaTeX3 kernel's shipout/background hook (ltshipout; available since
% the 2021-06-01 LaTeX release, well predating this TeX Live), which
% fires once per \shipout -- i.e. once per physical page, regardless of
% how many \chapter/\clearpage/page breaks produced it -- rather than as
% a page-list Lua callback (see the engine note above
% marginalreader-margin.lua's M.draw_rules for why: the design draft's own
% pre_shipout_filter-based approach does not exist on this engine, and
% \pdfliteral does not exist under this LuaLaTeX format either).
%
% is_recto is evaluated HERE, at actual shipout time (mirroring
% \mr@marginitem's \if@twoside/\ifodd\value{page} convention exactly, so
% the column rule always lines up with the margin content it separates
% from the text) -- which is in fact MORE reliable than \mr@marginitem's
% own anchor-time check (a concern recorded in the development notes):
% by shipout time,
% page-breaking has already finished deciding this page's final content
% and page number, so there is no remaining risk of the check firing
% before an anchor's "actual" page is settled.
% also passes the current page number (\arabic{page}, evaluated
% at this same shipout-time point) so M.draw_rules can look up THIS
% page's blocked regions from M.blocked_by_page -- see
% marginalreader-margin.lua's M.draw_rules and the "Full-width elements"
% section, below, for the full rationale (blocked regions are always the
% PREVIOUS compile's data, never this run's own).
% Rules can be suspended for title/display pages (\rulesoff ...
% \ruleson). The flag is \global and consulted at SHIPOUT time, so the
% intended pattern brackets whole pages: \rulesoff, the page content,
% \clearpage (which ships the page while the flag is still off), then
% \ruleson. Display front matter (half title, title page, imprint) is
% the intended use.
\newif\ifmr@rules
\mr@rulestrue
\newcommand{\rulesoff}{\global\mr@rulesfalse}
\newcommand{\ruleson}{\global\mr@rulestrue}

\newcommand{\mr@draw@rules}{%
  % Record every page's kind first, rules on or off: a rules-off page
  % (part page, front/back matter) is a DISPLAY page, and the margin
  % system must keep carried items off it -- M.build_overlay defers any
  % carry that lands on one this run (see below), and the recorded set,
  % written to the blocked-region side file as kind="display" markers,
  % lets the NEXT run's pre-pass route carry past display pages up
  % front (M.run_blocked_prepass / M.run_layout_prepass).
  \directlua{
    marginalreader_margin.record_page_display(\the\mr@abspage,
      \ifmr@rules false\else true\fi)
  }%
  \ifmr@rules
    \directlua{
      marginalreader_margin.draw_rules(%
        \if@twoside\ifodd\value{page}true\else false\fi\else true\fi,
        \the\mr@abspage)
    }%
  \fi
}
\AddToHook{shipout/background}{\mr@draw@rules}

% Overlay painting at SHIPOUT time (carried-over margin items). This
% used to be spliced into the page list from the pre_output_filter
% callback (M.process_page), but that callback can fire on
% page-builder FALSE ALARMS -- observed concretely: \chapter's
% \clearpage invoking the output routine on a still-empty page, which
% consumed the (destructively read) carry data and discarded the
% painted overlay before any of the page's content existed, silently
% losing the carried margin items. shipout/background fires exactly
% once per page actually shipped, so consumption here can never lose
% content or paint it twice. M.build_overlay builds the positioned
% chain from the Lua-side boxes, deposits it in \mr@overlaybox, and
% sets \mr@overlayx/\mr@overlayy to the text block's top-left corner
% for this page's parity; the \put places the zero-extent box there
% (kernel picture coordinates: origin at the paper's top-left corner,
% y upward, so the y offset is negative). Runs AFTER \mr@draw@rules
% (hook order = addition order).
\newbox\mr@overlaybox
\newdimen\mr@overlayx
\newdimen\mr@overlayy
\AddToHook{shipout/background}{%
  \directlua{
    marginalreader_margin.build_overlay(
      \the\mr@abspage,
      \if@twoside\ifodd\value{page}true\else false\fi\else true\fi)
  }%
  \ifvoid\mr@overlaybox\else
    \put(\mr@overlayx,\mr@overlayy){\copy\mr@overlaybox}%
  \fi
}

% Internal counter for margin items, plus the scratch boxes used to
% build and place each one.
\newcount\mr@itemid
\mr@itemid=0
\newif\ifmr@recto
\newif\ifmr@hasprepassrecto
\newsavebox\mr@marginbox
\newbox\mr@marginadjbox
% set by M.get_correction (marginalreader-margin.lua), consulted
% by \mr@marginitem below -- \ifmr@overflow is true when the
% collision/carryover pre-pass decided this item cannot be placed at its
% own anchor at all (it is placed instead, whole, at the top of the next
% page's margin by M.process_page); \mr@pushdim is the extra downward
% shift (0pt by default) to apply to a NON-overflowing item so it clears
% the item before it on the same page.
\newif\ifmr@overflow
\newdimen\mr@pushdim

% Internal command: typeset #1 into a box, record it (Lua-side box
% storage and a shipout-time anchor position), and place it in the
% outer margin at the current line via \vadjust. This is the plumbing
% gloss-facing commands (\gloss, marginblock, ...) are built on --
% and test documents use it directly.
%
% Placement works by building an hbox holding the margin content
% shifted sideways to the outer margin, then forcing its width, height
% and depth to zero (the standard \rlap+\smash trick: the box still
% *paints* its content at its natural position, but claims no space of
% its own). Handed to \vadjust, that zero-extent box is spliced into
% the vertical list at the position of the current line without
% disturbing normal interline spacing -- \vadjust material does not
% participate in baselineskip glue computation between surrounding
% lines, which is exactly the property needed here.
%
% Recto/verso is approximated with \ifodd\value{page} at the point
% \mr@marginitem is called. This is the standard approximation used by
% plain \marginpar too: \c@page is only truly authoritative for
% material that does not cross a page boundary between here and
% shipout, so a gloss anchored right at a page break can occasionally
% land shifted to the wrong side. Acceptable; revisit if some later
% mechanism needs exact placement.
\newcommand{\mr@marginitem}[1]{%
  \begingroup
    % \vadjust below requires horizontal mode (it attaches material to
    % "the current line", which is meaningless with no current line).
    % Every early call site happened to already be mid-paragraph, so
    % this never mattered until \glossblock and marginblock arrived,
    % which can be the very first thing in a paragraph (nothing printed
    % beforehand to force the mode switch) -- discovered via "You can't
    % use \vadjust in vertical mode" on tests/test-gloss.tex.
    % \leavevmode is the standard, side-effect-free fix: it unpacks a
    % void box, which is enough to trigger TeX's usual vertical-to-
    % horizontal mode switch (and the normal \parskip/\parindent/
    % \everypar that entails) without contributing any visible material
    % of its own -- safe regardless of whether the caller already
    % established horizontal mode.
    \leavevmode
    \global\advance\mr@itemid by 1\relax
    \edef\mr@curid{\the\mr@itemid}%
    % Typeset the margin content into a box.
    % Set in_margin flag so line numbering callback skips these paragraphs.
    \directlua{marginalreader_linenums.in_margin = true}%
    \savebox{\mr@marginbox}{%
      \parbox[t]{\marginwidth}{%
        % Margin apparatus stays single-spaced whatever the document's
        % linespacing= factor (see the "Line spacing" section) -- a
        % user who truly wants spaced glosses can put their own
        % \linespread in \marginfontsetup, which comes after this and
        % wins.
        \linespread{1}%
        \mr@marginfontsetup
        #1%
      }%
    }%
    \directlua{marginalreader_linenums.in_margin = false}%
    % Normalise the box register FIRST -- restore its reference point to
    % the first baseline if leading whatsit material collapsed the
    % \parbox[t]'s height to zero (see M.normalize_box in
    % marginalreader-margin.lua: babel's \selectlanguage inside a
    % user's \marginfontsetup did exactly that, shifting every painted
    % gloss AND every recorded first-line height by one line ascent) --
    % then store a copy in Lua-side storage (see engine note in
    % marginalreader-margin.lua for why boxes live there rather than in
    % TeX box registers). One \directlua, two statements: both the
    % \vadjust path (\copy\mr@marginbox below) and the stored copy must
    % see the same, already-normalised box.
    \directlua{
      marginalreader_margin.normalize_box(\the\mr@marginbox)
      marginalreader_margin.store_box(\mr@curid,
        node.direct.todirect(node.copy(tex.box[\the\mr@marginbox])))
    }%
    % Record the anchor's shipout-time PDF position for later tasks.
    % Deferred via \latelua: pdf.getpos() only returns a meaningful
    % value once the page is actually being shipped out -- but
    % \latelua's argument is macro-expanded only at that later point,
    % by which time this \begingroup...\endgroup has long closed and a
    % locally-\edef'd \mr@curid would be undefined. So expand it into
    % the argument now, via an outer \edef, instead of leaving it for
    % \latelua to (re-)expand at shipout.
    \edef\mr@latelua@tmp{%
      \latelua{%
        local x, y = pdf.getpos()
        marginalreader_margin.record_position(\mr@curid, x, y)
      }%
    }%
    \mr@latelua@tmp
    % ask the collision-avoidance/cross-page-flow pre-pass (run
    % once per compile, over the PREVIOUS compile's recorded positions --
    % see M.load_positions/M.run_layout_prepass in
    % marginalreader-margin.lua) what to do with THIS item. Sets
    % \ifmr@overflow and, when not overflowing, \mr@pushdim. Defaults to
    % "not overflowing, no push" for any item the pre-pass has no
    % opinion on (new item, or a first compile with no recorded data
    % yet) -- i.e. degrades exactly to the original uncorrected placement.
    \mr@hasprepassrectofalse
    \directlua{marginalreader_margin.get_correction(\mr@curid)}%
    \ifmr@overflow
      % This item cannot be placed at its own anchor without running off
      % the bottom of the page -- M.process_page places it instead, at
      % the top of the NEXT page's margin, from the Lua-side box copy
      % already stored above. Nothing to do here.
    \else
      % get_correction may have set \ifmr@recto from previous run's page
      % data (via \mr@hasprepassrectotrue). If not (first compile), fall
      % back to the local \ifodd\value{page} approximation.
      \ifmr@hasprepassrecto\else
        \if@twoside
          \ifodd\value{page}\mr@rectotrue\else\mr@rectofalse\fi
        \else
          \mr@rectotrue
        \fi
      \fi
      % First item inside the box: a \latelua whatsit recording where
      % the \vadjust box actually lands in the vertical list. It sits at
      % the box's baseline level (= its insertion point, once \ht is
      % zeroed below) and OUTSIDE the \lower, so its value is the anchor
      % line's own bottom edge, independent of this run's corrections.
      % M.record_adjust turns it into the per-item `dy` (anchor baseline
      % minus insertion point = the anchor line's depth) written to the
      % side file; the next run's M.get_correction folds -dy into
      % \mr@pushdim so the item's first baseline lands exactly ON the
      % anchor baseline instead of one line-depth below it. Same
      % expand-now-via-\edef idiom as the anchor \latelua above, for the
      % same reason (\mr@curid is long out of scope at shipout).
      \edef\mr@latelua@adj{%
        \latelua{%
          local x, y = pdf.getpos()
          marginalreader_margin.record_adjust(\mr@curid, y)
        }%
      }%
      \setbox\mr@marginadjbox=\hbox{%
        \mr@latelua@adj
        \ifmr@recto
          \hskip\dimexpr\textwidth+\mr@marginsep\relax
        \else
          \hskip-\dimexpr\mr@marginsep+\marginwidth\relax
        \fi
        % \lower\mr@pushdim (0pt unless the pre-pass found a collision
        % with the item before this one on the same page) nudges the
        % content down from its natural anchor position without
        % disturbing the outer box's own claimed zero height/depth,
        % below -- the same "content paints beyond the box's own
        % declared extent" property the \hskip above already relies on
        % for the horizontal shift. \raise/\lower need a <box> primitive
        % directly, not \usebox's own \leavevmode-wrapped expansion, so
        % this uses \copy rather than \usebox (equivalent here since
        % this hbox is already mid-construction, definitely in
        % horizontal mode).
        \lower\mr@pushdim\copy\mr@marginbox
      }%
      \wd\mr@marginadjbox=0pt
      \ht\mr@marginadjbox=0pt
      \dp\mr@marginadjbox=0pt
      \vadjust{\box\mr@marginadjbox}%
    \fi
  \endgroup
}

%% --- Gloss commands ---

% \gloss{word}{definition} -- prints word in text, headword + def in margin
\newcommand{\gloss}{\@ifstar\mr@gloss@star\mr@gloss@nostar}

\newcommand{\mr@gloss@nostar}[2]{%
  #1%
  \mr@marginitem{%
    {\mr@glossstyle #1}\mr@glosssep{\mr@glossdefstyle #2}%
  }%
}

% Star form: a single-argument, headword-free margin note (see
% tests/test-gloss.tex: \gloss*{Viri sunt Iulius et Cornelius.} -- one
% brace group, no separate inline word to attach a headword to -- and
% Step 5's "\gloss* shows only the definition"). \newcommand's default
% is a \long macro, so a 2-argument \mr@gloss@star (mirroring
% \mr@gloss@nostar's {word}{def} shape) would not error on that call
% site -- it would silently grab the \par from the following blank
% line as #2, print #1 (the whole note) inline where a real word
% belongs, and leave the margin note empty. Declared with the
% 1-argument shape the actual call site and description require.
\newcommand{\mr@gloss@star}[1]{%
  \mr@marginitem{%
    {\mr@glossdefstyle #1}%
  }%
}

% \mr@glosssep is already defined by this class's own option processing
% (\DeclareOptionX{glosssep}..., near the top of this file; default
% \space\space) -- that is what lets \documentclass[glosssep=...]{...}
% control the separator. Redefining it here with \newcommand would be a
% hard "already defined" error; \renewcommand would compile but
% silently discard whatever the glosssep class option set. Neither is
% wanted, so \gloss below just uses the existing \mr@glosssep as-is.

% \glossblock{headword}{multi-line content} -- content may contain \\;
% it is typeset inside \mr@marginitem's own \parbox (paragraph mode),
% so passing it through raw, unboxed, is correct as written.
\newcommand{\glossblock}[2]{%
  \mr@marginitem{%
    {\mr@glossstyle #1}\\
    {\mr@glossdefstyle #2}%
  }%
}

%% --- Margin environments ---
%
% marginblock, marginfigure and margintable each need their body --
% free-form material between \begin{...} and \end{...} -- handed to
% \mr@marginitem as a single, raw (not-yet-typeset) argument, exactly
% the way \glossblock above hands it #2. \mr@marginitem does the only
% boxing this content needs: one
% \parbox[t]{\marginwidth}{\mr@marginfontsetup ...}.
%
% Pre-flight ruling on a double-wrap bug: an earlier draft of this
% section had each environment collect its body into its OWN \vbox,
% with \hsize=\marginwidth and \mr@marginfontsetup applied there, then
% hand that finished box to \mr@marginitem -- which wraps it in a
% second \parbox with the same \hsize/font settings applied again. That
% is not merely redundant: a \vbox's contents are line-broken and sized
% as soon as the \vbox closes, so the INNER settings are what actually
% determine the typeset result, while the outer \parbox's copies become
% dead code operating on a single already-built box atom.
%
% Fixed by capturing each environment's body as plain, unexpanded
% tokens and handing that raw token list to \mr@marginitem, so \hsize
% and \mr@marginfontsetup are each applied exactly once, by
% \mr@marginitem itself, at the point the content is actually typeset.
%
% The capture uses the environ package's \NewEnviron (\BODY holds the
% collected body). An earlier draft used the plain "#1\end#2"
% delimited-argument idiom instead, which breaks the moment the body
% contains ANY nested environment: the grab stops at the FIRST \end
% token, i.e.\ the nested environment's own \end{tabular} (etc.),
% truncating the body and corrupting the environment nesting --
% discovered when a tabular was placed inside margintable. environ's
% \Collect@Body scans for the \end whose name matches the environment
% being collected, so nested environments of any other name are safe.
% (Same-name nesting -- a marginblock inside a marginblock -- remains
% unsupported, as it is in environ generally; there is no use case.)
\RequirePackage{environ}

% marginblock: free-form margin content
\NewEnviron{marginblock}{%
  \mr@marginitem{\BODY}%
}

% marginfigure: margin figure with optional caption
\newcounter{mr@marginfig}
\NewEnviron{marginfigure}[1][]{%
  \def\mr@marginfig@opt{#1}%
  \mr@marginitem{\centering\BODY}%
}

% margintable: margin table with optional caption
\newcounter{mr@margintab}
\NewEnviron{margintable}[1][]{%
  \def\mr@margintab@opt{#1}%
  \mr@marginitem{\BODY}%
}

%% --- Numbered margin notes ---
% Three note apparatuses coexist in a reader, so their call marks must
% be visually distinct at a glance:
%   \marginnote  -- superscript minuscule letters, reset per chapter
%   \footnote    -- superscript footnote symbols (*, dagger, ...),
%                   reset per page (see the footnote section below)
%   \endnote     -- superscript arabic numerals, running through the
%                   whole book (the endnotes package's own default; the
%                   class does not load endnotes, documents that want
%                   endnotes load it themselves)
\newcounter{mr@notecount}[chapter]
\renewcommand*{\themr@notecount}{\alph{mr@notecount}}

% \marginnote{text} -- lettered, per chapter
\newcommand{\marginnote}[1]{%
  \stepcounter{mr@notecount}%
  \textsuperscript{\themr@notecount}%
  \mr@marginitem{%
    \textsuperscript{\themr@notecount}\space{\mr@glossdefstyle #1}%
  }%
}

% \margintext{text} -- unnumbered
\newcommand{\margintext}[1]{%
  \mr@marginitem{{\mr@glossdefstyle #1}}%
}

%% --- Line numbering ---
% See marginalreader-linenums.lua's own header comment for the full
% design rationale (departures from the original design draft's draft, the node-
% filtering this relies on, and the heading-detection mechanism). Loaded
% unconditionally -- \linenumbering/\linenumincrement/\firstlinenum must
% work even in a document that starts with linenumbers=false (the
% default).
\directlua{marginalreader_linenums = require("marginalreader-linenums")}

% \linenumfont -- one of the class's four font "slots" (design spec sec.
% 8: \rmfamily, \sffamily, \glossfont, \linenumfont). A bare declaration,
% invoked the same way as \rmfamily/\sffamily (e.g. "{\linenumfont 5}"),
% switching to the font+size used for inner-margin line numbers. Plain,
% user-\renewcommand-able default -- matches how \rmfamily/\sffamily
% themselves work; this class's other font slot (\glossfont's role) is
% filled by \mr@marginfontsetup, which follows the same
% "plain redefinable declaration" shape.
\newcommand{\linenumfont}{\footnotesize}

\AtBeginDocument{%
  % Capture \linenumfont's resolved font as a Lua-side font id, for
  % marginalreader-linenums.lua's own glyph-node construction (see that
  % file's header comment, "What this module does instead"). Must run
  % with \linenumfont's own font actually SELECTED, hence \begingroup
  % ... \endgroup around it: font.current() reports whatever font TeX
  % has currently selected at the exact moment it is called, not
  % whatever \linenumfont happens to expand to textually.
  \begingroup
    \linenumfont
    \directlua{marginalreader_linenums.set_font(font.current())}%
  \endgroup
  \directlua{
    marginalreader_linenums.configure({
      increment    = \mr@linenumincrement,
      first_line   = \mr@firstlinenum,
      inner_margin = tex.sp("\the\mr@innermargin"),
      line_sep     = tex.sp("3pt"),
      text_width   = tex.sp("\the\textwidth"),
      is_twoside   = \if@twoside true\else false\fi,
    })
  }%
  % linenumbers class option: false (default) / true / continuous -- see
  % the design specification, sec. 9.
  % Both \mr@linenumbers@false and \mr@linenumbers@continuous must be
  % DEFINED before the \ifx comparisons below that test against them
  % (the original design draft's own Step 4 draft compared against these two
  % control sequences before ever defining them, which -- \ifx against an
  % undefined control sequence -- does not do what that draft intended;
  % fixed here by simply defining both first).
  \def\mr@linenumbers@false{false}%
  \def\mr@linenumbers@continuous{continuous}%
  \ifx\mr@linenumbers\mr@linenumbers@false
    \directlua{
      marginalreader_linenums.continuous = false
      marginalreader_linenums.set_enabled(false)
    }%
  \else
    \ifx\mr@linenumbers\mr@linenumbers@continuous
      \directlua{marginalreader_linenums.continuous = true}%
    \else
      \directlua{marginalreader_linenums.continuous = false}%
    \fi
    \directlua{marginalreader_linenums.set_enabled(true)}%
  \fi
  % Registered UNCONDITIONALLY, regardless of the option value just
  % processed above -- see marginalreader-linenums.lua's own M.register
  % comment: this is what lets \linenumbering{on} work later even in a
  % linenumbers=false document. M.enabled (set above) is the actual
  % on/off switch; callback registration is not.
  \directlua{marginalreader_linenums.register()}%
}

% User commands (design spec sec. 6/9): toggle numbering, and change the
% interval/starting line, mid-document.
\newcommand{\linenumbering}[1]{%
  \def\mr@linenumbering@arg{#1}%
  \def\mr@linenumbering@on{on}%
  \def\mr@linenumbering@off{off}%
  \ifx\mr@linenumbering@arg\mr@linenumbering@on
    \directlua{marginalreader_linenums.set_enabled(true)}%
  \else\ifx\mr@linenumbering@arg\mr@linenumbering@off
    \directlua{marginalreader_linenums.set_enabled(false)}%
  \fi\fi
}
\newcommand{\linenumincrement}[1]{%
  \directlua{marginalreader_linenums.increment = #1}%
}
\newcommand{\firstlinenum}[1]{%
  \directlua{marginalreader_linenums.first_line = #1}%
}

% Front/back matter: outside the main matter the
% reader layout is suspended entirely -- the gloss column has no
% content there, so the text block is re-centred on the page (same
% measure, symmetric margins), the top/column rules are not drawn, and
% line numbering pauses. \mainmatter restores the reader geometry,
% rules, and (when the class option asked for it) line numbering.
%
% Geometry switching uses the geometry package's \newgeometry/
% \restoregeometry, which are designed for mid-document changes and
% issue the necessary \clearpage themselves. The Lua modules' cached
% geometry (rule positions, margin x-offsets) is computed from the
% MAIN geometry and is not updated for front/back matter -- safe,
% because rules are off and no margin items or line numbers exist
% outside the main matter.
\newcommand{\mr@plainmattergeometry}{%
  \newgeometry{
    textwidth=\textwidth,
    textheight=\textheight,
    hcentering=true,
    top=\mr@topmargin,
    headheight=\mr@headheight,
    headsep=3mm,
    footskip=\mr@footskip,
  }%
}

\let\mr@orig@frontmatter\frontmatter
\renewcommand{\frontmatter}{%
  \mr@orig@frontmatter
  \rulesoff
  \mr@plainmattergeometry
  \directlua{marginalreader_linenums.set_enabled(false)}%
}
\let\mr@orig@mainmatter\mainmatter
\renewcommand{\mainmatter}{%
  \restoregeometry
  \mr@orig@mainmatter
  \ruleson
  \def\mr@lnfalse@tmp{false}%
  \ifx\mr@linenumbers\mr@lnfalse@tmp\else
    \directlua{marginalreader_linenums.set_enabled(true)}%
  \fi
}
\let\mr@orig@backmatter\backmatter
\renewcommand{\backmatter}{%
  % Ship the last main-matter page (rules still on), then flush any
  % margin carry still pending onto real reader pages BEFORE the
  % geometry and rules switch -- otherwise the carry would paint on
  % top of the first back-matter page (see \mr@flushmargins).
  \clearpage
  \mr@flushmargins
  \rulesoff
  \mr@orig@backmatter
  \mr@plainmattergeometry
  \directlua{marginalreader_linenums.set_enabled(false)}%
}

% \part pages are display pages: no top/column rules, and no margin
% carry may spill onto them. Ship the current page with rules still on
% (the explicit \clearpage), then let KOMA's \part ship the part page
% (and, under open=right, its blank companion pages) with rules off.
% KOMA's \part issues its own \cleardoublepage first, so a parity
% blank BEFORE the part page also ships inside the rules-off bracket
% -- intended: it belongs to the part-page spread. The reader geometry
% itself is untouched (a part page is a main-matter page; only the
% painted apparatus is suspended).
%
% Margin carry is NOT flushed here (deliberately unlike \backmatter):
% mid-document, M.carry_in still holds every LEGITIMATE future-page
% carry the pre-pass planned, and \mr@flushmargins would emit filler
% pages up to the highest such page -- observed as dozens of blank
% pages erupting before chapter 1 the moment the first \part called
% it, growing every run. Instead, rules-off pages are recorded to the
% side files as display pages (see \mr@draw@rules and M.record_page_
% display), the pre-pass routes carry past them, and M.build_overlay
% defers any carry that still lands on one to the next page.
% A part page always opens on a RECTO, whatever chapteralibi says
% about ordinary chapters, and so does the part's FIRST chapter (the
% \chapter wrapper below consumes the \ifmr@afterpart flag). Order in
% the bracket: \clearpage ships the current page with its rules still
% on (it belongs to the preceding chapter); the \cleardoublepage after
% \rulesoff then ships any parity blank as a rules-off display page.
% Inserted blanks use the empty page style (KOMA's
% cleardoublepage=empty, set at the chapter-formatting section).
% The part page is set under the same centred geometry the front and
% back matter use (\mr@plainmattergeometry): on the reader geometry
% the text block sits toward the spine to make room for the gloss
% column, and a title centred on that block looks displaced on the
% physical page. \newgeometry/\restoregeometry each issue their own
% \clearpage, but both fire here on an already-fresh page, so no
% extra pages are emitted; the reader geometry is back in force
% before the part's first chapter begins.
\newif\ifmr@afterpart
\let\mr@orig@part\part
\RenewDocumentCommand{\part}{s o m}{%
  \clearpage
  \rulesoff
  \cleardoublepage
  \mr@plainmattergeometry
  \IfBooleanTF{#1}%
    {\mr@orig@part*{#3}}%
    {\IfNoValueTF{#2}{\mr@orig@part{#3}}{\mr@orig@part[#2]{#3}}}%
  \restoregeometry
  \ruleson
  \global\mr@afterparttrue
}

% First chapter after a \part: force the recto opening before KOMA's
% own \chapter code runs (its open= behaviour stays in charge of every
% other chapter). The parity blank, if any, ships inside a rules-off
% bracket, like the part page's own.
\let\mr@orig@chapter\chapter
\RenewDocumentCommand{\chapter}{s o m}{%
  \ifmr@afterpart
    \rulesoff
    \cleardoublepage
    \ruleson
    \global\mr@afterpartfalse
  \fi
  \IfBooleanTF{#1}%
    {\mr@orig@chapter*{#3}}%
    {\IfNoValueTF{#2}{\mr@orig@chapter{#3}}{\mr@orig@chapter[#2]{#3}}}%
}

% Footnote text is not body text: suppress line counting while a
% footnote's paragraph is typeset (it goes through the same
% post_linebreak_filter as everything else, at the point of the
% \footnote call, and would otherwise be counted -- and even get a
% stray number painted next to a footnote line). Same display_push/
% display_pop mechanism the display environments use.
\let\mr@orig@footnotetext\@footnotetext
\long\def\@footnotetext#1{%
  \directlua{marginalreader_linenums.display_push()}%
  \mr@orig@footnotetext{#1}%
  \directlua{marginalreader_linenums.display_pop()}%
}

% Footnote marks: superscript symbols (*, dagger, double dagger, ...),
% restarting on every page -- so they can never be confused with margin
% notes (superscript letters, per chapter) or endnotes (superscript
% arabic numerals, continuous through the book); see the "Numbered
% margin notes" section above for the three-apparatus scheme. The
% per-page reset uses the perpage package (bigfoot bundle), which
% tracks each footnote's real page through the .aux file -- one more
% two-pass mechanism, converging on the same rerun the margin layout
% already asks for. The symbol sequence is LaTeX's standard \fnsymbol
% list (nine marks); with a per-page reset a reader page will never
% come close to exhausting it.
\RequirePackage{perpage}
\MakePerPage{footnote}
\renewcommand*{\thefootnote}{\fnsymbol{footnote}}
% scrbook resets `footnote' at every \chapter, and perpage counts that
% reset as one more same-page event -- so the first footnote on a
% chapter-OPENING page was numbered as instance 2 and printed a dagger
% instead of the asterisk (observed; any later page was unaffected,
% which hid the bug in documents whose footnotes sit past the opening
% page). A per-chapter reset is meaningless under a per-page reset, so
% detach the counter from \chapter entirely (starred form: \thefootnote
% stays untouched).
\counterwithout*{footnote}{chapter}

% Footnote BLOCK layout: the mark on the baseline at full size, which
% suits this class's symbol marks ("* Geneva enters written
% history..."), right-aligned into a small hanging indent so wrapped
% lines align under the text. The mark must sit INSIDE the text
% column: a zero-width mark box (the \deffootnote{0em}{0em}{...}
% idiom) hangs the mark LEFT of the block, where this class draws the
% column rule on verso pages -- observed as the asterisk overprinting
% the rule. The in-text call mark stays a superscript
% (\deffootnotemark, KOMA's default, untouched).
\deffootnote{1.3em}{0em}{\thefootnotemark\hspace*{.4em}}

% Heading detection and chapter-boundary counter reset -- see
% marginalreader-linenums.lua's "Heading detection" header note for the
% full rationale (in particular why this is a Lua flag consumed by the
% NEXT post_linebreak_filter firing, not a node attribute set from
% \chapterlinesformat/\sectionlinesformat the way the original design draft
% originally drafted it -- that approach cannot work, since the "line"
% hlist nodes it would need to mark do not exist yet at \vadjust{pre}
% time).
%
% A recorded design ruling: the line counter reset
% must NOT use \let\mr@orig@chapter\chapter / \renewcommand{\chapter}{...}
% -- the chapter-formatting section above already redefined the headings
% via \RedeclareSectionCommand and KOMA's own formatting hooks, and
% wrapping \chapter again here on top of that would be fragile and risk
% breaking them. \AddtoDoHook{heading/begingroup/<level>} is KOMA-
% Script's OWN hook for "about to start typesetting this heading level"
% (confirmed by direct inspection of scrbook.cls: every one of its
% internal chapter/section-level implementations calls
% \ExecuteDoHook{heading/begingroup/#1} before producing the heading's
% title text, regardless of how far the \RedeclareSectionCommand/
% \renewcommand*{\chapterlinesformat}/\sectionlinesformat customise what
% that title text looks like) -- so this layers on cleanly without
% touching \chapter, \section or anything the heading setup defined.
\AddtoDoHook{heading/begingroup/chapter}{%
  \directlua{
    if not marginalreader_linenums.continuous then
      marginalreader_linenums.reset_counter()
    end
    marginalreader_linenums.mark_heading_next()
  }%
}
\AddtoDoHook{heading/begingroup/part}{%
  \directlua{marginalreader_linenums.mark_heading_next()}%
}
\AddtoDoHook{heading/begingroup/section}{%
  \directlua{marginalreader_linenums.mark_heading_next()}%
}
\AddtoDoHook{heading/begingroup/subsection}{%
  \directlua{marginalreader_linenums.mark_heading_next()}%
}
\AddtoDoHook{heading/begingroup/subsubsection}{%
  \directlua{marginalreader_linenums.mark_heading_next()}%
}
% Safety net: guarantees the heading flag is cleared even if a heading's
% title happens to produce no counted paragraph line at all (e.g. an
% empty title) -- without this, such a case would leave the flag stuck,
% incorrectly swallowing the count of the next real body paragraph.
\AddtoDoHook{heading/endgroup/part}{%
  \directlua{marginalreader_linenums.clear_heading_flag()}%
}
\AddtoDoHook{heading/endgroup/chapter}{%
  \directlua{marginalreader_linenums.clear_heading_flag()}%
}
\AddtoDoHook{heading/endgroup/section}{%
  \directlua{marginalreader_linenums.clear_heading_flag()}%
}
\AddtoDoHook{heading/endgroup/subsection}{%
  \directlua{marginalreader_linenums.clear_heading_flag()}%
}
\AddtoDoHook{heading/endgroup/subsubsection}{%
  \directlua{marginalreader_linenums.clear_heading_flag()}%
}

%% --- Full-width elements ---
%
% fullwidth (non-floating) and the starred figure*/table* floats let
% content span the text column AND the outer margin (design spec sec.
% 7). Built on the `changepage` package's `adjustwidth*` environment,
% which shifts \leftmargin/\rightmargin (via an inner `list`) rather
% than touching \textwidth/\marginwidth themselves -- so it composes
% cleanly with everything already built on those lengths,
% purely a per-paragraph-group local effect.
\RequirePackage{changepage}
% adjustwidth*'s odd/even side-swap (see \checkoddpage in
% changepage.sty) defaults to a plain, immediate `\ifodd\c@page`
% test, which guesses WRONG for any block typeset just before a page
% break -- observed, converged and permanent, in the pocket-size
% example: a fullwidth painting typeset while the counter still read
% 49 landed on page 50 with the recto-side overhang, running the
% image and its caption off the fore-edge. \strictpagecheck switches
% the test to the write-to-.aux + pageref "true final page" mechanism
% (the same idiom \label/\ref use): the FIRST compile of a new block
% may place the overhang on the wrong side, and the standard
% "Label(s) may have changed. Rerun" warning then asks for the rerun
% that fixes it. That cost is nothing new here -- this class's margin
% layout is already two-pass ("compile until the rerun warning
% stops"), and a converged build must be CORRECT, which the quick
% check cannot guarantee.
\strictpagecheck

% The overhang: how far full-width content extends past the text
% block's own edge, into the margin separator + margin column.
\newlength{\mr@overhang}
\setlength{\mr@overhang}{\dimexpr\mr@marginsep + \marginwidth\relax}

% ---------------------------------------------------------------------
% \fullwidth: length vs environment name collision
% ---------------------------------------------------------------------
% The \fullwidth LENGTH (\newlength{\fullwidth}, = textwidth + marginsep
% + marginwidth) and the `fullwidth` ENVIRONMENT (design
% spec sec. 7, whose examples use
% \begin{fullwidth} verbatim) are, unavoidably, THE SAME CONTROL
% SEQUENCE in standard LaTeX: \begin{fullwidth} always dispatches
% through \csname fullwidth\endcsname (confirmed directly against this
% kernel's own \begin, latex.ltx: "\protected\def\begin#1{...
% \@ifundefined{#1}{...undefined...}{...\csname #1\endcsname}...}" --
% the modern env/#1/before,begin,after HOOKS this kernel also provides
% are layered AROUND that same \csname #1\endcsname dispatch, not a
% replacement for it, so they do not avoid this either). There is no
% LaTeX-level trick under which a single control sequence can
% simultaneously be a real internal dimen (required for \the\fullwidth,
% \rule{\fullwidth}{...}, \includegraphics[width=\fullwidth], or any
% other dimension-context use) AND ordinary macro replacement text
% (required for \begin{fullwidth} to run environment code): a bare
% internal dimen invoked as a command -- by ANY route, including one
% reached through a level of macro expansion -- always starts an
% implicit self-assignment scan instead of running "code". Confirmed
% empirically before this fix: with \fullwidth left as the plain
% \newlength, \newenvironment{fullwidth} itself failed outright
% ("Command \fullwidth already defined"), and forcing the redefinition
% through anyway (e.g. via \renewenvironment) trades that error for
% \begin{fullwidth} instead expanding as an implicit
% "\fullwidth=<value>" assignment attempt at the START of every
% fullwidth block -- observed as "Missing number, treated as zero" /
% "Illegal unit of measure" pointing at whatever token happens to follow
% \begin{fullwidth} in the source.
%
% Resolved by giving the underlying VALUE a separate, internal name
% (\mr@fullwidth, \let to whatever real dimen register the original
% \fullwidth already computed -- NOT a second, independently-tracked
% copy) and reserving the PUBLIC \fullwidth control sequence for the
% environment, matching the design spec sec. 7's
% \begin{fullwidth} example over tests/test-skeleton.tex's narrower,
% internal `\the\fullwidth` sanity line (updated to
% `\the\mr@fullwidth`, under \makeatletter, as part of this task -- a
% deliberate, necessary cross-task interface change, not a silent one;
% see the development notes). \fullwidth remains usable AS A VALUE, UNCHANGED,
% in every context this class's own design spec and this task's own
% brief actually show it used in (\rule{\fullwidth}{...},
% \includegraphics[width=\fullwidth]{...}) -- \mr@blocked@begin, below,
% locally \lets \fullwidth back to \mr@fullwidth as the very first thing
% it does, so it resolves as a dimension again for the rest of that one
% \begin{...}/\end{...} group -- i.e. exactly the body of whichever
% fullwidth/figure*/table* block called it, which is exactly where the
% design spec actually uses \fullwidth as a value.
% (A `fullwidth` nested inside another fullwidth/figure*/table* block
% would not work -- \fullwidth would resolve as the dimension, not the
% environment, inside the outer block's shadowed scope -- but nesting
% these environments inside each other is not a use case this class's
% design spec shows or implies.)
\let\mr@fullwidth\fullwidth

% ---------------------------------------------------------------------
% Blocked-region boundary marking
% ---------------------------------------------------------------------
% The column rule (M.draw_rules) must be interrupted, and
% margin items (M.run_layout_prepass) pushed clear, around every
% full-width element. The element's true vertical extent on the page is
% only known at actual shipout -- the same reason \mr@marginitem records
% anchor positions via \latelua+pdf.getpos() rather than any TeX-side
% dimension arithmetic (see marginalreader-margin.lua's file-top note)
% -- so blocked-region marking reuses that exact idiom: a \latelua+
% pdf.getpos() call at the start and end of the content, tagged with a
% per-block id (\mr@blockid, a separate counter from \mr@marginitem's
% own \mr@itemid) so the Lua side can pair the two recorded points back
% up. \mr@curblockid is set (via a LOCAL \edef, not \xdef) by
% \mr@blocked@begin and read again by \mr@blocked@end -- safe because
% \begin{env}/\end{env} share one implicit TeX group for the whole
% environment body (opened by \begin, closed by \end), so a local
% assignment made in the begin-code is still visible in the end-code,
% exactly as long as nothing in between explicitly closes that group.
%
% Because the recording is deferred to shipout, and \mr@draw@rules
% (below) fires via an IMMEDIATE \directlua from shipout/background --
% which necessarily runs BEFORE the PDF backend has processed any
% \latelua whatsit in that SAME page's own body content, including
% these very markers -- neither the column-rule interruption nor Task
% 6's collision-avoidance pre-pass can see a blocked region recorded
% THIS run. Both consume the PREVIOUS run's recorded data instead
% (marginalreader-margin.lua's M.blocked_by_page), exactly the two-pass,
% cross-run design already established for margin-item
% corrections (M.corrected/M.carry_in) -- see that module's file-top
% "Pre-pass status" note for the rationale, which applies here unchanged.
% Practical consequence: a full-width element's column-rule interruption
% and margin-item avoidance are only correct from the SECOND compile
% onward -- the first compile renders the full-width content correctly
% but with the column rule drawn straight through it and no margin-item
% avoidance around it. \ifmr@positionschanged (above) now also covers
% this (see M.blocked_changed_since_last_run in the Lua module), so the
% existing "Rerun lualatex..." warning fires for this case too.
\newcount\mr@blockid
\mr@blockid=0

\newcommand{\mr@blocked@begin}{%
  % Locally restore \fullwidth as a usable DIMENSION for the rest of
  % this environment body -- see the "\fullwidth: length vs environment
  % name collision" note above \mr@fullwidth's own declaration. Local
  % (not \global): \begin{...} already opened a group before running
  % this environment's begin-code (confirmed against this kernel's own
  % \begin: "\begingroup\@endpefalse\reserved@a"), so this \let is
  % automatically, cleanly undone again at the matching \end{...}'s own
  % \endgroup -- \fullwidth reverts to meaning the environment outside.
  \let\fullwidth\mr@fullwidth
  % Full-width content is a display element: the design spec's line
  % numbering counts "body text lines only, skipping headings, display
  % elements, and vertical skips" -- suppress the line counter for the
  % whole environment body (depth counter, so nesting unwinds cleanly).
  \directlua{marginalreader_linenums.display_push()}%
  \global\advance\mr@blockid by 1\relax
  \edef\mr@curblockid{\the\mr@blockid}%
  \edef\mr@latelua@tmp{%
    \latelua{%
      local x, y = pdf.getpos()
      marginalreader_margin.begin_blocked(\mr@curblockid, x, y)
    }%
  }%
  \mr@latelua@tmp
}
\newcommand{\mr@blocked@end}{%
  \edef\mr@latelua@tmp{%
    \latelua{%
      local x, y = pdf.getpos()
      marginalreader_margin.end_blocked(\mr@curblockid, x, y)
    }%
  }%
  \mr@latelua@tmp
  % Re-enable line counting after the display element. \par first so
  % the environment's LAST paragraph is broken into lines (and thus
  % seen by post_linebreak_filter) while the flag is still up.
  \par
  \directlua{marginalreader_linenums.display_pop()}%
}

% fullwidth: non-floating, appears exactly where declared, spans text +
% margin (design spec sec. 7). \@ifundefined-guarded the same way
% figure*/table* are, below -- NOT for the same "might not exist yet"
% reason (\fullwidth is DEFINITELY already defined, as the class's length
% -- see above), but so this always resolves to \renewenvironment, which
% \lets the OLD \fullwidth (whatever it was) to \relax before defining
% the new environment, rather than \newenvironment's OWN "already
% defined" safety check, which would otherwise (correctly, but
% unhelpfully here) refuse to overwrite it. Confirmed directly against
% this kernel's own \renew@environment: it \lets \csname
% fullwidth\endcsname to \relax UNCONDITIONALLY, with no check on what
% kind of thing it previously was, before (re)defining it -- exactly
% what is needed to cleanly repurpose a dimen register's control
% sequence as an environment.
\@ifundefined{fullwidth}{\newenvironment}{\renewenvironment}{fullwidth}{%
  \mr@blocked@begin
  \begin{adjustwidth*}{0pt}{-\mr@overhang}%
}{%
  \end{adjustwidth*}%
  \mr@blocked@end
}

% figure*/table*: proper floats (placement [htbp]), full width. Built on
% the UNSTARRED \figure/\table's own float-opening/closing code (whatever
% KOMA-Script's scrbook has ultimately made those, at this point in class
% loading) rather than \@dblfloat -- scrbook does not define \figure*/
% \table* itself at all (unlike book/article/report, confirmed by
% inspection: no \newenvironment{figure*} anywhere in scrbook.cls), so
% there is no existing two-column-spanning float mechanism to hook into
% here anyway, and reusing plain \figure/\table's mechanics keeps
% figure*/table* content registered under the ordinary \c@figure/
% \c@table counters and list-of-figures/tables -- exactly like
% book.cls's own \@dblfloat-based figure*/table* do (same counter,
% different placement/width, not a separate float type). \@ifundefined
% guards \newenvironment vs \renewenvironment below purely so this never
% emits an "Environment figure*/table* undefined" warning on a class
% that (like this one) does not predefine them -- functionally
% equivalent either way, LaTeX's own \renewenvironment still defines an
% undefined environment, just with an extra warning.
%
% \mr@orig@figure[#1] (not bare \mr@orig@figure) is required, not
% redundant: \figure's real definition is \@float{figure}, which itself
% peeks the INPUT STREAM for an optional [placement] via \@ifnextchar --
% but by the time #1 exists here, \renewenvironment{figure*}[1][htbp]'s
% OWN argument-scanning has already consumed the "[htbp]" text out of
% the true input stream (leaving only the float's body next). Splicing
% "[#1]" back in literally, right after \mr@orig@figure in this
% definition's OWN replacement text, is what lets \@float{figure}'s
% \@ifnextchar actually see a "[" again.
\let\mr@orig@figure\figure
\let\mr@orig@endfigure\endfigure
\@ifundefined{figure*}{\newenvironment}{\renewenvironment}{figure*}[1][htbp]{%
  \mr@orig@figure[#1]%
  \mr@blocked@begin
  \begin{adjustwidth*}{0pt}{-\mr@overhang}%
}{%
  \end{adjustwidth*}%
  \mr@blocked@end
  \mr@orig@endfigure
}

\let\mr@orig@table\table
\let\mr@orig@endtable\endtable
\@ifundefined{table*}{\newenvironment}{\renewenvironment}{table*}[1][htbp]{%
  \mr@orig@table[#1]%
  \mr@blocked@begin
  \begin{adjustwidth*}{0pt}{-\mr@overhang}%
}{%
  \end{adjustwidth*}%
  \mr@blocked@end
  \mr@orig@endtable
}

%% --- Text-width display elements ---
% textfigure: a NON-floating, text-width display block (image, diagram,
% caption text...). It stays inside the text column, so the column rule
% is NOT interrupted and the margin beside it stays usable -- but its
% content is a display element, so line numbering is suppressed for the
% whole body (design spec sec. 6: count "body text lines only, skipping
% headings, display elements, and vertical skips").
\newenvironment{textfigure}{%
  \par
  \directlua{marginalreader_linenums.display_push()}%
  \medskip
  % A textfigure's image is typically set at exactly \textwidth, so a
  % single stray interword space on its line already overflows the
  % measure (observed: a constant ~1.3pt overfull on every use, at
  % every paper size, from the newline after the \includegraphics
  % line). \ignorespaces eats the space after \begin{textfigure}
  % itself; the shrinkable \parfillskip absorbs any trailing space
  % before the \par -- local to this environment's group, and inert
  % for any line that fits anyway.
  \setlength{\parfillskip}{0pt plus 1fil minus 1em}%
  \noindent\ignorespaces
}{%
  \par
  \directlua{marginalreader_linenums.display_pop()}%
  \medskip
}

% Standard (unstarred) figure/table floats are display elements too:
% suppress line counting for their content. Their body is typeset at
% the point of declaration (into the float box), so a push/pop around
% the environment body covers it, wherever the float finally lands.
\renewenvironment{figure}[1][htbp]{%
  \mr@orig@figure[#1]%
  \directlua{marginalreader_linenums.display_push()}%
}{%
  \directlua{marginalreader_linenums.display_pop()}%
  \mr@orig@endfigure
}
\renewenvironment{table}[1][htbp]{%
  \mr@orig@table[#1]%
  \directlua{marginalreader_linenums.display_push()}%
}{%
  \directlua{marginalreader_linenums.display_pop()}%
  \mr@orig@endtable
}

%% --- Enumerations ---
% aenumerate: an enumerate whose items are labelled with small-caps
% letters -- (a), (b), ... in the reader's small caps.
\newenvironment{aenumerate}{%
  \def\theenumi{\textsc{\alph{enumi}}}%
  \enumerate
}{%
  \endenumerate
}

%% --- Captions ---
% Caption text and label in \small, via KOMA's own font elements (no
% caption package needed).
\setkomafont{caption}{\small}
\setkomafont{captionlabel}{\small}

%% --- Page filling ---
% Ragged bottom prevents TeX from stretching vertical glue to fill
% pages, which causes text to start mid-page when there's not enough
% stretchable glue. Important for graded readers where pages may have
% varying amounts of content.
\raggedbottom

%% --- Paragraph setting ---
% A justified Latin text column runs as narrow as 68mm under the
% pocket presets, and long words (tribe lists, unbreakable \textsf
% names) then produce 1-3pt overfull lines. \emergencystretch gives
% TeX's third line-breaking pass room to resolve exactly those
% paragraphs; any paragraph that already sets within tolerance never
% reaches that pass, so wider presets are typeset identically with or
% without this.
\setlength{\emergencystretch}{1.5em}

% No widows or orphans, ever: TeX would rather run a page short --
% \raggedbottom above already permits that -- than leave a single
% line of a paragraph at the top or bottom of a page.
\clubpenalty=10000
\widowpenalty=10000
\displaywidowpenalty=10000

%% --- PDF page labels (hyperref) ---
% Without /PageLabels a PDF viewer numbers pages physically (1..N), so
% the viewer's "page 7" is the reader's folio 1 -- the main matter's
% printed pages and the PDF's do not agree. hyperref's pdfpagelabels
% option solves this: it mirrors every \pagenumbering switch into the
% PDF catalogue -- front matter i, ii, iii..., main matter 1, 2, 3...
% Loaded from the class, since the page-label problem is the class's
% own front/main-matter design. Loaded at begindocument/before
% (the kernel hook \AtEndPreamble maps to), i.e. after every package
% the document's own preamble loads -- hyperref's required position --
% and skipped entirely if the document already loaded hyperref with its
% own option set. hidelinks: a print-first reader wants no coloured
% boxes around TOC entries; hyperfootnotes=false because the per-page
% symbol footnotes this class uses (see \MakePerPage above) would
% otherwise generate colliding link anchors.
\AddToHook{begindocument/before}{%
  \IfPackageLoadedTF{hyperref}{}{%
    \RequirePackage[pdfpagelabels,hidelinks,hyperfootnotes=false]{hyperref}%
  }%
}

\endinput