Explorable
The learner sees the complete mechanism and explanation, then can manipulate the figure or try optional practice. Every number on screen comes from one model function, so the figure, the questions, the film and the checks can't disagree.
Build one
- Quantitative lessons use a checked pure function from parameters to state. Qualitative lessons use a sourced selection/context model. Do not invent measurements for a language or history lesson.
- Write
checks: facts the model must satisfy (limits, symmetries, a known value). They run in the test.
- Draw the figure from the state with
kit (below). Draw the claim, not decoration.
- Write 3 to 7 steps. Each step: one idea, which controls are live, what to look for, an optional check, a margin note, and at least one other way to explain it.
- Build, test, look:
python3 scripts/build.py assets/examples/seasons.lesson.js -o seasons.html # one file, opens anywhere
node scripts/test_lesson.mjs seasons.html # drives every step in Chromium
node scripts/check_code.mjs lesson.js --include course.model.js # structural check; does not execute authored code
node scripts/check_code.mjs lesson.js --include course.model.js --trust-authored-code # only after reviewing/trusting every input
node ../visual-qa/scripts/check_page.mjs seasons.html --eval "window.__explorable.check()"
Use --fragment when publishing to a host that wraps pages (Claude artifacts). Open the screenshots before showing the learner anything.
test_lesson.mjs, check_page.mjs, narration, and bundle_lesson.mjs load the
lesson in Chromium and execute its JavaScript. Run them only for a lesson and
includes you have reviewed and chosen to trust. Chromium is part of the render
pipeline, not a hostile-code sandbox; use the bundled checker sandbox or an external restricted environment for
third-party material.
The lesson file
window.LESSON = {
id: "seasons-v1", title: "Why seasons happen", subtitle: "...", subject: "Earth science", level: "...",
params: { day: { label: "Date", min: 1, max: 365, step: 1, value: 172, fmt: (v) => "21 Jun" } },
model: (p) => ({ elev: ... }), // pure; the single source of truth
readouts: (s, p) => [["noon sun", `${s.elev.toFixed(0)}°`]],
figure: {
viewBox: (narrow) => (narrow ? "0 0 340 690" : "0 0 700 360"), // or a string
label: (s, p) => "A sentence describing what the figure shows right now",
draw(g, s, p, kit) { /* kit.el, kit.mark, kit.hand, kit.ink, kit.seed, kit.group, kit.narrow */ },
},
steps: [{
id /* optional, stable */, title, say /* HTML */, set: { day: 172 }, controls: ["day"], lookFor: "...",
ask: { kind: "choice", q, options: [...], answer: 2, hint, why }, // or kind: "number", answer: (p, s) => n, tol, unit
// options show in a shuffled order (fixed per question; all-number options stay sorted; keepOrder: true opts out).
// Add needsFigure: true when q can't be answered without the figure (a course's "Quiz me" leaves it out).
note: "the margin note this step earns",
alts: [{ label: "A torch on a table", say: "...", set: { ... } }],
}],
film: [{ chapter, say, set }], // optional; defaults to one scene per step
misconceptions: [...], deeper: [...], checks: [{ name, test: (model) => bool }],
};
kit.mark(ink.arrow(...), { tone: "red" }) and kit.hand(x, y, "text", { tone: "blue" }) draw in the coach's hand; the pen animates them when a step opens and redraws instantly when a slider moves. kit.group("translate(...)") returns a kit for a sub-panel, which is how a figure rearranges itself when kit.narrow is true.
More lesson fields
hook: HTML shown above step 1 under "Why this mattered": the stakes or the story (who needed this, what broke without it). Short.
code: { title, cpp, python, stdin(params), expect(params), cases: [params...] }. Mark lines with a trailing //@id (C++) or #@id (Python). A step with line: "id" (or line: (p, s) => "id") shows the panel with that line lit. The Code tab shows the whole program; Python runs in the browser (Pyodide, in a Web Worker with a Stop button and a 10 s limit, so an endless loop never freezes the lesson) where the host allows it, and every panel shows what the model says the program prints for the current inputs. The default check_code.mjs invocation is structural and reports code as unverified. Only after reviewing every lesson/include, pass --trust-authored-code to compile and run both languages. For third-party executable examples, use --sandbox --sandbox-image sha256:...; see sandbox setup.
ask: { kind: "explain", q, model, points: [...] }: the learner writes the idea in their own words first, then sees the teacher's version and ticks the key points they covered. The text goes into the report so the teacher can correct it.
- Shared course code: put the model in one file that sets
window.Something and build with --include course.model.js (also for check_code.mjs).
figure.narrowText: text scale on narrow screens (default 1). Raise it until visual-qa stops flagging figure text under 11px.
- Readout labels are set in capitals. When case carries meaning (
|a| against |A|), give the row a third item: ["|a|", "5", { keepCase: true }]. Long values wrap on phones.
Every page also has: "Or see it as a film / code" under "Still confused?", a "Questions to chase" list in the margin that goes into the report, Board (auto/paper/chalk) and Sound buttons.
What the page does
- Layout: contents, lesson, margin notes, kept apart, with Film and "Notes and report" as their own tabs. Progress, answers and notes stay ephemeral unless the learner checks "Remember progress on this device". Withdrawing it removes this page's local progress and consent key; it cannot erase exported or externally copied records. The page works when storage is blocked. Saved progress is matched to steps by key (the step's
id, else its title and question), so a step that is inserted, removed or moved never inherits another step's answers; give steps an id if you expect to reword them.
- Questions: Next is always available in the default explanation style. Optional practice lives in a closed detail after the explanation. Only explicitly requested practice locks Next until the question is resolved or shown. A miss gets the hint. A second miss, or "Show me", teaches it directly. Every attempt is recorded.
- "Still confused? Try another way": cycles through
alts, changing the representation, example or analogy, and records which ones were tried.
- Film: the same figure, eased between each scene's parameters, with captions, play, pause, scrub, chapters, speed and a transcript (the human-sounding voice is in the narrated video:
scripts/narrate.py).
- The end isn't a score. "Where to next?" offers: got it, go deeper, another example, explain it differently, practise. Then a plain-text report (steps, misses, explanations tried, notes, choice) the learner copies back to the teacher, so the next session fits them.
- Chalkboard toggle, keyboard control of the film, reduced motion, phone layout.
Rules
- Every visual explains something. The step's
say states the claim, lookFor says where to look, and the figure's label says it in words.
- Explain first. Attempt-first applies only to
style: "practice-first" or ?practice=1 after an explicit learner request. ?practice=0 exits it.
- One idea per step. If a step needs two sliders and three paragraphs, split it.
- Numbers come from the model, never typed into the figure by hand.
alts must change one thing (the example, the representation, the granularity or the analogy), not repeat the same explanation louder.
- Phone first: test the narrow layout.
visual-qa fails figure text under 11px as drawn.
Examples: assets/examples/seasons.lesson.js (Earth science, no code).
Six formats from one lesson
Add sources: [{title, url, note}] and an honest limits statement to source-grounded lessons. After reviewing the executable lesson, build the explorer, render narrated video, then use node scripts/bundle_lesson.mjs explorer.html --out output --video lesson.mp4 --timing lesson.timing.json. The exporter produces editable still/PNG, Q&A, cards, static fallback and interactive video. Real video and matching timing/captions are required for the video explorer; missing media is not silently labelled complete.
1---2name: explorable3description: Build an interactive lesson where one executable model drives every view, a figure the learner manipulates, live readouts, optional practice questions, a narrated film, margin notes and a report back to the teacher. Complete explanation first, with immediate controls; attempt-first only for explicitly requested practice. One hint after a miss, taught directly after a second, and a "still confused?" button that swaps in a different explanation and records what was tried. Use for any "teach me X" where something can be varied, in any subject. Builds to one self-contained HTML file in the lesson-notebook style.4metadata:5 source: https://skillmd.com/skills/praxstack/explorable6---78# Explorable910The learner sees the complete mechanism and explanation, then can manipulate the figure or try optional practice. Every number on screen comes from one model function, so the figure, the questions, the film and the checks can't disagree.1112## Build one13141. Quantitative lessons use a checked pure function from parameters to state. Qualitative lessons use a sourced selection/context model. Do not invent measurements for a language or history lesson.152. Write `checks`: facts the model must satisfy (limits, symmetries, a known value). They run in the test.163. Draw the figure from the state with `kit` (below). Draw the claim, not decoration.174. Write 3 to 7 steps. Each step: one idea, which controls are live, what to look for, an optional check, a margin note, and at least one other way to explain it.185. Build, test, look:1920```sh21python3 scripts/build.py assets/examples/seasons.lesson.js -o seasons.html # one file, opens anywhere22node scripts/test_lesson.mjs seasons.html # drives every step in Chromium23node scripts/check_code.mjs lesson.js --include course.model.js # structural check; does not execute authored code24node scripts/check_code.mjs lesson.js --include course.model.js --trust-authored-code # only after reviewing/trusting every input25node ../visual-qa/scripts/check_page.mjs seasons.html --eval "window.__explorable.check()"26```2728Use `--fragment` when publishing to a host that wraps pages (Claude artifacts). Open the screenshots before showing the learner anything.2930`test_lesson.mjs`, `check_page.mjs`, narration, and `bundle_lesson.mjs` load the31lesson in Chromium and execute its JavaScript. Run them only for a lesson and32includes you have reviewed and chosen to trust. Chromium is part of the render33pipeline, not a hostile-code sandbox; use the [bundled checker sandbox](references/SANDBOX.md) or an external restricted environment for34third-party material.3536## The lesson file3738```js39window.LESSON = {40 id: "seasons-v1", title: "Why seasons happen", subtitle: "...", subject: "Earth science", level: "...",41 params: { day: { label: "Date", min: 1, max: 365, step: 1, value: 172, fmt: (v) => "21 Jun" } },42 model: (p) => ({ elev: ... }), // pure; the single source of truth43 readouts: (s, p) => [["noon sun", `${s.elev.toFixed(0)}°`]],44 figure: {45 viewBox: (narrow) => (narrow ? "0 0 340 690" : "0 0 700 360"), // or a string46 label: (s, p) => "A sentence describing what the figure shows right now",47 draw(g, s, p, kit) { /* kit.el, kit.mark, kit.hand, kit.ink, kit.seed, kit.group, kit.narrow */ },48 },49 steps: [{50 id /* optional, stable */, title, say /* HTML */, set: { day: 172 }, controls: ["day"], lookFor: "...",51 ask: { kind: "choice", q, options: [...], answer: 2, hint, why }, // or kind: "number", answer: (p, s) => n, tol, unit52 // options show in a shuffled order (fixed per question; all-number options stay sorted; keepOrder: true opts out).53 // Add needsFigure: true when q can't be answered without the figure (a course's "Quiz me" leaves it out).54 note: "the margin note this step earns",55 alts: [{ label: "A torch on a table", say: "...", set: { ... } }],56 }],57 film: [{ chapter, say, set }], // optional; defaults to one scene per step58 misconceptions: [...], deeper: [...], checks: [{ name, test: (model) => bool }],59};60```6162`kit.mark(ink.arrow(...), { tone: "red" })` and `kit.hand(x, y, "text", { tone: "blue" })` draw in the coach's hand; the pen animates them when a step opens and redraws instantly when a slider moves. `kit.group("translate(...)")` returns a kit for a sub-panel, which is how a figure rearranges itself when `kit.narrow` is true.6364### More lesson fields6566- `hook`: HTML shown above step 1 under "Why this mattered": the stakes or the story (who needed this, what broke without it). Short.67- `code`: `{ title, cpp, python, stdin(params), expect(params), cases: [params...] }`. Mark lines with a trailing `//@id` (C++) or `#@id` (Python). A step with `line: "id"` (or `line: (p, s) => "id"`) shows the panel with that line lit. The Code tab shows the whole program; Python runs in the browser (Pyodide, in a Web Worker with a Stop button and a 10 s limit, so an endless loop never freezes the lesson) where the host allows it, and every panel shows what the model says the program prints for the current inputs. The default `check_code.mjs` invocation is structural and reports code as unverified. Only after reviewing every lesson/include, pass `--trust-authored-code` to compile and run both languages. For third-party executable examples, use `--sandbox --sandbox-image sha256:...`; see [sandbox setup](references/SANDBOX.md).68- `ask: { kind: "explain", q, model, points: [...] }`: the learner writes the idea in their own words first, then sees the teacher's version and ticks the key points they covered. The text goes into the report so the teacher can correct it.69- Shared course code: put the model in one file that sets `window.Something` and build with `--include course.model.js` (also for `check_code.mjs`).70- `figure.narrowText`: text scale on narrow screens (default 1). Raise it until `visual-qa` stops flagging figure text under 11px.71- Readout labels are set in capitals. When case carries meaning (`|a|` against `|A|`), give the row a third item: `["|a|", "5", { keepCase: true }]`. Long values wrap on phones.7273Every page also has: "Or see it as a film / code" under "Still confused?", a "Questions to chase" list in the margin that goes into the report, Board (auto/paper/chalk) and Sound buttons.7475## What the page does7677- Layout: contents, lesson, margin notes, kept apart, with Film and "Notes and report" as their own tabs. Progress, answers and notes stay ephemeral unless the learner checks "Remember progress on this device". Withdrawing it removes this page's local progress and consent key; it cannot erase exported or externally copied records. The page works when storage is blocked. Saved progress is matched to steps by key (the step's `id`, else its title and question), so a step that is inserted, removed or moved never inherits another step's answers; give steps an `id` if you expect to reword them.78- Questions: Next is always available in the default explanation style. Optional practice lives in a closed detail after the explanation. Only explicitly requested practice locks Next until the question is resolved or shown. A miss gets the hint. A second miss, or "Show me", teaches it directly. Every attempt is recorded.79- "Still confused? Try another way": cycles through `alts`, changing the representation, example or analogy, and records which ones were tried.80- Film: the same figure, eased between each scene's parameters, with captions, play, pause, scrub, chapters, speed and a transcript (the human-sounding voice is in the narrated video: `scripts/narrate.py`).81- The end isn't a score. "Where to next?" offers: got it, go deeper, another example, explain it differently, practise. Then a plain-text report (steps, misses, explanations tried, notes, choice) the learner copies back to the teacher, so the next session fits them.82- Chalkboard toggle, keyboard control of the film, reduced motion, phone layout.8384## Rules8586- Every visual explains something. The step's `say` states the claim, `lookFor` says where to look, and the figure's label says it in words.87- Explain first. Attempt-first applies only to `style: "practice-first"` or `?practice=1` after an explicit learner request. `?practice=0` exits it.88- One idea per step. If a step needs two sliders and three paragraphs, split it.89- Numbers come from the model, never typed into the figure by hand.90- `alts` must change one thing (the example, the representation, the granularity or the analogy), not repeat the same explanation louder.91- Phone first: test the narrow layout. `visual-qa` fails figure text under 11px as drawn.9293Examples: `assets/examples/seasons.lesson.js` (Earth science, no code).9495## Six formats from one lesson9697Add `sources: [{title, url, note}]` and an honest `limits` statement to source-grounded lessons. After reviewing the executable lesson, build the explorer, render narrated video, then use `node scripts/bundle_lesson.mjs explorer.html --out output --video lesson.mp4 --timing lesson.timing.json`. The exporter produces editable still/PNG, Q&A, cards, static fallback and interactive video. Real video and matching timing/captions are required for the video explorer; missing media is not silently labelled complete.