oddlyalive 0.2.0-alpha.2

package/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to OddlyAlive are documented here. This project follows
+[Semantic Versioning](https://semver.org/) for its public package versions.
+
+## [Unreleased]
+
+## [0.2.0-alpha.2] - 2026-07-21
+
+### Added
+
+- Photographic, provenance-tracked object cutouts shared by the public gallery
+  and the deterministic HyperFrames demo composition.
+- Five 6.4-second recipe demos and a 32-second high-quality overview render.
+- Automated visual-contract fixtures covering all recipe fingerprints,
+  renderer sources, composition sources, and approved image assets.
+- GitHub Actions CI, contribution guidance, security policy, issue forms, and
+  pull-request template.
+
+### Changed
+
+- Rebuilt the strand, crystal, rigid-body, football, and wave renderers around
+  hybrid photographic materials and simulated SVG deformation.
+- Consolidated demo assets under `assets/photoreal/` with explicit provenance.
+- Set the canonical package homepage to the public OddlyAlive project showcase at
+  `https://thevibefounder.com/os/oddlyalive/`.
+
+### Fixed
+
+- Included the photographic asset library and correct PNG response types in
+  generated recipe projects.
+- Kept generated HyperFrames bundles, render outputs, media caches, snapshots,
+  and Studio thumbnails out of source control and npm package contents.
+
+## [0.2.0-alpha.1] - 2026-07-18
+
+### Added
+
+- Initial public alpha with deterministic strand, rigid-circle, and coupled
+  surface-wave solvers.
+- JSON scene schema, CLI, five browser recipes, diagnostics, and Codex skill.
+
+[Unreleased]: https://github.com/thevibefounder/OddlyAlive/compare/v0.2.0-alpha.2...HEAD
+[0.2.0-alpha.2]: https://github.com/thevibefounder/OddlyAlive/compare/v0.2.0-alpha.1...v0.2.0-alpha.2
+[0.2.0-alpha.1]: https://github.com/thevibefounder/OddlyAlive/releases/tag/v0.2.0-alpha.1

package/CONTRIBUTING.md

@@ -0,0 +1,62 @@
+# Contributing to OddlyAlive
+
+Thanks for helping make deterministic object motion more useful and easier to
+understand.
+
+## Development setup
+
+OddlyAlive requires Node.js 20 or newer. The demo-video pipeline additionally
+requires FFmpeg.
+
+```bash
+npm ci
+npm start
+```
+
+Run the complete repository gate before opening a pull request:
+
+```bash
+npm run check
+```
+
+For changes to the HyperFrames demo composition:
+
+```bash
+cd videos/oddlyalive-demos
+npm ci
+npm run check
+```
+
+## Project invariants
+
+- AI may describe scene intent; deterministic simulation authors the motion.
+- Simulations use fixed timesteps and may not depend on wall-clock time.
+- Seeded material variation and diagnostic fingerprints must remain
+  reproducible.
+- Choose a physical model that fits the object family. Do not describe a
+  recipe as physically universal.
+- Keep solvers renderer-agnostic. SVG is the reference renderer, not the
+  physics representation.
+- Disclose whether example artwork is original, generated, licensed, or only
+  used as reference.
+
+## Visual fixture changes
+
+`tests/fixtures/visual-baselines.json` protects every shipped recipe's
+simulation fingerprint and the approved bytes that define its appearance.
+When an intentional visual change has been reviewed in the browser, update the
+fixture explicitly:
+
+```bash
+npm run fixtures:update
+npm run test:visual
+```
+
+Include before/after screenshots or a short capture in the pull request. A
+baseline update without visual evidence should not be merged.
+
+## Pull requests
+
+Keep changes focused, add or update tests for behavioral changes, and explain
+which solver or renderer family is affected. Generated MP4 files belong in
+release assets, not Git history.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 TheVibeFounder
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,158 @@
+# OddlyAlive
+
+**Make anything feel alive.**
+
+[Project page](https://thevibefounder.com/os/oddlyalive/) ·
+[Source](https://github.com/thevibefounder/OddlyAlive)
+
+OddlyAlive is an open-source toolkit for natural, deterministic object motion.
+Describe the physical setup once; the solver produces every frame.
+
+The toolkit began with the tactile strand interaction developed for
+TheVibeFounder’s city-postcard series. It now ships three small, inspectable
+solver families: flexible strands, rigid balls, and a rigid prop coupled to a
+damped wave surface.
+
+![OddlyAlive string-touch recipe](docs/assets/oddlyalive-string-touch.gif)
+
+No runtime dependencies. No cloud account. No animation keyframes.
+
+## Start in 60 seconds
+
+```bash
+git clone https://github.com/thevibefounder/OddlyAlive.git
+cd OddlyAlive
+npm start
+```
+
+Open the printed local URL and choose a recipe. Nothing is uploaded; the
+simulation and SVG rendering run locally.
+
+For the full install, customization, and scene-authoring path, read
+[`docs/QUICKSTART.md`](docs/QUICKSTART.md).
+
+## Try the repository
+
+```bash
+npm start
+```
+
+Then open the printed local URL. The gallery contains five SVG-rendered physics
+examples with local high-resolution object cutouts, simulated at a fixed 240Hz
+and rendered at 60fps.
+
+## Built-in recipes
+
+| Recipe | Physical idea | Good for |
+|---|---|---|
+| `string-touch` | XPBD strands + pressure/friction contact | strings, charms, garlands, hanging type |
+| `crystal-mobile` | weighted terminal masses on strands | crystals, pendants, mobiles |
+| `ball-lab` | rigid circles + material response | balls, marbles, loose round props |
+| `football-kick` | one impulse + gravity/spin/friction | kicks, hits, throws |
+| `shoe-splash` | rigid prop + damped 1D surface | graphic splashes, floating props, ripples |
+
+```bash
+npx oddlyalive list
+npx oddlyalive play crystal-mobile
+npx oddlyalive play football-kick
+```
+
+Create a self-contained starter:
+
+```bash
+npx oddlyalive new my-motion \
+  --preset football-kick
+
+cd my-motion
+npm start
+```
+
+Inspect or simulate any scene without opening a browser:
+
+```bash
+npx oddlyalive inspect scene.json
+npx oddlyalive simulate scene.json --output result.json
+```
+
+`schemas/scene.schema.json` provides editor autocomplete and catches malformed
+recipes before simulation.
+
+## Why this exists
+
+Most prompt-to-animation systems ask a model to guess transforms frame by frame.
+OddlyAlive uses the model only to select and configure physical intent:
+
+```text
+prompt → scene recipe → constraints + gesture → simulation → renderer
+```
+
+The same scene gives the same frames on every run. That makes the result
+seek-safe, testable, renderable in the browser, and suitable for video pipelines.
+
+## Alpha scope
+
+Available now:
+
+- XPBD strand fields with length, bend, and anchor constraints
+- `FREE → STICK → SLIP → COOLDOWN` friction per strand
+- Elliptical touch capsule with pressure
+- Deterministic seeded material variation
+- SVG reference renderer
+- JSON scene schema and diagnostics
+- Deterministic circle collisions, restitution, friction, spin and impulses
+- Weighted strand payloads for pendants and crystals
+- Damped 1D wave surface coupled to a falling rigid prop
+- Five one-command browser demos and project presets
+- Bundled Codex skill
+
+Planned object families:
+
+- articulated walking bodies with joints and inverse kinematics
+- articulated flowers, rackets, and hinged mobiles
+- cloth, banners, and garlands
+- a prompt compiler for local models and cloud agents
+
+## Library usage
+
+```js
+import {
+  createStringTouchScene,
+  simulateScene
+} from "oddlyalive";
+
+const scene = createStringTouchScene({
+  payload: { text: "HELLO PHYSICS" }
+});
+
+const result = simulateScene(scene);
+console.log(result.diagnostics);
+```
+
+See `examples/` for the complete browser gallery and
+`docs/ARCHITECTURE.md` for the separation between AI, physics, and rendering.
+Contributions are welcome; start with [`CONTRIBUTING.md`](CONTRIBUTING.md).
+
+## Rebuild the demo videos
+
+With Node 20+ and FFmpeg installed:
+
+```bash
+npm run demos:render
+npm run demos:verify
+```
+
+This produces a 32-second reel, five 6.4-second recipe clips, and the README
+GIF from the same deterministic simulations. See
+[`docs/DEMO-VIDEOS.md`](docs/DEMO-VIDEOS.md) for output paths, preview commands,
+and the review-before-publish protocol.
+
+## Status
+
+`0.2.0-alpha.2` is a focused technical preview. The five listed recipes are
+real and deterministic; full fluid dynamics, cloth, articulated walking, and
+the broader “animate any object” prompt compiler remain roadmap items.
+
+## License
+
+MIT. Example artwork is original or generated specifically for this project;
+see [`assets/photoreal/PROVENANCE.md`](assets/photoreal/PROVENANCE.md).

package/SECURITY.md

@@ -0,0 +1,29 @@
+# Security policy
+
+## Supported versions
+
+OddlyAlive is currently an alpha. Security fixes are applied to the newest
+`0.2.x` prerelease only.
+
+| Version | Supported |
+| --- | --- |
+| `0.2.x` alpha | Yes |
+| Earlier versions | No |
+
+## Reporting a vulnerability
+
+Please use GitHub's private vulnerability reporting for this repository:
+
+1. Open the repository's **Security** tab.
+2. Choose **Report a vulnerability**.
+3. Include reproduction steps, affected versions, impact, and any suggested
+   mitigation.
+
+Do not open a public issue for an unpatched vulnerability. Maintainers will
+acknowledge a report as soon as practical and coordinate disclosure after a
+fix is available.
+
+OddlyAlive executes local scene recipes and serves a local development site.
+Reports involving path traversal, unintended network access, malicious scene
+input, generated-project integrity, or package-install behavior are especially
+useful.

package/assets/photoreal/PROVENANCE.md

@@ -0,0 +1,19 @@
+# Photoreal example assets
+
+These transparent PNG object cutouts were generated specifically for
+OddlyAlive with OpenAI's image-generation tooling on 2026-07-19. They do not
+contain stock photography, brand marks, or third-party source pixels.
+
+The generation prompts requested isolated studio-product photographs on a
+solid chroma background: a soccer ball, basketball, baseball, white canvas
+sneaker, faceted champagne crystal pendant, white soccer cleat with lower leg,
+and two ivory-enamel/brass letter-charm shapes. The chroma backgrounds were
+removed locally with a soft matte and despill pass. Only the final transparent
+cutouts are distributed; chroma intermediates and review renders are excluded.
+
+The files are used solely as appearance layers. OddlyAlive's deterministic
+solvers still calculate the bodies, constraints, collisions, net response,
+surface waves, and every output frame.
+
+The project distributes these generated assets under the repository's MIT
+license to the extent permitted by applicable law.

package/bin/oddlyalive.js

@@ -0,0 +1,283 @@
+#!/usr/bin/env node
+
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  writeFileSync
+} from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { simulateScene, validateScene } from "../src/index.js";
+import { startServer } from "../scripts/serve.js";
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const commands = new Set(["help", "inspect", "list", "new", "play", "simulate"]);
+const presets = new Map([
+  ["string-touch", "deterministic XPBD strand field"],
+  ["crystal-mobile", "weighted payloads on flexible strands"],
+  ["ball-lab", "rigid-body material comparison"],
+  ["football-kick", "single-impulse flight, bounce and roll"],
+  ["shoe-splash", "rigid prop coupled to a damped wave surface"]
+]);
+
+function flagValue(args, flag, fallback = undefined) {
+  const index = args.indexOf(flag);
+  return index === -1 ? fallback : args[index + 1];
+}
+
+function printHelp() {
+  console.log(`OddlyAlive — Make anything feel alive.
+
+Usage:
+  oddlyalive play [gallery|preset] [--port 4173] [--no-open]
+  oddlyalive new <directory> [--preset string-touch] [--text "HELLO"]
+  oddlyalive inspect <scene.json>
+  oddlyalive simulate <scene.json> [--output result.json]
+  oddlyalive list
+
+Start here:
+  npx oddlyalive play
+  npx oddlyalive play football-kick
+`);
+}
+
+function loadScene(path) {
+  if (!path) throw new TypeError("A scene.json path is required.");
+  return validateScene(JSON.parse(readFileSync(resolve(path), "utf8")));
+}
+
+function diagnosticSummary(result) {
+  const { scene, diagnostics, fingerprint } = result;
+  const common = {
+    ok: true,
+    name: scene.name,
+    type: scene.type,
+    seed: scene.seed,
+    duration: scene.timing.duration,
+    fps: scene.timing.fps,
+    simulationHz: scene.timing.fps * scene.timing.substeps,
+    frameCount: Math.round(scene.timing.duration * scene.timing.fps) + 1,
+    fingerprint
+  };
+  if (scene.type === "strand-field") {
+    return {
+      ...common,
+      particleCount: scene.field.columns * scene.field.rows,
+      configuredStaticGripCap: scene.contact.maxStaticGrip,
+      observedMaxStaticGrip: diagnostics.observedMaxStaticGrip,
+      observedMaxCombinedContact: diagnostics.observedMaxCombinedContact,
+      firstGripTime: diagnostics.firstGripTime,
+      lastGripTime: diagnostics.lastGripTime,
+      observedMaxStretch: diagnostics.observedMaxStretch,
+      maxStretchPerProjection: scene.material.maxStretch
+    };
+  }
+  if (scene.type === "rigid-balls") {
+    return {
+      ...common,
+      bodyCount: scene.bodies.length,
+      collisionCount: diagnostics.collisionCount,
+      firstImpactTime: diagnostics.firstImpactTime,
+      maxSpeed: diagnostics.maxSpeed,
+      maxPenetration: diagnostics.maxPenetration,
+      appliedImpulses: diagnostics.appliedImpulses,
+      finalRestingBodies: diagnostics.finalRestingBodies
+    };
+  }
+  return {
+    ...common,
+    surfaceSamples: scene.surface.samples,
+    impactCount: diagnostics.impactCount,
+    firstImpactTime: diagnostics.firstImpactTime,
+    maxWaveHeight: diagnostics.maxWaveHeight,
+    maxSubmersion: diagnostics.maxSubmersion,
+    maxBodySpeed: diagnostics.maxBodySpeed
+  };
+}
+
+function createStarter(args) {
+  const targetArgument = args[0]?.startsWith("-") ? undefined : args[0];
+  if (!targetArgument) {
+    throw new TypeError("Provide a directory name: oddlyalive new my-motion");
+  }
+  const target = resolve(targetArgument);
+  const preset = flagValue(args, "--preset", "string-touch");
+  const text = flagValue(args, "--text");
+  if (!presets.has(preset)) {
+    throw new RangeError(`Unknown preset: ${preset}`);
+  }
+  if (existsSync(target) && readdirSync(target).length > 0) {
+    throw new Error(`Target directory is not empty: ${target}`);
+  }
+
+  mkdirSync(target, { recursive: true });
+  cpSync(join(packageRoot, "src"), join(target, "src"), { recursive: true });
+  cpSync(
+    join(packageRoot, "examples", preset),
+    join(target, "examples", preset),
+    { recursive: true }
+  );
+  cpSync(
+    join(packageRoot, "examples", "shared"),
+    join(target, "examples", "shared"),
+    { recursive: true }
+  );
+  cpSync(join(packageRoot, "schemas"), join(target, "schemas"), {
+    recursive: true
+  });
+  cpSync(join(packageRoot, "assets"), join(target, "assets"), {
+    recursive: true
+  });
+  mkdirSync(join(target, "scripts"), { recursive: true });
+  cpSync(
+    join(packageRoot, "scripts", "serve.js"),
+    join(target, "scripts", "serve.js")
+  );
+
+  const scenePath = join(target, "examples", preset, "scene.json");
+  const scene = JSON.parse(readFileSync(scenePath, "utf8"));
+  if (text) {
+    scene.name = `${text} — OddlyAlive`;
+    if (scene.type === "strand-field") {
+      scene.payload.text = `${text}  •  `;
+    }
+  }
+  writeFileSync(scenePath, `${JSON.stringify(scene, null, 2)}\n`);
+  const exampleIndexPath = join(target, "examples", preset, "index.html");
+  const exampleIndex = readFileSync(exampleIndexPath, "utf8")
+    .replaceAll('href="../"', 'href="./"')
+    .replace(
+      /<nav>[\s\S]*?<\/nav>/,
+      '<nav><a href="./">LOCAL RECIPE</a></nav>'
+    );
+  writeFileSync(exampleIndexPath, exampleIndex);
+
+  const packageName = basename(target)
+    .toLowerCase()
+    .replace(/[^a-z0-9-]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  writeFileSync(
+    join(target, "package.json"),
+    `${JSON.stringify(
+      {
+        name: packageName || "oddlyalive-motion",
+        private: true,
+        type: "module",
+        scripts: {
+          start: `node ./scripts/serve.js --path /examples/${preset}/`
+        }
+      },
+      null,
+      2
+    )}\n`
+  );
+  writeFileSync(
+    join(target, "README.md"),
+    `# ${text ?? scene.name}\n\nGenerated from the OddlyAlive \`${preset}\` recipe.\n\n\`\`\`bash\nnpm start\n\`\`\`\n\nEdit \`examples/${preset}/scene.json\` to change the world, material, objects, or timing.\n`
+  );
+
+  console.log(`Created ${target}`);
+  console.log(`Next:\n  cd ${target}\n  npm start`);
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const command = args[0] ?? "help";
+  if (!commands.has(command)) {
+    throw new RangeError(`Unknown command: ${command}`);
+  }
+
+  if (command === "help") {
+    printHelp();
+    return;
+  }
+
+  if (command === "list") {
+    console.log(
+      `Available recipes:\n${[...presets]
+        .map(([name, description]) => `  ${name.padEnd(16)} ${description}`)
+        .join("\n")}`
+    );
+    return;
+  }
+
+  if (command === "play") {
+    const preset =
+      args[1]?.startsWith("-") ? "gallery" : args[1] ?? "gallery";
+    if (preset !== "gallery" && !presets.has(preset)) {
+      throw new RangeError(`Unknown preset: ${preset}`);
+    }
+    const port = Number(flagValue(args, "--port", 4173));
+    await startServer({
+      root: packageRoot,
+      port,
+      pathname: preset === "gallery" ? "/examples/" : `/examples/${preset}/`,
+      shouldOpen: !args.includes("--no-open")
+    });
+    return;
+  }
+
+  if (command === "new") {
+    createStarter(args.slice(1));
+    return;
+  }
+
+  if (command === "inspect") {
+    const scene = loadScene(args[1]);
+    const details =
+      scene.type === "strand-field"
+        ? {
+            particles: scene.field.columns * scene.field.rows,
+            gesturePoints: scene.gesture.points.length,
+            configuredStaticGripCap: scene.contact.maxStaticGrip
+          }
+        : scene.type === "rigid-balls"
+          ? {
+              bodies: scene.bodies.length,
+              scheduledImpulses: scene.impulses.length,
+              floorY: scene.world.floorY
+            }
+          : {
+              surfaceSamples: scene.surface.samples,
+              bodyKind: scene.body.kind,
+              surfaceY: scene.surface.restY
+            };
+    console.log(
+      JSON.stringify(
+        {
+          ok: true,
+          name: scene.name,
+          version: scene.version,
+          type: scene.type,
+          canvas: scene.canvas,
+          timing: scene.timing,
+          ...details
+        },
+        null,
+        2
+      )
+    );
+    return;
+  }
+
+  if (command === "simulate") {
+    const scene = loadScene(args[1]);
+    const result = simulateScene(scene, { includeFrames: false });
+    const summary = diagnosticSummary(result);
+    const output = flagValue(args, "--output");
+    if (output) {
+      writeFileSync(resolve(output), `${JSON.stringify(summary, null, 2)}\n`);
+      console.log(`Wrote ${resolve(output)}`);
+    } else {
+      console.log(JSON.stringify(summary, null, 2));
+    }
+  }
+}
+
+main().catch((error) => {
+  console.error(`OddlyAlive: ${error.message}`);
+  process.exitCode = 1;
+});

package/docs/ARCHITECTURE.md

@@ -0,0 +1,55 @@
+# Architecture
+
+OddlyAlive separates creative intent from physical truth.
+
+## Layers
+
+1. **Prompt compiler** — converts language into a validated scene recipe. This
+   layer may run through Codex, another cloud model, or a local model.
+2. **Scene schema** — declares bodies, constraints, material ranges, gestures,
+   duration, frame rate, and seed.
+3. **Physics recipes** — select a solver appropriate to the object family.
+4. **Simulation** — advances at a fixed timestep and emits renderer-neutral
+   transforms plus diagnostics.
+5. **Render adapters** — map transforms to SVG, Canvas, WebGL, HyperFrames, or a
+   frame sequence.
+
+## Alpha data flow
+
+```text
+scene.json
+        │
+        ├── validate by scene type
+        ├── select strand / rigid / wave solver
+        ├── simulate at 240Hz
+        └── sample states at output fps
+                  │
+                  ├── SVG browser renderer
+                  └── JSON diagnostics
+```
+
+## Determinism contract
+
+- Advance simulation using `1 / (fps × substeps)`.
+- Sample an authored gesture by simulation time, never wall-clock time.
+- Seed all material variation from the scene.
+- Store live state in `Float64Array`.
+- Reset constraint lambdas at each substep.
+- Hash rounded output state in tests.
+- A renderer may interpolate states but must never modify simulation state.
+
+## Object-family boundary
+
+No individual solver is a universal physics engine. Recipes currently use:
+
+- strand XPBD for strings, garlands, stems, and ropes;
+- weighted strand terminals for crystals and pendants;
+- rigid-circle dynamics for balls and kickable round props;
+- a damped 1D surface coupled to one rigid prop for stylized water ripples.
+
+Future recipes should use cloth XPBD for connected surfaces and articulated
+joints plus inverse kinematics for walking bodies, rackets, flowers, and
+mechanisms.
+
+The prompt compiler selects a recipe. It must not force unrelated objects through
+the strand model simply because that solver already exists.