explico 0.7.0 → 0.11.0

package/docs/authoring/structure-rules.md

@@ -1,7 +1,9 @@
 # Structure rules
 
-`S` rules govern the shape of a lesson's headings and the short titles on its
-keyed floats — the parts of a page a reader scans before reading prose. This
+`S` rules govern the shape of a lesson's headings, the short captions on its
+keyed floats, the paragraphs that open a part page, and how a table, a
+diagram, or a convention is declared so the rest of the course can reach it —
+the parts of a page a reader scans, links to, or cites. This
 is not [structure.md](structure.md), which is the taxonomy these rules (and
 the rest of the engine) speak in, not a rule set itself.
 
@@ -12,58 +14,438 @@ and "Review-only" mean here, and how to amend a rule.
 
 ## S1
 
-**No heading, and no figure/diagram/memo/short-note title, runs past 65
-characters.**
+**No heading, no short caption (`short`, an equation's `\caption{}`) and no
+short-note title runs past 65 characters.**
 
 This caps every Markdown heading (`##` through `######`), a lesson's own
-`frontmatter.title` (rendered as the page's `<h1>`), and the short `title` /
-`label` prop on `Figure`, `Diagram`, `Memo`, and `ShortNote` — the text shown
-on a collapsed title bar, a diagram's caption line, or a chapter's sidebar
-entry. `Table` is exempt: it has only a `caption`, no separate `title`, and
-that caption is the LaTeX-convention full sentence shown above the table.
+`frontmatter.title` (rendered as the page's `<h1>`), the `short` caption of a
+`Figure`, `Diagram`, `Table`, `Memo` or `CompactExamples`, a display
+equation's `\caption{…}`, and a `ShortNote`'s `title` (its inline link
+text). A short caption is the name a float goes by away from itself — the
+heading of its `[[…]]` preview card, an equation's "Copy LaTeX — ‹caption›"
+tooltip — the `[short]` half of LaTeX's `\caption[short]{long}`. The long
+`caption` is never measured: it is the full sentence shown with the float's
+number (see [components.md § The caption pair](components.md#the-caption-pair)).
+A heading is measured as the reader sees it: its markers (`[collapsed]`,
+`[card]`, …) never render, so they never count.
 
-A heading or float title that runs long is usually doing a caption's job. Move
-the rest of the sentence into the paragraph right after a heading, or into the
-float's own `caption`.
+A heading or short caption that runs long is usually doing a caption's job.
+Move the rest of the sentence into the paragraph right after a heading, or
+into the float's long `caption`.
 
 ```mdx
-<!-- Over the limit: the title carries the whole explanation. -->
+<!-- Over the limit: the short caption carries the whole explanation. -->
 <Figure
   id="ar1-forecast-fan"
-  caption="Multi-step AR(1) forecast: the conditional mean (teal) decays geometrically to the unconditional mean while the Gaussian 95% band (shaded) widens toward the stationary dispersion Γ₀; the coral line is one seeded future path."
+  short="Multi-step AR(1) forecast: the conditional mean decays while the band widens"
+  caption="…"
 >
 
-<!-- At the limit: a short label, the rest moved into `caption`. -->
+<!-- At the limit: a short noun phrase, the rest in the long caption. -->
 <Figure
   id="ar1-forecast-fan"
-  title="Multi-step AR(1) forecast"
+  short="Multi-step AR(1) forecast"
   caption="The conditional mean (teal) decays geometrically to the unconditional mean while the Gaussian 95% band (shaded) widens toward the stationary dispersion Γ₀; the coral line is one seeded future path."
 >
 ```
 
-_Rationale._ A `Figure`'s `title` falls back to `caption` when omitted (see
-`Figure.astro`), so an unset `title` on a long-captioned figure silently
-becomes the text on the always-visible collapsible title bar — the reader
-sees the entire caption twice, once as the "heading" and once again in
-`<figcaption>` once they expand it. The same abuse happens with a heading
-authored as a full sentence instead of a label: the sidebar, the table of
-contents, and every anchor link now carry a paragraph instead of a title.
-Sixty-five characters is roughly one sidebar line at normal zoom before
-Starlight starts wrapping or truncating it.
-
-_How to apply._ Write the heading or `title` as a short noun phrase (a topic,
-not a claim about it); put the claim in the prose or the `caption`. If a
-`Figure` needs no distinct title beyond its caption's own first clause,
-extract that clause into `title` explicitly rather than omitting the prop and
-relying on the fallback — an omitted `title` on a long caption is exactly the
-failure this rule exists to catch.
+_Rationale._ A short name lands where space is tight: the sidebar, the table
+of contents, an anchor link, the heading of a preview card, a tooltip. A
+heading authored as a full sentence instead of a label puts a paragraph in
+every one of them. Sixty-five characters is roughly one sidebar line at
+normal zoom before Starlight starts wrapping or truncating it.
+
+_How to apply._ Write the heading or short caption as a short noun phrase (a
+topic, not a claim about it); put the claim in the prose or the long
+`caption`. A float needs no `short` at all when its long caption is already
+short — leave it out rather than repeat the caption.
 
 _Enforcement._ Build-enforced (`gate-heading-length.ts`, `pnpm
-validate:content`) for every Markdown heading in a lesson body and every
-`Figure`/`Diagram`/`Memo`/`ShortNote` `title`/`label` prop. Review-only for a
-lesson's `frontmatter.title` — the gate scans lesson body text and cannot see
-frontmatter, so a long page title (`<h1>`) is caught by a reviewer, not the
-build.
-
-_Exceptions._ None — a heading or float title that must exceed the limit
-should not be a heading or a float title; find the shorter label first.
+validate:content`) for every Markdown heading in a lesson body, every literal
+`short` prop on a `Figure`/`Diagram`/`Table`/`Memo`/`CompactExamples`, every
+display equation's `\caption{…}`, and every `ShortNote` `title`. Review-only
+for a lesson's `frontmatter.title` — the gate scans lesson body text and
+cannot see frontmatter, so a long page title (`<h1>`) is caught by a
+reviewer, not the build — and for a `short` set in a wrapper component the
+gate never sees (`DerivationDiagram.astro` passing `short` to `<Diagram>`).
+
+_Exceptions._ None — a heading or short caption that must exceed the limit
+should not be one; find the shorter label first.
+
+## S2
+
+**A part's overview page carries two authored paragraphs: a `<PartBridge>`
+on how the earlier parts lead into this one, then a `<PartScope>` on what
+this part covers.**
+
+This applies to every `content/docs/<dir>/index.mdx` a course authors (see
+[structure.md § Part pages](structure.md#part-pages)). Each slot holds exactly
+one paragraph, whose length falls inside the course's word range. The bridge
+comes before the scope. The first part has no earlier part to link from, so
+its bridge is optional; every other part must have one.
+
+```mdx
+import PartBridge from 'explico/components/PartBridge.astro';
+import PartOverview from 'explico/components/PartOverview.astro';
+import PartScope from 'explico/components/PartScope.astro';
+
+<PartBridge>
+
+Part 1 gave two results for a point that moves under a constant acceleration:
+its velocity and its position at any later time. … So this part needs no new
+law of motion.
+
+</PartBridge>
+
+<PartScope>
+
+This part answers two questions about a projectile launched over level
+ground. The first chapter derives the range … The second chapter finds the
+launch angle that gives the largest range.
+
+</PartScope>
+
+<PartOverview />
+```
+
+Keep a blank line inside each tag, so MDX parses the paragraph as Markdown and
+its math and `[[key]]` references render.
+
+The word range is a course setting, `rules.S2` in `course.settings.json`
+(`CourseConfig.rules`). Each end defaults to 30–150 words; list only what
+differs:
+
+```json
+"rules": {
+  "S2": { "bridgeMaxWords": 120, "scopeMaxWords": 120 }
+}
+```
+
+The four keys are `bridgeMinWords`, `bridgeMaxWords`, `scopeMinWords`,
+`scopeMaxWords`.
+
+A math span and a `[[key]]` reference count as one word each; a link counts
+by its text; a citation and markup count nothing.
+
+_Rationale._ `<PartOverview>` lists a part's chapters and the parts it builds
+on, but a list does not say _why_ the part follows the one before it. A reader
+who lands on a part page from a search result or a link needs to know which
+earlier results this part reuses before the chapter list means anything.
+Without a required slot, an intro drifts into one of two failures: it restates
+the chapter list, or it describes this part as if nothing came before it. A
+separate scope paragraph stops the bridge from turning into a summary of the
+part itself. A length range keeps both paragraphs substantive but short enough
+to read before the chapter list.
+
+_How to apply._ In the bridge, name the earlier part and the results from it
+that this part uses, and state what those results now make possible. In the
+scope, state the question this part answers and how its chapters answer it,
+in reading order. Keep prose that fits neither paragraph outside both slots.
+
+_Enforcement._ Build-enforced (`gate-part-pages.ts`, `pnpm validate:content`)
+for the presence, count, order, paragraph count, and word range of both
+slots. Review-only for what each paragraph says — the gate cannot tell a
+bridge that links the parts from one that does not.
+
+_Exceptions._ None for a part that has an overview page. A part without an
+`index.mdx` is out of scope: overview pages stay opt-in.
+
+## S3
+
+**A table is a `<Table id="…">`, never a raw Markdown or HTML table.**
+
+A pipe table or a `<table>` element written straight into a lesson renders,
+but it has no number, no anchor, and `[[tab-…]]` cannot reach it. Wrapping it
+gives it all three:
+
+```mdx
+<Table id="kinematics-summary" caption="Position and velocity under constant acceleration.">
+
+| Quantity | Formula |
+| --- | --- |
+| $x(t)$ | $x_0 + v_0 t + \tfrac{1}{2} a t^2$ |
+
+</Table>
+```
+
+_Rationale._ Every other float on a page — equation, figure, diagram, knowledge
+check — is numbered and citable; a table that is not breaks the reader's
+expectation that "Table 2.3" exists and the author's ability to say "see
+[[tab-kinematics-summary]]". The keyed-float validator never sees a raw table,
+so its header labels, its overflow handling, and its place in the page's float
+count are all skipped too.
+
+_How to apply._ Wrap the table in `<Table id="…" caption="…">` with a blank
+line inside each tag. The `id` is kebab-case and unique on the page; the
+`caption` is the full sentence shown above the table.
+
+_Enforcement._ Build-enforced (`raw-floats-validate.ts`, `pnpm
+validate:content`) — a warning per lesson (`raw-table-markdown`,
+`raw-table-html`); `remarkNotation` repeats it at render time for content
+added since the manifest was compiled. It does not fail the build.
+
+_Exceptions._ A table inside a component that already gives it identity is
+out of scope: the scan only counts tables at the top level of the lesson
+body.
+
+## S4
+
+**A `<Diagram>` carries an `id` and sits where diagram numbering can see it.**
+
+Diagram numbering scans the top level of a lesson and the bodies of
+`<Memo>`, `<ShortNote>`, `<Table>`, and `<Figure>`. A `<Diagram>` with no `id`,
+or one nested anywhere else (inside `<CompactExample>`, say), is drawn but
+never numbered, and `[[dia-…]]` cannot reach it.
+
+```mdx
+<!-- Numbered, citable. -->
+<Diagram id="velocity-dependencies" caption="What the velocity depends on" … />
+
+<!-- Drawn, but invisible to numbering. -->
+<CompactExample>
+  <Diagram caption="…" … />
+</CompactExample>
+```
+
+_Rationale._ The same reason as S3: a float the reader can see but the author
+cannot cite is a hole in the reference system. Nesting is the subtler case —
+the diagram *looks* fine on the page, and only the missing number gives it
+away.
+
+_How to apply._ Give the diagram an `id`. Move it to the top level, or into a
+`<Memo>`/`<ShortNote>`, or wrap it in `<Figure id="…">` so the figure carries
+the identity.
+
+_Enforcement._ Build-enforced (`raw-floats-validate.ts`, `pnpm
+validate:content`) — a warning per lesson (`diagram-unkeyed`,
+`diagram-nested`); repeated by `remarkNotation` at render time. It does not
+fail the build.
+
+_Exceptions._ A purely decorative diagram that nothing will ever cite may stay
+unkeyed; say so in a comment next to it.
+
+## S5
+
+**A sign or perspective convention is declared once and cited everywhere
+else.**
+
+A course names one notation entry as its sign convention
+(`conventions.signConventionKey`) and one competency as its cash-flow /
+perspective convention (`conventions.cashFlowPerspectiveCompetency`). A lesson
+whose prose states such a convention — "outflows are negative", "angles are
+measured counter-clockwise from the horizontal" — resolves it to that single
+declaration rather than restating it.
+
+```mdx
+<!-- Restated: a second, drifting definition. -->
+In this chapter, an outflow is a negative cash flow.
+
+<!-- Resolved to the declaration. -->
+Cash flows follow the [[cash-flow.sign]] convention: an outflow is negative.
+```
+
+_Rationale._ A convention restated in several lessons drifts — one says
+"negative", another "shown in parentheses" — and a reader who learned it in
+one place cannot tell whether the other place means the same thing. One
+declaration, cited, keeps the meaning in one file.
+
+_How to apply._ Cite the convention's notation entry with `[[key]]` in the
+sentence that invokes it, or list the convention's competency in the lesson's
+`teaches` / `requires`. Either anchors the prose to the declaration.
+
+_Enforcement._ Build-enforced (`consistency.ts`
+`checkConventionSingleDefinition`, `pnpm validate:content`) — a warning
+(`convention-single-definition`) for a lesson whose prose matches the
+convention pattern and is anchored by neither the term nor the competency.
+
+_Exceptions._ The lesson that *is* the declaration — the one that teaches the
+convention's competency — is anchored by definition.
+
+## S6
+
+**Headings descend one level at a time: a lesson body starts at `##` and
+never skips a level on the way down.**
+
+The page title (`frontmatter.title`) is the lesson's `<h1>`, so the body's
+first heading is a `##`, and a `#` in the body is a second title. From there
+each heading is at most one level deeper than the one before it: `##` → `###`
+→ `####`, never `##` → `####`. Going back up is free — a `####` may be
+followed by a `##`. A knowledge check's heading (`<AssessmentSet />`) and a
+worked-example set's (`<CompactExamples>`) are a `##` here, since that is what
+each renders.
+
+```mdx
+<!-- A skip: the #### has no ### above it. -->
+## Two ways to name the same point
+The same point has a Cartesian and a polar name.
+#### From Cartesian to polar
+
+<!-- One level at a time. -->
+## Two ways to name the same point
+The same point has a Cartesian and a polar name.
+### From Cartesian to polar
+```
+
+_Rationale._ A heading's level is its place in the outline, not its type
+size. A skipped level leaves a subsection with no section above it: the
+numbering has to invent a `0` for it (`1.1.1.0.1`), "On this page" indents it
+under nothing, and a screen reader's heading list — the way many readers move
+through a page — reports a level that does not exist.
+
+_How to apply._ Pick the level from what the heading belongs under, never
+from how large it should look. When the material near the bottom of the
+outline needs more structure, do not open deeper headings to get it: see
+[structure.md § Structure from the bottom up](structure.md#structure-from-the-bottom-up).
+
+_Enforcement._ Build-enforced (`gate-heading-structure.ts`, `pnpm
+validate:content`, `heading-skip`) over a lesson's outline — the top-level
+headings the section numbers count. A heading inside a component's children
+(a `<Memo>`, a `<CompactExample>`) belongs to that component and is not part
+of the outline, and a memo's own bar is not a heading of the lesson.
+
+_Exceptions._ None in the rule; waive one place with
+`{/* explico-allow S6: reason */}` above the heading.
+
+## S7
+
+**A heading is followed by body content, never directly by another heading.**
+
+Between a heading and the next one — whatever their levels — comes body
+content: at least a sentence on what the section is about, or a figure, a
+table, an equation. A comment renders nothing and does not count.
+`<AssessmentSet />` and `<CompactExamples>` count as headings here, because
+each draws an `<h2>` of its own (the kind's badge, its number and its topic):
+no heading goes directly above either.
+
+```mdx
+<!-- Two titles in a row: "Try it", then the set's own heading. -->
+## Try it
+
+<CompactExamples id="coordinate-conversions" short="Calculation examples between coordinate systems">
+
+<!-- A section heading with no body under it. -->
+## Two ways to name the same point
+### From Cartesian to polar
+
+<!-- The section says what it is about before it subdivides. -->
+## Two ways to name the same point
+The same point has a Cartesian and a polar name; each converts to the other.
+### From Cartesian to polar
+```
+
+_Rationale._ A heading introduces the text below it. Two in a row give the
+reader two labels and nothing to read; the first says nothing of its own,
+and a collapsed section with only a heading inside it folds away nothing.
+The engine already names a knowledge check and a worked-example set, so a
+heading written above either repeats a title the reader sees next.
+
+_How to apply._ Write a sentence under a heading that has subsections, on
+what the section covers. Drop a heading that only announces the block below
+it ("Try it" above worked examples, "Check yourself" above a knowledge
+check): the block's own title does that.
+
+_Enforcement._ Build-enforced (`gate-heading-structure.ts`, `pnpm
+validate:content`, `heading-adjacent`) over a lesson's outline, reported at
+the first heading of the pair. A memo, a figure and every other component
+count as body content.
+
+_Exceptions._ None in the rule; waive one place with
+`{/* explico-allow S7: reason */}` above the first heading.
+
+## S8
+
+**Use a `<Memo>`, not a Starlight aside, for content that deserves an anchor,
+a caption, or collapsing.**
+
+A Starlight aside — `:::note`, `:::tip`, `:::caution`, `:::danger`, or
+`<Aside>` — is a short callout read in passing. It renders in the aside tier
+(a left rule and a tint, Starlight's icon per type kept), but it has no
+number, no link, and it never folds. A `<Memo>` is the same aside tier with
+all three: a letter and a chain icon a reader can link to, a caption shown on
+its bar and in its `[[memo-…]]` preview, and a collapsed state that
+remembers the reader's choice.
+
+```mdx
+<!-- A passing remark: an aside is right. -->
+:::note
+Air resistance is ignored throughout this part.
+:::
+
+<!-- A derivation a reader may skip, and a later lesson may cite: a memo. -->
+<Memo id="range-check" short="Checking the range formula" caption="…">
+  …
+</Memo>
+```
+
+The icon is Starlight's default for the type (note → `information`, tip →
+`rocket`, caution → `warning`, danger → `error`). Name any Starlight
+built-in icon to replace it (`:::note{icon="heart"}`, `<Aside icon="heart">`),
+or leave the value empty to drop it (`:::note{icon=""}`, `<Aside icon="">`).
+`note` and `tip` take the course accent; `caution` and `danger` keep a
+warning and a danger hue.
+
+_Rationale._ An aside that grows into a derivation, or that another lesson
+wants to point at, has outgrown its container: nothing can link to it, and a
+reader who has already understood it cannot fold it away. Choosing the memo
+up front keeps the reference system whole.
+
+_How to apply._ Ask whether anyone would cite, skip, or return to the block.
+If so, make it a `<Memo id="…">`; if it is one or two sentences read once,
+keep the aside.
+
+_Enforcement._ Review-only — no check can tell a passing remark from a
+derivation that deserves a number.
+
+_Exceptions._ None.
+
+## S9
+
+**A float’s short caption names it, and its long caption goes on from that
+name instead of restating it; a figure holds no running text, and a lab’s
+instructions go in its tools.**
+
+A figure's, a table's or a diagram's `short` caption is its name wherever the
+page names it: the bold title that opens its caption line, a folded
+section's "Hidden here", a `<Fold>`'s bar, a copied link and the "Figures and
+tables" page ([components.md § The caption pair](components.md#the-caption-pair)).
+Printed as the title, it is read right before the long caption, so the long
+caption continues from it, as a journal's figure legend does ("Fig. 1 |
+Title. Description"), instead of saying the same thing twice. Each part of a
+figure's text has one job:
+
+- the short caption names the float;
+- the long caption says what it shows — its subject, its marks and symbols,
+  the case shown with its parameters — and may state the one thing to
+  notice;
+- the argument drawn from the figure is lesson text, after the figure;
+- what to do with a lab's controls is the first line of its tools, never the
+  caption.
+
+```mdx
+<!-- Restated: the title says "sampled flight data", then the caption does. -->
+<Table id="projectile-telemetry" short="Sampled flight data"
+  caption="Flight data sampled at eleven times: position, velocity, …">
+
+<!-- Goes on from the title. -->
+<Table id="projectile-telemetry" short="Sampled flight data"
+  caption="Position, velocity, acceleration and specific mechanical energy through one flight, from launch to landing.">
+```
+
+_Rationale._ With the short caption printed as the caption line's title, a
+long caption that opens with the same words reads as a stutter. A caption
+that carries the argument hides it where a reader of the text does not look,
+and one that tells the reader to move a slider prints that instruction on a
+page with no slider on it.
+
+_How to apply._ Write the `short` first: the name a reader would use for the
+float ("Sampled flight data"). Then read the caption line as it prints, the
+title and the long caption together, and cut what the title already says.
+Move a sentence that argues into the paragraph after the float, and a
+sentence that says what to do with a lab's controls into its tools.
+
+_Enforcement._ Review-only — no check can tell a caption that restates its
+title from one that builds on it.
+
+_Exceptions._ A float that needs no name of its own may go without a
+`short`; the "Figures and tables" page then lists it by its long caption,
+muted.