# /bowl — Bowling physics research

**Status, November 11, 2026:** the first interactive browser prototype is available alongside the research package. It is an exploratory visual workbench, not a physically validated bowling predictor. No production deployment has been performed.

## Open the prototype

Run `npm run build` and `npm run preview` from this directory, then open [the local preview](http://127.0.0.1:8765/). The first shot computes automatically and starts paused. Use Play, reverse, the timeline, camera presets, and object selection to explore it. Change release settings and press **Simulate shot** for a new run.

See [the prototype guide](docs/PROTOTYPE.md) for controls, architecture, export conventions, and physical approximations. The UI includes model notes so exploratory coefficients are not confused with measured properties.

- **Camera:** drag/scroll to orbit/zoom; Line starts at standing eye level on the approach, 2.5 m behind the foul line, looking down the lane; Free uses WASD, Q/E, right-drag look, and Shift.
- **Replay:** play/pause, reverse, scrub, sample step, speed, and first-impact jump.
- **Inspector:** click a ball/pin/lane or choose it from the list; display velocity, angular speed, mass, COM position and interval-average net force.
- **Build:** Three.js + Rapier module worker, statically bundled with esbuild. No remote runtime libraries are required; the optional Google Fonts stylesheet has system-font fallbacks.
- **Checks:** `npm run test:prototype` passes seven prototype tests; `npm test` retains the 13 passing research/data tests. The existing benchmark stress failure remains documented below.

Read [REQUIREMENTS.md](REQUIREMENTS.md) for the full specification and [docs/RESEARCH_STATUS.md](docs/RESEARCH_STATUS.md) for findings and the engine decision. [docs/MEASUREMENT_PLAN.md](docs/MEASUREMENT_PLAN.md) describes the physical measurements still needed.

## What is available

- Five Brunswick 15 lb catalog ball variants and four Kegel conditioner records, with source links and missing measurements explicitly represented as `null`.
- Three official 2026 PBA/Kegel Atlas Pro PDF recipe tables: Cheetah 35, Chameleon 39, and Shark 48. Every forward/reverse load is extracted; row volumes and direction totals are checked. Original archives and every non-metadata member have SHA-256 provenance.
- Versioned JSON Schemas for these **seed datasets**, plus semantic volume, unit, reference, and missing-data checks. These are not yet the complete runtime simulation schema.
- Rapier 0.21.0 feasibility experiments and an independent double-precision Euler/RK4 reference.
- Machine-readable benchmark results, including a retained collision-detection failure.

The recipes say `KEGEL`, not a named conditioner. Do not assign Fire, Ice, Current, Terrain, or their viscosities to them. A machine recipe also does not constitute a measured lane oil-thickness field.

## Reproduce

Tested with Node.js 24.13.1 and npm 11.8.0 on macOS arm64. Dependencies are pinned by `package-lock.json`. No global installation is needed.

```sh
cd ohdeven/bowl
npm ci --ignore-scripts
npm test
npm run benchmark
```

`npm test`: **13 tests pass** for schemas, data consistency, unit conversion, and independent reference mechanics.

`npm run benchmark`: **7 of 8 experiment groups pass; exits 1 intentionally because the unguarded dynamic/dynamic CCD stress sweep fails.** It writes `docs/benchmark-results.json`, preserving both successes and failure metrics. This is a scientific feasibility gate, not a green production test suite. Do not ignore the exit code in automation or weaken the gate to make it pass.

The failing test launches two small spheres at ±100 m/s, outside normal bowling release speeds, to expose an engine limit. An 8,000 Hz case-specific travel bound prevents tunneling in that case. This does not establish adequate timesteps for rotating pins. The browser draft now exercises approximate pins and rack contacts, but their numerical accuracy, measured oil traction, and material calibration remain unvalidated.

## Refresh the official recipe extraction

The downloaded commercial originals remain outside the repository. Fetch exactly the recorded versions, then use the PDF extractor:

```sh
python3 research/fetch-patterns.py /tmp/bowl-downloads
python3 -m venv /tmp/bowl-research-venv
/tmp/bowl-research-venv/bin/pip install -r research/requirements.txt
/tmp/bowl-research-venv/bin/python research/import-patterns.py /tmp/bowl-downloads
npm test
```

The fetcher rejects changed archive hashes, requiring review of a source revision. The importer accepts the three known PDF layouts and rejects inconsistent totals. Its access date records the original November 10 research acquisition; update provenance and visual-review status when intentionally adopting new source versions. The original three one-page PDFs were rendered and visually checked against their extracted tables.

The archive text, spreadsheet, PAT, DAT, and Pattern members are inventoried, **not decoded**. Their distances and settings must not be merged into the rounded PDF values without format documentation. In particular, the first Cheetah row prints `0 → 0` yet dispenses 1,575 µL; dropping it would corrupt the total.

## Files

| Path | Purpose |
|---|---|
| `index.html`, `app/style.css` | Browser prototype interface |
| `app/`, `assets/` | Source modules and static bundled browser/worker entries |
| `docs/PROTOTYPE.md` | Controls, approximations, export format and UI checks |
| `REQUIREMENTS.md` | Requirements, equations, scientific standards, and build plan |
| `data/equipment.json` | Source-linked seed ball and conditioner facts |
| `data/patterns.json` | Extracted recipe rows, limitations, and source fingerprints |
| `data/schema/` | Versioned seed dataset validation |
| `research/math.mjs` | Independent quaternion, inertia, and torque-free reference math |
| `research/benchmark.mjs` | Rapier experiments and machine-readable report generation |
| `research/*.test.mjs` | Data and reference-mechanics regression tests |
| `research/fetch-patterns.py` | Pinned official-archive acquisition |
| `research/import-patterns.py` | PDF factual table extraction and conservation checks |
| `docs/benchmark-results.json` | Recorded experiment settings and results |
| `docs/RESEARCH_STATUS.md` | Findings, limitations, and next research gates |
| `docs/MEASUREMENT_PLAN.md` | Physical experiment acquisition protocol |

## Next gate

Rapier remains a candidate. Its stock JavaScript API lacks a per-contact modification callback, which matters for the planned custom oil-dependent traction. Decide between a custom Rust/WASM adapter and a carefully validated alternative only after checking contact-law integration and spinning/compound-body collision handling. Rust/Cargo was not available in this environment and has not been installed.

Physical validation also requires lane access or measured datasets. Until supplied, all numerical experiments use explicit synthetic parameters. The meaning of “PBC” is still unresolved; no source has been silently substituted. Continue research without treating those gaps as solved.

Prototype interaction update: **Simulate shot** is sticky at the top of setup controls. Replays finish 0.25 seconds after full ball clearance into the pit (seven-second maximum); an explicitly idealized capture zeros ball spin and retires its collisions. The rev-rate readout follows the playhead. See [prototype notes](docs/PROTOTYPE.md).

The animation pane and replay transport now stay sticky while scrolling shot controls. The scene height adapts to the browser height to keep playback controls accessible.

Release controls now update a live setup preview immediately, including board position and loft. Editing pauses the replay and hides its stale trajectory; Simulate computes the new path. The computed path is bright cyan with a four-pixel stroke. Toggle Angles for magenta spin/tilt, amber horizontal spin projection/axis rotation, and green travel arrows. Angular guides follow recorded world angular velocity during replay; undefined angles disappear at zero spin. Guide lengths are illustrative, not vector magnitudes. Playback and scrubbing return to the stored shot.

Replay completion update: after full deck clearance the ball follows a one-second, visibly rolling guided return to the back-left pit corner (an illustrative pinsetter mechanism). Replay continues until the ball is parked and every active pin stays below 0.025 m/s and 0.12 rad/s for 0.2 seconds. Pins falling below the modeled pit collection boundary are retired. A 20-second safety cap is reported as `time-limit`, not settled. This supersedes the earlier fixed post-clearance delay and zero-spin return description.

Rack initialization now places every pin upright with its base at deck height and zero velocity, with active contact initialization. The former half-second settling pass was removed because it introduced pre-shot tilt and lift, especially on pin 10. Initial rack pose and velocity are checked in the prototype tests.

Resting-contact fix: pins are created awake so floor contacts initialize immediately, with an analytic cylindrical foot replacing the lowest faceted section. Deck restitution is zero (minimum combine rule); pin–pin restitution remains unchanged. A two-second untouched-rack regression checks every recorded sample for sub-0.2 mm displacement, upright orientation, and near-zero speed. Pins remain dynamic and sleep naturally. The cylindrical foot is a draft collision-shape approximation.

### Wicked Gremlin and mirrored release

Added Roto Grip Wicked Gremlin with an approximate procedural Citrine/Red/Purple swirl. [Official technical sheet](https://stormproducts.nyc3.cdn.digitaloceanspaces.com/product_pages/Balls/Roto_Grip/Wicked_Gremlin/WICKED%20GREMLIN_Tech%20Doc.pdf) gives G-R1 Solid Reactive, Rondure MaxD asymmetric core, 2000-grit Abralon, and 15 lb RG 2.500 in, differential .058 in, PSA .010 in. The prototype scales this 15 lb inertia for other weights; traction remains assumed. The actual product is offered in 12–16 lb; other slider values are hypothetical.

**Lefty backup** implements the requested left-to-right hook convention: it mirrors board position (40 − board), negates launch angle, mirrors core orientation, and uses the spin vector mirrored from the right-hand preset. It selects Left and locks hand buttons while enabled; turning it off mirrors values back and restores the previous hand. Tilt and rotation magnitudes remain unchanged while their world-space directions mirror. This describes the requested motion, not a biomechanical model of a backup release. The ball-return mechanism stays on the physical back-left side.

Default shot: Wicked Gremlin, 14 lb, 300 rpm, board 27.5, launch −3.0°. Other release settings remain unchanged. Left-hand and Lefty backup modes now preserve the positive vertical spin-axis component (tilt) while reversing lateral spin. This user-selected convention replaces the earlier full axial mirror; it is intentionally not an exact spatial reflection.

The initial and Reset shot is directly left-handed, with Lefty backup off. Its specified board 27.5 and launch −3.0° are used unchanged; no toggle or mirroring operation runs during initialization.

## Next Prompt implementation — November 11, 2026

The requested list was at the end of `REQUIREMENTS.md`. This section supersedes earlier handedness-toggle descriptions.

- Removed Lefty backup. Changing Right/Left mirrors board (`40 − board`), launch angle and core orientation, reverses lateral spin, and preserves vertical tilt. Selecting the current hand does nothing to the values. Initial/Reset remains the requested left-handed Gremlin shot.
- The trajectory map uses the original ten pin spots, never the final animated positions. It now labels the fixed rack and remains visible on narrow screens.
- **Blue oil** toggles transparent blue shading. It is still the illustrative pattern envelope, not an imported measured film.
- Added Hammer **Black Widow Tour V1** with approximate black/blue/purple swirls. [Hammer's official page](https://hammerbowling.com/collections/upper-mid-performance/products/black-widow-tour-v1) supplies 15 lb RG 2.500, differential .034, asymmetry .016, Gas Mask Low Diff core, HK22 Aggression Hybrid cover. As with other draft presets, other weights scale this 15 lb tensor and traction is assumed.
- Added an OhDeven wordmark to the backstop and four brown visual range-finder boxes (two per side). “Baker box” was interpreted as down-lane aiming rectangles: one-board wide, three feet long, beginning at 35/40 feet on mirrored 10/15-board offsets. Placement is a visual approximation, not a certified lane marking layout.
- **Strike finder · aimbot:** check a parameter to lock it, then Find best shot. The ball, mass, hand, and pattern are always fixed. By default only board and launch angle vary. A deterministic 18-run coordinate search applies the best candidate and preserves its replay. Cancel stops the worker and retains the previous run. If all controls are locked, it evaluates the current shot once.

Search uses actual simulated final pinfall, a projected pocket offset, a signed entry-angle target of 5° within the conventional 4–6° window, and an observed direct-ball contact sequence preference (right 1→3→5→9; left 1→2→5→8). The [IBPSIA entry-angle discussion](https://ibpsia.com/entry-angle-part-2/) provides the six-degree/17.5-board starting reference; our code converts the offset to the prototype's centered X convention. These are heuristic preferences, not a universal mandatory collision order. First significant contact per pin is recorded at physics-step resolution; contacts within the same step are not temporally ordered more finely. Full causal pin–pin chain analysis is not implemented by this finder. A ten-down result is a draft simulation outcome, not a guaranteed real-world strike or global optimum. Time-limit outcomes are labeled provisional.

Validation: seven prototype tests pass, including hand-switch round trips, locked search parameters, finite repeatable impacts, and resting-rack stability. Existing research validation remains separate.

Browser verification: the 18-candidate search completed with locks preserved and found 10/10 pins, first ball contacts 1→2→5→8, entry 2.6°, settled. This is outside the preferred angle window and is reported numerically rather than labeled perfect. No browser errors were logged.

Vector visualization update: green is horizontal travel; yellow is the direction opposing the spin-only bottom-point surface velocity; orange opposes the total bottom-point slip (`v + ω × [0,0,−R]`). The yellow arc reports the signed angle from travel to spin pull. These are normalized directional guides, not force vectors or independent additive forces. While lofted they are labeled projected contact directions; return-path guides are hidden. Magenta remains the angular-velocity axis, with signed amber axis-rotation labeling. Left/right changes flip lateral guide directions while retaining the requested positive vertical tilt convention.


### Additional ball presets (November 16, 2026)

Added Radical No Doubt (original pearl), Brunswick Vaporize, and Brunswick Energize. Defaults remain the 14 lb Wicked Gremlin left-handed shot. Procedural swirls approximate the published Smoke/Blue/Purple, Carbon, and Red/Black/Blue palettes respectively; they are not product scans.

Manufacturer references:
- [Radical No Doubt](https://radicalbowling.com/uploads/downloads/Ball-Talkers/No-Doubt_Ball_Talker_0824-16.pdf): 15 lb RG 2.485 in, differential .051 in, symmetric, HK22+ Pearl.
- [Brunswick Vaporize](https://brunswickbowling.com/uploads/downloads/Ball-Info-Sheets/Vaporize_Info_Sheet_0424-46.pdf): 15 lb RG 2.478 in, differential .048 in, intermediate differential .017 in, Zone Asymmetric, HK22C EVO Pearl.
- [Brunswick Energize](https://brunswickbowling.com/products/balls/retired/energize): same 15 lb core numbers, HK22C EVO Hybrid.

These presets use the existing 15 lb reference-inertia approximation at other weights. Traction multipliers (.85 for the pearls, .9 for the hybrid) are assumed prototype values, not measured manufacturer friction data. Published weight-specific core tables still need integration.


### Approach visualization and outside-lane release
Release-board bounds are now −5.5 to 45.5: six board widths beyond the modeled edges at 0.5 and 39.5. The finder uses the same bounds. Loft remains a horizontal initial velocity with gravitational descent, including collision with gutter rails; clearing the gutter depends on speed, loft and angle.

The optional 3/5-step and one/two-handed visual rig works backward from the specified release position, with mirrored arms/stance and geometric elbow/knee bends. Negative replay time is approach time. Segment sizes, stride, timing and torso placement are illustrative; they are not a biomechanical reconstruction or additional release-force model. The rig can stretch at extreme settings. Shot defaults remain unchanged. The page footer documents the finder’s full scoring and search rules.


### Coordinated approach revision
The bowler now uses scheduled foot contacts, quintic step easing, cubic Hermite swing interpolation, a continuous release tangent matching the simulated ball velocity, and a held follow-through. Two-bone arm/leg IK clamps unreachable targets instead of stretching segments and exposes a reach warning. Rounded procedural anatomy replaces the thin cylinder rendering. Tests cover fixed limb lengths, release continuity and planted-foot intervals. This remains a procedural visual rig, not a skinned production character or motion-captured/validated biomechanics. Extreme settings may visibly separate the constrained hand from the authoritative ball path. A professionally authored skinned character and delivery clips remain future asset work.
