# Chain Reaction Builder: research and model boundaries

Updated 20 October 2026. The user approved moving to this app after Evolution Sandbox. This page separates source-backed ideas, design predictions and the rules of our illustrative model.

## Sources → decisions

- [Exploratorium Tinkering Studio: Chain Reaction activity guide](https://www.exploratorium.edu/sites/default/files/tinkering/files/Instructions/chainreaction_guide_final_-_screen.pdf) recommends simple starting examples, predictions before a run, frequent testing and revisions based on observations. It treats breakdowns as part of building rather than assuming a perfect first attempt. **Decision:** provide bounded starter challenges, a prediction prompt, a recorded contact sequence and a one-change-at-a-time repair workflow. Our missing-link experiment makes an interrupted chain a useful result. The guide informs the interaction; no artwork, contraptions or instructional text is copied.
- [PhET: Pendulum Lab](https://phet.colorado.edu/en/simulations/pendulum-lab/) identifies experiments about variables affecting period and the relationship between position, speed and mechanical energy as learning goals. **Decision:** let learners vary pendulum length and release angle separately and inspect timed contacts and ball speed. Our simpler pendulum and collision model does not implement PhET's energy instrumentation or establish numerical equivalence to its simulation.
- [OpenStax: University Physics, Rotational Variables](https://openstax.org/books/university-physics-volume-1/pages/10-1-rotational-variables) relates tangential speed to radius and angular speed, `v = rω`, and gives the perpendicular direction of surface motion. **Decision:** use the prescribed motor speed and contact radius to calculate moving-surface velocity. Label rim speed separately from measured ball speed. Increasing radius at the same angular speed increases rim speed; it does not guarantee the same increase in ball speed. This relation does not validate our simplified friction or collision response.

These sources provide educational precedents. They do not validate our collision constants, computed outcomes or educational effectiveness.

## Design predictions

**Prediction:** a familiar marble-run workbench, readable 3D parts and short explanations tied to actual events will help children connect one contact to the next. A separate 2D view keeps placement and direction easy to inspect. A contact log and speed/height history should also help an experienced experimenter locate an interrupted sequence. These are hypotheses requiring learner testing, not measured improvements.

Both views represent one planar model. Rotating the 3D camera changes the view; it does not add sideways movement or a third physics dimension. Brand orange indicates actions and selection. Part colours and labels may distinguish roles.

| Experiment | One change to try | Prediction to test | Evidence or counterexample |
| --- | --- | --- | --- |
| Marble delivery | One ramp angle | Its exit direction may change the next contact or arrival. | Compare trail, recorded contacts and arrival time. A steeper ramp need not deliver the ball to the goal. |
| Pass it along | One domino spacing | A falling tip may or may not reach the next tile. | Compare fallen count and first remaining upright tile. The chain does not jump an unreachable gap. |
| Motor-powered delivery | Stop or reverse the wheel motor | The same route may deliver, stall or send the ball the other way. | Compare contact measurements and goal entry with identical placement. A spinning untouched wheel cannot push the ball. |
| The missing link | Move or add one tile at the gap | Repairing the contact path may extend the chain. | Compare the last falling tile before and after the edit; downstream success is not promised. |
| The playground swing | One release angle or pendulum length | The timing and location of a ball–bob meeting may change. | Inspect actual contact events and subsequent motion, including a complete miss. |
| A glide in space | Gravity, keeping the launch unchanged | Before contact, zero gravity preserves velocity; positive gravity changes its vertical component. | Check the trail and velocity. A resting ball remains at rest without a push; zero gravity does not create energy. Boundaries and powered parts can still affect it. |

## What is calculated

Read `model.js` as the implementation authority. This is a toy planar mechanism model, not an engineering dynamics solver.

- The workbench is 1000 × 600 model pixels, with its floor at Y = 580. Positive X points right and positive Y points down. Speed is in px/s, gravity in px/s² and simulated time in seconds. Pixel units have no defined metre conversion. Height is measured above the floor, not absolute elevation.
- Numerical integration uses small 1/240-second steps. Playback pacing must not be presented as a physical parameter or a CPU benchmark. Repeated runs should use the same initial design and inputs for a controlled comparison.
- There is one ball with fixed model mass, position, radius and velocity. It accelerates under gravity. It has no simulated angular momentum, rolling inertia or spin energy. The 3D ball's appearance cannot establish those quantities.
- Ramps and boundaries remain fixed. Contacts resolve overlap and change velocity using approximate restitution and damping. Mechanical energy can dissipate; total-energy conservation must not be claimed for the whole toy machine.
- Dominoes rotate about anchored bases. Gravity acts on a lean, and a falling tip must geometrically reach an upright neighbour before the approximate tipping rule starts it. Their transfer is not a solved rigid-body impact; dominoes cannot slide or accumulate into a physical pile. The fallen counter uses a lean greater than 0.8 radians (about 46°), not a claim that a tile is flat.
- Powered wheels hold a prescribed angular speed. Roller mode uses a circular contact surface with tangential grip. Paddle mode uses a central hub and six rotating physical contact arms; gaps between arms remain open. Surface velocity uses angular speed and contact radius, and grip controls tangential velocity transfer. Decorative roller marks are not separate collision teeth. Wheels do not mesh or turn one another, and there is no transmission-ratio, motor-load or torque model. Motor contacts may add energy supplied from outside the machine. The app does not measure motor work, so it cannot report full-machine efficiency.
- A pendulum has a fixed anchor and length, gravitational angular acceleration and damping. Only its bob collides with the ball. The cord is not a physical collision surface; pendulum motion remains planar. Ball–bob impulse transfer is simplified.
- Other authored-part collisions are not general-purpose rigid-body collisions. The ball can meet ramps, dominoes, motor wheels and pendulum bobs; domino tip-to-tile propagation is the special additional interaction. Overlapping ramps, gears and pendulums do not push one another.
- A goal is a detection rectangle. Success is recorded when the ball's centre enters it, not when its entire outline fits, and the goal does not physically catch the ball. A completion record is historical even if the ball subsequently leaves the rectangle.
- Speed and height charts show ball state, not energy. The general contact count is the number of distinct touched surfaces, not a count of every impact. The log retains the first contact per surface, the first fallen-threshold crossing per domino and the first goal entry per target; repeated bounces on the same surface are not logged again. The separate motor readout counts continuous ball–wheel contact episodes and records entry speed, latest outgoing speed, and their signed difference. That difference includes the complete contact response; it is not isolated motor work, energy gain or force. Guidance must distinguish a recorded contact from a prediction or an untested causal explanation.
- Builds are bounded for stable interactive use. Rejection or clamping of unsupported values should be visible. A build saved before running is a starting design, not automatically a resumable dynamic checkpoint.

## Learning and regression checks

The pure `ChainLearning` library supplies six experiment descriptions, explanations for all six selectable part types and current-run guidance. It must describe fresh/build state honestly, report success only from recorded state, use actual fallen counts and event times, explain powered wheels, and handle zero gravity without inventing motion or energy. Pausing must change the label without inventing a new event. Explanations must not mutate the simulation.

Model checks should cover unchanged repeated runs, fixed-step batching, simple gravity/free-flight cases, boundary response, static-ramp contact, finite values, goal entry, domino contact propagation and unreachable gaps, pendulum contacts, motor direction, validation and persistence. Do not use this list as a claim that every check has passed.

Browser review should cover building and selecting each part in both views, camera recovery, keyboard placement, pause/step/restart, predictable edits, presets, save/load, displayed event/state values and chart history. Check light and dark themes and phone/tablet/desktop layouts. Preserve useful DOM controls and a 2D fallback when WebGL is unavailable. Record verified results separately after implementation.

## Verified implementation — 20 October 2026

- All 52 automated checks passed: 22 model checks, 19 learning checks and 11 scene checks. The shared Lab catalog checks also passed for app routes, local references, workers and unique page IDs.
- The controller stops at the first goal-entry physics step. Tests compare that exact terminal state at 30, 60 and 144 display frames per second with quarter, half, normal and double playback pace. The underlying model can continue after a goal when this optional controller setting is not used.
- Browser review confirmed a completed marble delivery, a pendulum contact at 1.18 seconds followed by goal entry at 3.53 seconds, and the missing-link experiment stopping at 6 of 12 fallen dominoes. The exact-measurement table refreshed during playback; changing between views preserved the paused state.
- Verified direct 3D dragging, part addition, numeric Apply values, undo/redo, camera fitting, a retained comparison trace, CSV export feedback and loading an older plain-design save. The existing saved build was not overwritten during review. The temporary comparison trace used for testing was cleared.
- Reviewed light and dark themes, desktop, 390-pixel phone, 820-pixel tablet and 844-by-390 landscape layouts. These viewports had no horizontal page overflow. Browser review ended with no captured warnings or errors.
- These are implementation checks, not a learner study or a validation for professional engineering calculations. Physics remains planar; the 3D view adds depth and camera movement to the same model.

### Selected-part popup

Added a movable editor inside both views, with shared validated component fields and explicit Apply. Ball launch speed and direction are also available there. The editor does not pause or reset a run merely by opening; applying a change resets to the starting design and supports undo. New parts open their settings immediately. Close/Escape returns focus to the scene.

Browser checks covered 3D click selection and dragging, 2D editing, ball speed/direction, ramp slope/length, pendulum angle/mass, motor direction, goal/domino fields, invalid-value feedback, duplicate/remove, undo, Escape and retained drafts through playback. Reviewed both themes and a 390-pixel phone: the popup stays within the scene, its body scrolls, action buttons remain available and the page has no horizontal overflow. All 52 existing checks and the shared catalog checks passed. The user's separate active build was left untouched during preview testing.

## Direct manipulation tools — 20 October 2026

The viewer now includes Select, Move, Rotate, Scale and Transform tools. The 3D view projects axis handles and a rotation ring onto the existing physics plane. The 2D blueprint uses a selection box with resize handles and a rotation control. Both edit the same starting design. Add, exact Values, Undo/Redo, Fit, fullscreen, Snap, Run and Reset are available inside the viewer.

One completed drag creates one undo step; Escape cancels the active gesture. Camera movement and viewport resizing reposition the handles. Snapping uses 10 model pixels for translation and 15 degrees for rotation. Shift preserves proportions when resizing. Fixed-anchor parts expose only meaningful resize directions; boundary constraints can shift a pivot to keep the entire part on the board. The ball uses launch direction instead of orientation, and goals remain axis-aligned to match detection. Rotating a pendulum changes its release angle. Wheel phase is retained through restart. It does not change circular roller contact geometry or motor speed, but it changes the initial arm positions in paddle mode. These controls do not add a third physics dimension.

All 68 checks passed: 23 model, 19 learning, 14 scene and 12 transform checks. Syntax checks passed. Browser review verified axis-constrained movement, rotation, 2D resizing with Undo/Redo, in-view part addition, keyboard mode switching and fullscreen. Desktop and phone layouts were inspected, and both themes were checked. The user's separate active build was preserved. Existing catalog checks remained passing.

## Powered wheel rework — 20 October 2026

**Problem:** the old wheel spun visibly but gave too little help in a typical build, and its starter route did not clearly demonstrate a useful motor action. Calling the object a gear also implied meshing that the model does not support.

**Design prediction:** a working conveyor-style delivery starter, a choice of gripping roller or physical paddles, direction and grip controls, and a readout placed with the selected wheel will make the motor's role easier to test. A stopped/reversed comparison should show that placement and contact direction matter as well as motor speed. This is a design hypothesis, not a measured learning outcome.

The renamed Powered wheel has two contact geometries. Roller mode transfers motion along its rim; paddle mode can catch and strike the ball with six rotating arms. Grip is a bounded model response setting from 0 to 1, not a measured material coefficient. The motor maintains its configured angular speed rather than solving drive torque or stalling under load. Ball spin, bearing losses and a general gear train remain outside this model.

The Motor-powered delivery starter begins with a stationary ball above a roller. With the wheel at +5 rad/s, its 55-pixel radius gives a prescribed rim speed of 275 px/s. A model check recorded the first contact leaving at 214.10 px/s and goal entry at 2.2375 s. With the same build and speed zero, the ball stayed above the wheel and did not reach the goal in 20 s. With speed −5 rad/s it initially travelled the other way and also did not reach the goal within 20 s. These are specific starter outcomes, not guarantees for edited builds or perpetual claims about a reversed run.

`motorReadout` distinguishes configured speed from measured contact results. A fresh build ignores any previous run's telemetry. Until contact is recorded, its speed-change value is absent rather than a fabricated zero or boost. During or after contact it can report faster, slower or almost unchanged ball speed. Pausing preserves the measurements. The readout explicitly attributes speed change to the whole contact, not motor work.

The 27 learning checks passed, including eight new checks for signed RPM, rim-speed calculation, fresh-run isolation, absent-contact behavior, actual contact measurements, slowing/zero change, safe empty data and immutability. The three starter comparisons above were also run directly against the model. Browser verification of this rework is recorded separately after integration; earlier browser results above do not establish the new controls' behavior.

Integration verification: all 87 checks passed (31 model, 27 learning, 17 scene, 12 transform), plus syntax and shared catalog checks. Browser testing confirmed goal entry at 2.24 seconds in the motor starter, paddle contact and speed measurements in 2D, actual paddle geometry in 3D, popup mode/grip edits, reversal and Undo, and off/on restoration of the previous 5 rad/s speed. Reverse is disabled while stopped. The ball-placement helper resets launch speed and is undoable; it makes room near board edges if necessary. Desktop layouts were reviewed in light and dark themes, and the 390-pixel phone layout in dark theme; these checks showed no horizontal overflow. The phone editor scrolls its fields and keeps Apply/Close available. Existing user tabs and saved builds were left unchanged.

## Logic and touch audit — 21 October 2026

### Predictions tested

- A resting ball that merely touches a domino while moving away cannot push it. Only an approaching contact (negative relative normal speed) can start a tip. Counterexample checked: the same ball moving toward the tile still topples it.
- A tipping domino transfers its push only to a tile on the side it is falling towards. Counterexample checked: wide, closely spaced tiles previously sent a "backwards" push to the tile behind a falling one, so that tile fell into the falling tile.
- Passive parts (ramps, pendulum bobs, floor and walls) can only dissipate the combined ball + pendulum mechanical energy. Powered wheels and the stored potential energy of upright dominoes are the only sources.

### Model changes

- Ball → domino start condition now also requires `approach < 0`. The tipping direction and initial angular speed are unchanged.
- Domino → domino propagation now skips tiles whose centre is not on the falling side (`sign(n.x − a.x) = sign(a.angle)`). All six starter machines produce the same outcomes as before.

### Verified results

- Random passive builds (80 in the test suite, 300 in the audit probe): after the first step, total ball + pendulum energy never rose above its starting value. The only earlier rises came from a ball placed overlapping a part, which the first step pushes out. This is a setup artefact, not a dynamic energy gain.
- Starter machines give identical ball, part, event and sample state at 30 Hz, 60 Hz and irregular frame times.
- Save envelopes survive a JSON round trip and replay identically. File export and import use the same validated `chain-build` v2 envelope as browser saving. The stored key and format are unchanged; only an optional `savedAt` time is added.
- Browser: tapping to place a part works in both views. The 2D blueprint now places on release, as the 3D view already did, so a pinch never adds a part. Pinch and wheel zoom work in 2D. Opening Add closes the part editor, which previously covered the menu on phones. Undo, redo, save/load and import round trips were all checked.

Integration verification: 92 checks passed (31 model, 27 learning, 17 scene, 12 transform, 5 audit).