oddlyalive 0.2.0-alpha.2

package/docs/DEMO-VIDEOS.md

@@ -0,0 +1,122 @@
+# Demo videos
+
+The demo package proves the current alpha with the real OddlyAlive solvers.
+There are no hand-authored motion keyframes or stock clips. Locally generated,
+high-resolution cutouts provide material appearance; SVG strings, shadows,
+nets, water, and deformation remain driven by deterministic simulation.
+
+## Outputs
+
+| File | Duration | Purpose |
+| --- | ---: | --- |
+| `videos/oddlyalive-demos/renders/oddlyalive-demos-overview.mp4` | 32.0s | Five-recipe reel |
+| `videos/oddlyalive-demos/renders/demos/01-string-touch.mp4` | 6.4s | Strand contact and peel |
+| `videos/oddlyalive-demos/renders/demos/02-crystal-mobile.mp4` | 6.4s | Weighted hanging payloads |
+| `videos/oddlyalive-demos/renders/demos/03-ball-lab.mp4` | 6.4s | Material response comparison |
+| `videos/oddlyalive-demos/renders/demos/04-football-kick.mp4` | 6.4s | Timed impulse and spin |
+| `videos/oddlyalive-demos/renders/demos/05-shoe-splash.mp4` | 6.4s | Body-to-surface coupling |
+| `docs/assets/oddlyalive-string-touch.gif` | 6.4s | Lightweight README preview |
+
+The MP4s are intentionally ignored by Git. Review them locally first; if
+approved, upload them as release assets or to the chosen media host instead of
+inflating the source repository.
+
+## One-command rebuild
+
+Install Node.js 20+ and FFmpeg, then run:
+
+```bash
+npm run demos:render
+```
+
+That command:
+
+1. installs the pinned demo-project dependencies;
+2. bundles the current OddlyAlive engine for a network-free browser render;
+3. runs HyperFrames lint, runtime, layout, motion, and contrast checks;
+4. renders the 1920×1080, 60 fps master;
+5. cuts five frame-accurate 6.4-second MP4s;
+6. rebuilds the README GIF; and
+7. decodes and verifies every MP4.
+
+Set `HF_WORKERS=1` on a low-memory machine:
+
+```bash
+HF_WORKERS=1 npm run demos:render
+```
+
+## Preview without rendering
+
+```bash
+cd videos/oddlyalive-demos
+npm ci
+npm run build:bundle
+npm run dev
+```
+
+The preview is seek-safe: scrubbing to any time paints the corresponding
+precomputed simulation frame. It does not use `requestAnimationFrame`,
+`performance.now()`, network fetches, or random values.
+
+## Verify existing outputs
+
+```bash
+npm run demos:verify
+```
+
+The verifier checks:
+
+- H.264 video with no audio stream;
+- 1920×1080 frame size;
+- 60 fps;
+- yuv420p pixel format;
+- 32.0 seconds / 1,920 frames for the reel;
+- 6.4 seconds / 384 frames for each recipe; and
+- a complete FFmpeg decode with zero reported errors.
+
+It also prints a SHA-256 checksum for every file so a reviewed master can be
+identified exactly.
+
+## Approved `0.2.0-alpha.2` media
+
+The 2026-07-21 release-candidate encodes were decoded, visually inspected, and
+approved with these SHA-256 checksums:
+
+| File | SHA-256 |
+| --- | --- |
+| `oddlyalive-demos-overview.mp4` | `2b885811737841364721a16b38c7417810d1f13bcb785caeca5318bf2bfb7ad8` |
+| `01-string-touch.mp4` | `a4816683c1edb8cc9b9c7a8d0937ffb36c5ddb47899df5bae1aff13bd27d373c` |
+| `02-crystal-mobile.mp4` | `e148c455f480e52bfb18c48f691bc98d46acd5dcb7f383d101833644ab3d0834` |
+| `03-ball-lab.mp4` | `38fcb06e7a0f6c571ef7d49055aa38242581b5aef6805cbabb054c0b3012d2e5` |
+| `04-football-kick.mp4` | `54b00a6adaeab87140403dbd3478a635c840424c56597e15ff3c2e2558088929` |
+| `05-shoe-splash.mp4` | `a7b061d1a9f192a2c944ef8001eafa4b6a4db7c9e2be0fc0a150b70cc408bc0b` |
+| `oddlyalive-string-touch.gif` | `da5d2db730703fdd7b99293f00a7e4e86de42137faf8252f13ac158bad5a00c2` |
+
+If any file differs, treat it as a new candidate and repeat decode and visual
+review before upload.
+
+## Review-before-publish protocol
+
+Do not push or publish merely because the build passed.
+
+1. Watch the full reel at normal speed.
+2. Watch every recipe clip twice: once for design, once for physical behavior.
+3. Check the first and last frame of each clip.
+4. Run `npm run demos:verify`.
+5. Review `git diff` and confirm generated MP4s remain ignored.
+6. Only after explicit approval, commit the source/docs/GIF.
+7. Upload approved MP4s as release assets separately.
+8. Update GitHub or npm only as a distinct, confirmed action.
+
+## Design contract
+
+- 1920×1080 landscape, 60 fps
+- 6.4 seconds per recipe
+- silent by design
+- paper, ink, and coral OddlyAlive identity
+- photographic object cutouts with procedural SVG physics and deformation
+- hard cuts between recipes so transitions never hide the physics
+- fixed-step solvers at four 240Hz substeps per displayed frame
+
+The composition source and exact scene sequence live in
+`videos/oddlyalive-demos/`.

package/docs/QUICKSTART.md

@@ -0,0 +1,115 @@
+# OddlyAlive quick start
+
+OddlyAlive turns a small JSON scene into deterministic simulation frames and
+renders them as procedural SVG. The same input produces the same output on
+every run.
+
+## Requirements
+
+- Node.js 20 or newer
+- npm
+- A modern browser
+- FFmpeg only if you want to rebuild the demo videos
+
+## 1. Run the gallery
+
+```bash
+git clone https://github.com/thevibefounder/OddlyAlive.git
+cd OddlyAlive
+npm start
+```
+
+Open the local URL printed in the terminal. Choose any of the five recipes:
+
+- `string-touch`
+- `crystal-mobile`
+- `ball-lab`
+- `football-kick`
+- `shoe-splash`
+
+The gallery runs entirely on your machine. It does not require an API key,
+cloud account, or hosted service.
+
+## 2. Run one recipe directly
+
+```bash
+npx oddlyalive play string-touch
+npx oddlyalive play football-kick
+npx oddlyalive play shoe-splash
+```
+
+Use `npx oddlyalive list` to see every built-in recipe.
+
+## 3. Create your own local project
+
+```bash
+npx oddlyalive new my-motion --preset crystal-mobile
+cd my-motion
+npm start
+```
+
+The generated folder contains a complete starter, including `scene.json`.
+Change the physical parameters there and refresh the browser.
+
+For example, a rigid ball is controlled by familiar material properties:
+
+```json
+{
+  "radius": 38,
+  "mass": 0.43,
+  "restitution": 0.62,
+  "friction": 0.58,
+  "vx": 0,
+  "vy": 0
+}
+```
+
+The scene schema is at `schemas/scene.schema.json`. Point your editor at it for
+autocomplete and validation.
+
+## 4. Inspect or simulate without a browser
+
+```bash
+npx oddlyalive inspect scene.json
+npx oddlyalive simulate scene.json --output result.json
+```
+
+`inspect` validates the scene and prints its structure. `simulate` runs the
+fixed-step solver and writes deterministic frame data.
+
+## 5. Use OddlyAlive as a library
+
+```js
+import {
+  createStringTouchScene,
+  simulateScene
+} from "oddlyalive";
+
+const scene = createStringTouchScene({
+  payload: { text: "HELLO PHYSICS" }
+});
+
+const result = simulateScene(scene);
+console.log(result.fingerprint);
+console.log(result.diagnostics);
+```
+
+The renderers are exported too, so a browser project can mount the result into
+an SVG element without recreating the physics.
+
+## 6. Verify the repository
+
+```bash
+npm test
+npm run check
+```
+
+The tests lock validation behavior and deterministic fingerprints across all
+three solver families.
+
+## Where to go next
+
+- `docs/ARCHITECTURE.md` — solver, scene, and renderer boundaries
+- `docs/ROADMAP.md` — planned object families
+- `skills/oddlyalive/SKILL.md` — instructions for Codex and compatible agents
+- `docs/DEMO-VIDEOS.md` — reproducible video build and review workflow

package/docs/ROADMAP.md

@@ -0,0 +1,33 @@
+# Roadmap
+
+## v0.1 — Touch the strings
+
+- Extract the deterministic strand solver.
+- Publish the JSON scene contract.
+- Ship one-command CLI, SVG demo, diagnostics, and agent skill.
+- Reproduce local catch, pressure, friction, staggered peel, and living settle.
+
+## v0.2 — Object recipes
+
+- [x] Add rigid-circle adapter and `football-kick`.
+- [x] Add weighted `crystal-mobile`.
+- [x] Add `ball-lab` material comparison.
+- [x] Add `shoe-splash` coupled wave recipe.
+- [x] Ship a unified five-example gallery.
+- [ ] Add articulated walking and `flower-touch`.
+- [ ] Add `pluck`, `drag`, `shake`, and reusable `drop` gesture primitives.
+- [x] Add automated visual regression fixtures for every recipe.
+
+## v0.3 — Prompt compiler
+
+- Translate natural language into bounded scene parameters.
+- Support local model providers and cloud agent workflows.
+- Reject impossible or ambiguous physical mappings with useful guidance.
+- Keep AI output behind schema validation and deterministic simulation.
+
+## v0.4 — Render everywhere
+
+- HyperFrames adapter and MP4 recipe.
+- Canvas/WebGL renderer for larger particle counts.
+- Transparent PNG sequence and animated SVG export.
+- Optional interactive editor for contact paths and material envelopes.

package/examples/ball-lab/PROVENANCE.md

@@ -0,0 +1,4 @@
+# Provenance
+
+The ball artwork is original procedural SVG built from circles, paths and
+polygons. No external image assets are used.

package/examples/ball-lab/app.js

@@ -0,0 +1,33 @@
+import {
+  createRigidBallRenderer,
+  simulateScene,
+  validateScene
+} from "../../src/index.js";
+import { mountPlayer } from "../shared/player.js";
+
+await new Promise((resolve) => requestAnimationFrame(resolve));
+
+const response = await fetch("./scene.json");
+if (!response.ok) throw new Error(`Could not load scene: ${response.status}`);
+const scene = validateScene(await response.json());
+const simulation = simulateScene(scene);
+const renderer = createRigidBallRenderer(
+  document.querySelector("#motion"),
+  simulation,
+  {
+    mode: "lab",
+    ballAssets: {
+      baseball: "../../assets/photoreal/baseball.png",
+      basketball: "../../assets/photoreal/basketball.png",
+      football: "../../assets/photoreal/soccer-ball.png"
+    }
+  }
+);
+
+mountPlayer({
+  scene,
+  simulation,
+  renderer,
+  metricLabel: "collisions",
+  metricValue: String(simulation.diagnostics.collisionCount)
+});

package/examples/ball-lab/index.html

@@ -0,0 +1,56 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="description" content="OddlyAlive rigid ball material lab" />
+    <title>Ball Lab — OddlyAlive</title>
+    <link rel="stylesheet" href="../shared/example.css" />
+  </head>
+  <body class="theme-ball">
+    <main>
+      <header>
+        <a class="wordmark" href="../"><span class="mark"></span>OddlyAlive</a>
+        <nav>
+          <a href="../crystal-mobile/">← Crystal Mobile</a>
+          <a href="../football-kick/">Football Kick →</a>
+        </nav>
+      </header>
+      <section class="stage">
+        <div class="poster">
+          <div class="poster-copy">
+            <p class="eyebrow">03 / RIGID BODY LAB</p>
+            <h1>THREE BALLS.<br /><em>THREE LIVES.</em></h1>
+            <p class="description">
+              Diameter is only the silhouette. Mass, restitution, friction and
+              spin determine whether an object snaps, rebounds or settles.
+            </p>
+          </div>
+          <p class="corner-note">BASEBALL · 145 G<br />BASKETBALL · 625 G<br />FOOTBALL · 430 G</p>
+          <svg
+            id="motion"
+            class="motion"
+            viewBox="0 0 960 540"
+            role="img"
+            aria-label="A baseball, basketball and football falling and bouncing differently"
+          ></svg>
+          <div class="folio">OA—003</div>
+          <div id="loading" class="loading">SOLVING WORLD…</div>
+        </div>
+      </section>
+      <footer>
+        <div class="controls">
+          <button id="toggle" type="button">PAUSE</button>
+          <input id="scrubber" type="range" min="0" value="0" aria-label="Timeline" />
+        </div>
+        <dl class="metrics">
+          <div><dt>solver</dt><dd>rigid circles</dd></div>
+          <div><dt>step</dt><dd>240 Hz</dd></div>
+          <div><dt id="metric-name">impacts</dt><dd id="metric">—</dd></div>
+          <div><dt>fingerprint</dt><dd id="fingerprint">—</dd></div>
+        </dl>
+      </footer>
+    </main>
+    <script type="module" src="./app.js"></script>
+  </body>
+</html>

package/examples/ball-lab/scene.json

@@ -0,0 +1,68 @@
+{
+  "$schema": "../../schemas/scene.schema.json",
+  "version": 1,
+  "type": "rigid-balls",
+  "name": "OddlyAlive — Ball Lab",
+  "seed": 21,
+  "canvas": { "width": 960, "height": 540 },
+  "timing": { "duration": 6.4, "fps": 60, "substeps": 4, "preRoll": 0 },
+  "world": {
+    "gravity": 920,
+    "airDrag": 0.08,
+    "floorY": 456,
+    "left": 84,
+    "right": 876,
+    "groundFriction": 1.8
+  },
+  "bodies": [
+    {
+      "id": "baseball",
+      "kind": "baseball",
+      "label": "BASEBALL",
+      "x": 250,
+      "y": 104,
+      "radius": 29,
+      "mass": 0.145,
+      "restitution": 0.52,
+      "friction": 0.38,
+      "vx": 34,
+      "vy": 0,
+      "angle": -8,
+      "angularVelocity": 1.2,
+      "color": "#f4efe4"
+    },
+    {
+      "id": "basketball",
+      "kind": "basketball",
+      "label": "BASKETBALL",
+      "x": 480,
+      "y": 72,
+      "radius": 48,
+      "mass": 0.625,
+      "restitution": 0.76,
+      "friction": 0.58,
+      "vx": -18,
+      "vy": 0,
+      "angle": 4,
+      "angularVelocity": -0.5,
+      "color": "#e66b2d"
+    },
+    {
+      "id": "football",
+      "kind": "football",
+      "label": "FOOTBALL",
+      "x": 710,
+      "y": 124,
+      "radius": 39,
+      "mass": 0.43,
+      "restitution": 0.63,
+      "friction": 0.5,
+      "vx": -42,
+      "vy": 0,
+      "angle": 11,
+      "angularVelocity": 0.8,
+      "color": "#f6f3e9"
+    }
+  ],
+  "impulses": []
+}

package/examples/crystal-mobile/PROVENANCE.md

@@ -0,0 +1,4 @@
+# Provenance
+
+All geometry is original SVG authored for OddlyAlive. No external raster or
+third-party illustration contributes pixels to this example.

package/examples/crystal-mobile/app.js

@@ -0,0 +1,26 @@
+import {
+  createCrystalRenderer,
+  simulateScene,
+  validateScene
+} from "../../src/index.js";
+import { mountPlayer } from "../shared/player.js";
+
+await new Promise((resolve) => requestAnimationFrame(resolve));
+
+const response = await fetch("./scene.json");
+if (!response.ok) throw new Error(`Could not load scene: ${response.status}`);
+const scene = validateScene(await response.json());
+const simulation = simulateScene(scene);
+const renderer = createCrystalRenderer(
+  document.querySelector("#motion"),
+  simulation,
+  { pendantHref: "../../assets/photoreal/crystal.png" }
+);
+
+mountPlayer({
+  scene,
+  simulation,
+  renderer,
+  metricLabel: "peak grip",
+  metricValue: `${simulation.diagnostics.observedMaxStaticGrip}/${scene.contact.maxStaticGrip}`
+});

package/examples/crystal-mobile/index.html

@@ -0,0 +1,56 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="description" content="OddlyAlive weighted crystal mobile example" />
+    <title>Crystal Mobile — OddlyAlive</title>
+    <link rel="stylesheet" href="../shared/example.css" />
+  </head>
+  <body class="theme-crystal">
+    <main>
+      <header>
+        <a class="wordmark" href="../"><span class="mark"></span>OddlyAlive</a>
+        <nav>
+          <a href="../string-touch/">← String Touch</a>
+          <a href="../ball-lab/">Ball Lab →</a>
+        </nav>
+      </header>
+      <section class="stage">
+        <div class="poster">
+          <div class="poster-copy">
+            <p class="eyebrow">02 / WEIGHTED STRANDS</p>
+            <h1>CRYSTAL<br /><em>MOBILE.</em></h1>
+            <p class="description">
+              The same touch becomes a different gesture when every cord carries
+              a faceted weight. Mass creates lag, overswing and a longer memory.
+            </p>
+          </div>
+          <p class="corner-note">13 CORDS<br />HEAVY TERMINALS<br />XPBD · 240 HZ</p>
+          <svg
+            id="motion"
+            class="motion"
+            viewBox="0 0 960 540"
+            role="img"
+            aria-label="A mobile of weighted crystals responding to an invisible touch"
+          ></svg>
+          <div class="folio">OA—002</div>
+          <div id="loading" class="loading">SOLVING WORLD…</div>
+        </div>
+      </section>
+      <footer>
+        <div class="controls">
+          <button id="toggle" type="button">PAUSE</button>
+          <input id="scrubber" type="range" min="0" value="0" aria-label="Timeline" />
+        </div>
+        <dl class="metrics">
+          <div><dt>solver</dt><dd>strand XPBD</dd></div>
+          <div><dt>step</dt><dd>240 Hz</dd></div>
+          <div><dt id="metric-name">grip</dt><dd id="metric">—</dd></div>
+          <div><dt>fingerprint</dt><dd id="fingerprint">—</dd></div>
+        </dl>
+      </footer>
+    </main>
+    <script type="module" src="./app.js"></script>
+  </body>
+</html>

package/examples/crystal-mobile/scene.json

@@ -0,0 +1,69 @@
+{
+  "$schema": "../../schemas/scene.schema.json",
+  "version": 1,
+  "type": "strand-field",
+  "name": "OddlyAlive — Crystal Mobile",
+  "seed": 17,
+  "canvas": {
+    "width": 960,
+    "height": 540
+  },
+  "timing": {
+    "duration": 6.4,
+    "fps": 60,
+    "substeps": 4,
+    "preRoll": 2
+  },
+  "field": {
+    "columns": 13,
+    "rows": 14,
+    "originX": 390,
+    "originY": 96,
+    "spacingX": 38,
+    "spacingY": 24
+  },
+  "material": {
+    "gravity": 480,
+    "linearDrag": 0.76,
+    "quadraticDrag": 0.0026,
+    "lengthCompliance": 0.0000011,
+    "compressionCompliance": 0.00052,
+    "bendCompliance": 0.00072,
+    "maxStretch": 1.045
+  },
+  "contact": {
+    "radiusX": 58,
+    "radiusY": 37,
+    "maxStaticGrip": 6,
+    "captureStartRow": 5,
+    "captureEndRow": 12
+  },
+  "gesture": {
+    "type": "touch-path",
+    "points": [
+      { "time": 0.48, "x": -60, "y": 320, "pressure": 0 },
+      { "time": 0.68, "x": 250, "y": 328, "pressure": 0.72 },
+      { "time": 1.14, "x": 430, "y": 360, "pressure": 1 },
+      { "time": 1.72, "x": 665, "y": 391, "pressure": 0.98 },
+      { "time": 2.14, "x": 900, "y": 379, "pressure": 0.94 },
+      { "time": 2.38, "x": 934, "y": 368, "pressure": 0.88 },
+      { "time": 2.72, "x": 770, "y": 404, "pressure": 0.86 },
+      { "time": 3.12, "x": 590, "y": 414, "pressure": 0.65 },
+      { "time": 3.58, "x": 390, "y": 386, "pressure": 0.32 },
+      { "time": 4.08, "x": 155, "y": 352, "pressure": 0.04 },
+      { "time": 4.34, "x": 30, "y": 348, "pressure": 0 }
+    ]
+  },
+  "payload": {
+    "text": "✦",
+    "fontFamily": "ui-monospace, SFMono-Regular, Menlo, monospace",
+    "fontSize": 12,
+    "terminalMass": 6
+  },
+  "render": {
+    "background": "#f4eedc",
+    "ink": "#292720",
+    "accent": "#cc5f4a",
+    "filament": "rgba(42, 40, 34, 0.45)"
+  }
+}

package/examples/football-kick/PROVENANCE.md

@@ -0,0 +1,4 @@
+# Provenance
+
+The football and field are original procedural SVG. The motion is solver output
+from one scheduled impulse; no authored flight path is used.

package/examples/football-kick/app.js

@@ -0,0 +1,33 @@
+import {
+  createRigidBallRenderer,
+  simulateScene,
+  validateScene
+} from "../../src/index.js";
+import { mountPlayer } from "../shared/player.js";
+
+await new Promise((resolve) => requestAnimationFrame(resolve));
+
+const response = await fetch("./scene.json");
+if (!response.ok) throw new Error(`Could not load scene: ${response.status}`);
+const scene = validateScene(await response.json());
+const simulation = simulateScene(scene);
+const renderer = createRigidBallRenderer(
+  document.querySelector("#motion"),
+  simulation,
+  {
+    mode: "kick",
+    labels: false,
+    ballAssets: {
+      football: "../../assets/photoreal/soccer-ball.png"
+    },
+    kickActorHref: "../../assets/photoreal/kicking-cleat.png"
+  }
+);
+
+mountPlayer({
+  scene,
+  simulation,
+  renderer,
+  metricLabel: "impulses",
+  metricValue: String(simulation.diagnostics.appliedImpulses)
+});