rshow 0.0.5 → 0.0.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rshow",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "description": "Publish static artifacts to rshow",
   "license": "MIT",
   "homepage": "https://rslib.github.io/rshow",
@@ -44,6 +44,7 @@
   "devDependencies": {
     "@types/node": "^26.6.6",
     "esbuild": "0.28.2",
+    "katex": "0.19.1",
     "rshow-shared": "*",
     "typescript": "^5.9.3"
   }

package/skills/rshow/SKILL.md

@@ -62,6 +62,11 @@ Copy this checklist into the reply and tick it as you go.
   Never write `latest`.
 - A report links `report.css` and `report.js` in place of `page.css`, and `mode.js` still goes in the head.
   Read [reports](reference/reports.md) before you write one.
+- Math is LaTeX in the text of an element with the class `math`, and the page links `math.css` and `math.js` for it.
+  Math needs theme version 8 or newer, so a page on an older version moves up with `rshow config <dir>`.
+  A `div.math` is display math and any other element is inline.
+  A `$` in the prose is a price and is never read as math, so `$5` stays text.
+  Read [reports](reference/reports.md) for the markup an equation takes.
 - The page reads at 360px wide.
   Tables go inside `<div class="table">`.
 - Nothing secret in a page, because anyone who holds the link can read the HTML source.
@@ -145,6 +150,8 @@ The short list above is a hard rule.
 - Never publish a folder that holds `.env`, a key, a credential or customer data.
 - Never publish a source tree, `node_modules` or a `dist` folder that still holds a draft.
 - Never write the token into a page, a script, a log line, a commit or a chat message.
+- Never fake math with Unicode subscripts, Greek letters in mono or an HTML `<sub>`.
+  Write the LaTeX in an element with the class `math` and link `math.css` and `math.js`.
 - Never create a second artifact with a `-v2` slug.
   Publish the same slug again.
 - Never delete an artifact or drop a share without a yes from the person.

package/skills/rshow/reference/mockups.md

@@ -110,6 +110,7 @@ Never present invented data as if somebody measured it.
 
 - `rshow check <dir>` exits 0, then `rshow preview <dir>`.
 - Look at the canvas, the focus view and Play mode, in both modes, at desktop width and at 360px.
+- Press `?` on the page for the keys: `w` `a` `s` `d` or the arrows pan, `[` `]` step between screens, `Enter` opens one, `1` to `9` pick a state, so tell the person about that list.
 - Switch the skin in the toolbar and check the drawing still reads.
 - Print puts one artboard on a page with no tool chrome, which is what a review meeting wants on paper.
 - `rshow publish <dir> --slug <slug> --label "<what changed>"`, then read `rshow-implement` before anybody writes code from it.

package/skills/rshow/reference/reports.md

@@ -109,7 +109,11 @@ Numbering is generated, so never type a number into a heading.
 
 `report.js` puts `Figure 1.` or `Table 1.` in front of the caption and counts in document order, so give every one an `id`.
 Draw the figure as inline `<svg>` with the colours from tokens, and give it a `viewBox` so it scales.
-An equation is `<div class="equation" id="eq-bytes">` with the formula inside, and `report.js` adds `(1)` at the end of the line.
+An equation is `<div class="equation" id="eq-bytes">` with a `<div class="math">` of LaTeX inside it, and `report.js` adds `(1)` at the end of the line.
+The report links `math.css` in the head and `math.js` before `report.js`, and `rshow check` reports bad LaTeX as an error.
+Inline math is a `<span class="math">` inside the sentence, and a wide equation scrolls inside its own box on a phone.
+Write `<` as `&lt;` and `&` as `&amp;` inside the LaTeX, and `&amp;` where lines align in a LaTeX alignment.
+A `$...$` in the prose is not math: it is text, so a price such as `$5` stays a price.
 Mark example data as example data in the caption, and never present a number you did not measure.
 
 ## Cross-references

package/skills/rshow-slides/SKILL.md

@@ -33,6 +33,7 @@ A topic on its own is not a slide.
 ## 2. Skeleton
 
 Replace `<name>@<n>` with the `theme` value that `rshow config <dir>` prints, which the server resolves to the current version. Use `default@3` only when `rshow config` warns that it cannot resolve the theme.
+Math needs theme version 8 or newer, so a page on an older version moves up with `rshow config <dir>`.
 
 ```html
 <!doctype html>
@@ -44,6 +45,9 @@ Replace `<name>@<n>` with the `theme` value that `rshow config <dir>` prints, wh
 <link rel="stylesheet" href="/_themes/default@3/fonts.css">
 <link rel="stylesheet" href="/_themes/default@3/tokens.css">
 <link rel="stylesheet" href="/_themes/default@3/deck.css">
+<!-- a deck that writes math links these two, and math.js goes before deck.js -->
+<link rel="stylesheet" href="/_themes/default@3/math.css">
+<script defer src="/_themes/default@3/math.js"></script>
 </head>
 <body>
 <main class="deck">
@@ -71,6 +75,7 @@ Replace `<name>@<n>` with the `theme` value that `rshow config <dir>` prints, wh
 ```
 
 The three stylesheet links and the script carry the same `<n>` on purpose, because a mixed version renders somewhere between two designs.
+A fallback to `default@3` keeps the page readable but has no math, so a deck on that version links neither `math.css` nor `math.js`, and the `math.js` warning of `rshow check` is the sign to move up.
 The deck needs no `mode.js`, because `deck.js` reads the same key and `t` does the same work.
 Override a token in one `:root` block after the theme links when the deck needs its own accent, with no limit on the declarations.
 An inline `<style>` block after the theme links may also carry a layout of the deck's own, as section 3 says.
@@ -85,6 +90,7 @@ Every slide is a `<section class="slide ...">`, and the second class is one of t
   One series is drawn in the accent blue and two or more take `--chart-1`, `--chart-2` and so on in order.
 - `table` for a clean data table and `code` for one command.
 - `two-col` for two blocks of text, `quote` for one sentence and `big-number` for one number.
+- A slide with an equation is a `bullets` slide with one `<div class="math">` of LaTeX under the title, and the deck links `math.css` and `math.js` for it.
 
 A sparse slide is centred a little above the middle of the canvas, so the air sits under the block.
 A bullets slide puts its points under the title at 28px with a 1.4 line, five at most.
@@ -102,6 +108,7 @@ Vary the rhythm: do not run more than three text slides (`two-col` or `bullets`)
 - Every slide gets one `<aside class="notes">`, including the title slide, because a slide without one shows nothing in the notes window.
 - Keep a note under 60 words.
   It is what you say, not what the room reads.
+- A note holds no math: an equation inside an `aside.notes` stays as its LaTeX, because the notes window loads no math stylesheet.
 - Press `n` for the notes window, which also names the next slide.
 - Press `p` for the presenter view: the current slide, the next slide, the notes and an elapsed timer, kept in step with the deck.
 - Put `class="step"` on any element inside a slide to reveal it one press later, because `deck.js` selects every `.step` in the slide.
@@ -112,6 +119,8 @@ Vary the rhythm: do not run more than three text slides (`two-col` or `bullets`)
   Press `Ctrl` and `P` for a print sheet when someone wants a pdf.
 - Press `t` to cycle the mode: system, light, dark, with the mode shown in the counter for a moment.
   The choice is remembered for every rshow document and print is always light.
+- On a phone held upright the deck reads as a stack of slides, each one reflowed to the width of the screen at phone sizes with a rule and an `n / total` label between slides, and a `Present` button goes back to one slide at a time.
+  `Esc` comes back to reading, and the arrows, space and a `#n` link work in both.
 
 ## 5. Check, preview, publish
 

package/skills/rshow-slides/reference/layouts.md

@@ -14,6 +14,7 @@
 - two-col
 - quote
 - big-number
+- math (an equation on a bullets slide)
 - your own layout
 
 One markup example per layout, all inside `<main class="deck">`.
@@ -252,6 +253,20 @@ The unit belongs in the statement and the source goes under it.
 
 A number you cannot measure is `[PLACEHOLDER]` until it is real, and a number that stands for an example says so in the source line.
 
+## math
+
+An equation takes a `bullets` slide: a takeaway title and one `div.math`.
+The LaTeX is the text of the element, and the deck links `math.css` and `math.js` for it.
+A note holds words, not math.
+
+```html
+<section class="slide bullets">
+  <h2>A republish sends only the bytes that changed</h2>
+  <div class="math">\mathrm{sent}(n) = \sum_{f \in \mathrm{new}(n)} |f|</div>
+  <aside class="notes"><p>The sum drops every file the host already holds.</p></aside>
+</section>
+```
+
 ## your own layout
 
 A layout of your own takes a short class name and sits second on the slide, in the same slot as the twelve.

package/themes/default/deck.css

@@ -517,6 +517,323 @@ aside.notes {
   pointer-events: none;
 }
 
+/* --------------------------------------------------------------- reading */
+
+/* A phone held upright cannot show a 16:9 slide: 390px of width leaves a 219px
+   strip. So the deck stops presenting and reads. Every slide becomes a block
+   down the page, the width of the screen, one after another, with no scale in
+   it: a 1280px canvas shrunk to 390px sets the body text near 9px, which is a
+   picture of a slide and not a slide. The type takes sizes a phone reads, each
+   figure takes the width it is given, a wide table or a block of code scrolls
+   sideways inside itself, and every grid stacks to one column. The notes stay
+   hidden, every step is out, and a hairline rule with an "n / total" label in
+   the margin marks where one slide ends and the next begins.
+   deck.js turns this on for a viewport that is portrait and narrower than 700px,
+   and off everywhere else: a landscape phone and a desktop keep one slide at a
+   time. The button that goes back to presenting is deck.js's, and Esc comes back
+   here. It is a screen mode, so it sits in @media screen: a sheet of paper keeps
+   one slide per page, laid out on the canvas it was drawn for. */
+
+@media screen {
+  html.is-reading,
+  body.is-reading {
+    height: auto;
+    overflow: visible;
+    background: var(--bg);
+    /* Reading sizes. The type scale has no 17px step and the canvas headings are
+       drawn for 1280px, so a phone slide names the size of its own body text and
+       of the one line a quote or a statement sets. Every other size below is a
+       token: 32px, 24px, 20px, 18px, 14px. */
+    --deck-read-body: 17px;
+    --deck-read-line: 22px;
+  }
+
+  /* The deck is the page now: no canvas, no transform, no clip. The bottom pad
+     clears the Present button, so the last line of the last slide stays under
+     the reader's thumb and not inside it. */
+  main.deck.is-reading {
+    position: static;
+    width: auto;
+    height: auto;
+    margin: 0;
+    padding: 0 0 80px;
+    overflow: visible;
+    transform: none !important;
+    background: var(--bg);
+    counter-reset: deck-slide;
+  }
+
+  /* One slide, one block: the width of the screen, a 16px gutter either side,
+     air above and below, and a rule where the previous slide ended. */
+  main.deck.is-reading > .slide,
+  main.deck.is-reading.is-ready > .slide {
+    position: relative;
+    inset: auto;
+    display: block;
+    width: auto;
+    height: auto;
+    min-height: 0;
+    margin: 0;
+    padding: var(--space-06) var(--space-05);
+    overflow: visible;
+    opacity: 1;
+    visibility: visible;
+    transform: none;
+    border-top: 1px solid var(--border-subtle);
+    counter-increment: deck-slide;
+  }
+
+  main.deck.is-reading > .slide:first-child {
+    border-top: 0;
+  }
+
+  /* Where this slide sits in the stack. It is a label, so sans, sentence case
+     and the muted colour of every other label: mono and caps are for code. */
+  main.deck.is-reading > .slide::before {
+    content: counter(deck-slide) " / " var(--deck-total, "");
+    display: block;
+    margin: 0 0 var(--space-05);
+    font-family: var(--font-sans);
+    font-size: var(--text-2xs);
+    font-weight: 400;
+    line-height: 1.33;
+    letter-spacing: 0;
+    text-transform: none;
+    color: var(--muted);
+    font-variant-numeric: tabular-nums;
+  }
+
+  /* ----------------------------------------------------- reading type --- */
+
+  /* The display steps belong to a 1280px slide: 76px of heading in 358px of
+     width is three words a line. In reading mode a heading is a heading. */
+  main.deck.is-reading .slide h1,
+  main.deck.is-reading .slide h2,
+  main.deck.is-reading .slide h3 {
+    margin: 0 0 var(--space-04);
+    max-width: none;
+    font-weight: 400;
+    line-height: var(--lh-heading);
+    letter-spacing: 0;
+  }
+
+  main.deck.is-reading .slide h1 {
+    font-size: var(--text-xl);
+  }
+
+  main.deck.is-reading .slide h2 {
+    font-size: var(--text-md);
+  }
+
+  main.deck.is-reading .slide h3 {
+    font-size: var(--text-base);
+    font-weight: 600;
+  }
+
+  /* Running text: 17px on a 1.45 leading reads on a phone without a pinch, and
+     the measure is the screen, so nothing caps it short of the gutter. */
+  main.deck.is-reading .slide p,
+  main.deck.is-reading .slide li,
+  main.deck.is-reading .slide li > p,
+  main.deck.is-reading .slide .col p,
+  main.deck.is-reading .slide .col li {
+    max-width: none;
+    font-size: var(--deck-read-body);
+    line-height: var(--lh-body);
+  }
+
+  main.deck.is-reading .slide ul,
+  main.deck.is-reading .slide ol {
+    padding-left: var(--space-06);
+  }
+
+  main.deck.is-reading .slide li {
+    margin-bottom: var(--space-03);
+  }
+
+  main.deck.is-reading .slide li:last-child {
+    margin-bottom: 0;
+  }
+
+  main.deck.is-reading .slide.title .subtitle {
+    margin-top: var(--space-04);
+    max-width: none;
+    font-size: var(--text-sm);
+    line-height: 1.4;
+  }
+
+  /* The line under a title, a figure or a table: a caption, so small and muted,
+     and never wider than the slide. */
+  main.deck.is-reading .slide .muted,
+  main.deck.is-reading .slide figcaption,
+  main.deck.is-reading .slide cite,
+  main.deck.is-reading .slide caption,
+  main.deck.is-reading .slide .byline,
+  main.deck.is-reading .slide .source,
+  main.deck.is-reading .slide li > p {
+    max-width: none;
+    font-size: var(--text-2xs);
+    line-height: 1.45;
+  }
+
+  main.deck.is-reading .slide.section h2 {
+    margin-bottom: 0;
+    font-size: var(--text-md);
+    font-weight: 400;
+  }
+
+  main.deck.is-reading .slide.statement p,
+  main.deck.is-reading .slide.quote blockquote {
+    max-width: none;
+    font-size: var(--deck-read-line);
+    font-weight: 400;
+    line-height: 1.4;
+  }
+
+  main.deck.is-reading .slide.big-number .value {
+    font-size: var(--text-2xl);
+    line-height: var(--lh-flat);
+  }
+
+  main.deck.is-reading .slide.big-number .caption {
+    max-width: none;
+    font-size: var(--text-sm);
+    line-height: 1.4;
+  }
+
+  /* A statement or a divider carries one short line, so it keeps a little
+     height and sits its text in the middle of it instead of at the top. */
+  main.deck.is-reading > .slide.statement,
+  main.deck.is-reading > .slide.section {
+    display: flex;
+    flex-direction: column;
+    justify-content: center;
+    min-height: 40vh;
+  }
+
+  /* ------------------------------------------------ reading containers -- */
+
+  /* Anything that holds a picture takes the width it is given, keeps its own
+     shape, and never reaches past the gutter. */
+  main.deck.is-reading .slide figure {
+    display: block;
+    margin: 0;
+    min-height: 0;
+  }
+
+  main.deck.is-reading .slide img,
+  main.deck.is-reading .slide svg,
+  main.deck.is-reading .slide video,
+  main.deck.is-reading .slide canvas {
+    display: block;
+    max-width: 100%;
+    height: auto;
+  }
+
+  /* A table keeps its columns and a code block keeps its lines: each one
+     scrolls sideways inside itself rather than widening the page. */
+  main.deck.is-reading .slide table {
+    display: block;
+    width: 100%;
+    max-width: 100%;
+    overflow-x: auto;
+    font-size: 15px;
+    line-height: 1.4;
+  }
+
+  main.deck.is-reading .slide th,
+  main.deck.is-reading .slide td {
+    padding: var(--space-03) var(--space-04);
+  }
+
+  main.deck.is-reading .slide pre {
+    max-width: 100%;
+    max-height: none;
+    padding: var(--space-05);
+    overflow-x: auto;
+    overflow-y: hidden;
+    font-size: 14px;
+    line-height: var(--lh-code);
+    white-space: pre;
+    word-break: normal;
+    tab-size: 2;
+  }
+
+  /* Two columns and two figures side by side are a landscape idea. On a phone
+     every grid is one column, in the order the deck wrote it. */
+  main.deck.is-reading > .slide.two-col,
+  main.deck.is-reading > .slide.three-col,
+  main.deck.is-reading > .slide .pair,
+  main.deck.is-reading > .slide .col,
+  main.deck.is-reading > .slide .cols,
+  main.deck.is-reading > .slide .grid,
+  main.deck.is-reading > .slide .gallery {
+    display: block;
+    grid-template-columns: none;
+    gap: 0;
+    min-height: 0;
+  }
+
+  main.deck.is-reading .slide.two-col > h2 {
+    grid-column: auto;
+    margin-bottom: var(--space-05);
+  }
+
+  main.deck.is-reading .slide .pair > figure + figure,
+  main.deck.is-reading .slide .col + .col {
+    margin-top: var(--space-06);
+  }
+
+  /* --------------------------------------------------- reading chrome --- */
+
+  /* A reader scrolls. A keypress it cannot give, so nothing waits for one, and
+     the notes and the counter are a presenter's furniture, not a reader's. */
+  main.deck.is-reading .step {
+    opacity: 1;
+  }
+
+  main.deck.is-reading aside.notes,
+  main.deck.is-reading .deck-hud {
+    display: none;
+  }
+}
+
+/* One slide at a time, for a room or for a phone turned back to presenting. */
+.deck-present {
+  position: fixed;
+  z-index: 20;
+  right: max(16px, env(safe-area-inset-right, 16px));
+  bottom: max(16px, env(safe-area-inset-bottom, 16px));
+  min-width: 44px;
+  min-height: 44px;
+  padding: 0 14px;
+  font-family: var(--font-sans);
+  font-size: var(--text-2xs);
+  line-height: 1;
+  letter-spacing: 0;
+  color: var(--fg);
+  background: var(--bg);
+  border: 1px solid var(--border-subtle);
+  border-radius: var(--radius);
+  cursor: pointer;
+  -webkit-appearance: none;
+  appearance: none;
+}
+
+.deck-present[hidden] {
+  display: none;
+}
+
+/* A phone in present mode keeps the canvas on the window rather than in the
+   document: a 1280px box in the page widens a phone's layout viewport and
+   pushes the slide off the screen. */
+@media (max-width: 699px) {
+  main.deck {
+    position: fixed;
+    inset: 0;
+  }
+}
+
 @media (prefers-reduced-motion: reduce) {
   .step {
     transition: none;
@@ -574,9 +891,16 @@ aside.notes {
   }
 
   .deck-hud,
-  aside.notes {
+  aside.notes,
+  .deck-present {
     display: none !important;
   }
+
+  /* Reading mode is a screen mode, so a page printed from a phone is the deck
+     on its canvas again: one slide, one sheet. Nothing here has to undo it. */
+  main.deck.is-reading {
+    overflow: visible;
+  }
 }
 
 /* Exact 16:9 sheet for one slide per page. */