From 1c73c5d8180de302dd6d4833f02baad4c1b15ca6 Mon Sep 17 00:00:00 2001
From: Brett Gentile <bgentile19@gmail.com>
Date: Fri, 14 Aug 2026 19:09:10 -0400
Subject: [PATCH 1/2] feat(web): the beat engine, keyboard controls and layer
 catalog (#41)

The keyboard becomes the primary driver. One pair of keys means the same
thing all four days, and every state is one keypress from anywhere.

The beat engine lives in state.js because the beat index is app state.
`setBeat` resets every derived field before applying the beat, so no beat
can depend on having passed through its predecessor -- which is what makes
a beat render identically whether it was stepped into, stepped back to, or
jumped at cold, and what forces the prefetch rule the spec keeps arriving
at: a spine is installed complete or not at all. Ends never wrap; an
out-of-range digit is a silent no-op rather than a clamp.

Views are jumpable in any order and each remembers its own beat and layer
set, so Flow & Cut stays parked on augmentation 3 while the instructor
detours to answer a question. `R` is a full view reset -- beat 0, default
layers, threat cleared -- leaving view and dataset untouched.

The layer catalog is one global set with per-view entry states, never
view-owned: the unit's strongest moments are cross-day mashups. The old
single lane label splits into `caps` and `costrisk`, because Flow & Cut
wants a capacity beside its flow and Cost & Risk wants cost and risk
instead. All-layers-on is illegible in every scheme and is not a legal
preset.

The scaffold tier dims untouched lanes to 30% and owns opacity alone, made
safe by the rule that an empty hot set means every lane is hot -- so the
pristine network, whose subject is the graph itself, is never dimmed.
Labels only on hot lanes falls out of that rather than being a special
case.

The token block gains the back-row smear as ONE authored quantity with a
derivation per pattern. Two floors apply to every dashed mark and they are
orthogonal: pitch (is it still broken?) is exactly independent of stroke
weight, and presence (is it there?) is `weight x duty x opacity`. The
failure mode is the whole argument for machine-checking them -- a dash
that loses does not vanish, it becomes a dimmer solid line. The residual
arc goes to stroke 4 / `22 18` and the min cut to `16 24`; the synthetic
machinery and the removed lane stay under the presence floor deliberately,
on a recorded and closed exemption list.

tests/test_web_assets.py re-derives the 3.16 dashed-stroke floor from the
smear rather than restating it, so retuning the room moves the floor
instead of leaving a constant nobody can re-justify.

Closes #41
---
 src/clopt/web/graph.js   |  37 ++--
 src/clopt/web/index.html |  76 +++++--
 src/clopt/web/render.js  |  75 +++++--
 src/clopt/web/state.js   | 253 ++++++++++++++++++++++-
 src/clopt/web/style.css  | 246 +++++++++++++++++++++--
 src/clopt/web/views.js   |  96 ++++++---
 tests/test_web_assets.py | 419 +++++++++++++++++++++++++++++++++++++++
 7 files changed, 1106 insertions(+), 96 deletions(-)

diff --git a/src/clopt/web/graph.js b/src/clopt/web/graph.js
index 8b12c21..776c846 100644
--- a/src/clopt/web/graph.js
+++ b/src/clopt/web/graph.js
@@ -602,19 +602,32 @@ export function buildGraph(svg, payload) {
 
   for (const edge of network.edges) {
     const bundle = handles.edges.get(edge.id);
-    /* Two texts share one anchor and one plate: the lane's static statistics
-     * (capacity, cost, risk) and the flow the solver put on it. They are
-     * separate elements rather than one because the layers that show them are
-     * switched independently. `flow` gets its content in a later ticket; the
-     * element exists from here so that nothing structural changes when it
-     * does. */
-    const plate = element("rect", { class: "anchor-plate" });
-    const stats = element("text", { class: "lane-label" });
+    /* Three texts on two rows, sharing one frozen anchor.
+     *
+     * The flow numeral takes the upper row and the lane's statistics the lower
+     * one. `caps` and `costrisk` are two elements on the SAME row rather than
+     * one text carrying all three numbers, because the catalog switches them
+     * independently: Flow & Cut wants a capacity beside its flow and Cost &
+     * Risk wants cost and risk instead, and a combined label put two unasked-for
+     * numbers on screen in both. They are never both on by default -- and if
+     * both are switched on by hand they overlap, which is one of the reasons
+     * all-layers-on is not a legal preset.
+     *
+     * Each row carries its own plate, so a row that is switched off leaves no
+     * unbacked rectangle behind. The whole lot lives in one group per lane so
+     * that the scaffold tier can dim a lane and its numerals together, from one
+     * class write. */
+    const group = element("g", { class: "lane-marks", "data-edge": edge.id });
+    const plateFlow = element("rect", { class: "anchor-plate plate-flow" });
     const flow = element("text", { class: "anchor-label" });
-    marks.appendChild(plate);
-    marks.appendChild(stats);
-    marks.appendChild(flow);
-    bundle.canvasLabel = { plate, stats, flow };
+    const plateStat = element("rect", { class: "anchor-plate plate-stat" });
+    const caps = element("text", { class: "lane-label lane-caps" });
+    const costrisk = element("text", { class: "lane-label lane-costrisk" });
+    for (const part of [plateFlow, flow, plateStat, caps, costrisk]) {
+      group.appendChild(part);
+    }
+    marks.appendChild(group);
+    bundle.canvasLabel = { group, plateFlow, flow, plateStat, caps, costrisk };
   }
 
   return handles;
diff --git a/src/clopt/web/index.html b/src/clopt/web/index.html
index bc65f44..9186ab0 100644
--- a/src/clopt/web/index.html
+++ b/src/clopt/web/index.html
@@ -110,17 +110,21 @@ <h2>Lanes</h2>
   -->
   <script type="module">
     import { fetchDatasets, fetchScenario } from "./api.js";
-    import { state, setScenario, setDataset, setView, toggleLayer,
-             pinLane, clearPin } from "./state.js";
+    import { state, setScenario, setDataset, setView, toggleLayer, pinLane,
+             stepBeat, stepUnit, jumpToUnit, resetView,
+             resolveBeat } from "./state.js";
     import { buildGraph } from "./graph.js";
     import { render } from "./render.js";
-    import { VIEWS, LAYERS, applyLayerClasses } from "./views.js";
+    import { VIEWS, LAYERS, applyLayerClasses, viewForKey } from "./views.js";
 
     const svg = document.getElementById("theater");
 
     function repaint() {
       applyLayerClasses(document.documentElement, state.layers);
       render(state);
+      // The controls follow the state rather than driving it, so a beat that
+      // overrides a layer lights the same button a click on it would have.
+      syncControls();
     }
 
     function buildControls() {
@@ -132,7 +136,6 @@ <h2>Lanes</h2>
         button.dataset.view = view.id;
         button.addEventListener("click", () => {
           setView(view.id);
-          syncControls();
           repaint();
         });
         views.appendChild(button);
@@ -146,7 +149,6 @@ <h2>Lanes</h2>
         button.dataset.layer = layer.id;
         button.addEventListener("click", () => {
           toggleLayer(layer.id);
-          syncControls();
           repaint();
         });
         layers.appendChild(button);
@@ -166,16 +168,61 @@ <h2>Lanes</h2>
       });
     }
 
-    /* The pin lasts until the next beat or `R`. The beat engine and the rest of
-     * the keyboard driver arrive with their own ticket; `R` is here because the
-     * rule the click lives under is that a pointer may never reach a state the
-     * keyboard cannot -- so the key that undoes it has to ship alongside it,
-     * not after it. */
+    /* The keyboard, which is the primary driver -- on-screen controls are
+     * pointer parity and never the other way round.
+     *
+     * ONE TABLE, and it is one table so that the pointer-only rule for layers
+     * is checkable rather than merely agreed: `tests/test_web_assets.py` reads
+     * this block and fails if a layer id or `toggleLayer` appears in it. The
+     * keys stay reserved for the controls used mid-narration.
+     *
+     * `event.code` rather than `event.key` throughout. The view jumps were
+     * chosen for being bottom-row, one-handed and modifier-free, which is a
+     * fact about where the key IS -- a layout that prints something else on the
+     * cap should still drive the tool.
+     *
+     * `PageDown` steps FORWARD and `PageUp` back, which is the way round a
+     * presenter remote sends them -- the alias exists so a remote drives the
+     * tool with no configuration, so the remote decides the direction, not the
+     * order the two keys are written down in.
+     *
+     * `ArrowDown` walks to the next coarse unit and `ArrowUp` to the previous
+     * one, matching every other transport control: down the list is forward. */
+    const KEY_ACTIONS = {
+      ArrowRight: () => stepBeat(1),
+      ArrowLeft:  () => stepBeat(-1),
+      PageDown:   () => stepBeat(1),
+      PageUp:     () => stepBeat(-1),
+      ArrowDown:  () => stepUnit(1),
+      ArrowUp:    () => stepUnit(-1),
+      KeyR:       () => resetView(),
+    };
+
+    const DIGIT = /^Digit([1-9])$/;
+
     function bindKeys() {
       window.addEventListener("keydown", (event) => {
-        if (event.key !== "r" && event.key !== "R") return;
+        // Modified keystrokes belong to the browser. Taking Ctrl-R would cost
+        // the instructor the reload that recovers from anything this page gets
+        // wrong, in exchange for a key `R` already provides.
+        if (event.ctrlKey || event.metaKey || event.altKey) return;
         if (event.target.matches("input, select, textarea")) return;
-        clearPin();
+
+        const digit = DIGIT.exec(event.code);
+        const view = viewForKey(event.code);
+        const action = KEY_ACTIONS[event.code];
+        // Digits jump straight to a coarse unit, 1-based as the instructor says
+        // it out loud. A digit above the view's unit count is a silent no-op --
+        // the mutators decline it rather than clamping, because a clamp moves
+        // the picture somewhere nobody asked for, mid-sentence.
+        if (digit) jumpToUnit(Number(digit[1]));
+        else if (view) setView(view);
+        else if (action) action();
+        else return;
+
+        // Only after the key is one of ours: the arrows and the page keys
+        // otherwise scroll the panel out from under the instructor.
+        event.preventDefault();
         repaint();
       });
     }
@@ -201,7 +248,10 @@ <h2>Lanes</h2>
       buildGraph(svg, payload);
       document.getElementById("scenario-name").textContent = payload.name;
       document.getElementById("scenario-description").textContent = payload.description;
-      syncControls();
+      // The beat is re-resolved against the new dataset rather than reset: the
+      // marks were cleared with the old theater's edge ids, and the current
+      // beat is the only thing that knows what should be marked instead.
+      resolveBeat();
       repaint();
     }
 
diff --git a/src/clopt/web/render.js b/src/clopt/web/render.js
index 7d95551..956e9f2 100644
--- a/src/clopt/web/render.js
+++ b/src/clopt/web/render.js
@@ -51,6 +51,13 @@ const PLATE_HEIGHT = 24;
 const CENTRE_BASELINE = 6;     /* drop a centred line to optical middle */
 const LABEL_GAP = 12;          /* air between a node's disc and its id */
 
+/* The anchor's two rows, straddling the frozen point rather than starting at
+ * it: the flow numeral sits half a row above and the lane's statistics half a
+ * row below, so the PAIR is centred on the point the anchor solve certified
+ * clear. Hanging both rows downward would put the lower one somewhere the
+ * solve never checked. */
+const ROW_OFFSET = 13;
+
 /**
  * Shorten a segment so it starts and ends clear of the discs it joins.
  *
@@ -76,6 +83,29 @@ function place(line, segment) {
   line.setAttribute("y2", segment.y2);
 }
 
+/**
+ * Place one row of an anchor's stacked text, and the plate behind it.
+ *
+ * `text` is what the plate is sized against, which is not always the row's own
+ * content -- two texts sharing a row share a plate, and it has to fit the wider
+ * of them whichever is switched on. Pass `null` for the plate on the second
+ * text of a shared row.
+ */
+function row(node, plate, anchor, offset, text) {
+  node.setAttribute("x", anchor.x);
+  node.setAttribute("y", anchor.y + offset);
+  if (!plate) return;
+  /* The plate is sized from the text it backs, which is geometry; its fill and
+   * opacity are the stylesheet's business. Deliberately NOT measured with
+   * `getBBox()`: the plate is `display: none` until its layer is switched on,
+   * and a hidden element measures as zero. */
+  const width = Math.max(text.length, PLATE_MIN_CHARS) * CHAR_ADVANCE;
+  plate.setAttribute("x", anchor.x - width / 2);
+  plate.setAttribute("y", anchor.y + offset - PLATE_HALF_HEIGHT);
+  plate.setAttribute("width", width);
+  plate.setAttribute("height", PLATE_HEIGHT);
+}
+
 /** Write one headline slot, showing the em dash rather than a gap when the
  *  active view does not own that number. */
 function slot(id, value) {
@@ -186,8 +216,16 @@ export function render(state) {
     }
     /* The canvas lane carries the emphasis states too, so a pinned row and its
      * lane light up together -- the click has to be visible in the room, not
-     * only on the instructor's display. */
+     * only on the instructor's display.
+     *
+     * `cold` is the scaffold tier, written onto the lane and its numerals from
+     * this one call so the two can never end up on opposite sides of it. Note
+     * that hot and cold are not complements: with an empty hot set neither
+     * class is written anywhere, which is the pristine screen -- the graph is
+     * never dimmed when the graph is itself the subject. */
     bundle.group.classList.toggle("hot", states.hot);
+    bundle.group.classList.toggle("cold", states.cold);
+    bundle.canvasLabel.group.classList.toggle("cold", states.cold);
 
     const removed = states.removed;
     bundle.group.classList.toggle("removed", removed);
@@ -227,25 +265,30 @@ export function render(state) {
     bundle.ledgerCells.cap.textContent = String(cap);
     bundle.ledgerCells.risk.textContent = risk.toFixed(2);
 
-    /* -- the anchor's text ------------------------------------------------- */
-    const { plate, stats, flow } = bundle.canvasLabel;
+    /* -- the anchor's two rows --------------------------------------------- */
+    const label = bundle.canvasLabel;
 
-    stats.setAttribute("x", anchor.x);
-    stats.setAttribute("y", anchor.y);
     /* Capacity, cost and risk, from the payload or from the server's `changes`
-     * block -- never arithmetic performed here. */
-    stats.textContent = `${cap}/${bundle.edge.cost}/${risk.toFixed(2)}`;
+     * block -- never arithmetic performed here. Two texts on the lower row,
+     * one per layer, so the catalog can show a capacity beside a flow without
+     * also putting cost and risk on the board. Both are written every pass
+     * whichever is visible: a text that is only updated while its layer is on
+     * is a text that shows a stale number the moment the layer comes back. */
+    label.caps.textContent = String(cap);
+    label.costrisk.textContent = `${bundle.edge.cost}/${risk.toFixed(2)}`;
 
-    flow.setAttribute("x", anchor.x);
-    flow.setAttribute("y", anchor.y);
+    /* The lower row's plate is sized to whichever of its two texts is longer,
+     * rather than to the one currently showing. Sizing it to the visible one
+     * would make the plate's width depend on the layer set -- a geometry write
+     * driven by appearance state, and a plate that changes size when a layer is
+     * toggled on a beat that changed nothing else. */
+    const statText = label.caps.textContent.length >= label.costrisk.textContent.length
+      ? label.caps.textContent
+      : label.costrisk.textContent;
 
-    /* The plate is sized from the text it backs, which is geometry; its fill
-     * and opacity are the stylesheet's business. */
-    const width = Math.max(stats.textContent.length, PLATE_MIN_CHARS) * CHAR_ADVANCE;
-    plate.setAttribute("x", anchor.x - width / 2);
-    plate.setAttribute("y", anchor.y - PLATE_HALF_HEIGHT);
-    plate.setAttribute("width", width);
-    plate.setAttribute("height", PLATE_HEIGHT);
+    row(label.flow, label.plateFlow, anchor, -ROW_OFFSET, label.flow.textContent);
+    row(label.caps, label.plateStat, anchor, ROW_OFFSET, statText);
+    row(label.costrisk, null, anchor, ROW_OFFSET, statText);
   }
 
   renderHeadline(state, certificates);
diff --git a/src/clopt/web/state.js b/src/clopt/web/state.js
index b753646..af45558 100644
--- a/src/clopt/web/state.js
+++ b/src/clopt/web/state.js
@@ -14,7 +14,7 @@
  * nothing raised anywhere.
  */
 
-import { layersForView } from "./views.js";
+import { layersForView, VIEWS } from "./views.js";
 
 export const state = {
   /** Dataset id currently drawn; `null` until the first load. */
@@ -22,12 +22,37 @@ export const state = {
   /** The `/scenario` payload, verbatim. */
   scenario: null,
   /** Active view id. */
-  view: "theater",
-  /** Active layer ids. */
-  layers: new Set(),
+  view: VIEWS[0].id,
+  /* Active layer ids, opening on the first view's entry set rather than empty.
+   * A blank set here is not a neutral starting point -- it is the one layer
+   * state the catalog forbids read from the other end, and the page would open
+   * on a diagram with nothing drawn over it and no beat responsible for that. */
+  layers: layersForView(VIEWS[0].id),
   /** Active threat picture name, or `null` for the pristine network. */
   threat: null,
 
+  /**
+   * Index into the active view's spine. See the beat engine below.
+   *
+   * The ONE number the keyboard moves, and the one every other field on this
+   * object is derived from. It is an index rather than a cursor for a reason:
+   * `setBeat` rebuilds everything below from scratch, so a beat renders
+   * identically whether it was reached by stepping forward, stepping back, or
+   * jumping to it cold.
+   */
+  beat: 0,
+
+  /**
+   * Per-view memory, `{viewId: {beat, layers}}`.
+   *
+   * Views are jumpable in any order and **each remembers its own state**: Flow
+   * & Cut stays parked on augmentation 3 while the instructor detours into
+   * another view to answer a question and comes back. Rebuilding Edmonds-Karp
+   * state live mid-sentence is the most expensive recovery in the unit, and it
+   * is also the most likely one.
+   */
+  views: {},
+
   /* ---- the lane subsets the panel and the canvas both read ----------------
    * Three of the panel's apparent content shapes were never components. The
    * cut's certifying lane list and the interdicted subset are *subsets of the
@@ -87,10 +112,194 @@ export function setDataset(datasetId) {
   for (const set of Object.values(state.marks)) set.clear();
 }
 
-/** Switch view, adopting that view's default layer set. */
+/* ---- the beat engine ------------------------------------------------------
+ *
+ * Every view has an ordered spine of beats, and in all three the beats come in
+ * `[proposal, consequence]` pairs -- so `->` always means *"and here's what
+ * that does"* and the room learns the rhythm. A beat is a plain record:
+ *
+ *   {unit, phase, label, apply}
+ *
+ * `unit` is the coarse step the instructor names out loud -- augmentation 3,
+ * budget level 2, Pareto detent 4 -- and `phase` is `"a"` or `"b"` within it.
+ * `apply` is optional and receives this state object; it is where a view's
+ * ticket puts the marks, the headline numbers and any layer overrides that
+ * beat carries.
+ *
+ * **`setBeat` is pure, synchronous and idempotent, and that is structural
+ * rather than a promise.** It resets every derived field before applying the
+ * beat, so no beat can depend on having passed through its predecessor. Which
+ * is what forces the prefetch rule the whole spec keeps arriving at:
+ * ANYTHING A KEYPRESS CAN REACH IS FETCHED BEFORE THE FIRST KEYPRESS, and a
+ * spine is installed complete or not at all. A beat that had to fetch could not
+ * be synchronous, and a beat that is not synchronous cannot be stepped
+ * backwards through at speaking pace.
+ *
+ * Ends never wrap. Leaning on a key must not silently restart the story.
+ */
+
+/** Installed spines, `{viewId: [beat, ...]}`. Filled by #42-#44. */
+const SPINES = new Map();
+
+/**
+ * The spine a view falls back to before its ticket installs one.
+ *
+ * One beat, which is the view's entry state -- so the keyboard is live and
+ * every key is a legal no-op from the first paint, rather than a set of keys
+ * that throw until three more tickets land.
+ */
+const ENTRY_SPINE = [{ unit: 0, phase: "a", label: "Entry" }];
+
+/** The active view's spine, or another view's if asked for one by id. */
+export function spine(viewId = state.view) {
+  return SPINES.get(viewId) || ENTRY_SPINE;
+}
+
+/**
+ * Install a view's whole spine, prefetched and complete.
+ *
+ * Clamps rather than resets the beat index, so re-installing a spine -- which
+ * is what a dataset switch does -- lands the instructor on the same step of the
+ * other network wherever that step still exists.
+ */
+export function setSpine(viewId, beats) {
+  SPINES.set(viewId, beats.length ? beats : ENTRY_SPINE);
+  if (viewId === state.view) setBeat(Math.min(state.beat, spine().length - 1));
+}
+
+/** How many coarse units the active view's spine has. */
+export function unitCount(viewId = state.view) {
+  return new Set(spine(viewId).map((beat) => beat.unit)).size;
+}
+
+/** The index of the first beat -- beat *a* -- of a coarse unit. */
+function firstBeatOfUnit(unit) {
+  return spine().findIndex((beat) => beat.unit === unit);
+}
+
+/**
+ * Rebuild every derived field from the current beat.
+ *
+ * The whole of what makes a beat idempotent: the reset comes first, so what a
+ * beat did NOT set is cleared rather than inherited from whatever was on screen
+ * a keypress ago. The pin goes with it -- a click pins a lane hot until the next
+ * beat or `R`, and "the next beat" is a promise only this function can keep.
+ *
+ * Layers are reset to the view's defaults here too, because a view's layer
+ * table is its *entry* state and beats drive it from there. The cost, stated:
+ * a layer the instructor toggled by hand does not survive the next keypress.
+ * That is the same rule read from the other end -- a beat renders identically
+ * however it was reached, including "reached after fiddling with the layers".
+ *
+ * `seed` is the one exception, and it exists for exactly one caller: returning
+ * to a view restores the layer set it was left holding, and the beat's own
+ * overrides are then re-applied on top of that rather than in place of it.
+ */
+export function resolveBeat(seed) {
+  clearPin();
+  for (const set of Object.values(state.marks)) set.clear();
+  state.throughput = null;
+  state.cut = null;
+  state.delta = null;
+  state.layers = seed ? new Set(seed) : layersForView(state.view);
+
+  const beat = spine()[state.beat];
+  if (beat && beat.apply) beat.apply(state);
+}
+
+/**
+ * Jump to a beat by index. Returns whether it happened.
+ *
+ * Out of range is a silent no-op rather than a clamp or a wrap: leaning on `->`
+ * at the end of the ladder must not restart the story, and a mistyped digit
+ * must not move the picture at all.
+ */
+export function setBeat(index) {
+  if (index < 0 || index >= spine().length) return false;
+  state.beat = index;
+  resolveBeat();
+  return true;
+}
+
+/** One beat forward (`+1`) or back (`-1`). */
+export function stepBeat(delta) {
+  return setBeat(state.beat + delta);
+}
+
+/**
+ * One coarse unit forward (`+1`) or back (`-1`), landing on that unit's beat
+ * *a*.
+ *
+ * Backward stepping exists at BOTH granularities rather than choosing between
+ * them, because the interrupted instructor wants "iteration 3", not three
+ * counted presses. Going back from mid-unit lands on the start of the unit
+ * being interrupted, not the previous one -- the same as every other transport
+ * control the instructor has ever used, and the reading that answers "start
+ * this one again" without a wasted press.
+ */
+export function stepUnit(delta) {
+  const beats = spine();
+  const current = beats[state.beat];
+  if (!current) return false;
+  if (delta < 0 && state.beat !== firstBeatOfUnit(current.unit)) {
+    return setBeat(firstBeatOfUnit(current.unit));
+  }
+  const target = firstBeatOfUnit(current.unit + delta);
+  return target === -1 ? false : setBeat(target);
+}
+
+/**
+ * Jump to a coarse unit by its 1-based number, as the digit keys name it.
+ *
+ * Digits above the view's unit count do nothing rather than wrapping or
+ * clamping. A mistyped key is a no-op; a clamp would move the picture to
+ * somewhere nobody asked for while the instructor is mid-sentence.
+ */
+export function jumpToUnit(number) {
+  const target = firstBeatOfUnit(number - 1);
+  return target === -1 ? false : setBeat(target);
+}
+
+/**
+ * `R`: a FULL reset of the current view -- beat 0, default layers, threat
+ * cleared -- leaving the view and the dataset untouched.
+ *
+ * Full rather than partial on purpose: a half-reset that leaves four layers
+ * burning is not a baseline, and the one key the instructor reaches for when
+ * the picture has got away from them has to land somewhere known. Accepted
+ * cost, stated where it bites: the cross-day layer mashup is both pointer-only
+ * *and* destroyed by `R`.
+ */
+export function resetView() {
+  state.threat = null;
+  state.beat = 0;
+  resolveBeat();
+}
+
+/**
+ * Switch view, restoring everything that view was last left holding.
+ *
+ * The beat index and the layer set are both remembered, which is the point:
+ * Flow & Cut stays parked on augmentation 3 while the instructor detours to
+ * answer a question. A view seen for the first time enters at beat 0 with its
+ * default layers.
+ */
 export function setView(viewId) {
+  /* Pressing a view's own key is a no-op, not a re-entry. It has to be: the
+   * stash below would otherwise write the current view's state and read it
+   * straight back, which is harmless in the middle of a class and is exactly
+   * how booting into the first view once left every layer switched off. */
+  if (viewId === state.view) return;
+  state.views[state.view] = { beat: state.beat, layers: new Set(state.layers) };
   state.view = viewId;
-  state.layers = layersForView(viewId);
+  const remembered = state.views[viewId];
+  state.beat = remembered ? Math.min(remembered.beat, spine(viewId).length - 1) : 0;
+  /* The marks and the headline numbers are rebuilt from the beat rather than
+   * remembered alongside it -- they are derived, and storing derived state is
+   * how a remembered view comes back showing last week's numbers. Layers are
+   * the exception because a hand toggle is not derivable from anything, so
+   * they are seeded back in and the beat's overrides re-applied over them. */
+  resolveBeat(remembered && remembered.layers);
 }
 
 export function toggleLayer(layerId) {
@@ -171,6 +380,24 @@ export function isRemoved(changes, edgeId) {
  */
 export const ROW_STATES = ["removed", "in-cut", "violating", "on-path", "hot"];
 
+/**
+ * Whether ANYTHING is hot right now -- the single question the scaffold tier
+ * turns on.
+ *
+ * **An empty hot set means every lane is hot**, which is what makes dimming
+ * safe: the pristine network, the one picture whose subject is the graph
+ * itself, is never dimmed. Read the rule as "there is nothing more specific to
+ * look at, so look at all of it" rather than as a special case bolted on to
+ * avoid an ugly screen.
+ *
+ * Exported so the canvas and the ledger cannot answer it differently. It is a
+ * question about the whole state, not about a lane, which is why it does not
+ * live inside `laneStates` below.
+ */
+export function anyHot(current = state) {
+  return current.marks.hot.size > 0 || current.pinned !== null;
+}
+
 /**
  * Every state one lane is in right now, as flags -- the one projection of the
  * lane subsets onto a single lane.
@@ -184,13 +411,25 @@ export const ROW_STATES = ["removed", "in-cut", "violating", "on-path", "hot"];
  *
  * `hot` is the emphasis channel rather than a fifth role: the beat's own hot
  * set, plus whatever the instructor pinned by clicking.
+ *
+ * `cold` is the sixth flag and deliberately NOT one of `ROW_STATES`: it is the
+ * scaffold tier's question, answered per lane for the canvas, and it has no
+ * ledger tick. Marking every cold row would ink eight of twelve rows on a
+ * typical beat to say "not this one", where the hot tick already says which one
+ * -- the same information, twice, in the noisier direction.
+ *
+ * Note that `hot` and `cold` are not complements. When nothing is hot, nothing
+ * is cold either: no lane is emphasised and no lane is dimmed, which is the
+ * pristine screen.
  */
 export function laneStates(current, changes, edgeId) {
+  const emphasised = current.marks.hot.has(edgeId) || current.pinned === edgeId;
   return {
     "removed": isRemoved(changes, edgeId),
     "in-cut": current.marks.inCut.has(edgeId),
     "violating": current.marks.violating.has(edgeId),
     "on-path": current.marks.onPath.has(edgeId),
-    "hot": current.marks.hot.has(edgeId) || current.pinned === edgeId,
+    "hot": emphasised,
+    "cold": anyHot(current) && !emphasised,
   };
 }
diff --git a/src/clopt/web/style.css b/src/clopt/web/style.css
index 33cf39f..ab26d2d 100644
--- a/src/clopt/web/style.css
+++ b/src/clopt/web/style.css
@@ -21,6 +21,52 @@
  */
 
 :root {
+  /* ---- the stroke model: ONE authored quantity, then derivations --------
+   * The room model: a 2.5 m image on a 1060-unit viewBox at 8 m, so **one
+   * viewBox unit is one arcminute** and stroke widths read as angles with no
+   * conversion.
+   *
+   * `--smear` is the back-row acuity blur, and it is the only number here that
+   * was chosen rather than derived. It is a SAFETY MARGIN, not a measurement --
+   * it corresponds to roughly a 20/204 observer, about ten times a 20/20 eye.
+   * If the real room differs from the model, change this and re-derive; do not
+   * edit the individual patterns, which is how a derived set becomes a set of
+   * magic numbers.
+   *
+   * Two floors apply to every dashed mark, and they are orthogonal:
+   *
+   *   pitch     does it still read as BROKEN? A dashed stroke is a union of
+   *             rectangles and a Gaussian is separable, so the across-stroke
+   *             term cancels out of the modulation ratio identically --
+   *             pitch is *exactly* independent of stroke weight. The floor is
+   *             a closed form in the smear and the duty cycle, with no
+   *             solution above duty ~0.65, which is itself the rule: author at
+   *             duty <= 0.6, because above it survival rests on harmonics and
+   *             harmonics are the first thing a blur removes.
+   *
+   *   presence  is the mark THERE? Effective width is `weight x duty x
+   *             opacity` and must clear 1 MAR (1.97 units) at the 20/40 design
+   *             observer, confirmed with the instructor. The angular floor and
+   *             the ink floor collapse together once a smeared dash is
+   *             recognised as a solid line of its own mean luminance.
+   *
+   * Together with a >=3-cycle requirement on the shortest lane that may carry
+   * a mark (120 units, so pitch <= 40) they give a minimum stroke weight for
+   * any dashed mark of **3.16 units**. `tests/test_web_assets.py` re-derives
+   * all of it from `--smear` rather than restating the numbers.
+   *
+   * The failure mode is the whole argument for checking it from a test: a dash
+   * that loses does not vanish, it becomes a dimmer solid line -- still there,
+   * still the right colour, and saying the wrong thing. */
+  --smear:              6.88;
+
+  /* The scaffold tier, and the ONLY dimming channel on the page. Lanes the
+   * active annotation does not touch drop to this; nothing else may use
+   * opacity as a channel, or two mechanisms compose into a lane at 9% nobody
+   * authored. Safe only because an empty hot set means EVERY lane is hot, so
+   * the graph is never dimmed when it is itself the subject. */
+  --scaffold-op:        .30;
+
   /* ---- ground ---------------------------------------------------------- */
   --bg:                 #07090d;
 
@@ -40,23 +86,76 @@
 
   /* The super-source and super-sink machinery. Dotted rather than dashed --
    * a different register, so derived scaffolding never reads as a real lane
-   * the instructor authored. */
+   * the instructor authored.
+   *
+   * Declared FRONT-OF-ROOM and never load-bearing for the back row. The dash
+   * register is only two-valued at that distance, because duty cycle *is* mean
+   * luminance once a pattern smears: a third value would have to be bought
+   * with stroke weight, taking the machinery to ~7.5 and running weight
+   * opposite to importance. So the machinery is allowed to fade instead, and
+   * `--synth` sits on the presence floor's recorded exemption list.
+   *
+   * derivation: duty 6/28 = 0.21, pitch floor 27.1 at smear 6.88 -> 28 clears;
+   *             presence 3 x 0.21 = 0.64, under 1.97 by design. */
   --synth:              #8d99a8;
   --synth-w:            3;
-  --synth-dash:         2 9;
+  --synth-dash:         6 22;
   --synth-fill:         #22303f;
   --synth-stroke:       #8d99a8;
   --synth-ink:          #ffffff;
 
   /* Removal is a style, not a deletion: a cut lane stays on screen, struck
    * out. Grey rather than red, so it reads as ABSENT rather than as alarming,
-   * and the X is what actually says "gone". */
+   * and the X is what actually says "gone".
+   *
+   * The second mark on the presence floor's exemption list, and for the same
+   * kind of reason: its meaning rides on the glyph, not on the stroke, so a
+   * mark intended to recede failing a presence floor is the criterion agreeing
+   * with the design rather than catching a defect.
+   *
+   * derivation: duty 6/28 = 0.21, pitch floor 27.1 -> 28 clears;
+   *             presence 3 x 0.21 x 0.55 = 0.35, under 1.97 by design. */
   --removed:            #999999;
   --removed-w:          3;
-  --removed-dash:       3 7;
+  --removed-dash:       6 22;
   --removed-op:         .55;
   --removed-glyph-w:    3;
 
+  /* ---- the annotation marks' strokes ------------------------------------
+   * Weight is a channel, and the order is load-bearing: lane 4.5 / residual 4
+   * / min cut 7 / path 11. The residual arc sits just under the lane on
+   * purpose -- taking it to 5 would invert the hierarchy and reproduce the
+   * exact pathology that made the dash register two-valued.
+   *
+   * The residual arc is the thinnest mark this board can carry. It was
+   * authored at 3 for a long time, just under the 3.16 floor, which is why the
+   * pitch work and the presence work landed on the same stroke from opposite
+   * directions.
+   *
+   * These are declared here, ahead of the marks that use them (#42-#44). The
+   * catalog is what the unit teaches from, and a value that appears the day
+   * its mark does is a value nobody has retuned against the room. Unreferenced
+   * tokens warn rather than fail, exactly so this is possible. */
+  --residual:           #56b4e9;
+  --residual-w:         4;
+  /* derivation: duty 22/40 = 0.55, pitch floor 34.4 -> 40 clears at 1.16x;
+   *             presence 4 x 0.55 = 2.20, over 1.97 at 1.12x;
+   *             3.0 cycles on the shortest legal lane. */
+  --residual-dash:      22 18;
+
+  --cut:                #e69f00;
+  --cut-w:              7;
+  /* derivation: duty 16/40 = 0.40, pitch floor 29.5 -> 40 clears at 1.36x;
+   *             presence 7 x 0.40 = 2.80, over 1.97 at 1.42x;
+   *             3.0 cycles on the shortest legal lane. */
+  --cut-dash:           16 24;
+
+  /* Solid, so neither floor applies beyond presence -- which a stroke-11 mark
+   * clears by a factor of five. It is the heaviest mark on the board because
+   * it is the one the room is being asked to trace. */
+  --path:               #f0e442;
+  --path-w:             11;
+
   /* ---- annotation tier ------------------------------------------------- */
   /* The knockout casing at a lane crossing. Painted in the background colour
    * on the annotation tier only -- never lane over lane -- so the pristine
@@ -383,7 +482,8 @@ html, body {
   display: none;
 }
 
-.lane-group.removed .removed-glyph { display: inline; }
+/* Whether the X shows is the `removed` layer's business; see the catalog
+ * below. The glyph is display:none by default and nothing else reveals it. */
 
 .synth {
   stroke: var(--synth);
@@ -460,25 +560,131 @@ html, body {
   display: none;
 }
 
-/* Layer visibility is a root class, set by `views.js`. Every rule that turns a
- * mark on lives here, so a view is a set of class names rather than a set of
- * style writes. */
-.show-lanelabels .lane-label { display: inline; }
-.show-flow .anchor-label     { display: inline; }
+/* ---- the annotation marks, ahead of the elements that carry them ----------
+ * Appearance for the three marks whose strokes the stroke model has already
+ * settled. The view tickets emit the elements; nothing about how they look is
+ * left for them to invent, which is the whole point of the token block --
+ * otherwise the retune against the real projector has to chase three more
+ * files. Each is `display: none` here and revealed by its layer class.
+ *
+ * Redundant encoding is mandatory rather than nice, and these are where it is
+ * spent: the catalog needs about eleven simultaneous categorical roles and the
+ * standard colour-blind-safe palette has eight, so hues run out IN PRINCIPLE.
+ * Dash register goes first, then weight, then glyphs. */
+.residual-arc {
+  stroke: var(--residual);
+  stroke-width: var(--residual-w);
+  stroke-dasharray: var(--residual-dash);
+  fill: none;
+  display: none;
+}
+
+.cut-mark {
+  stroke: var(--cut);
+  stroke-width: var(--cut-w);
+  stroke-dasharray: var(--cut-dash);
+  fill: none;
+  display: none;
+}
 
-/* The plate and the casing follow the marks they back, not one named layer.
- * Either annotation layer puts text on the annotation tier over the lanes, and
- * text over a lane needs its plate under it and its crossings broken -- so
- * both appear whenever either does. Listing only `.show-flow` here is what put
- * unbacked numerals on the opening screen once already. */
-.show-lanelabels .anchor-plate,
-.show-flow .anchor-plate { display: inline; }
+/* Solid and the heaviest stroke on the board, because it is the mark the room
+ * is being asked to trace. Every on-lane treatment leaves none of the lane
+ * visible underneath it -- which is a decision, not an oversight: at the one
+ * beat whose subject is that lane's own commitment, the path IS the lane. */
+.path-mark {
+  stroke: var(--path);
+  stroke-width: var(--path-w);
+  stroke-linecap: round;
+  fill: none;
+  display: none;
+}
+
+.cut-shade, .route-mark, .naive-mark, .violation { display: none; }
 
-/* The casing is bought exactly when a route is being traced over the lanes,
+/* ---- the scaffold tier ----------------------------------------------------
+ * Lanes the active annotation does not touch dim to 30%, so the room's eye goes
+ * to the lanes the instructor is currently talking about. This tier OWNS
+ * opacity: nothing else on the page may use dimming as a channel, or two
+ * mechanisms compose into a lane at 9% that nobody authored.
+ *
+ * Safe only because of the rule in `state.js` that an empty hot set means EVERY
+ * lane is hot -- so the pristine network, the one picture whose subject is the
+ * graph itself, is never dimmed. `render.js` writes `cold` onto the lane and
+ * its marks together from one call, so a lane and its numerals can never end up
+ * on opposite sides of the tier. */
+.lane-group.cold,
+.lane-marks.cold { opacity: var(--scaffold-op); }
+
+/* Cap/cost/risk labels appear only on hot lanes. This is not a special case --
+ * it falls out of the scaffold rule: a cold lane is not the subject, and its
+ * numerals are the densest thing on the canvas. The flow numeral is deliberately
+ * NOT suppressed here; it dims with its lane, because "this lane carries 0" is
+ * part of reading a flow even where the flow is not the subject. */
+.lane-marks.cold .lane-label { display: none; }
+
+/* ---- the layer catalog ----------------------------------------------------
+ * ONE GLOBAL CATALOG. A view is a named default toggle-state, not an owner --
+ * view-scoped layers were rejected because the unit's strongest moments are
+ * cross-day mashups, and showing Day 3's cut on top of Day 4's interdicted
+ * network is Day 4's entire punchline. Layer visibility is a root class set by
+ * `views.js`, so a view is a set of class names rather than a set of style
+ * writes, and beats override layer state by changing the same set.
+ *
+ * Every layer has a rule here from the day the catalog lands, including the
+ * ones whose marks arrive with #42-#44 -- the same reason `views.js` lists them
+ * ahead of their marks. A layer that appears the day its marks do is a toggle
+ * nobody has pressed before the class it matters in.
+ *
+ * ALL-LAYERS-ON IS NOT A LEGAL PRESET: it is illegible in every colour scheme,
+ * so no view may declare the whole catalog, and there is no control that
+ * switches everything on. `tests/test_web_assets.py` asserts it. */
+
+/* base topology's derived machinery -- on in all three views, but still a
+ * toggle, because the S/T partition is worth being able to take away while
+ * talking about the authored network alone. */
+.synth, .terminal { display: none; }
+.show-synth .synth,
+.show-synth .terminal { display: inline; }
+
+/* the two halves of the old single lane label. Split because Flow & Cut wants
+ * capacities beside a flow and Cost & Risk wants cost and risk instead --
+ * one text carrying all three put two of them on screen unasked in both. They
+ * share the anchor's second row and are never both on by default. */
+.show-caps .lane-caps         { display: inline; }
+.show-costrisk .lane-costrisk { display: inline; }
+.show-flow .anchor-label      { display: inline; }
+
+/* The plate follows the text it backs rather than one named layer: text over a
+ * lane needs its plate under it whichever layer put it there. Listing only
+ * `.show-flow` here is what put unbacked numerals on the opening screen once
+ * already. */
+.show-flow .plate-flow { display: inline; }
+.show-caps .plate-stat,
+.show-costrisk .plate-stat { display: inline; }
+
+/* The casing is bought exactly when something is being drawn over the lanes,
  * and not before: on the pristine screen there is nothing above the lane tier,
  * so there is nothing to break and the crossings stay unmarked. */
-.show-lanelabels .casing,
-.show-flow .casing { display: inline; }
+.show-flow .casing,
+.show-caps .casing,
+.show-costrisk .casing { display: inline; }
+
+/* The blockade's X. The layer gates the ANNOTATION, not the lane's own stroke:
+ * a lane whose capacity the server has zeroed is drawn struck out whatever the
+ * catalog says, because the stroke is a fact about the network and must never
+ * claim a capacity the panel disagrees with. What the layer controls is whether
+ * the room's attention is drawn to it. */
+.show-removed .lane-group.removed .removed-glyph { display: inline; }
+
+/* Marks landing with the view tickets. Their strokes are already tokenised and
+ * derived above; these are the rules that will switch them on. */
+.show-residual .residual-arc { display: inline; }
+.show-path .path-mark        { display: inline; }
+.show-cut .cut-mark,
+.show-cut .cut-shade         { display: inline; }
+.show-route .route-mark      { display: inline; }
+.show-naive .naive-mark,
+.show-naive .violation       { display: inline; }
 
 /* Arrowheads are appearance, so they are attached here rather than written
  * onto each line from JavaScript. */
diff --git a/src/clopt/web/views.js b/src/clopt/web/views.js
index d220c44..1734e08 100644
--- a/src/clopt/web/views.js
+++ b/src/clopt/web/views.js
@@ -5,6 +5,16 @@
  * whole of it: no view owns a code path, so a view cannot drift from what the
  * same layers show when switched on by hand.
  *
+ * **One global catalog; a view is a named default toggle-state, not an owner.**
+ * View-scoping was rejected because the unit's strongest moments are cross-day
+ * mashups -- showing Day 3's cut on top of Day 4's interdicted network is Day
+ * 4's entire punchline, and a layer owned by a view cannot be borrowed by
+ * another one.
+ *
+ * **A view's layer table is its ENTRY state only, not an invariant.** Beats
+ * drive layer state from there, so a view can change what is shown as its story
+ * advances without any of that living in a view-shaped code path.
+ *
  * The layers whose marks land in later tickets are listed here from the start.
  * The catalog is what the unit teaches from, and a layer that appears the day
  * its marks do is a layer whose toggle nobody has ever pressed before the
@@ -13,52 +23,82 @@
 
 /** The layer catalog. `id` is the toggle; the root class is `show-<id>`. */
 export const LAYERS = [
-  { id: "lanelabels", label: "Lane labels", hint: "Capacity, cost and risk at each lane anchor" },
-  { id: "flow",       label: "Flow",        hint: "Flow on each lane (Days 1-3)" },
-  { id: "synth",      label: "S / T",       hint: "The derived super-source and super-sink" },
-  { id: "residual",   label: "Residual",    hint: "Residual and reverse arcs (Day 2)" },
-  { id: "path",       label: "Path",        hint: "Augmenting path and its bottleneck (Day 2)" },
-  { id: "cut",        label: "Min cut",     hint: "The cut, and the S/T partition it defines (Day 3)" },
-  { id: "removed",    label: "Interdicted", hint: "Lanes struck out by an interdiction (Day 4)" },
-  { id: "naive",      label: "Naive load",  hint: "Day 1's counterexample and its violations" },
+  /* Base topology is on in all three views. It is still a toggle rather than a
+   * permanent fixture, because taking the derived S/T machinery away while
+   * talking about the authored network alone is a thing the instructor asks
+   * for -- and a mark that can never be switched off is one nobody can check
+   * the graph against. */
+  { id: "synth",    label: "S / T",      hint: "The derived super-source and super-sink" },
+  /* Two layers where there was one text. Flow & Cut wants capacities beside a
+   * flow; Cost & Risk wants cost and risk instead. A single `cap/cost/risk`
+   * label put two unasked-for numbers on screen in both. */
+  { id: "caps",     label: "Capacity",   hint: "Capacity at each lane anchor (Days 2-4)" },
+  { id: "costrisk", label: "Cost / risk", hint: "Cost and risk at each lane anchor (Day 1)" },
+  { id: "flow",     label: "Flow",       hint: "Flow on each lane (all three views)" },
+  { id: "residual", label: "Residual",   hint: "Residual and reverse arcs (Day 2)" },
+  { id: "path",     label: "Path",       hint: "Augmenting path and its bottleneck (Day 2)" },
+  { id: "cut",      label: "Min cut",    hint: "The cut, and the S/T partition it defines (Day 3)" },
+  { id: "removed",  label: "Interdicted", hint: "Lanes struck out by an interdiction (Day 4)" },
+  { id: "route",    label: "Single path", hint: "The cheapest or safest single route (Day 1)" },
+  { id: "naive",    label: "Naive load", hint: "Day 1's counterexample and its violations" },
 ];
 
 const LAYER_IDS = LAYERS.map((layer) => layer.id);
 
 /**
- * The three views of the unit, each a default layer set.
+ * The three views of the unit, in DAY ORDER, which is also left-to-right on the
+ * keyboard: `Z` `X` `C`.
+ *
+ * The keys are declared here rather than in the page's key map so that day
+ * order has one home. Bottom-row, one-handed, no modifier -- function keys were
+ * rejected because the function row defaults to media keys on many laptops and
+ * needs a modifier, which is a live-class hazard on the most-pressed non-beat
+ * key.
  *
- * The pristine opening screen is the first entry's business: it switches on the
- * lanes' own labels and nothing else, so the theater opens as a bare node-link
- * diagram with zero marks over it.
+ * Each view's `layers` is its entry state. Note that no view lists the whole
+ * catalog and none may: `WORST CASE` -- every layer on at once -- is illegible
+ * in every colour scheme, so all-on is not a legal preset and there is no
+ * control that produces it. `tests/test_web_assets.py` asserts it rather than
+ * leaving it as a thing everyone agrees about.
  */
 export const VIEWS = [
   {
-    /* The pristine opening screen, and it carries ZERO marks: bare lanes, the
-     * nodes, and the derived machinery. Lane numerals have a permanent place
-     * to sit from the first paint -- the anchors are solved and the elements
-     * exist -- but the place is empty until the instructor asks for it. This
-     * is the screen the room sees while the problem is being stated, so
-     * anything drawn over a lane here is something nobody asked for yet. */
-    id: "theater",
-    label: "Theater",
-    hint: "The pristine network, as authored",
-    layers: ["synth"],
+    /* Day 1: routing is the wrong model, and the lambda/Pareto sequel. The
+     * naive plan and its violations are the subject, so the lane numerals here
+     * are cost and risk -- capacity is what the *next* view is about. */
+    id: "cost-risk",
+    key: "KeyZ",
+    label: "Cost & Risk",
+    hint: "Day 1: why serving each base from its cheapest hub fails",
+    layers: ["synth", "costrisk", "flow", "route", "naive"],
   },
   {
-    id: "throughput",
-    label: "Throughput",
-    hint: "Max flow, residuals and the min cut (Days 2-3)",
-    layers: ["flow", "synth", "residual", "path", "cut"],
+    /* Days 2-3, merged: the min cut is a certificate OF the flow just computed,
+     * and re-rendering it on a fresh screen severs the argument. */
+    id: "flow-cut",
+    key: "KeyX",
+    label: "Flow & Cut",
+    hint: "Days 2-3: Edmonds-Karp, and the cut that certifies it",
+    layers: ["synth", "caps", "flow", "residual", "path", "cut"],
   },
   {
+    /* Day 4 stands alone: it is the adversary's turn, a different actor. The
+     * cut is on from beat 0 so that a budgeted adversary rediscovering it reads
+     * as recognition rather than as a surprise reveal. */
     id: "interdiction",
+    key: "KeyC",
     label: "Interdiction",
-    hint: "What a budget of removals costs the theater (Day 4)",
-    layers: ["flow", "synth", "cut", "removed"],
+    hint: "Day 4: what a budget of removals costs the theater",
+    layers: ["synth", "caps", "flow", "cut", "removed"],
   },
 ];
 
+/** The view a key code selects, or `null`. */
+export function viewForKey(code) {
+  const view = VIEWS.find((candidate) => candidate.key === code);
+  return view ? view.id : null;
+}
+
 /** A view's default layer set, as a fresh `Set` the caller may mutate. */
 export function layersForView(viewId) {
   const view = VIEWS.find((candidate) => candidate.id === viewId);
diff --git a/tests/test_web_assets.py b/tests/test_web_assets.py
index c4a11b8..b9aa753 100644
--- a/tests/test_web_assets.py
+++ b/tests/test_web_assets.py
@@ -14,6 +14,7 @@
 classroom.
 """
 
+import math
 import os
 import re
 import warnings
@@ -446,3 +447,421 @@ def test_no_javascript_test_runner_is_introduced():
             f"Python or not at all -- a JS toolchain here is a second way to "
             f"install this repo on the teaching laptop."
         )
+
+
+# ---- the beat engine, keyboard and layer catalog (issue #41) -----------------
+# Three rules land here, and each is invisible while authoring on a laptop: the
+# stroke model (a dash that loses does not vanish, it becomes a dimmer solid
+# line), the keyboard contract (a key that silently does nothing looks broken),
+# and the illegal all-on preset.
+
+# The documented control surface. Restated here rather than parsed out of the
+# page, because this is the list the *spec* fixed -- a test that read the page's
+# own key map could not catch the page dropping a key from it.
+KEYS = [
+    "ArrowLeft", "ArrowRight",      # one beat
+    "PageDown", "PageUp",           # the same, for a presenter remote
+    "ArrowUp", "ArrowDown",         # one coarse unit, landing on beat a
+    "KeyZ", "KeyX", "KeyC",         # the three views, in day order
+    "KeyR",                         # full view reset
+]
+
+# The beat engine's mutators. `state.js` owns them because the beat index is app
+# state and that module owns app state; the keyboard driver in `index.html` may
+# only call them.
+BEAT_MUTATORS = ["setBeat", "stepBeat", "stepUnit", "jumpToUnit", "resetView",
+                 "setSpine"]
+
+
+def test_the_keyboard_reaches_every_documented_axis(assets):
+    """Every key in the spec's control table is bound.
+
+    `event.code` rather than `event.key` for the letters: `Z`/`X`/`C` were
+    chosen for being bottom-row, one-handed and modifier-free, which is a fact
+    about position rather than about the glyph printed on the cap.
+
+    Scanned across both modules that own the driver. `index.html` holds the
+    action table, but the three view keys are declared on the views themselves,
+    so that day order -- which is also left-to-right on the keyboard -- has one
+    home rather than two that can disagree about which key is Day 4.
+    """
+    page = COMMENT.sub(" ", assets["index.html"] + assets["views.js"])
+    for key in KEYS:
+        assert key in page, (
+            f"index.html binds no {key}. The keyboard is the primary driver, "
+            f"and a key the spec promises must not go missing mid-class."
+        )
+    # Digits 1-9 jump to a coarse unit. Bound as a range rather than nine
+    # literals, so the assertion is on the range check rather than on nine
+    # string matches a refactor would scatter.
+    assert "Digit" in page, (
+        "index.html binds no digit jump; `1`-`9` are the direct-jump axis"
+    )
+
+
+def test_the_beat_engine_lives_in_state_js(assets):
+    code = COMMENT.sub(" ", assets["state.js"])
+    for mutator in BEAT_MUTATORS:
+        assert f"export function {mutator}" in code, (
+            f"state.js exports no {mutator}. The beat index is app state, so "
+            f"every mutation of it belongs to the module that owns app state."
+        )
+
+
+def _catalog(views_js):
+    """Every layer id the catalog declares."""
+    return set(re.findall(r'\{\s*id:\s*"([a-z]+)"', views_js))
+
+
+def _view_layer_sets(views_js):
+    """Each view's declared default layer set, as `{viewId: [layerId, ...]}`."""
+    found = {}
+    for block in re.finditer(
+        r'id:\s*"([a-z-]+)",(?:.*?)layers:\s*\[(.*?)\]', views_js, re.DOTALL
+    ):
+        found[block.group(1)] = re.findall(r'"([a-z]+)"', block.group(2))
+    return found
+
+
+def test_layer_toggles_are_pointer_only(assets):
+    """No keystroke reaches a layer toggle.
+
+    The keyboard driver is a single `KEY_ACTIONS` table so that this is
+    checkable at all: the table's actions are beat, view and reset, and never a
+    layer. Layer ids are searched for by name, so adding a layer and quietly
+    binding it to a key fails here.
+    """
+    page = COMMENT.sub(" ", assets["index.html"])
+    match = re.search(r"const KEY_ACTIONS = \{(.*?)\n    \};", page, re.DOTALL)
+    assert match, (
+        "index.html has no `const KEY_ACTIONS = {...};` table. The keyboard's "
+        "whole action set must be one readable block, or the pointer-only rule "
+        "for layers cannot be checked."
+    )
+    table = match.group(1)
+    assert "toggleLayer" not in table, (
+        "a key reaches toggleLayer. Layer toggles are pointer-only: the keys "
+        "stay reserved for the controls used mid-narration."
+    )
+    for layer in sorted(_catalog(assets["views.js"])):
+        assert f'"{layer}"' not in table, (
+            f"KEY_ACTIONS names the layer `{layer}`; layer toggles are "
+            f"pointer-only"
+        )
+
+
+def test_all_layers_on_is_not_an_available_preset(assets):
+    """`WORST CASE` is illegible in every colour scheme, so it is not legal.
+
+    A view that happens to list every layer is exactly that preset arriving by
+    accident, which is why this is checked rather than merely agreed.
+    """
+    catalog = _catalog(assets["views.js"])
+    assert catalog, "views.js declares no layer catalog"
+    sets = _view_layer_sets(assets["views.js"])
+    assert sets, "views.js declares no view default layer sets"
+    for view, layers in sets.items():
+        assert set(layers) != catalog, (
+            f"view `{view}` switches on the whole catalog. All-layers-on is "
+            f"illegible in every scheme and is not a legal preset."
+        )
+
+
+def test_every_view_default_is_a_layer_the_catalog_declares(assets):
+    """The catalog is global and a view is a named subset of it, never an owner.
+
+    View-scoping was rejected because the unit's strongest moments are cross-day
+    mashups -- Day 3's cut on top of Day 4's interdicted network is Day 4's
+    entire punchline.
+    """
+    catalog = _catalog(assets["views.js"])
+    for view, layers in _view_layer_sets(assets["views.js"]).items():
+        unknown = sorted(set(layers) - catalog)
+        assert not unknown, f"view `{view}` defaults to unknown layer(s) {unknown}"
+
+
+def test_every_layer_has_a_root_class_rule(assets, stylesheet):
+    """A layer is a root class, so switching a view on is a set of class names.
+
+    A layer with no rule is a toggle that shows nothing -- a button in the
+    catalog that has never done anything, discovered by pressing it in class.
+    """
+    for layer in sorted(_catalog(assets["views.js"])):
+        assert f".show-{layer}" in stylesheet, (
+            f"layer `{layer}` has no `.show-{layer}` rule in style.css; its "
+            f"toggle would switch on nothing"
+        )
+
+
+def test_no_transition_on_a_state_carrying_property(stylesheet):
+    """Nothing animates, anywhere.
+
+    Motion during a sentence steals the room from the instructor's voice, and
+    fast stepping must degrade into a legible flip-book rather than a queue of
+    overlapping animations. A blanket ban rather than a per-property one:
+    every appearance value in this file is state-carrying by construction,
+    since the whole page is a class change followed by a repaint.
+    """
+    code = COMMENT.sub(" ", stylesheet)
+    for banned in ("transition", "animation", "@keyframes"):
+        assert banned not in code, (
+            f"style.css declares `{banned}`. No CSS transition on any "
+            f"state-carrying property: a transition mid-sentence competes with "
+            f"the instructor's voice, and fast stepping would overlap them."
+        )
+
+
+# ---- the stroke model -------------------------------------------------------
+# Two halves of one model: pitch (does the pattern still read as broken?) and
+# presence (is the mark there at all?). Both are arithmetic over authored values
+# with no DOM, which is what lets them live under this file's Python-or-nothing
+# rule -- exactly like the crossing-angle floor in `layout_geometry.py`.
+#
+# The room: a 2.5 m image on a 1060-unit viewBox at 8 m, so ONE VIEWBOX UNIT IS
+# ONE ARCMINUTE and stroke widths read as angles with no conversion.
+MODULATION_FLOOR = 0.5182   # Michelson depth a smeared pattern must keep
+MAR = 1.97                  # 1 minimum angle of resolution at the 20/40 design
+                            # observer, in viewBox units. Confirmed with the
+                            # instructor; the room, not the eye chart, is what
+                            # this is retuned against.
+MIN_LANE = 120              # the shortest lane that may carry a mark
+MIN_CYCLES = 3              # fewer reads as an accident of where the lane ended
+DUTY_CAP = 0.6              # above this the closed form runs away; see below
+DASHED_W_FLOOR = 3.16       # minimum stroke weight for any dashed mark, in
+                            # viewBox units. A recorded value rather than a
+                            # derived one, and the test below is what keeps the
+                            # two honest with each other.
+
+# Marks allowed to fail the PRESENCE floor, and why. Both are on record so the
+# question is not reopened a third time: neither is a mark the back row is meant
+# to read, and both carry their meaning somewhere other than the stroke.
+FADE_ALLOWED = {
+    "--synth": "derived machinery, declared front-of-room; scaffolding may fade",
+    "--removed": "removal's meaning is on the X glyph, not on the stroke",
+}
+
+
+def _pitch_floor(duty, smear):
+    """The shortest dash pitch whose smeared modulation still clears the floor.
+
+    Closed form, not a table. Keep the fundamental of the square wave: mean
+    coverage is the duty cycle *d*, the fundamental's amplitude is
+    `(2/pi)sin(pi d)`, and a Gaussian's MTF at period *p* is
+    `exp(-2 pi^2 sigma^2 / p^2)`. Set the depth to the floor and solve.
+
+    Accurate to ~1% up to duty 0.6 against a numeric sweep, then it runs away,
+    and above duty ~0.65 it has NO SOLUTION at all -- which is the useful half:
+    above that a square wave's trough is held open by its harmonics, and
+    harmonics are the first thing a blur removes.
+
+    **Exactly independent of stroke weight.** A dashed stroke is a union of
+    rectangles and a Gaussian is separable, so blurred coverage factorises into
+    an along-stroke term and an across-stroke one; the across term is constant
+    along the stroke, multiplies peak and trough alike, and cancels out of the
+    ratio identically. Weight decides whether the mark is present, not whether
+    it is dashed -- which is why there are two floors here and not one.
+    """
+    ratio = (2 / math.pi) * math.sin(math.pi * duty) / (MODULATION_FLOOR * duty)
+    if ratio <= 1:
+        return math.inf     # no pitch survives at this duty
+    return math.pi * smear * math.sqrt(2 / math.log(ratio))
+
+
+def _dash_patterns(stylesheet):
+    """Every declared dash pattern, as `{prefix: (dash, gap)}`.
+
+    Keyed by the token's prefix so a pattern can be paired with the weight and
+    opacity tokens sharing it -- `--residual-dash` with `--residual-w`. That
+    naming rule is what makes both floors checkable at all, and
+    `test_every_dash_pattern_pairs_with_a_stroke_weight` asserts it directly.
+    """
+    match = re.search(r":root\s*\{(.*?)\}", stylesheet, re.DOTALL)
+    found = {}
+    for token in re.finditer(
+        r"(--[a-z0-9-]+)-dash\s*:\s*([\d.]+)\s+([\d.]+)\s*;", match.group(1)
+    ):
+        found[token.group(1)] = (float(token.group(2)), float(token.group(3)))
+    assert found, "no dash pattern found in :root -- this would pass vacuously"
+    return found
+
+
+@pytest.fixture(scope="module")
+def smear(stylesheet):
+    """The back-row smear: ONE authored quantity the whole model derives from.
+
+    A safety margin rather than a measurement -- it corresponds to roughly a
+    20/204 observer, about ten times a 20/20 eye. If the real room differs from
+    the model, this is the number that changes, and every clearance below
+    re-derives from it. That is the entire reason it is one token.
+    """
+    value = _numeric_tokens(stylesheet).get("--smear")
+    assert value, (
+        "style.css defines no --smear. The stroke model is one authored "
+        "quantity plus a derivation per pattern; without the quantity, every "
+        "derived value is a magic number nobody can retune against the room."
+    )
+    return value
+
+
+def test_every_dash_pattern_pairs_with_a_stroke_weight(stylesheet):
+    numeric = _numeric_tokens(stylesheet)
+    for prefix in sorted(_dash_patterns(stylesheet)):
+        assert f"{prefix}-w" in numeric, (
+            f"{prefix}-dash has no {prefix}-w. Presence is `weight x duty x "
+            f"opacity`, so a pattern whose weight cannot be found by name is a "
+            f"pattern neither floor can be applied to."
+        )
+
+
+def test_every_dash_pattern_is_authored_under_the_duty_cap(stylesheet):
+    for prefix, (dash, gap) in sorted(_dash_patterns(stylesheet).items()):
+        duty = dash / (dash + gap)
+        assert duty <= DUTY_CAP, (
+            f"{prefix}-dash is `{dash} {gap}`, duty {duty:.2f}, over the "
+            f"{DUTY_CAP} authoring cap. Above it a pattern's trough is held "
+            f"open by its harmonics -- the first thing a blur removes -- so it "
+            f"survives for a reason that does not survive the room."
+        )
+
+
+def test_every_dash_pattern_clears_the_pitch_floor(stylesheet, smear):
+    """A dash that loses does not vanish -- it becomes a dimmer solid line.
+
+    That failure mode is the whole argument for checking this from a test: the
+    mark is still there, still the right colour, and saying the wrong thing.
+    """
+    for prefix, (dash, gap) in sorted(_dash_patterns(stylesheet).items()):
+        pitch = dash + gap
+        floor = _pitch_floor(dash / pitch, smear)
+        assert pitch >= floor, (
+            f"{prefix}-dash has pitch {pitch} against a floor of {floor:.1f} at "
+            f"smear {smear}. It will read as a solid line from the back row."
+        )
+
+
+def test_every_dash_pattern_shows_at_least_three_cycles(stylesheet):
+    """Fewer than three cycles reads as an accident of where the lane ended
+    rather than as a pattern, which spends the register without buying it."""
+    ceiling = MIN_LANE / MIN_CYCLES
+    for prefix, (dash, gap) in sorted(_dash_patterns(stylesheet).items()):
+        assert dash + gap <= ceiling, (
+            f"{prefix}-dash has pitch {dash + gap}, over the {ceiling:.0f} that "
+            f"fits {MIN_CYCLES} cycles on the shortest lane a mark may sit on "
+            f"({MIN_LANE} units)"
+        )
+
+
+def test_the_dashed_stroke_floor_is_what_the_two_constraints_imply(smear):
+    """3.16 units is derived here rather than restated.
+
+    The pitch floor and the three-cycle ceiling together cap the duty cycle; the
+    presence floor then divides through that cap. Pinning the derivation instead
+    of the number means a retune of the smear moves the floor, rather than
+    leaving 3.16 behind as a constant nobody can re-justify.
+
+    The two checks are asymmetric on purpose. The duty cap is compared loosely,
+    because the closed form is a ~1% approximation and pinning it tighter than
+    its own accuracy would be pinning noise. The stroke floor is compared with a
+    DIRECTION: the shipped 3.16 must be at least what the model implies -- a
+    recorded constant that is a shade conservative is a rounding, while one that
+    is a shade generous is a mark authored under the floor with a test agreeing.
+    """
+    ceiling = MIN_LANE / MIN_CYCLES
+    duty = max(step / 1000 for step in range(1, 651)
+               if _pitch_floor(step / 1000, smear) <= ceiling)
+    assert abs(duty - 0.625) < 0.01, (
+        f"the pitch rule and the three-cycle ceiling now cap duty at {duty:.3f}, "
+        f"not the 0.625 on record -- further apart than the closed form's own "
+        f"~1% accuracy explains, so something in the model has moved"
+    )
+    implied = MAR / duty
+    assert implied <= DASHED_W_FLOOR, (
+        f"the model now implies a dashed-stroke floor of {implied:.2f}, above "
+        f"the {DASHED_W_FLOOR} on record. Marks authored at the recorded floor "
+        f"are under the real one."
+    )
+    assert DASHED_W_FLOOR - implied < 0.05, (
+        f"{DASHED_W_FLOOR} is {DASHED_W_FLOOR - implied:.2f} above the "
+        f"{implied:.2f} the model implies -- no longer a rounding, so the "
+        f"recorded floor has come adrift from its derivation"
+    )
+
+
+def test_every_dashed_mark_clears_the_presence_floor(stylesheet, smear):
+    """Effective width = weight x duty x opacity, and it must clear 1 MAR.
+
+    The angular floor and the ink floor collapse together once a smeared dash is
+    recognised as a solid line of its own mean luminance -- so there is one
+    number here rather than two.
+    """
+    numeric = _numeric_tokens(stylesheet)
+    for prefix, (dash, gap) in sorted(_dash_patterns(stylesheet).items()):
+        duty = dash / (dash + gap)
+        effective = numeric[f"{prefix}-w"] * duty * numeric.get(f"{prefix}-op", 1.0)
+        if prefix in FADE_ALLOWED:
+            # Recorded, not silently skipped. A mark intended to recede failing
+            # a presence floor is the criterion agreeing with the design -- and
+            # an exemption that stops being needed should come off the list
+            # rather than sit here unexamined.
+            assert effective < MAR, (
+                f"{prefix} is on the fade list ({FADE_ALLOWED[prefix]}) but now "
+                f"clears the presence floor at {effective:.2f}. Either the token "
+                f"moved or the exemption is stale -- take it off the list."
+            )
+            continue
+        assert effective >= MAR, (
+            f"{prefix} has effective width {effective:.2f} against the {MAR} "
+            f"floor at the 20/40 design observer. It is a dashed mark thinner "
+            f"than the room can resolve, so it reads as an absence."
+        )
+
+
+def test_the_fade_list_is_closed(stylesheet):
+    """Only the two marks on record may fade, and they must still exist."""
+    patterns = _dash_patterns(stylesheet)
+    for prefix in FADE_ALLOWED:
+        assert prefix in patterns, (
+            f"{prefix} carries no dash pattern any more, so its fade exemption "
+            f"is stale and should be removed rather than left standing"
+        )
+
+
+# ---- the scaffold tier ------------------------------------------------------
+def test_the_scaffold_tier_owns_opacity_alone(stylesheet):
+    """Dimming is one tier's channel, and nothing else may use it.
+
+    Lanes the active annotation does not touch dim to the scaffold tier, which
+    is only safe because an empty hot set means *every* lane is hot -- so the
+    graph is never dimmed when it is itself the subject. If a second mechanism
+    also dimmed, the two would compose into a lane at 9% nobody authored.
+    """
+    assert "--scaffold-op" in _defined_tokens(stylesheet), (
+        "no --scaffold-op token; the scaffold tier's dimming would be a "
+        "hard-coded opacity outside the block that retunes the diagram"
+    )
+    code = COMMENT.sub(" ", stylesheet)
+    for rule in re.finditer(r"([^{}]*)\{([^{}]*)\}", code):
+        selector, body = rule.group(1), rule.group(2)
+        if "var(--scaffold-op)" in body:
+            assert ".cold" in selector, (
+                f"`{selector.strip()}` dims with the scaffold opacity but is "
+                f"not a `.cold` rule. The scaffold tier owns opacity."
+            )
+
+
+def test_an_empty_hot_set_means_every_lane_is_hot(assets):
+    """The rule that makes the scaffold tier safe, asserted where it lives.
+
+    Without it, the pristine opening screen -- the one picture whose subject is
+    the graph itself -- would render with every lane dimmed to 30%.
+    """
+    code = COMMENT.sub(" ", assets["state.js"])
+    assert "export function anyHot" in code, (
+        "state.js exports no `anyHot`. Whether anything is hot at all is the "
+        "single question the scaffold tier turns on, and it must be answered in "
+        "one place or the canvas and the ledger will answer it differently."
+    )
+    assert "cold" in code, (
+        "state.js never computes coldness, so nothing decides which lanes the "
+        "scaffold tier dims"
+    )

From 080518e8f4b91e6532b82370f15e3ad6153438d7 Mon Sep 17 00:00:00 2001
From: Brett Gentile <bgentile19@gmail.com>
Date: Fri, 14 Aug 2026 19:16:40 -0400
Subject: [PATCH 2/2] fix(web): hand-toggled layers survive the story moving
 (#41)

Review findings on the beat engine, all three from the spec axis.

`resolveBeat` rebuilt the layer set from the view's entry table alone, so
`->` destroyed any pointer toggle. The spec spends the cross-day layer
mashup -- Day 3's cut over Day 4's interdicted network, the unit's
strongest moment -- on `R` and on nothing else; as built it survived zero
beats. Layers are now resolved from three sources in order: the view's
entry table, the beat's overrides, then the instructor's own toggles,
which are recorded in `layerOverrides` and cleared by `R` alone. Rebuilding
from all three every time keeps a beat idempotent including its layers,
which resetting to bare defaults also did but at that price.

A layer toggle re-resolves the layers alone rather than the whole beat, so
a pinned lane survives a click on a layer button.

The coarse controls now address units by ordinal rather than by the value
in `beat.unit`. Reading the value assumed units numbered from zero with no
gaps, and silently mis-jumped on both spines #42-#44 are expected to build
-- an interdiction ladder whose k starts at 1, and a Pareto spine with
duplicate detents collapsed out.

Standards axis: the spine clamp and the "first beat of unit" contract each
appeared twice; extracted to `clampToSpine` and `setUnitAt`.

Also records two things so they are not rediscovered: why the promoted
reverse arc's `24 15` is not in the token block (duty 0.615 is over this
ticket's own authoring cap and it clears the pitch floor inside the closed
form's error bar, so it ships with the mark that justifies it), and what
the two-row anchor does to the label footprint -- +/-25 where it was +/-12,
which clears every distance the anchor solve enforces and exceeds only the
lane half-band that governs casings.

Adds the flat `w >= 3.16` assertion the acceptance criteria state, beside
the derived presence floor, on the same recorded exemption list.
---
 src/clopt/web/render.js  |  19 +++-
 src/clopt/web/state.js   | 194 +++++++++++++++++++++++++++++++--------
 src/clopt/web/style.css  |  11 +++
 tests/test_web_assets.py |  30 ++++++
 4 files changed, 213 insertions(+), 41 deletions(-)

diff --git a/src/clopt/web/render.js b/src/clopt/web/render.js
index 956e9f2..eea4ea0 100644
--- a/src/clopt/web/render.js
+++ b/src/clopt/web/render.js
@@ -54,8 +54,23 @@ const LABEL_GAP = 12;          /* air between a node's disc and its id */
 /* The anchor's two rows, straddling the frozen point rather than starting at
  * it: the flow numeral sits half a row above and the lane's statistics half a
  * row below, so the PAIR is centred on the point the anchor solve certified
- * clear. Hanging both rows downward would put the lower one somewhere the
- * solve never checked. */
+ * clear. Hanging both rows downward would put the lower one somewhere the solve
+ * never checked.
+ *
+ * The one geometry consequence of splitting the lane label in two, and worth
+ * naming because it is a footprint change made outside the ticket that measured
+ * the clearances. Two rows are not optional -- Flow & Cut shows a capacity AND
+ * a flow, so the catalog requires both on screen at once, and the single-row
+ * layout that preceded this drew them on top of each other. The label block now
+ * spans the anchor +/-25 where it spanned +/-12, and 13 is near the minimum
+ * that keeps two 24-unit plates apart.
+ *
+ * That still clears every distance the anchor solve enforces -- 74 from a node
+ * (44 of it air beyond the disc), 74 from another anchor, 44 from a crossing.
+ * What it does exceed is the 14-unit lane half-band, which governs the casing
+ * width rather than the label, so nothing the crossing solve depends on moves.
+ * If the retune against the real projector shows a plate crowding a lane it is
+ * not attached to, this constant is the one to pull, not the anchor solve. */
 const ROW_OFFSET = 13;
 
 /**
diff --git a/src/clopt/web/state.js b/src/clopt/web/state.js
index af45558..cdad80d 100644
--- a/src/clopt/web/state.js
+++ b/src/clopt/web/state.js
@@ -26,8 +26,24 @@ export const state = {
   /* Active layer ids, opening on the first view's entry set rather than empty.
    * A blank set here is not a neutral starting point -- it is the one layer
    * state the catalog forbids read from the other end, and the page would open
-   * on a diagram with nothing drawn over it and no beat responsible for that. */
+   * on a diagram with nothing drawn over it and no beat responsible for that.
+   *
+   * DERIVED, not authored: rebuilt on every beat from the view's entry table,
+   * the beat's own overrides and `layerOverrides` below, in that order. Nothing
+   * outside this module may write to it -- see `toggleLayer`. */
   layers: layersForView(VIEWS[0].id),
+
+  /**
+   * The layers the instructor has switched by hand, `{layerId: on}`.
+   *
+   * Only the ones actually touched, so a view's entry table can change under a
+   * running class without the untouched layers being pinned to whatever they
+   * happened to be. Layer toggles are pointer-only and this is what makes them
+   * durable: the resolved set is rebuilt every beat, and without a record of
+   * the hand's intent a toggle would last exactly one keypress. `R` clears it,
+   * and `R` alone.
+   */
+  layerOverrides: new Map(),
   /** Active threat picture name, or `null` for the pristine network. */
   threat: null,
 
@@ -155,6 +171,20 @@ export function spine(viewId = state.view) {
   return SPINES.get(viewId) || ENTRY_SPINE;
 }
 
+/**
+ * A beat index the given view's spine actually has, by clamping.
+ *
+ * The one place "carry the beat index across, as far as it still goes" is
+ * written down. Every ladder in this application is derived from data -- the
+ * augmentation count, the interdiction rungs, the Pareto detents -- so a spine's
+ * length moves under the instructor whenever the dataset or the threat picture
+ * does, and clamping is what keeps the render pure across that move rather than
+ * leaving the index pointing past the end.
+ */
+function clampToSpine(beat, viewId = state.view) {
+  return Math.min(Math.max(beat, 0), spine(viewId).length - 1);
+}
+
 /**
  * Install a view's whole spine, prefetched and complete.
  *
@@ -164,17 +194,57 @@ export function spine(viewId = state.view) {
  */
 export function setSpine(viewId, beats) {
   SPINES.set(viewId, beats.length ? beats : ENTRY_SPINE);
-  if (viewId === state.view) setBeat(Math.min(state.beat, spine().length - 1));
+  if (viewId === state.view) setBeat(clampToSpine(state.beat));
+}
+
+/**
+ * The distinct coarse units of a spine, in spine order.
+ *
+ * The coarse controls address units by ORDINAL -- "the third one" -- rather
+ * than by the value in `beat.unit`, which is deliberate and load-bearing. The
+ * instructor says "go back to the second one", and what makes that the second
+ * one is its position in the story, not an integer a view ticket happened to
+ * number from zero. Reading the value directly would silently mis-jump on a
+ * ladder numbered from 1 (an interdiction budget *k* starts at 1, not 0) and
+ * would skip whole digits on a Pareto spine whose detents leave gaps where
+ * duplicate plans collapsed out. Both of those are spines #42-#44 are expected
+ * to build, so the coupling is removed here rather than left as a rule three
+ * later tickets have to remember.
+ */
+function unitValues(viewId = state.view) {
+  return [...new Set(spine(viewId).map((beat) => beat.unit))];
 }
 
 /** How many coarse units the active view's spine has. */
 export function unitCount(viewId = state.view) {
-  return new Set(spine(viewId).map((beat) => beat.unit)).size;
+  return unitValues(viewId).length;
 }
 
-/** The index of the first beat -- beat *a* -- of a coarse unit. */
-function firstBeatOfUnit(unit) {
-  return spine().findIndex((beat) => beat.unit === unit);
+/**
+ * Jump to the *n*th coarse unit's beat *a*, counting from zero, or decline if
+ * the view has no such unit.
+ *
+ * Both coarse controls end here -- the arrows and the digits differ only in how
+ * they name the unit they want. Declining rather than clamping is the shared
+ * half: an out-of-range unit leaves the picture exactly where it was, whether it
+ * was asked for by leaning on an arrow or by mistyping a digit.
+ */
+function setUnitAt(ordinal) {
+  const values = unitValues();
+  if (ordinal < 0 || ordinal >= values.length) return false;
+  return setBeat(spine().findIndex((beat) => beat.unit === values[ordinal]));
+}
+
+/** Which coarse unit, by ordinal, the current beat sits in. */
+function currentUnitOrdinal() {
+  const beat = spine()[state.beat];
+  return beat ? unitValues().indexOf(beat.unit) : -1;
+}
+
+/** The index of the first beat -- beat *a* -- of the unit at an ordinal. */
+function firstBeatOfUnitAt(ordinal) {
+  const values = unitValues();
+  return spine().findIndex((beat) => beat.unit === values[ordinal]);
 }
 
 /**
@@ -185,26 +255,55 @@ function firstBeatOfUnit(unit) {
  * a keypress ago. The pin goes with it -- a click pins a lane hot until the next
  * beat or `R`, and "the next beat" is a promise only this function can keep.
  *
- * Layers are reset to the view's defaults here too, because a view's layer
- * table is its *entry* state and beats drive it from there. The cost, stated:
- * a layer the instructor toggled by hand does not survive the next keypress.
- * That is the same rule read from the other end -- a beat renders identically
- * however it was reached, including "reached after fiddling with the layers".
+ * Called on every beat change, and also by the page after a dataset is built:
+ * the marks were cleared along with the old theater's edge ids, and the current
+ * beat is the only thing that knows what should be marked instead.
+ *
+ * **Layers are rebuilt, not preserved, and the order of the three sources is
+ * the decision.** The view's entry table goes down first, because a view's
+ * layer table is its entry state and not an invariant; the beat overrides it,
+ * because beats drive layer state as the story advances; and the instructor's
+ * own toggles go on top, because a hand on the pointer is the most recent
+ * authority in the room.
  *
- * `seed` is the one exception, and it exists for exactly one caller: returning
- * to a view restores the layer set it was left holding, and the beat's own
- * overrides are then re-applied on top of that rather than in place of it.
+ * Rebuilding from those three every time is what keeps a beat idempotent
+ * *including its layers* -- a leftover layer from the beat before would make
+ * the picture depend on the route taken to it. But rebuilding from the entry
+ * table ALONE would destroy the hand toggles on the very next keypress, and the
+ * cross-day mashup they exist for -- Day 3's cut over Day 4's interdicted
+ * network -- is the strongest moment in the unit. The spec spends that mashup
+ * on `R` and on nothing else, so `R` is the only thing here that clears
+ * `layerOverrides`.
  */
-export function resolveBeat(seed) {
+export function resolveBeat() {
   clearPin();
   for (const set of Object.values(state.marks)) set.clear();
   state.throughput = null;
   state.cut = null;
   state.delta = null;
-  state.layers = seed ? new Set(seed) : layersForView(state.view);
+  state.layers = layersForView(state.view);
 
   const beat = spine()[state.beat];
   if (beat && beat.apply) beat.apply(state);
+
+  /* What the beat asked for, kept so a later hand toggle can be re-applied over
+   * it without re-running the beat -- running `apply` again would clear the pin
+   * and the marks, and a click on a lane must survive a click on a layer. */
+  beatLayers = new Set(state.layers);
+  state.layers = withOverrides(beatLayers);
+}
+
+/** The beat's own layer set, before the instructor's toggles go on top. */
+let beatLayers = new Set();
+
+/** A layer set with the hand toggles applied over it. */
+function withOverrides(base) {
+  const resolved = new Set(base);
+  for (const [layerId, on] of state.layerOverrides) {
+    if (on) resolved.add(layerId);
+    else resolved.delete(layerId);
+  }
+  return resolved;
 }
 
 /**
@@ -238,14 +337,12 @@ export function stepBeat(delta) {
  * this one again" without a wasted press.
  */
 export function stepUnit(delta) {
-  const beats = spine();
-  const current = beats[state.beat];
-  if (!current) return false;
-  if (delta < 0 && state.beat !== firstBeatOfUnit(current.unit)) {
-    return setBeat(firstBeatOfUnit(current.unit));
+  const ordinal = currentUnitOrdinal();
+  if (ordinal === -1) return false;
+  if (delta < 0 && state.beat !== firstBeatOfUnitAt(ordinal)) {
+    return setUnitAt(ordinal);
   }
-  const target = firstBeatOfUnit(current.unit + delta);
-  return target === -1 ? false : setBeat(target);
+  return setUnitAt(ordinal + delta);
 }
 
 /**
@@ -256,8 +353,7 @@ export function stepUnit(delta) {
  * somewhere nobody asked for while the instructor is mid-sentence.
  */
 export function jumpToUnit(number) {
-  const target = firstBeatOfUnit(number - 1);
-  return target === -1 ? false : setBeat(target);
+  return setUnitAt(number - 1);
 }
 
 /**
@@ -266,23 +362,33 @@ export function jumpToUnit(number) {
  *
  * Full rather than partial on purpose: a half-reset that leaves four layers
  * burning is not a baseline, and the one key the instructor reaches for when
- * the picture has got away from them has to land somewhere known. Accepted
- * cost, stated where it bites: the cross-day layer mashup is both pointer-only
- * *and* destroyed by `R`.
+ * the picture has got away from them has to land somewhere known.
+ *
+ * THE ONLY THING THAT CLEARS THE HAND TOGGLES, which is where the accepted cost
+ * bites: the cross-day layer mashup is both pointer-only *and* destroyed by
+ * `R`. Every other control leaves it standing, which is what makes it usable at
+ * all -- a mashup that did not survive a beat step could never be built while
+ * the story was moving.
  */
 export function resetView() {
   state.threat = null;
   state.beat = 0;
+  state.layerOverrides.clear();
   resolveBeat();
 }
 
 /**
  * Switch view, restoring everything that view was last left holding.
  *
- * The beat index and the layer set are both remembered, which is the point:
+ * The beat index and the hand toggles are both remembered, which is the point:
  * Flow & Cut stays parked on augmentation 3 while the instructor detours to
  * answer a question. A view seen for the first time enters at beat 0 with its
  * default layers.
+ *
+ * Note what is remembered: the OVERRIDES, not the resolved layer set. The
+ * resolved set is derived from the view table, the beat and the overrides, and
+ * remembering a derived value is how a view comes back showing a layer state
+ * that no longer follows from anything on screen.
  */
 export function setView(viewId) {
   /* Pressing a view's own key is a no-op, not a re-entry. It has to be: the
@@ -290,21 +396,31 @@ export function setView(viewId) {
    * straight back, which is harmless in the middle of a class and is exactly
    * how booting into the first view once left every layer switched off. */
   if (viewId === state.view) return;
-  state.views[state.view] = { beat: state.beat, layers: new Set(state.layers) };
+  state.views[state.view] = {
+    beat: state.beat,
+    overrides: new Map(state.layerOverrides),
+  };
   state.view = viewId;
   const remembered = state.views[viewId];
-  state.beat = remembered ? Math.min(remembered.beat, spine(viewId).length - 1) : 0;
-  /* The marks and the headline numbers are rebuilt from the beat rather than
-   * remembered alongside it -- they are derived, and storing derived state is
-   * how a remembered view comes back showing last week's numbers. Layers are
-   * the exception because a hand toggle is not derivable from anything, so
-   * they are seeded back in and the beat's overrides re-applied over them. */
-  resolveBeat(remembered && remembered.layers);
+  state.beat = remembered ? clampToSpine(remembered.beat, viewId) : 0;
+  state.layerOverrides = remembered ? new Map(remembered.overrides) : new Map();
+  resolveBeat();
 }
 
+/**
+ * Toggle one layer by hand, and remember that the hand did it.
+ *
+ * Recorded as an override rather than written straight onto `state.layers`,
+ * because the layer set is rebuilt from scratch on every beat. Writing the set
+ * directly would put the toggle on screen for exactly as long as it took to
+ * press the next key.
+ *
+ * Re-resolves the layers alone, not the whole beat: a pinned lane must survive
+ * a layer toggle, and the marks have not changed.
+ */
 export function toggleLayer(layerId) {
-  if (state.layers.has(layerId)) state.layers.delete(layerId);
-  else state.layers.add(layerId);
+  state.layerOverrides.set(layerId, !state.layers.has(layerId));
+  state.layers = withOverrides(beatLayers);
 }
 
 /** Switch threat picture. `null` restores the pristine network. */
diff --git a/src/clopt/web/style.css b/src/clopt/web/style.css
index ab26d2d..1eac393 100644
--- a/src/clopt/web/style.css
+++ b/src/clopt/web/style.css
@@ -156,6 +156,17 @@
   --path:               #f0e442;
   --path-w:             11;
 
+  /* NOT HERE, and deliberately: the promoted reverse arc's adopted `24 15` at
+   * stroke 11. Its duty is 0.615, over the 0.6 authoring cap, and it clears the
+   * pitch floor by 1.008x -- inside the closed form's own ~1% error bar, which
+   * is to say it is a value the rule cannot actually certify. It is also
+   * geometry-specific in a way nothing else here is: it exists only for an arc
+   * promoted to offset 22 with a hollow head and its lane's plain residual
+   * suppressed, all of which lands with Flow & Cut. Shipping the token now
+   * would put a pattern in the catalog that fails this ticket's own duty rule,
+   * with no mark on screen to justify the exception. Recorded here so the
+   * ticket that draws it re-opens the question rather than rediscovering it. */
+
   /* ---- annotation tier ------------------------------------------------- */
   /* The knockout casing at a lane crossing. Painted in the background colour
    * on the annotation tier only -- never lane over lane -- so the pristine
diff --git a/tests/test_web_assets.py b/tests/test_web_assets.py
index b9aa753..842cb32 100644
--- a/tests/test_web_assets.py
+++ b/tests/test_web_assets.py
@@ -816,6 +816,36 @@ def test_every_dashed_mark_clears_the_presence_floor(stylesheet, smear):
         )
 
 
+def test_every_dashed_mark_clears_the_recorded_stroke_floor(stylesheet):
+    """`w >= 3.16` for any dashed mark, stated as flatly as the spec states it.
+
+    Nearly but not quite the presence floor above: that one divides through each
+    pattern's own duty cycle, where this is the single number an author can
+    check a new mark against without doing any arithmetic. Both are here because
+    the flat one is the rule people will actually apply, and it should fail on
+    the same marks the derived one fails on rather than being a second opinion.
+
+    Same exemption list, for the same recorded reasons. A mark that is allowed
+    to be too faint to read is allowed to be too thin to carry a dash.
+    """
+    numeric = _numeric_tokens(stylesheet)
+    for prefix in sorted(_dash_patterns(stylesheet)):
+        weight = numeric[f"{prefix}-w"]
+        if prefix in FADE_ALLOWED:
+            assert weight < DASHED_W_FLOOR, (
+                f"{prefix} is on the fade list ({FADE_ALLOWED[prefix]}) but is "
+                f"now {weight} units, at or over the {DASHED_W_FLOOR} floor -- "
+                f"the exemption is stale, take it off the list"
+            )
+            continue
+        assert weight >= DASHED_W_FLOOR, (
+            f"{prefix} is a dashed mark at {weight} units, under the "
+            f"{DASHED_W_FLOOR} floor. Below it there is no duty cycle that "
+            f"satisfies pitch and presence at once, so the pattern cannot be "
+            f"rescued by re-pitching it -- the stroke has to get heavier."
+        )
+
+
 def test_the_fade_list_is_closed(stylesheet):
     """Only the two marks on record may fade, and they must still exist."""
     patterns = _dash_patterns(stylesheet)