oddlyalive 0.2.0-alpha.2

package/tests/cli.test.js

@@ -0,0 +1,101 @@
+import assert from "node:assert/strict";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+import test from "node:test";
+
+test("the CLI creates a dependency-free strand starter", async () => {
+  const temporaryRoot = await mkdtemp(join(tmpdir(), "oddlyalive-"));
+  const target = join(temporaryRoot, "my-motion");
+  const result = spawnSync(
+    process.execPath,
+    [
+      "./bin/oddlyalive.js",
+      "new",
+      target,
+      "--text",
+      "HELLO MOTION"
+    ],
+    { cwd: new URL("..", import.meta.url), encoding: "utf8" }
+  );
+
+  assert.equal(result.status, 0, result.stderr);
+  const scene = JSON.parse(
+    await readFile(join(target, "examples/string-touch/scene.json"), "utf8")
+  );
+  const packageJson = JSON.parse(
+    await readFile(join(target, "package.json"), "utf8")
+  );
+  assert.match(scene.payload.text, /HELLO MOTION/);
+  assert.equal(
+    packageJson.scripts.start,
+    "node ./scripts/serve.js --path /examples/string-touch/"
+  );
+  await rm(temporaryRoot, { recursive: true, force: true });
+});
+
+test("the CLI can create every built-in recipe", async () => {
+  const temporaryRoot = await mkdtemp(join(tmpdir(), "oddlyalive-recipes-"));
+  const presets = [
+    "string-touch",
+    "crystal-mobile",
+    "ball-lab",
+    "football-kick",
+    "shoe-splash"
+  ];
+  const requiredAssets = {
+    "string-touch": ["letter-charm-square.png"],
+    "crystal-mobile": ["crystal.png"],
+    "ball-lab": ["baseball.png", "basketball.png", "soccer-ball.png"],
+    "football-kick": ["kicking-cleat.png", "soccer-ball.png"],
+    "shoe-splash": ["sneaker.png"]
+  };
+  for (const preset of presets) {
+    const target = join(temporaryRoot, preset);
+    const result = spawnSync(
+      process.execPath,
+      ["./bin/oddlyalive.js", "new", target, "--preset", preset],
+      { cwd: new URL("..", import.meta.url), encoding: "utf8" }
+    );
+    assert.equal(result.status, 0, `${preset}: ${result.stderr}`);
+    const scene = JSON.parse(
+      await readFile(join(target, `examples/${preset}/scene.json`), "utf8")
+    );
+    assert.equal(typeof scene.type, "string");
+    await readFile(join(target, "examples/shared/player.js"), "utf8");
+    await readFile(join(target, "schemas/scene.schema.json"), "utf8");
+    for (const asset of requiredAssets[preset]) {
+      await readFile(join(target, "assets/photoreal", asset));
+    }
+    await readFile(join(target, "assets/photoreal/PROVENANCE.md"), "utf8");
+    await readFile(join(target, "scripts/serve.js"), "utf8");
+    const html = await readFile(
+      join(target, `examples/${preset}/index.html`),
+      "utf8"
+    );
+    assert.doesNotMatch(
+      html,
+      /href="\.\.\/(string-touch|crystal-mobile|ball-lab|football-kick|shoe-splash)\//
+    );
+  }
+  await rm(temporaryRoot, { recursive: true, force: true });
+});
+
+test("the CLI lists the complete recipe gallery", () => {
+  const result = spawnSync(
+    process.execPath,
+    ["./bin/oddlyalive.js", "list"],
+    { cwd: new URL("..", import.meta.url), encoding: "utf8" }
+  );
+  assert.equal(result.status, 0, result.stderr);
+  for (const preset of [
+    "string-touch",
+    "crystal-mobile",
+    "ball-lab",
+    "football-kick",
+    "shoe-splash"
+  ]) {
+    assert.match(result.stdout, new RegExp(preset));
+  }
+});

package/tests/determinism.test.js

@@ -0,0 +1,57 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  createStringTouchScene,
+  simulateScene
+} from "../src/index.js";
+
+const compactScene = createStringTouchScene({
+  timing: {
+    duration: 4.8,
+    fps: 30,
+    substeps: 8,
+    preRoll: 0.5
+  },
+  field: {
+    columns: 13,
+    rows: 10,
+    originX: 145,
+    originY: 108,
+    spacingX: 48,
+    spacingY: 28
+  },
+  contact: {
+    maxStaticGrip: 6,
+    captureStartRow: 3,
+    captureEndRow: 9
+  }
+});
+
+test("the same scene produces the same simulation fingerprint", () => {
+  const first = simulateScene(compactScene, { includeFrames: false });
+  const second = simulateScene(compactScene, { includeFrames: false });
+  assert.equal(first.fingerprint, second.fingerprint);
+  assert.equal(
+    first.diagnostics.observedMaxStaticGrip,
+    second.diagnostics.observedMaxStaticGrip
+  );
+  assert.ok(first.diagnostics.observedMaxStaticGrip > 0);
+  assert.ok(
+    first.diagnostics.observedMaxStaticGrip <=
+      compactScene.contact.maxStaticGrip
+  );
+  assert.ok(first.diagnostics.firstGripTime !== null);
+  assert.ok(
+    first.diagnostics.observedMaxStretch <
+      compactScene.material.maxStretch + 0.02
+  );
+});
+
+test("changing the material seed changes the fingerprint", () => {
+  const first = simulateScene(compactScene, { includeFrames: false });
+  const second = simulateScene(
+    { ...compactScene, seed: compactScene.seed + 1 },
+    { includeFrames: false }
+  );
+  assert.notEqual(first.fingerprint, second.fingerprint);
+});

package/tests/fixtures/visual-baselines.json

@@ -0,0 +1,27 @@
+{
+  "version": 1,
+  "description": "Approved deterministic motion and visual-source baselines. Update only after visual review.",
+  "sceneFingerprints": {
+    "string-touch": "4c56b4e5",
+    "crystal-mobile": "04e45087",
+    "ball-lab": "c3b9e206",
+    "football-kick": "2179d5a7",
+    "shoe-splash": "438ccfca"
+  },
+  "fileSha256": {
+    "assets/photoreal/baseball.png": "0d8e6be0dc67ad577a40772d6d6b17cd70732d15f57b1184500c9676abd387b6",
+    "assets/photoreal/basketball.png": "5c5c8e714525066a46fa8f694f1ada3312f202b6bd8e9059015c4b6acf92f6af",
+    "assets/photoreal/crystal.png": "92ea76d9d9fb24899510764670eb0d88887a70822d6689fe5df4f374a2c62903",
+    "assets/photoreal/kicking-cleat.png": "9151599c10eb26e3250e9f7c4921e6e4b44dd8286a19a61fa6ae09a79dfa673f",
+    "assets/photoreal/letter-charm-square.png": "b2bccab5e482bfa86c0f71ae70f6d5cef44ab1d892135384c27a6f763bd73cae",
+    "assets/photoreal/letter-charm.png": "e20eb93043feb7bf307a432db53cf00af0997c3d17d6e59c070f835375b87364",
+    "assets/photoreal/sneaker.png": "a6736fbdc0120cbd95cdb6157522e980226c9dc53e7d9af31e1817df180c6da9",
+    "assets/photoreal/soccer-ball.png": "38e85510f7380e8334f2f6562aad55240132af21787de8746d2698e000bcf542",
+    "src/crystal-renderer.js": "e63ead4940827c4a47f685ce1657b2e0f12ef721ad533f3659fd5d5edcbc8059",
+    "src/rigid-renderer.js": "39e1fe69fa84a3c9ec499554b8551655443988d18c6f357db6e86109288976b3",
+    "src/svg-renderer.js": "c5848d44d7560a23b32db26503b231f2482a41dbcbb6f1bab01e6a3e615ece3a",
+    "src/wave-renderer.js": "5c8d1d2aff3dbfe8aede895ddf1cce8317b31a962ccc70ff569bfe2125cc384d",
+    "videos/oddlyalive-demos/app.js": "393414f946090b67a2dec2a2bf254d4b8fd4a2b74d4fdeb1022da4d005841a68",
+    "videos/oddlyalive-demos/index.html": "86bf5c2502a67c9e70154ec11f9bcb79bb96344f8cba85c6b354ad5b0e8a5107"
+  }
+}

package/tests/rigid-balls.test.js

@@ -0,0 +1,77 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  createRigidBallsScene,
+  simulateScene,
+  validateScene
+} from "../src/index.js";
+
+test("rigid ball worlds are deterministic and collide within bounds", () => {
+  const scene = validateScene(createRigidBallsScene());
+  const first = simulateScene(scene, { includeFrames: false });
+  const second = simulateScene(scene, { includeFrames: false });
+
+  assert.equal(first.fingerprint, second.fingerprint);
+  assert.ok(first.diagnostics.collisionCount > 0);
+  assert.ok(first.diagnostics.firstImpactTime > 0.5);
+  assert.ok(first.diagnostics.firstImpactTime < 1.5);
+  assert.ok(first.diagnostics.maxPenetration < 10);
+  assert.equal(first.diagnostics.appliedImpulses, 0);
+});
+
+test("a scheduled kick is applied exactly once and changes the world", () => {
+  const scene = createRigidBallsScene({
+    bodies: [
+      {
+        id: "ball",
+        kind: "football",
+        label: "FOOTBALL",
+        x: 180,
+        y: 392,
+        radius: 38,
+        mass: 0.43,
+        restitution: 0.62,
+        friction: 0.58,
+        vx: 0,
+        vy: 0,
+        angle: 0,
+        angularVelocity: 0,
+        color: "#f6f3e9"
+      }
+    ],
+    world: { floorY: 430, left: 70, right: 910, groundFriction: 2.4 },
+    impulses: [
+      {
+        time: 0.62,
+        body: "ball",
+        impulseX: 300,
+        impulseY: -235,
+        angularImpulse: 4.6
+      }
+    ]
+  });
+  const kicked = simulateScene(scene, { includeFrames: false });
+  const still = simulateScene(
+    createRigidBallsScene({ ...scene, impulses: [] }),
+    { includeFrames: false }
+  );
+
+  assert.equal(kicked.diagnostics.appliedImpulses, 1);
+  assert.notEqual(kicked.fingerprint, still.fingerprint);
+  assert.ok(kicked.diagnostics.maxSpeed > 500);
+});
+
+test("rigid pre-roll advances the world before output frame zero", () => {
+  const withoutPreRoll = simulateScene(
+    createRigidBallsScene({
+      timing: { duration: 1, fps: 60, substeps: 4, preRoll: 0 }
+    })
+  );
+  const withPreRoll = simulateScene(
+    createRigidBallsScene({
+      timing: { duration: 1, fps: 60, substeps: 4, preRoll: 0.25 }
+    })
+  );
+
+  assert.ok(withPreRoll.frames[0].y[0] > withoutPreRoll.frames[0].y[0]);
+});

package/tests/scene.test.js

@@ -0,0 +1,78 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  createRigidBallsScene,
+  createStringTouchScene,
+  createSurfaceWaveScene,
+  sampleGesture,
+  validateScene
+} from "../src/index.js";
+
+test("the default scene validates and merges payload overrides", () => {
+  const scene = validateScene(
+    createStringTouchScene({ payload: { text: "HELLO" } })
+  );
+  assert.equal(scene.payload.text, "HELLO");
+  assert.equal(scene.field.columns, 23);
+  assert.equal(scene.timing.fps * scene.timing.substeps, 240);
+});
+
+test("the registry validates every implemented scene family", () => {
+  assert.equal(validateScene(createRigidBallsScene()).type, "rigid-balls");
+  assert.equal(validateScene(createSurfaceWaveScene()).type, "surface-wave");
+  assert.throws(
+    () => validateScene({ type: "cloth" }),
+    /Unsupported scene type/
+  );
+});
+
+test("rigid impulse references and wave sample counts are guarded", () => {
+  assert.throws(
+    () =>
+      validateScene(
+        createRigidBallsScene({
+          impulses: [
+            {
+              time: 0.2,
+              body: "missing",
+              impulseX: 1,
+              impulseY: 1
+            }
+          ]
+        })
+      ),
+    /unknown body/
+  );
+  assert.throws(
+    () =>
+      validateScene(
+        createSurfaceWaveScene({ surface: { samples: 4 } })
+      ),
+    /at least 16/
+  );
+});
+
+test("gesture sampling is smooth and bounded at both ends", () => {
+  const scene = createStringTouchScene();
+  const before = sampleGesture(scene.gesture.points, -10);
+  const middle = sampleGesture(scene.gesture.points, 1.3);
+  const after = sampleGesture(scene.gesture.points, 20);
+  assert.equal(before.pressure, 0);
+  assert.ok(middle.pressure > 0.9);
+  assert.equal(after.pressure, 0);
+});
+
+test("invalid pressure and unordered gesture points are rejected", () => {
+  assert.throws(
+    () =>
+      validateScene({
+        gesture: {
+          points: [
+            { time: 1, x: 0, y: 0, pressure: 0 },
+            { time: 0, x: 1, y: 1, pressure: 1.2 }
+          ]
+        }
+      }),
+    /pressure|ordered/
+  );
+});

package/tests/surface-wave.test.js

@@ -0,0 +1,39 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import {
+  createSurfaceWaveScene,
+  simulateScene,
+  validateScene
+} from "../src/index.js";
+
+test("the coupled wave is deterministic and responds to impact", () => {
+  const scene = validateScene(createSurfaceWaveScene());
+  const first = simulateScene(scene, { includeFrames: false });
+  const second = simulateScene(scene, { includeFrames: false });
+
+  assert.equal(first.fingerprint, second.fingerprint);
+  assert.ok(first.diagnostics.impactCount > 0);
+  assert.ok(first.diagnostics.firstImpactTime > 0.5);
+  assert.ok(first.diagnostics.firstImpactTime < 1.5);
+  assert.ok(first.diagnostics.maxWaveHeight > 1);
+  assert.ok(first.diagnostics.maxWaveHeight < 100);
+  assert.ok(first.diagnostics.maxSubmersion < scene.body.height);
+});
+
+test("surface parameters alter the deterministic result", () => {
+  const original = simulateScene(createSurfaceWaveScene(), {
+    includeFrames: false
+  });
+  const calmer = simulateScene(
+    createSurfaceWaveScene({
+      surface: { damping: 5.5, coupling: 0.22 }
+    }),
+    { includeFrames: false }
+  );
+
+  assert.notEqual(original.fingerprint, calmer.fingerprint);
+  assert.ok(
+    calmer.diagnostics.maxWaveHeight <
+      original.diagnostics.maxWaveHeight
+  );
+});

package/tests/visual-fixtures.test.js

@@ -0,0 +1,43 @@
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+
+import { simulateScene, validateScene } from "../src/index.js";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const baseline = JSON.parse(
+  await readFile(resolve(root, "tests/fixtures/visual-baselines.json"), "utf8")
+);
+const expectedScenes = [
+  "string-touch",
+  "crystal-mobile",
+  "ball-lab",
+  "football-kick",
+  "shoe-splash"
+];
+
+test("approved recipe motion fingerprints remain stable", async () => {
+  assert.deepEqual(Object.keys(baseline.sceneFingerprints), expectedScenes);
+  for (const name of expectedScenes) {
+    const scene = validateScene(
+      JSON.parse(
+        await readFile(resolve(root, `examples/${name}/scene.json`), "utf8")
+      )
+    );
+    const actual = simulateScene(scene, { includeFrames: false }).fingerprint;
+    assert.equal(actual, baseline.sceneFingerprints[name], `${name} changed`);
+  }
+});
+
+test("approved visual source bytes remain stable", async () => {
+  assert.ok(Object.keys(baseline.fileSha256).length >= 14);
+  for (const [path, expected] of Object.entries(baseline.fileSha256)) {
+    const actual = createHash("sha256")
+      .update(await readFile(resolve(root, path)))
+      .digest("hex");
+    assert.equal(actual, expected, `${path} changed`);
+  }
+});

package/videos/oddlyalive-demos/BRIEF.md

@@ -0,0 +1,40 @@
+---
+workflow: general-video
+flow: automation
+storyboard: no
+message: "OddlyAlive turns ordinary objects into deterministic, physically believable motion."
+destination: github-and-social
+aspect: 1920x1080
+language: en
+audience: creative-coders
+length: 32s
+angle: product-demo
+---
+
+## Intent
+
+Create a local-first demo package for the OddlyAlive open-source alpha. Each
+recipe must show the real solver and renderer at work, preserve the gallery's
+paper-and-ink identity, and make the physical behavior understandable without
+voice-over.
+
+## Assets
+
+- `../../src/` — the current OddlyAlive engine, bundled into the render so the
+  browser runtime has no external dependency.
+- `../../assets/photoreal/` — locally frozen transparent object cutouts shared
+  with the browser examples; provenance is recorded beside the assets.
+
+## Customizations
+
+- Five faithful 6.4-second recipe demos.
+- One 32-second combined reel.
+- One lightweight GIF preview for the repository README.
+- Silent by design so the demos work in GitHub, npm, and social previews.
+
+## Notes
+
+- No stock footage or third-party artwork; locally generated photographic
+  cutouts provide material detail while SVG owns deformation and physics.
+- No live network data.
+- Do not commit, push, release, or publish until the user reviews the package.

package/videos/oddlyalive-demos/DEMO-PLAN.md

@@ -0,0 +1,13 @@
+# OddlyAlive demo plan
+
+| Time | Recipe | Physical idea | Visual proof |
+| --- | --- | --- | --- |
+| 00:00–00:06.4 | String Touch | Local contact, grip, slip, peel, and settle | Only nearby strands catch; every strand releases independently |
+| 00:06.4–00:12.8 | Crystal Mobile | Coupled pendulum-like strands with weighted payloads | Crystals lag, overshoot, and settle at different rates |
+| 00:12.8–00:19.2 | Ball Lab | Mass, restitution, friction, and collision | Three familiar balls bounce and roll with distinct character |
+| 00:19.2–00:25.6 | Football Kick | A timed impulse under gravity | The ball launches, spins, bounces, and loses energy naturally |
+| 00:25.6–00:32.0 | Shoe Splash | Rigid-body entry coupled to a wave surface | The shoe displaces water, floats, and leaves propagating waves |
+
+Each scene uses the current OddlyAlive implementation at 60 fps with four
+solver substeps per frame. The reel uses hard cuts so no transition hides the
+start or end state of a simulation.

package/videos/oddlyalive-demos/README.md

@@ -0,0 +1,45 @@
+# OddlyAlive demo composition
+
+This HyperFrames project renders the current five OddlyAlive recipes from the
+real deterministic engine.
+
+## Local preview
+
+```bash
+npm ci
+npm run build:bundle
+npm run dev
+```
+
+## Validate
+
+```bash
+npm run check
+```
+
+## Render the 32-second reel
+
+```bash
+npm run render -- \
+  -o renders/oddlyalive-demos-overview.mp4 \
+  --fps 60 \
+  --quality high \
+  --strict
+```
+
+The root-level `npm run demos:render` command is the preferred path because it
+also cuts the five clips, rebuilds the README GIF, and verifies every encode.
+
+## Source map
+
+- `BRIEF.md` — intent and delivery constraints
+- `DEMO-PLAN.md` — exact five-scene sequence
+- `index.html` — visual system and timed clips
+- `app.js` — scene configuration, simulation, and seek-safe timeline
+- `../../src/` — current OddlyAlive source bundled by esbuild
+- `../../assets/photoreal/` — canonical high-resolution object cutouts
+- `prepare-assets.mjs` — copies canonical cutouts into the ignored local render cache
+- `app.bundle.js` — generated by `npm run build:bundle` and ignored by Git
+- `renders/`, `review/`, `snapshots/` — generated and ignored by Git
+
+No Git or publishing command is part of this project.