explico 0.13.1 → 0.14.0

package/docs/authoring/deck.md

@@ -0,0 +1,588 @@
+# Decks
+
+A **deck** is the slide edition of a lesson: `content/docs/<part>/<lesson>.deck.mdx`.
+It is written in frames, shown one at a time in the browser's Present mode, read
+as a study page with its notes at home, and downloaded as a beamer PDF. Its
+symbols, sources, abbreviations, checks and competencies are the lesson's, so it
+is validated like a chapter and every symbol on it explains itself. A part can
+have a deck too, the lecture of the whole part
+([A deck for a part](#a-deck-for-a-part)).
+
+`D` rules govern what only a frame has: its grammar, its fit, its steps and its
+notes. The rest of the rule set holds for a deck as for a chapter, except the
+few rules about a chapter's page (V7, V8, S1, S6, S7), which a `D` rule says of
+a frame instead. `pnpm content rules --edition deck` (or
+`build/rules-in-effect-deck.md`) lists exactly the rules in force for a deck.
+
+See [README.md](README.md) for what "strong recommendation", "Build-enforced",
+and "Review-only" mean here, and how to amend a rule.
+
+## The deck file
+
+A lesson has up to two **editions**: its chapter (`<lesson>.mdx`) and its deck
+(`<lesson>.deck.mdx`), side by side in the part's directory.
+
+| The course has | The deck is served at | Its frontmatter |
+| --- | --- | --- |
+| a chapter and a deck | `/<part>/<lesson>/slides/`; the lesson's sidebar row opens one edition and carries the other as an icon, and `sidebarEditions` and the reader's switch say which | `title` and `description` only: the chapter holds the lesson's `teaches`, `assumptions`, `studyMinutes` and `notation` |
+| a deck only (slides first) | `/<part>/<lesson>/`, the lesson's own URL | the lesson's: `title`, `description`, `teaches`, `assumptions`, `studyMinutes`, `notation` |
+| a part's deck, `<part>/index.deck.mdx` | `/<part>/slides/`, sharing the part's row with its Overview | `title` and `description` only: its chapters hold the rest |
+
+What the two editions share is the lesson's: its notation (a deck binds its
+symbols in the lesson's scope, the chapter's `notation.local` included), its
+checks (`<lesson>.checks.yml`), its sources, its competencies, and its part and
+chapter numbers. A slides-first lesson is a lesson like any other: it has a
+chapter number, a place in the sidebar and the curriculum map, and checks.
+
+`pnpm content new deck <part>/<lesson>` drafts a deck: from the chapter when
+there is one — a section per `##`, a frame per `###`, a `<Recall>` for every
+numbered equation, figure, table and diagram, and the section's first sentence in
+the notes — or as a slides-first lesson when there is none. `pnpm content new
+deck <part>`, for a part's directory with its page, drafts the part's deck: a
+section per chapter, in the order the tracks read them, and a frame per section
+of the chapter. Rewrite the draft: the frame titles become claims (D3), the
+frames keep to what fits (D2), and the argument goes into the notes (D4).
+
+The `decks` invariant holds always: a deck sits in a part's directory, sets only
+`title` and `description` beside a chapter and as a part's, recalls only what its
+chapter numbers (a part's: what the chapters it covers number), and gives
+`<Pause>` only the props below. Its codes: `deck-frontmatter`,
+`deck-outside-part`, `recall-unresolved` and `pause-invalid`; on a part's deck,
+`deck-chapter-unknown` (a section names no chapter of the part),
+`deck-chapter-repeated` (a chapter named again after another section), `deck-check-no-chapter`
+(an `<AssessmentSet>` in a section that names no chapter) and
+`deck-route-taken` (a lesson of the part is named `slides`, the deck's address);
+`deck-chapter-outside-part` for a `[chapter: …]` on a lesson's deck, and
+`deck-marker-misplaced` for a `[chapter: …]` on a `###` or a `[morph]` on a
+`##`. It cannot be waived.
+
+## Writing a deck
+
+```mdx
+---
+title: Projectile Range
+description: Derive and compute the range of a projectile over level ground.
+---
+
+## The range
+
+### Range is largest at a 45° launch angle
+
+<Recall ref="eq-range" />
+
+- $\sin(2\theta)$ peaks at $\theta = 45^\circ$
+
+<Pause />
+
+- the same range at $\theta$ and at $90^\circ - \theta$
+
+<Notes>
+The range formula is [[eq-range]] from the notes. Ask where $\sin(2\theta)$ is
+largest before showing the second bullet; most of the class says 90°.
+</Notes>
+```
+
+| You write | It means |
+| --- | --- |
+| `## Title` | a section: a divider frame that shows its title, and an entry in the deck's outline |
+| `### Title` | a frame; the heading is its title (D3) |
+| `<Pause />` | a step: what follows appears on the next key press (D6) |
+| `<Notes>…</Notes>` | the frame's speaker notes: Markdown, math and cards (D4) |
+| `<Recall ref="eq-range" />` | the chapter's equation (`fig-`, `tab-`, `dia-`: figure, table, diagram), as it is in the chapter, with its number, linked to it (D8) |
+| `### Title [morph]` | the frame morphs from the one before it |
+| `## Title [chapter: <name>]` | on a part's deck, the section covers that chapter of the part ([A deck for a part](#a-deck-for-a-part)) |
+
+None of them needs an `import` line. The engine writes three kinds of frame
+itself: the **title frame** first (the deck's title, the course, its authors and
+version), the **outcomes frame** last but one (what the lesson's competencies say
+the student can now do; `deck.outcomesFrame`), and the **references frame** last
+when the deck cites a source.
+
+Everything a chapter may hold is allowed on a frame. A `<Memo>` and an aside are
+blocks, always open; a `<Figure>` is the frame's picture, its lab live in Present
+mode; `<AssessmentSet />` makes a question frame; a citation `[@id]` puts its
+marker on the frame and its entry on the references frame.
+
+### A deck for a part
+
+A part's deck is the lecture of the whole part, beside the part's page:
+
+```text
+content/docs/motion/index.mdx        the part's page (as before)
+content/docs/motion/index.deck.mdx   the part's deck, served at /motion/slides/
+```
+
+```mdx
+---
+title: Motion in the plane
+description: The lecture's slides for both chapters.
+---
+
+## Where the point is [chapter: position-and-coordinates]
+
+### A position is two coordinates on one clock
+
+<Recall ref="eq-position-components" />
+
+## Two coordinate systems [chapter: position-and-coordinates]
+
+### Polar coordinates give distance and direction
+
+<Recall ref="eq-polar-from-cartesian" />
+
+## Velocity over time [chapter: constant-acceleration]
+
+### A constant acceleration adds the same each second
+
+<Recall ref="eq-velocity" />
+```
+
+A `##` section may name the chapter it covers, `[chapter: <name>]`, `<name>`
+being the chapter's file in the part's directory; a section without one is the
+deck's own. A chapter may run over several sections in a row, each naming it,
+as a chapter's own deck runs over its sections; it never comes back after a
+section of another chapter, or of the deck's own (`deck-chapter-repeated`). A
+lesson taught as slides only has no chapter to cover. The first divider of a
+chapter's run is the chapter's address in the deck: above,
+`/motion/slides/#slide-6` for the second chapter, after the title frame and the
+first chapter's four. To turn a chapter's own deck into its part's, give each of
+its `##` headings the marker and move its frames in; the chapter's deck goes.
+
+The deck is the part's, so it draws on every chapter of it:
+
+- **Symbols** bind in the scope of the part's chapters, a key two chapters
+  define locally binding to the first in reading order.
+- **`<Recall ref>`** shows a float of a chapter a section covers, with that
+  chapter's number, linked to that chapter: the section's own chapter first,
+  else the one covered chapter that numbers it. Two that number it, with
+  neither the section's own, leave it open (`recall-unresolved`), as does one
+  ref recalled from two chapters on two frames. `[[eq-…]]` and the rest name
+  the deck's own or recalled float first, else the one covered chapter that
+  has it; write `[[<chapter>#eq-…]]` where two do.
+- **`<AssessmentSet />`** on a frame asks the checks of the chapter its
+  section covers; it cannot stand in a section that names none
+  (`deck-check-no-chapter`).
+- **The generated frames**: the title frame shows the deck's title (the
+  part's label without one); the outcomes frame lists the competencies of
+  every chapter the deck covers, in reading order.
+
+In the sidebar the part's deck shares the part's row with its Overview, and
+follows the sidebar's two controls as a chapter's deck does, Overview standing
+for the chapter ([In the sidebar](#in-the-sidebar)): "Overview" with the deck
+as the icon at its end, or "Slides for this part" with Overview there, or one
+alone. Its glyph is two frames, and both links keep theirs in every state; a
+compact part joins their tiles. Its tooltip names the part, its chapters and
+its slides ("Chapters 1–2 · 26 slides"). In a part with no Overview it is a
+row of its own. A chapter it covers that has no deck of its own gets its
+sections as its other edition, "Slides: *chapter title*" (its tooltip adds
+"Slides 17–25 of the part's slides"), which opens the part's deck at the
+chapter's first divider; "Slides for this chapter" under the chapter's title
+goes there too, and the chapter's Download menu offers the part's deck as "Its
+slides". While the part's deck is open, the section of the chapter on screen
+is lit as the open page is, and the rail runs to it; the title and outcomes
+frames, no chapter's, light none. A lesson's own deck wins over its part's. The part's page offers
+"Slides for this part", and the deck's page "Open the part" beside Present.
+Everything else is what a deck has: Present mode, the marks of the slides a
+reader has seen, rule C5's version of its page (`motion/slides`), its
+downloads (`motion-slides.pdf` and the rest, listed on its page, on the
+part's and on each chapter it covers that has no deck of its own), and the `D`
+rules. A deck for an arbitrary set of chapters is not part of the model: a
+part's deck covers its own part.
+
+### Numbers on a deck
+
+Numbers belong to the chapter. A recalled equation, figure, table or diagram keeps
+the chapter's number, and the number links to the chapter. An equation the deck
+labels itself (`\label{eq:…}`) numbers (1), (2), … within the deck. The deck's own
+figures, tables and diagrams are unnumbered. `[[eq-…]]`, `[[fig-…]]` and the rest
+name the deck's own or recalled float first, and the chapter's otherwise;
+`[[sec-…]]` names a section of the chapter.
+
+### Steps and animation
+
+A frame shows in steps. `<Pause />` alone reveals what follows it. With props, the
+step also does something to the frame — what the browser can show that a PDF
+cannot:
+
+| Step | What it shows | On paper |
+| --- | --- | --- |
+| `<Pause />` | the next claim, when the speaker reaches it | `\pause` |
+| `<Pause control="Launch angle" to="75" seconds="3" />` | the frame's lab moves the control labelled "Launch angle" to 75 over 3 s (`from` sets its start), and the figure follows: cause and effect while it happens | the figure as captured |
+| `<Pause highlight="motion.launch-angle" />` | every occurrence of the symbol on the frame lights up: in the equation, the text, the legend and the figure | nothing |
+| `### Title [morph]` | moving to this frame keeps every symbol the two frames share in its identity: each moves from its old place to its new one, so a derivation shows which term went where | two frames |
+
+A driven step moves the lab's own control as a reader's hand would, so any lab can
+be driven. Stepping back and forward replays every step; reduced motion turns the
+movement off and shows each step's end.
+
+### The canvas and the legend
+
+Every deck of the course is laid out on one canvas, `deck.aspectRatio` in the
+course settings: `16:9` (800 × 450 px, the default), `16:10` (720 × 450) or `4:3`
+(600 × 450). The canvas is as wide as the page's reading column, so a figure, a
+table or a lab lays out on a frame at the size it was made for. A frame is laid
+out at that size and scaled to the screen, so what fits when the build measures
+it fits everywhere (D2); printed, it fills a page 7.5 in tall.
+
+Each frame ends on a **legend line**: the symbols it shows for the first time in
+the deck, each with its name, because a projected frame has no mouse to hover a
+card with. `deck.legend` is `first-use` (the default), `every-frame` or `off`.
+
+### Present mode and the study page
+
+The deck's page is a study page: every frame in its final step, its notes under it
+(`deck.notes`: `reader`, the default; `presenter` keeps them to the presenter
+window and the handout; `off`), every card, lab and question live. Each
+frame there has an edge and a drop shadow, set by `appearance.slides` in the
+course settings: `lifted` (the default; in the dark theme the slide is a
+step lighter than the page), `edge` (on the page's own colour) or `sorter`
+(the deck on a tinted well). **Present** shows one frame at a time, full
+screen, with none of them:
+
+| Key | Does |
+| --- | --- |
+| → ↓ Space PageDown | the next step, then the next frame (a clicker sends PageDown) |
+| ← ↑ PageUp Backspace | the step or frame before |
+| Home, End | the first frame, the last |
+| a number, then Enter | that frame |
+| `F` | full screen on or off |
+| `N` | the notes beside the frame |
+| `P` | the presenter window: the frame, the next one, the notes and a clock |
+| `B` | a black screen, and back |
+| Esc | leaves Present mode |
+
+The address of frame 7 is `#slide-7`, the same number the PDF prints; a link to
+it opens the study page at that frame. A reader who left Present mode on frame
+7 with a step of it still to come finds a "Continue at slide 7" button beside
+Present, which presents from there; one who was shown all of frame 7 finds
+"Continue at slide 8". It is there right after Esc, after a reload, and on a
+later visit where the course's reading memory may keep their place. One who
+was shown all of the last frame finds "Present again", which presents from the
+first.
+
+Above each frame is a line in the page's own type, outside the frame: "Slide
+7", whether Present mode has shown it ("Shown", "Not shown yet" or "Changed
+since shown"), and a button. On the frame to continue at it is "Continue
+here", always shown; on every other it is "Present from here", shown, with a
+ring round the frame, while the pointer is on the frame or the keyboard's
+focus is in it (always, as its icon, on a touch screen). Under the title, the
+**slide map** shows every frame as a numbered square: filled once shown,
+outlined before, dotted when changed since, the frame to continue at ringed and
+the one in view underlined. It stays under the header while the deck scrolls,
+and a square scrolls to its frame. A deck too long for the map's line keeps
+its first and last frames, the frames before and after the one to continue at,
+and those round the one in view, as many as the line has room for, with a gap
+for each run left out; a gap scrolls to the frame in its middle.
+
+The deck keeps each frame Present mode showed the reader, at any step, in the
+room's window or the presenter's, as it was. A frame counts as changed when
+what it shows changed: its text, its notes, or the chapter's number for what it
+recalls (`decks[].frames[].id`); a frame moved by one added before it is still
+the frame the reader saw. "Not shown yet" and "Changed since shown" are the
+sidebar's two marks: `sidebarMarks` turns either off here too, and with
+`unopened` off no frame says "Shown" either. A line under Present counts them
+("14 slides not shown yet", "2 slides changed since shown") and offers "Mark
+all as seen" and "Mark all as unseen" for the deck; the sidebar's two buttons
+cover every deck's frames as well as the pages. Before the reader answers the
+course's reading-memory question, the frames shown are kept and marked for
+the tab alone, as kept cards are; "Remember" keeps them for later visits, and
+"Don't remember" clears them and records none after. With `readingMemory:
+"off"`, nothing is marked and no frame is recorded. The resume button, the
+lines, the map and the marks are the reader's own: Present mode, print and a
+downloaded deck show none of them.
+
+### In the sidebar
+
+A lesson is one row in the sidebar, whatever editions it has. The row opens
+the **lead** edition under the lesson's title, and the other edition is an
+icon at the row's end, a second tile joined to the first in a compact part,
+named "Slides: *title*" or "Chapter: *title*". A lesson with one edition is a
+row like any other; only when that edition is not the lead does the row carry
+its glyph (a slide frame with a play mark cut out of it, or a sheet with
+lines of text). A part's deck shares the part's row with its Overview, and
+follows the sidebar's two controls as a chapter's deck does; a chapter it
+covers with no deck of its own takes its section as the other edition
+([A deck for a part](#a-deck-for-a-part)). `sidebarEditions`
+in the course settings sets the default:
+
+```json
+"sidebarEditions": { "lead": "chapter", "other": "listed" }
+```
+
+`lead` is `chapter` (the default) or `slides`. `other` is `listed` (the
+default) or `hidden`, which leaves the other edition out of the sidebar: the
+chapter's "Slides for this chapter" and the deck's "Read the chapter" still
+reach it, and the page open now is listed whatever the setting. Each reader
+switches both in the sidebar's foot ("Lessons open as" Chapter or Slides, "List
+the other edition too"). Their choice is a setting kept in their browser
+(`explico-sidebar-editions`), field by field, so a field they never set follows
+the course's default. Without scripts the sidebar lists each chapter, then its
+"Slides" row.
+
+At the foot of the page, Next and Previous read on in the edition the reader
+is in: from chapter to chapter on a chapter's page, from deck to deck on a
+deck's ("Slides: *title*"), a part's deck and a slides-first lesson among
+them.
+
+### Downloads
+
+With the course's exports on (`lessonExports`), the Download menu has a row for
+the deck, on its page and on its chapter's (a part's deck: on its part's page):
+
+- **HTML**: the deck page as one file. It presents offline, with its notes,
+  cards, labs and checks.
+- **PDF**: the slides in beamer, one page per step. Every symbol on a frame
+  links to its entry on the notation frames after the last frame.
+- **Handout**: each frame in its final step, followed by a page of its notes
+  and its check's answers. It is built when `deck.handoutPdf` is on and
+  `deck.notes` is not `off`.
+- **LaTeX**: the folder both PDFs are built from: `main.tex`, `handout.tex`,
+  `deck.tex`, the theme `beamerthemeexplico.sty` and `explico-common.sty`,
+  which the chapters' class shares.
+- **Markdown**: Marp's dialect, one slide per frame, the notes as comments. It
+  opens in Marp, its VS Code extension or Deckset.
+
+The build fails when the PDF numbers a frame differently from the page, as it
+does for a chapter's numbers, and warns when a frame runs over its slide on
+paper. Beamer cannot write a tagged PDF, so the deck's PDFs do not serve a
+screen reader; its page and its chapter's PDF do. A part's and the course's
+book keep a slides-first lesson's place with a short chapter: its title, its
+outcomes and a link to its slides. The chapters after it keep their numbers.
+
+---
+
+## D1
+
+**A deck is sections of frames: `##` opens a section, `###` is a frame, and
+nothing is deeper or outside a frame.**
+
+A `##` heading is a divider frame that shows its title and opens a section of the
+deck's outline. A `###` heading is a frame, and everything up to the next `##` or
+`###` is that frame. Nothing else is a heading in a deck.
+
+```mdx
+<!-- Not a deck: content outside a frame, a heading too deep. -->
+An opening sentence.
+
+## The range
+
+The range is how far the projectile flies.
+
+### Range is largest at 45°
+
+#### Why
+
+<!-- A deck: every line in a frame. -->
+## The range
+
+### The range is how far the projectile flies
+
+### Range is largest at 45°
+```
+
+_Rationale._ The frame is the unit everything else is built on: the deck page's
+cards, Present mode's paging, the frame numbers, the PDF's frames. A line outside
+a frame has nowhere to be shown, and a `####` inside one would be a second title
+on a frame that has one.
+
+_How to apply._ Start each frame with `###`; put a section's words in a frame of
+their own. Emphasis inside a frame is bold text or a list, not a heading.
+
+_Enforcement._ Build-enforced (`decks-validate.ts`, `pnpm validate:content`):
+`frame-depth` for a `#` or `####`, `deck-loose-content` for content before the
+first heading or between a `##` and its first `###`, `deck-empty` for a deck with
+no frame. Locked: it cannot be turned off.
+
+_Exceptions._ None.
+
+## D2
+
+**A frame fits its canvas in every step, and never continues on the next frame.**
+
+Everything a frame shows — its title, its body at its last step, its legend line —
+fits the course's canvas. A frame that does not fit is two frames.
+
+_Rationale._ The frame number is the address of what the room saw: "slide 7" in
+the lecture, on the web, and in the PDF. A frame that overflows is clipped by
+beamer without a word and scrolls on the web, and a frame that continues on the
+next makes two numbers for one idea. Shrinking the type to make it fit defeats the
+canvas: the back row reads what the front row reads.
+
+_How to apply._ Keep a frame to one claim (D3) and what supports it. Move the
+argument into its notes (D4), split a list over two frames, and recall a long
+table's head rows rather than the table. `content check` warns early, from the
+source, when a frame passes `maxWords` words or `maxBullets` list items.
+
+_Enforcement._ Partial. `frame-dense` (`decks-validate.ts`, `pnpm
+validate:content`) warns from the source. `frame-overflow` (`deck-fit.ts`) fails
+the build: after Astro builds the site, every deck page is opened in the course's
+Chromium and each frame measured at its canvas size, every step shown. Without a
+browser it warns and measures nothing; in CI a missing browser fails the build.
+Review-only: the paper, where the PDF's export reports a frame that runs over as
+a warning naming it.
+
+_Exceptions._ None for the fit. A frame may pass the word count when the words are
+a quotation the room reads together; waive `frame-dense` on that frame with its
+reason.
+
+## D3
+
+**A frame makes one claim, and its title states the claim.**
+
+The title of a frame is the sentence the frame shows to be true: "Range is largest
+at a 45° launch angle", not "Range". Everything on the frame serves that claim.
+
+_Rationale._ A room reads the title first and sometimes only the title. A topic
+title ("Range") makes the room work out what the frame is for; a claim tells it,
+and makes the deck's outline a summary of the lecture.
+
+_How to apply._ Write the title as a statement with a verb. If a frame needs two
+claims, it is two frames.
+
+_Enforcement._ Review-only.
+
+_Exceptions._ A section's divider (`##`) names the section; it is a topic, not a
+claim.
+
+## D4
+
+**A frame with text carries speaker notes: the argument is in `<Notes>`, the frame
+shows its claims.**
+
+A `###` frame whose body has words carries a `<Notes>…</Notes>` block with what the
+speaker says: the reasoning, the transitions, the question to ask the room.
+
+_Rationale._ A frame shows claims; the argument between them is spoken. Written
+down, it is what the presenter window shows, what the handout prints under each
+frame, and what a student reads at home, so the deck is as complete as the chapter
+without the frame carrying paragraphs. The prose rules (P1–P9) hold for the notes.
+
+_How to apply._ Write the notes as you would say them, in full sentences. A frame
+that only shows a picture, an equation or a question needs none.
+
+_Enforcement._ Build-enforced (`decks-validate.ts`, `pnpm validate:content`):
+`frame-notes-missing`, a warning.
+
+_Exceptions._ A frame whose words are a label the room needs no help with.
+
+## D5
+
+**A frame title fits one line: at most `maxLength` characters.**
+
+A `##` or `###` heading in a deck runs to at most `maxLength` characters (50 by
+default) as the reader sees it: math as it reads, a `[[key]]` term as its label.
+
+_Rationale._ A title that wraps pushes the frame's body down by a line of the
+largest type on it, and a two-line title is usually a claim and its reason; the
+reason belongs on the frame.
+
+_How to apply._ Shorten the claim; move its condition or reason into the frame.
+
+_Enforcement._ Build-enforced (`decks-validate.ts`, `pnpm validate:content`):
+`frame-title-length`. The limit is `rules.D5.maxLength`.
+
+_Exceptions._ None.
+
+## D6
+
+**A frame shows in at most `maxSteps` steps, and each step adds to what is shown.**
+
+`<Pause />` is the one step mark. What follows it appears on the next key press, and
+nothing shown earlier changes or goes, so the last step is the whole frame — what the
+scroll view, the print and the PDF show.
+
+_Rationale._ A build-up shows the order of an argument; more steps than the room can
+hold in mind is a second frame. A step that takes something away would leave the
+handout, which shows the last step, without what the room saw.
+
+_How to apply._ Put `<Pause />` where the speaker stops to ask or to explain. Keep to
+`maxSteps` steps (4 by default); a driven figure or a spotlight is a step too.
+
+_Enforcement._ Partial (`decks-validate.ts`, `pnpm validate:content`): `frame-steps`
+warns past `maxSteps`. Review-only: that a later step contradicts nothing already
+shown.
+
+_Exceptions._ None.
+
+## D7
+
+**A frame holds at most one figure, table or diagram, and it is the frame’s
+picture.**
+
+One `<Figure>`, `<Table>`, `<Diagram>` or recalled float per frame, laid out at the
+canvas width. A lab's controls are the frame's tools, live in Present mode.
+
+_Rationale._ Two pictures on one frame each get half the canvas, and the room looks
+at neither long enough. One picture at full width is what a projector shows well.
+
+_How to apply._ Give a second picture its own frame, or put the two side by side in
+one figure when the comparison is the point.
+
+_Enforcement._ Build-enforced (`decks-validate.ts`, `pnpm validate:content`):
+`frame-floats`, a warning.
+
+_Exceptions._ A small table and the figure it reads off, when the frame is about
+reading one from the other.
+
+## D8
+
+**A result the chapter numbers is recalled with `<Recall>`, never retyped; the
+deck’s own floats carry no number.**
+
+`<Recall ref="eq-range" />` (and `fig-`, `tab-`, `dia-`) shows the chapter's
+equation, figure, table or diagram as it is in the chapter, with the chapter's
+number, and links to it.
+
+_Rationale._ A retyped equation drifts from the chapter's the first time either is
+corrected, and its number cannot be the chapter's. A recall is the chapter's own, so
+"(2.1.3)" on the frame is the same equation as (2.1.3) in the notes.
+
+_How to apply._ Recall what the chapter numbers; label (`\label{eq:…}`) only an
+equation that exists on the deck alone. A deck beside no chapter has nothing to
+recall: its floats are its own.
+
+_Enforcement._ Build-enforced (`decks-validate.ts`, `pnpm validate:content`):
+`frame-retyped` warns at a display equation whose LaTeX is a labelled chapter
+equation's; a recall that names nothing is the `decks` invariant's
+`recall-unresolved`.
+
+_Exceptions._ A step of a derivation that rewrites the chapter's equation on the way
+to it is not a retype.
+
+## D9
+
+**A frame introduces at most `maxNewSymbols` symbols the deck has not shown before.**
+
+Count the symbols a frame shows for the first time in the deck. The legend line
+under the frame names them.
+
+_Rationale._ The room reads a frame once, at the speaker's pace. Each new symbol is a
+name to learn on the spot; past a handful, the frame is read as notation, not as an
+argument.
+
+_How to apply._ Introduce a symbol on the frame that first needs it; split a frame
+that introduces many.
+
+_Enforcement._ Build-enforced (`decks-validate.ts`, `pnpm validate:content`):
+`frame-new-symbols`, info.
+
+_Exceptions._ A frame that lists the lesson's notation on purpose.
+
+## D10
+
+**A deck opens on its title frame and closes on what the student can now do.**
+
+The title frame (the lesson, the course, its authors and version) and the closing
+frame (the outcomes of the competencies the lesson teaches) are generated: do not
+write them.
+
+_Rationale._ The title frame is what the room sees while it sits down, and the
+closing frame is what it leaves with. Generated, they are the same in every deck and
+always current.
+
+_How to apply._ Write neither. With `deck.outcomesFrame` off, end on a `###` frame
+that says what the student can now do.
+
+_Enforcement._ Review-only: the engine writes both frames.
+
+_Exceptions._ None.