# A voltage is a difference

A standalone HTML/CSS/JavaScript prototype of an authored, reactive lesson that gradually becomes a retrieval surface. No build step, dependencies, accounts, or API calls. Open `index.html`, or serve the parent `pocs` directory and visit `/voltage/`.

## A short route through it

1. **Between two points.** Drag the voltmeter leads onto nodes, swap them, and move the reference potential. The node labels move; the measured difference stays fixed. Keyboard alternative: choose a probe, then focus and activate a node.
2. **Share a supply.** Drag the underlined numbers—or the source and resistors in the drawing. Arrow keys adjust values; clicking a number opens exact entry. Circuit, prose, equations and potential plot share one numerical model. Hover or focus equation terms to connect representations. Double both resistors to separate current from voltage division.
3. **Walk a loop.** Choose a starting node and direction, then collect signed changes one step at a time. The equation is a record of a path, not a formula appearing out of nowhere. Reverse direction to make the signs meaningful.
4. **Predict a change.** Commit to an expectation before revealing a doubled resistance or supply. Compare the old and new traces. The record distinguishes the initial prediction from later inspection.
5. **Add another path.** Attach a load to the voltage divider. Explore shared branch voltage, unequal currents and output loading. Try the mistaken “subtract every resistor drop” equation and see why it does not describe the selected closed path.
6. **Try without the clues.** Move between worked examples, supported practice and a six-item test. The circuit remains, but computed readings and solutions disappear. Practice misses return with new numbers after two intervening items; test feedback stays hidden until completion.

The practice record identifies the concept, numerical example, response and reopened support. JSON export supports inspection of those events. Only the latest 100 events are kept in browser local storage under `little-worlds-voltage-v1`; reset affects this prototype only. Test exports are disabled until the test is finished. This is a same-session repair queue, not a time-based spaced-repetition scheduler or a mastery estimate.

## What this experiment is testing

- **Authored reactive prose:** numerical controls sit inside meaningful statements, alongside deliberately chosen questions.
- **Linked representations:** a component has a consistent identity across drawing, equation and potential trace.
- **Temporal comparison:** a frozen baseline makes the consequence of one intervention inspectable.
- **Fading support:** the work surface can supply a relationship, supply a hint, or leave it for the learner to retrieve.
- **Contextual review:** subtraction and signed differences reappear inside series circuits, loop traversal and branching rather than living only in isolated drills.
- **Inspectable learning evidence:** an exploration event, a supported answer and a blind prediction are recorded differently.

Characters are short authored prompts, not an LLM dialogue. All chapters remain accessible. A next experiment would add delayed return sessions and explanations in the learner's own words; neither is simulated here.

## Electrical scope

The model is an ideal, steady DC source with two series resistors, optionally loading the lower resistor with a parallel resistor. Units are volts, kilo-ohms and milliamps. It computes the circuit analytically; it is not a general circuit solver. Kirchhoff's voltage law is used for these lumped DC circuits. Time-varying magnetic flux, transients, source impedance and component tolerances are outside this example. Potential diagrams represent electrical potential along a chosen path, not physical height. Rounded displayed terms can differ slightly from their unrounded sum.

## Sources and influences

- Bret Victor, [Explorable Explanations](https://worrydream.com/ExplorableExplanations/): authored reactive documents, linked consequences and explanation through interaction.
- Bret Victor, [Kill Math](https://worrydream.com/KillMath/): direct manipulation and graphical relationships.
- OpenStax, [University Physics Volume 2, 10.3: Kirchhoff's Rules](https://openstax.org/books/university-physics-volume-2/pages/10-3-kirchhoffs-rules): loop reasoning, current conservation and sign conventions.

All dialogue and lesson text here are original. This prototype tests design possibilities; it makes no claim that these interactions establish durable learning.

## Files and validation

`model.js` contains the circuit and question model; `app.js` contains the six scenes, interaction bindings and local record; `style.css` contains responsive and reduced-motion styling. `index.html` is the entry point.

Validation included 647 model and DOM assertions covering reference invariance, reversed probes, loop directions, resistor scaling, loaded-divider conservation, grading, answer masking, practice repair order and the six-item test. Browser checks covered probe dragging, keyboard control, direct resistor dragging, loop traversal and responsive layout.