@jokerized/decksmith 0.6.0 → 0.8.0

package/README.md

@@ -13,13 +13,19 @@ source.
 
 ## Prerequisites
 
-- Node 22 or later, and nothing else to **generate** a deck. `ingest`, `build`, `pack` and
-  `unpack` are pure Node: they read files, write files, and never open a browser. Decide
-  your deployment on that line — a service that turns papers into decks runs in a plain
-  Node image.
+- Node 22 or later, and nothing else to **generate** a deck. `ingest` of a file, `build`,
+  `pack` and `unpack` run in plain Node. `build` also opens each stop in Chrome when it can
+  find one, and warns `not_measured` when it cannot. Decide your deployment on that line —
+  a service that turns papers into decks runs in a plain Node image.
 - A Chromium build and ffmpeg to **render or check** one. `verify` drives the HyperFrames
   gates in a headless browser, and the MP4 encode is ffmpeg's. Both arrive with the
   hyperframes toolchain during `npm install`; there is nothing to install by hand.
+- On Linux, Chrome's sandbox needs unprivileged user namespaces, and Ubuntu 23.10 and later
+  deny them by default. DeckSmith then opens its own pages, the gates' view of a deck and a
+  caption band, without the sandbox, as HyperFrames' render always does, and prints a
+  `chrome:` line saying so. `ingest` of a URL refuses instead, because that page comes from
+  the web. `sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0`, or an AppArmor
+  profile for Chrome, gives the sandbox back.
 - Three commands reach outside for their own reasons: `plan` runs the Codex CLI, `narrate`
   runs edge-tts over the network, and `illustrate` asks an image backend or that same Codex
   account for pictures — and draws its own when neither will.
@@ -850,8 +856,8 @@ Three, each a position rather than a hue.
 
 `mono`'s four tones are a grey ladder plus one red rather than four hues, because value is
 what survives a bad projector and hue is not; four hues would have collapsed into one
-grey. All three keep the Inter stack — font families auto-resolve from a fixed allowlist,
-and a serif naming a family the bundle does not declare falls back silently.
+grey. All three keep the Inter stack — `build` ships Inter beside every deck, and a serif
+naming a family the deck does not declare falls back silently.
 
 A theme is a name and a palette, and that is the whole extension point: a new one is a
 file in `src/emit/themes/` plus a line in `THEMES`. No archetype learns it exists.
@@ -1199,13 +1205,28 @@ mechanically rather than free-hand.
   root timeline holds only a dummy tween spanning the deck.
 - KaTeX renders with `output: "html"`. The default also emits a hidden MathML mirror that
   the layout inspector reads as overlapping text.
+- No TeX reaches a `katex.render` call that KaTeX has not already parsed in Node, with
+  `throwOnError` and the deck's own options (`src/emit/tex.ts`). A formula that fails gets
+  a repair only where it cannot change what the formula says — a missing `\right.`, an
+  unclosed brace, a dropped `\label`, a paper's undefined macro drawn as its name — and the
+  repair is printed at `plan` and again at `build`. One no repair saves is shown as its
+  source in plain text by `equation-walk`, and costs the beat, by name, in
+  `equation-morph`. Until this existed the first parser a formula met was the browser at
+  `verify`, after the deck had been built and narrated: 26 of 92 failed HypePaper builds
+  in the week to 2026-10-07, 25 of them from `wrapTerms` cutting a `\left`/`\right` pair or
+  a superscript in half.
+- `equation-walk` measures its display after fonts and fits it to its box: smaller down to
+  the 40px floor, then broken after top-level relations and operators. One that still does
+  not fit fails `fidelity` as `math_unfit`, with the formula in the message.
 - No `Date.now()`, no `Math.random()`, no network at render time *in the composition*.
   Two renders of an image-free deck must be byte-identical. `deck.html` is exempt: it is
   presented, never rendered, and its subtitle loop legitimately reads a clock.
 - `deck.html` never contains the string `data-composition-id`. A root-level HTML file that
   does trips lint's `multiple_root_compositions`, and the deck stops being navigable.
-- Fonts auto-resolve only from a fixed allowlist. Inter is on it, Noto Sans KR is not, so
-  every CJK deck ships its own subsetted `@font-face` or the text silently falls back.
+- Every deck declares the face its stack names. A CJK deck ships a subsetted Noto; every
+  other deck ships Inter from `@fontsource-variable/inter`. HyperFrames resolves Inter from
+  its own allowlist, but only inside a render: the gates' page and `deck.html` never run its
+  compiler, and without the deck's own face they drew SF on a Mac and DejaVu on Linux.
 - Audience text never goes below 40px at 1920x1080, display equations sit at 60–76px. A
   30px equation passes every automated gate and is unreadable from row six.
 - **No archetype declares its own content width.** The box comes from