Fix audit findings for runner, docs, and CI

Author: adewale

.github/workflows/regenerate-generated-files.yml

@@ -54,8 +54,9 @@ jobs:
               exit 0
             fi
             echo "Push raced with another commit; retrying (attempt $attempt)."
-            git reset --soft HEAD~1
-            git restore --staged .
+            # Drop the unpushed generated commit and its worktree changes;
+            # the next iteration rebases a clean checkout, then rebuilds.
+            git reset --hard HEAD~1
           done
           echo "Failed to push regenerated files after 3 attempts." >&2
           exit 1

README.md

@@ -126,6 +126,7 @@ Source assets live at stable paths such as:
 public/site.css
 public/syntax-highlight.js
 public/editor.js
+public/runner.js
 ```
 
 Before tests/deploy, regenerate embedded example data, fingerprinted asset copies, and Python manifests:
@@ -140,6 +141,7 @@ This writes files such as:
 public/site.<hash>.css
 public/syntax-highlight.<hash>.js
 public/editor.<hash>.js
+public/runner.<hash>.js
 src/asset_manifest.py
 src/editorial_registry_data.py
 ```

docs/rubric-saturation.md

@@ -1,9 +1,14 @@
-# Rubric saturation analysis
+# Historical rubric saturation analysis (superseded)
 
-After six iteration passes, the figure system attaches a figure to
-every example (one banner per slug on `main`) from the 124 paint
-functions in `src/marginalia.py FIGURES`. Coverage is 100%.
-Distribution against `docs/example-figure-rubric.md`:
+> **Historical record, not release evidence.** This snapshot predates the
+> current figure rubric and its ≥8.5 production gate. It is retained to explain
+> the rubric changes below; use `docs/quality-registries.toml`,
+> `docs/example-figure-rubric.md`, and the quality checks for current scores
+> and release decisions.
+
+At the time of this analysis, the figure system attached one banner per slug
+from 124 paint functions in `src/marginalia.py FIGURES`. Its then-current
+scoring distribution was:
 
 | band | count | composition |
 |---|---:|---|
@@ -12,17 +17,14 @@ Distribution against `docs/example-figure-rubric.md`:
 | 8.5 | ~55 | strong but honest reuse, or generic placeholders |
 | 8.0 | ~16 | binding pictures, abstract pictures, weak reuses |
 
-Mean ≈ 8.7. **No figure scores below 8.0.** No figure exceeds 9.5.
-Pushing further requires changes to the rubric itself, because the
-remaining drag comes from criteria that are structurally over-strict
-for a library this size.
+The historical mean was approximately 8.7, with no score below 8.0. Those
+scores do **not** satisfy or describe today's production gate.
 
-## Why every figure cannot reach 9.0 under the current rubric
+## Why every figure could not reach 9.0 under the v1 rubric
 
-Two criteria in `docs/example-figure-rubric.md` cap most figures
-at 8.5 by design:
+Two v1 criteria capped most figures at 8.5 by design:
 
-### Criterion 2 — "Match the running variables (0–1.0)"
+### v1 Criterion 2 — "Match the running variables (0–1.0)"
 
 A figure loses up to 1.0 when its placeholders (`a`, `b`, `xs`) do
 not match the cell's specific names (`first`, `second`, `factor`,
@@ -57,7 +59,7 @@ journey-section figure already sits at `/journeys/<slug>`, and the
 lesson appears alone at `/examples/<slug>`; readers don't see both
 beside each other. The "independence" penalty fires regardless.
 
-## What the rubric needs
+## Historical recommendations for the rubric
 
 Four upgrades would let further iteration produce visible quality
 gains rather than just shuffling the same band.
@@ -81,7 +83,7 @@ For canonical figures: criteria 2 and 9 stay as written. Cap at
 Result: ~70 library figures (today reuse-shaped) all reach 9.0;
 ~30 canonical figures reach 9.0–9.5 by being slug-specific.
 
-### 2. Replace criterion 2 with **"the figure earns its place"**
+### 2. Replace criterion 2 with **"the figure earns its place"** (implemented)
 
 Strict variable-matching loses information value at scale. The
 better question is "does swapping in this figure improve the cell
@@ -124,7 +126,7 @@ page-level rubric (0–1.0) would score:
 Today this is a manual judgement; codifying it would prevent the
 inevitable "too many figures" failure mode as coverage grows.
 
-## What this turn changed
+## Changes recorded by this historical analysis
 
 - Fixed the layout regression: cells stay 2-col always; figures live
   in banner rows BETWEEN cells. `hello-world` now matches production.

docs/visual-explainer-spec.md

@@ -9,8 +9,8 @@ between prose and code, which works at every viewport.
 ## Goals
 
 - **One column model per page type, fixed.** Example pages keep cells in
-  the prose|code 2-col grid; journey pages keep section heading + figure
-  in a 2-col grid. Figures never reflow the surrounding columns.
+  the prose|code 2-col grid; journey pages keep headings, figures, and lists
+  in one centered flow. Figures never reflow the surrounding columns.
 - **Universal, not viewport-conditional.** A reader at any width sees the
   same figure in the same place. No `@media` breakpoints for figure
   positioning; no overlay layer.
@@ -121,11 +121,12 @@ single-column flow on every viewport:
 ```
 
 One figure per section, faithful to the section's conceptual shift,
-scored against `docs/journey-visualisation-rubric.md`. Figures are
-mapped by section title via `SECTION_FIGURES` in `src/marginalia.py`;
-`render_for_section` returns empty for unmapped titles, but the
-SectionFigureContract requires every production journey section to
-have one.
+scored against `docs/journey-visualisation-rubric.md`. Journey-section
+metadata lives in `docs/quality-registries.toml` and is loaded through
+`src/editorial_registry.py`; `src/marginalia.py` renders the resulting
+registry entry. `render_for_section` returns empty for an unmapped title,
+but the SectionFigureContract requires every production journey section
+to have one.
 
 ### Why these two, not five
 
@@ -138,38 +139,22 @@ vary instead. Adding a second or third figure changes the banner's
 internal grid (auto-fit handles 1/2/3+), but the cells around it
 remain unchanged — no reflow, no cognitive context-switch.
 
-## Anchors and attachments
+## Anchors, attachments, and journey figures
 
-`src/marginalia.py` declares which figures attach where. The data shape
-will move from per-cell injection toward per-position banners:
+`docs/quality-registries.toml` is the source of truth for attachment and
+caption metadata. Each `[[figure_attachments]]` row names an example slug,
+cell anchor, paint-function name, and caption; each
+`[[journey_section_figures]]` row names a journey-section title, figure, and
+caption. `src/editorial_registry.py` loads those rows, while
+`src/marginalia.py` owns only executable paint functions and the
+`render_for_anchor` / `render_for_section` renderers.
 
-```python
-# proposed shape — banners keyed by position, each holding 1+ figures
-BANNERS = {
-    "mutability": {
-        "after-cell-0": [
-            ("aliasing-mutation",
-             "Two names share one mutable list — appending through one "
-             "name changes the object visible through both."),
-            ("tuple-no-mutation",
-             "By contrast, a tuple is frozen — aliases share a value "
-             "no method can change in place."),
-        ],
-    },
-}
-```
-
-Banner positions:
-
-| position           | renders                              |
-|--------------------|--------------------------------------|
-| `before`           | once, before the first cell           |
-| `after-cell-0`, …  | once, after cell N (zero-indexed)     |
-| `after-walkthrough`| once, after the last cell             |
-
-Each position is a list, not a single figure: the same banner may hold
-multiple figures as a small multiple. Most slugs will start empty.
-Adding a banner is a one-line edit in `src/marginalia.py`.
+Example-page rendering interleaves each cell with
+`render_for_anchor(slug, "cell-N")`. A registry row may therefore attach one
+or more figures after a teaching cell. Journey pages call
+`render_for_section(section_title)` between a section heading and its list.
+Add or move metadata in the registry; add a `FIGURES` paint function only when
+the diagram itself is new.
 
 ## Authoring model
 
@@ -235,12 +220,14 @@ explicitly. Re-introducing either is a defect.
 - `src/marginalia_grammar.py` — palette, tokens, words, phrases, metrics.
   Aligned with `public/site.css` design tokens; figures use the four
   palette constants and never pick colours directly.
-- `src/marginalia.py` — figure registry (`FIGURES`) and attachment map.
-  Exports `render_for_anchor(slug, anchor)` for the current cell-inline
-  layout; banner-rendering helpers will land alongside.
-- `src/app.py` — `_render_walkthrough_cell` is the current rendering
-  helper; the banner-between rollout will rename or replace it with a
-  walkthrough-level renderer that interleaves cells and banners.
+- `docs/quality-registries.toml` — source of truth for attachments,
+  captions, journeys, and curated editorial scores.
+- `src/editorial_registry.py` — loader for the registry (or its generated
+  Worker fallback).
+- `src/marginalia.py` — executable figure registry (`FIGURES`) plus
+  `render_for_anchor(slug, anchor)` and `render_for_section(title)`.
+- `src/app.py` — `render_example_page` interleaves teaching cells and
+  `render_for_anchor`; `render_journey_page` places section figures.
 - `public/site.css` — `.cell-banner` rules. Production uses the
   banner-between grammar; cells always render with the prose|code
   2-column grid and never receive a `has-figure` class.

public/_headers

@@ -3,7 +3,7 @@
   Referrer-Policy: strict-origin-when-cross-origin
   X-Frame-Options: DENY
   Strict-Transport-Security: max-age=31536000; includeSubDomains; preload
-  Content-Security-Policy: default-src 'self'; base-uri 'none'; object-src 'none'; frame-ancestors 'none'; form-action 'self'; img-src 'self' data:; font-src 'self'; style-src 'self' 'unsafe-inline'; script-src 'self' 'nonce-pbe-inline-v1' https://esm.sh https://challenges.cloudflare.com 'wasm-unsafe-eval'; script-src-attr 'none'; connect-src 'self' https://esm.sh https://challenges.cloudflare.com; frame-src https://challenges.cloudflare.com; worker-src 'self'
+  Content-Security-Policy: default-src 'self'; base-uri 'none'; object-src 'none'; frame-ancestors 'none'; form-action 'self'; img-src 'self' data:; font-src 'self'; style-src 'self' 'unsafe-inline'; script-src 'self' https://esm.sh https://challenges.cloudflare.com 'wasm-unsafe-eval'; script-src-attr 'none'; connect-src 'self' https://esm.sh https://challenges.cloudflare.com; frame-src https://challenges.cloudflare.com; worker-src 'self'
 
 /site.*.css
   Cache-Control: public, max-age=31536000, immutable
@@ -14,6 +14,9 @@
 /editor.*.js
   Cache-Control: public, max-age=31536000, immutable
 
+/runner.*.js
+  Cache-Control: public, max-age=31536000, immutable
+
 /favicon.svg
   Cache-Control: public, max-age=31536000, immutable
 

public/editor.a4a7766e1b9b.js public/editor.3ca30601334a.jspublic/editor.a4a7766e1b9b.js renamed to public/editor.3ca30601334a.js

@@ -17,6 +17,9 @@ if (textarea && form) {
         syntaxHighlighting(defaultHighlightStyle),
         lineNumbers(),
         EditorView.lineWrapping,
+        EditorView.contentAttributes.of({
+          'aria-label': textarea.getAttribute('aria-label') || 'Editable Python example code',
+        }),
         EditorView.updateListener.of((update) => {
           if (update.docChanged) textarea.value = update.state.doc.toString();
         }),
@@ -37,5 +40,5 @@ if (textarea && form) {
   }
 
   form.addEventListener('submit', syncTextarea);
-  window.pythonByExampleEditor = { setValue, syncTextarea };
+  window.pythonByExampleEditor = { setValue, syncTextarea, focus: () => view.focus() };
 }

public/editor.js

@@ -17,6 +17,9 @@ if (textarea && form) {
         syntaxHighlighting(defaultHighlightStyle),
         lineNumbers(),
         EditorView.lineWrapping,
+        EditorView.contentAttributes.of({
+          'aria-label': textarea.getAttribute('aria-label') || 'Editable Python example code',
+        }),
         EditorView.updateListener.of((update) => {
           if (update.docChanged) textarea.value = update.state.doc.toString();
         }),
@@ -37,5 +40,5 @@ if (textarea && form) {
   }
 
   form.addEventListener('submit', syncTextarea);
-  window.pythonByExampleEditor = { setValue, syncTextarea };
+  window.pythonByExampleEditor = { setValue, syncTextarea, focus: () => view.focus() };
 }

public/runner.eddb185f7433.js

@@ -0,0 +1,143 @@
+function initializeRunner() {
+  const textarea = document.getElementById('code-editor');
+  const form = document.querySelector('form.runner-editor');
+  if (!textarea || !form) return;
+
+  const originalCode = textarea.dataset.originalCode ?? textarea.defaultValue;
+  const setCode = (value) => {
+    textarea.value = value;
+    window.pythonByExampleEditor?.setValue(value);
+  };
+
+  const resetButton = form.querySelector('[data-reset]');
+  if (resetButton) {
+    resetButton.addEventListener('click', () => {
+      setCode(originalCode);
+      window.pythonByExampleEditor?.focus();
+    });
+  }
+
+  const hash = new URL(window.location.href).hash;
+  if (hash.startsWith('#code=')) {
+    try {
+      setCode(decodeURIComponent(escape(atob(hash.slice(6)))));
+    } catch (_) {
+      // Ignore malformed share fragments and leave the authored example intact.
+    }
+  }
+
+  const outputPanel = document.querySelector('.output-panel');
+  if (!outputPanel) return;
+  const challengeBox = document.querySelector('[data-turnstile-sitekey]');
+  let turnstileWidgetId = null;
+  let loadingTurnstile = null;
+
+  function loadTurnstile() {
+    if (window.turnstile) return Promise.resolve();
+    if (loadingTurnstile) return loadingTurnstile;
+    loadingTurnstile = new Promise((resolve, reject) => {
+      const script = document.createElement('script');
+      script.src = 'https://challenges.cloudflare.com/turnstile/v0/api.js?render=explicit';
+      script.async = true;
+      script.defer = true;
+      script.onload = resolve;
+      script.onerror = () => reject(new Error('Turnstile failed to load'));
+      document.head.appendChild(script);
+    });
+    return loadingTurnstile;
+  }
+
+  function removeTurnstile() {
+    if (!challengeBox) return;
+    if (window.turnstile && turnstileWidgetId !== null) {
+      try {
+        turnstile.remove(turnstileWidgetId);
+      } catch (_) {
+        try {
+          turnstile.reset(turnstileWidgetId);
+        } catch (_) {
+          // The widget is already gone.
+        }
+      }
+    }
+    turnstileWidgetId = null;
+    challengeBox.hidden = true;
+    challengeBox.innerHTML = '';
+  }
+
+  async function requestTurnstileToken() {
+    if (!challengeBox) throw new Error('Turnstile challenge is not configured');
+    await loadTurnstile();
+    challengeBox.hidden = false;
+    return new Promise((resolve, reject) => {
+      challengeBox.innerHTML = '';
+      turnstileWidgetId = turnstile.render(challengeBox, {
+        sitekey: challengeBox.dataset.turnstileSitekey,
+        execution: 'execute',
+        callback: (token) => {
+          removeTurnstile();
+          resolve(token);
+        },
+        'error-callback': () => {
+          removeTurnstile();
+          reject(new Error('Turnstile challenge failed'));
+        },
+        'expired-callback': () => {
+          removeTurnstile();
+          reject(new Error('Turnstile challenge expired'));
+        },
+      });
+      turnstile.execute(turnstileWidgetId);
+    });
+  }
+
+  function responseErrorMessage(response, body) {
+    if (response.status === 413) {
+      return 'Submitted code is too large (over 100 kB). Trim it and run again.';
+    }
+    const document = new DOMParser().parseFromString(body, 'text/html');
+    return document.querySelector('.output-panel code')?.textContent?.trim()
+      || body.trim()
+      || `HTTP ${response.status}`;
+  }
+
+  async function submitRun(turnstileToken = '') {
+    outputPanel.removeAttribute('data-output-placeholder');
+    window.pythonByExampleEditor?.syncTextarea();
+    outputPanel.querySelector('code').textContent = 'Running in a Dynamic Python Worker…';
+    const formData = new FormData(form);
+    if (turnstileToken) formData.set('cf-turnstile-response', turnstileToken);
+    const response = await fetch(form.action, {
+      method: 'POST',
+      body: new URLSearchParams(formData),
+      headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+    });
+    const html = await response.text();
+    if (!response.ok) throw new Error(responseErrorMessage(response, html));
+    const document = new DOMParser().parseFromString(html, 'text/html');
+    const challengeRequired = document.querySelector('[data-turnstile-required]');
+    if (challengeRequired) {
+      outputPanel.querySelector('code').textContent = challengeRequired.textContent
+        || 'Verification required before running edited code…';
+      return submitRun(await requestTurnstileToken());
+    }
+    const nextOutput = document.querySelector('.output-panel');
+    if (nextOutput) outputPanel.innerHTML = nextOutput.innerHTML;
+  }
+
+  form.addEventListener('submit', async (event) => {
+    event.preventDefault();
+    try {
+      await submitRun();
+    } catch (error) {
+      removeTurnstile();
+      outputPanel.querySelector('code').textContent = `Run failed: ${error.message}`;
+    }
+  });
+}
+
+if (document.readyState === 'loading') {
+  document.addEventListener('DOMContentLoaded', initializeRunner, { once: true });
+} else {
+  initializeRunner();
+}