--- name: explainer-studio description: "Build premium interactive 3D explainers: one procedural three.js page that teaches ONE idea through chapters, camera views, a console of controls, exact live numbers, and an honest write-up. Use this skill whenever the user asks for an interactive explainer, a 3D lesson, a visual simulation of a concept, a sael.net-style explainer, an educational three.js scene, or a kid-friendly interactive model of math, science, civics, or how a machine works, even if they never say 'explainer'. Read it before writing PLAN.md or any scene code. Pair it with explainer-assets-gpu when the explainer needs generated textures, CAD parts, narration, presenter video, baked simulation data, or preview clips." --- # Explainer Studio An explainer is a teaching instrument, not a demo reel. The learner should be able to change one thing, watch the model respond, read the exact number that changed, and then read a short, honest account of what was real, what was calculated, and what was drawn only to illustrate. **Inspiration and credit.** The bar comes from Ryan Sael's free interactive explainers at `https://sael.net/explainers`. Treat them as a style reference ONLY. You NEVER copy their code, text, names, chapter structures, or layouts, and you never name an explainer after one of his. Credit him as the inspiration when the user publishes a collection built with this skill. ## The quality bar These numbers come from profiling twelve sael.net explainers live in Chromium (fraction-kitchen, heart-pump, soap-bubble, periodic-table, internet, electricity, river-bend, earthquake-tower, plane-of-focus, flatpack, pendulum-rhythm, lightning-path). Every one was procedural three.js, and that is the default here. - **Procedural first.** Geometry, materials, skies, and motion are generated in code. Total transfer for the page is **under 1 MB** (the profiled set ran 0.3 to 0.9 MB). No glTF/GLB models, no HDR/EXR environment maps, no KTX2 textures, no WASM physics, no Gaussian splats, unless the `explainer-assets-gpu` skill's budget rules justify one specific asset and PLAN.md records why. - **Runtime is the viewer's own GPU through WebGL.** No server, no network after load. three.js is vendored next to the page (current releases' `build/three.module.js` imports `./three.core.js`, so ship both, plus each addon you use); never load it from a CDN. - **Media is small.** The only video is a short muted preview clip (about 25 to 260 KB) and a poster image. - **The structure is complete.** At least 3 chapters, at least 2 camera views plus a cinematic toggle, a slim console (chapter tabs, sliders, +/- steppers, live readouts, a replay action), keyboard shortcuts with a `?` help list, toggleable floating labels, a short themed loading line, and a write-up drawer with the honesty sections below and a "these are simplified models" line. `references/quality-bar.md` has the full checklist used to grade a finished explainer. ## Workflow 1. **Plan first.** Write `PLAN.md` with every section in the next list before any scene code. Show it to the user and build only once it is complete and, when a user is present, approved. A plan with a missing section is not a plan. 2. **Pure math module first.** Write the exact-math module and its self-test before the scene (see Exact math). 3. **Skeleton.** Renderer, sky, lights, ground, camera presets, the console shell, the state object, the loading line. Verify it renders with zero console errors before adding chapters. 4. **One chapter at a time.** Build, then verify that chapter (screenshot, readouts, keyboard path) before starting the next one. 5. **Write-up.** Fill the drawer from the plan's honesty table; every sentence must be true. 6. **Verify and report** (see Verification). "It should work" is not a report. ## PLAN.md sections (all required) 1. **Goal**: one sentence naming the single idea the learner leaves with. 2. **Audience and levels**: ages, prior knowledge, and what changes between a younger and an older level. 3. **The idea and misconceptions**: the core insight and the two or three wrong ideas the scene must break. 4. **Chapters**: for each, what the learner does, what the scene shows, which readouts change, and the success check that ends it. 5. **Views**: named camera presets, what each is for, and the cinematic camera's path. 6. **Console and keyboard map**: every control with its label, range, step, default, and key. 7. **Math model**: the exact number types, every formula, edge cases (zero, maximum, invalid input), and the self-test cases. 8. **Honesty table**: real, calculated, drawn to illustrate, simplified, one row per claim. 9. **Look**: palette (one accent colour per concept), lighting, camera, typography. 10. **Accessibility**: keyboard paths, live regions, text alternatives, reduced-motion behaviour. 11. **Performance budget**: transfer size, draw calls, instance counts, target frame rate. 12. **Assets**: "none" by default; otherwise each asset with its source, size, and the budget rule it meets. 13. **Kid safety**: required when the audience includes children. 14. **Verification plan**: the exact screenshots, checks, poster frames, and clip you will produce. 15. **Out of scope**: what this explainer deliberately does not teach. A complete worked example is in `references/sample-plan.md`; a matching build prompt is in `references/sample-build-prompt.md`. ## Scene, lighting, and camera - **Sky and fog:** a large inside-out sphere with a two- or three-stop gradient shader (`depthWrite: false`), and `scene.fog` set to the horizon colour so the ground melts into the sky. Dusk palettes read well: a warm horizon under a deep blue zenith. - **Lighting:** a `HemisphereLight` for soft fill plus ONE shadow-casting `DirectionalLight` whose shadow camera is fitted tightly to the stage. ACES filmic tone mapping, sRGB output. Avoid more than three lights. - **Ground:** a large disc or plane with a subtle radial fade; the subject sits on a low plinth or table so it has a place in the world. - **Camera:** `OrbitControls` with damping, a clamped polar angle (never under the ground), and min/max distance. Presets ease position and target together over about 0.8 s. The cinematic camera is a slow orbit or dolly that ANY user input cancels. - **Materials:** `MeshStandardMaterial` with restrained roughness and metalness. The accent colour of a concept is the same in the scene, the label, and the readout that names it. Copy-ready, original recipes (renderer setup, the sky shader, light rig, presets with easing, labels, instancing, the visibility pause) are in `references/scene-recipes.md`. ## The console, chapters, and views - **One state object** drives the scene, the console, and the readouts. Serialize it to the URL hash so any state, and therefore any screenshot, is reproducible. - **Chapters** (tabs, keys `1` to `9`) each own a scene state, a one-line caption, and a goal. Switching tweens; it never snaps, except under reduced motion. - **Controls** each have a visible label, a range, a step, a keyboard path, and a readout that updates on every change. Steppers move by exactly one step; sliders snap to steps so values stay exact. - **Views** (named buttons, key `V` to cycle, `C` for cinematic) move only the camera, never the model. - **Polish:** `?` toggles the shortcut list, `L` toggles floating labels, `R` replays the current chapter, and the loading line is short and themed ("Warming up the gem carts..." style, in your own words). ## Exact math - Use integers and rationals: integer or `BigInt` numerator and denominator, reduced by gcd, sign on the numerator, comparison by cross-multiplication, lcm for common denominators. - NEVER display a binary float. `0.1 + 0.2` must never reach the screen. Terminating decimals are printed exactly from the rational; any rounded value is shown with an approximately-equals sign and its precision. - Real-world constants carry units and a source in the write-up; if you are unsure of a fact, leave it out. - The math lives in a pure module with a self-test table that runs in a `?selftest` mode and under `bun test`. `references/exact-math.md` has an original rational type, mixed numbers, exact decimal expansion with repeating cycles, and a long-division stepper. ## The honesty write-up The drawer is plain language at the audience's reading level, with these sections in this order: **How it works**, **The idea**, **Worked examples** (with the exact arithmetic), **What's real**, **What's calculated**, **What's drawn to illustrate**, **What's simplified**, **Controls**, and the closing line that the scene uses simplified models. Scale is the most common lie in a 3D scene: if sizes or distances are not to scale, say so and give the real figures. ## Accessibility and reduced motion - Semantic `