oddlyalive 0.2.0-alpha.2

package/schemas/scene.schema.json

@@ -0,0 +1,336 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://oddlyalive.dev/schemas/scene.schema.json",
+  "title": "OddlyAlive scene",
+  "oneOf": [
+    { "$ref": "#/$defs/strandScene" },
+    { "$ref": "#/$defs/rigidScene" },
+    { "$ref": "#/$defs/waveScene" }
+  ],
+  "$defs": {
+    "schemaProperty": { "type": "string" },
+    "version": { "const": 1 },
+    "name": { "type": "string", "minLength": 1 },
+    "seed": { "type": "number" },
+    "canvas": {
+      "type": "object",
+      "required": ["width", "height"],
+      "properties": {
+        "width": { "type": "number", "minimum": 64 },
+        "height": { "type": "number", "minimum": 64 }
+      },
+      "additionalProperties": false
+    },
+    "timing": {
+      "type": "object",
+      "required": ["duration", "fps", "substeps", "preRoll"],
+      "properties": {
+        "duration": { "type": "number", "minimum": 0.1, "maximum": 60 },
+        "fps": { "type": "integer", "minimum": 1, "maximum": 240 },
+        "substeps": { "type": "integer", "minimum": 1, "maximum": 16 },
+        "preRoll": { "type": "number", "minimum": 0, "maximum": 30 }
+      },
+      "additionalProperties": false
+    },
+    "strandScene": {
+      "type": "object",
+      "required": [
+        "version",
+        "type",
+        "seed",
+        "canvas",
+        "timing",
+        "field",
+        "material",
+        "contact",
+        "gesture",
+        "payload"
+      ],
+      "properties": {
+        "$schema": { "$ref": "#/$defs/schemaProperty" },
+        "version": { "$ref": "#/$defs/version" },
+        "type": { "const": "strand-field" },
+        "name": { "$ref": "#/$defs/name" },
+        "seed": { "$ref": "#/$defs/seed" },
+        "canvas": { "$ref": "#/$defs/canvas" },
+        "timing": { "$ref": "#/$defs/timing" },
+        "field": {
+          "type": "object",
+          "required": [
+            "columns",
+            "rows",
+            "originX",
+            "originY",
+            "spacingX",
+            "spacingY"
+          ],
+          "properties": {
+            "columns": { "type": "integer", "minimum": 1, "maximum": 128 },
+            "rows": { "type": "integer", "minimum": 3, "maximum": 128 },
+            "originX": { "type": "number" },
+            "originY": { "type": "number" },
+            "spacingX": { "type": "number", "exclusiveMinimum": 0 },
+            "spacingY": { "type": "number", "exclusiveMinimum": 0 }
+          },
+          "additionalProperties": false
+        },
+        "material": {
+          "type": "object",
+          "required": [
+            "gravity",
+            "linearDrag",
+            "quadraticDrag",
+            "lengthCompliance",
+            "compressionCompliance",
+            "bendCompliance",
+            "maxStretch"
+          ],
+          "properties": {
+            "gravity": { "type": "number" },
+            "linearDrag": { "type": "number", "minimum": 0 },
+            "quadraticDrag": { "type": "number", "minimum": 0 },
+            "lengthCompliance": { "type": "number", "minimum": 0 },
+            "compressionCompliance": { "type": "number", "minimum": 0 },
+            "bendCompliance": { "type": "number", "minimum": 0 },
+            "maxStretch": { "type": "number", "minimum": 1, "maximum": 1.5 }
+          },
+          "additionalProperties": false
+        },
+        "contact": {
+          "type": "object",
+          "required": [
+            "radiusX",
+            "radiusY",
+            "maxStaticGrip",
+            "captureStartRow",
+            "captureEndRow"
+          ],
+          "properties": {
+            "radiusX": { "type": "number", "exclusiveMinimum": 0 },
+            "radiusY": { "type": "number", "exclusiveMinimum": 0 },
+            "maxStaticGrip": { "type": "integer", "minimum": 1 },
+            "captureStartRow": { "type": "integer", "minimum": 0 },
+            "captureEndRow": { "type": "integer", "minimum": 0 }
+          },
+          "additionalProperties": false
+        },
+        "gesture": {
+          "type": "object",
+          "required": ["type", "points"],
+          "properties": {
+            "type": { "const": "touch-path" },
+            "points": {
+              "type": "array",
+              "minItems": 2,
+              "items": {
+                "type": "object",
+                "required": ["time", "x", "y", "pressure"],
+                "properties": {
+                  "time": { "type": "number" },
+                  "x": { "type": "number" },
+                  "y": { "type": "number" },
+                  "pressure": { "type": "number", "minimum": 0, "maximum": 1 }
+                },
+                "additionalProperties": false
+              }
+            }
+          },
+          "additionalProperties": false
+        },
+        "payload": {
+          "type": "object",
+          "required": ["text", "fontFamily", "fontSize"],
+          "properties": {
+            "text": { "type": "string", "minLength": 1 },
+            "fontFamily": { "type": "string", "minLength": 1 },
+            "fontSize": { "type": "number", "exclusiveMinimum": 0 },
+            "terminalMass": { "type": "number", "minimum": 0.1, "maximum": 50 }
+          },
+          "additionalProperties": false
+        },
+        "render": {
+          "type": "object",
+          "properties": {
+            "background": { "type": "string" },
+            "ink": { "type": "string" },
+            "accent": { "type": "string" },
+            "filament": { "type": "string" }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    },
+    "rigidScene": {
+      "type": "object",
+      "required": [
+        "version",
+        "type",
+        "seed",
+        "canvas",
+        "timing",
+        "world",
+        "bodies",
+        "impulses"
+      ],
+      "properties": {
+        "$schema": { "$ref": "#/$defs/schemaProperty" },
+        "version": { "$ref": "#/$defs/version" },
+        "type": { "const": "rigid-balls" },
+        "name": { "$ref": "#/$defs/name" },
+        "seed": { "$ref": "#/$defs/seed" },
+        "canvas": { "$ref": "#/$defs/canvas" },
+        "timing": { "$ref": "#/$defs/timing" },
+        "world": {
+          "type": "object",
+          "required": ["gravity", "airDrag", "floorY", "left", "right", "groundFriction"],
+          "properties": {
+            "gravity": { "type": "number" },
+            "airDrag": { "type": "number", "minimum": 0 },
+            "floorY": { "type": "number" },
+            "left": { "type": "number" },
+            "right": { "type": "number" },
+            "groundFriction": { "type": "number", "minimum": 0 }
+          },
+          "additionalProperties": false
+        },
+        "bodies": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 64,
+          "items": {
+            "type": "object",
+            "required": [
+              "id",
+              "kind",
+              "x",
+              "y",
+              "radius",
+              "mass",
+              "restitution",
+              "friction",
+              "vx",
+              "vy",
+              "angle",
+              "angularVelocity",
+              "color"
+            ],
+            "properties": {
+              "id": { "type": "string", "minLength": 1 },
+              "kind": { "type": "string", "minLength": 1 },
+              "label": { "type": "string" },
+              "x": { "type": "number" },
+              "y": { "type": "number" },
+              "radius": { "type": "number", "exclusiveMinimum": 0 },
+              "mass": { "type": "number", "exclusiveMinimum": 0 },
+              "restitution": { "type": "number", "minimum": 0, "maximum": 1 },
+              "friction": { "type": "number", "minimum": 0, "maximum": 1 },
+              "vx": { "type": "number" },
+              "vy": { "type": "number" },
+              "angle": { "type": "number" },
+              "angularVelocity": { "type": "number" },
+              "color": { "type": "string" }
+            },
+            "additionalProperties": false
+          }
+        },
+        "impulses": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["time", "body", "impulseX", "impulseY"],
+            "properties": {
+              "time": { "type": "number", "minimum": 0 },
+              "body": { "type": "string", "minLength": 1 },
+              "impulseX": { "type": "number" },
+              "impulseY": { "type": "number" },
+              "angularImpulse": { "type": "number" }
+            },
+            "additionalProperties": false
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "waveScene": {
+      "type": "object",
+      "required": [
+        "version",
+        "type",
+        "seed",
+        "canvas",
+        "timing",
+        "surface",
+        "world",
+        "body"
+      ],
+      "properties": {
+        "$schema": { "$ref": "#/$defs/schemaProperty" },
+        "version": { "$ref": "#/$defs/version" },
+        "type": { "const": "surface-wave" },
+        "name": { "$ref": "#/$defs/name" },
+        "seed": { "$ref": "#/$defs/seed" },
+        "canvas": { "$ref": "#/$defs/canvas" },
+        "timing": { "$ref": "#/$defs/timing" },
+        "surface": {
+          "type": "object",
+          "required": ["x", "width", "restY", "samples", "waveSpeed", "damping", "coupling"],
+          "properties": {
+            "x": { "type": "number" },
+            "width": { "type": "number", "exclusiveMinimum": 0 },
+            "restY": { "type": "number" },
+            "samples": { "type": "integer", "minimum": 16, "maximum": 1024 },
+            "waveSpeed": { "type": "number", "exclusiveMinimum": 0 },
+            "damping": { "type": "number", "minimum": 0 },
+            "coupling": { "type": "number", "minimum": 0 }
+          },
+          "additionalProperties": false
+        },
+        "world": {
+          "type": "object",
+          "required": ["gravity", "airDrag", "waterDrag", "buoyancy"],
+          "properties": {
+            "gravity": { "type": "number" },
+            "airDrag": { "type": "number", "minimum": 0 },
+            "waterDrag": { "type": "number", "minimum": 0 },
+            "buoyancy": { "type": "number", "minimum": 0 }
+          },
+          "additionalProperties": false
+        },
+        "body": {
+          "type": "object",
+          "required": [
+            "id",
+            "kind",
+            "x",
+            "y",
+            "width",
+            "height",
+            "mass",
+            "vx",
+            "vy",
+            "angle",
+            "angularVelocity",
+            "restitution"
+          ],
+          "properties": {
+            "id": { "type": "string", "minLength": 1 },
+            "kind": { "type": "string", "minLength": 1 },
+            "x": { "type": "number" },
+            "y": { "type": "number" },
+            "width": { "type": "number", "exclusiveMinimum": 0 },
+            "height": { "type": "number", "exclusiveMinimum": 0 },
+            "mass": { "type": "number", "exclusiveMinimum": 0 },
+            "vx": { "type": "number" },
+            "vy": { "type": "number" },
+            "angle": { "type": "number" },
+            "angularVelocity": { "type": "number" },
+            "restitution": { "type": "number", "minimum": 0, "maximum": 1 }
+          },
+          "additionalProperties": false
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/scripts/render-demo-videos.sh

@@ -0,0 +1,77 @@
+#!/bin/sh
+
+set -eu
+
+ROOT_DIR=$(CDPATH= cd -- "$(dirname "$0")/.." && pwd)
+PROJECT_DIR="$ROOT_DIR/videos/oddlyalive-demos"
+MASTER="$PROJECT_DIR/renders/oddlyalive-demos-overview.mp4"
+CLIPS_DIR="$PROJECT_DIR/renders/demos"
+WORKERS="${HF_WORKERS:-2}"
+
+command -v node >/dev/null 2>&1 || {
+  echo "Node.js 20+ is required." >&2
+  exit 1
+}
+command -v npm >/dev/null 2>&1 || {
+  echo "npm is required." >&2
+  exit 1
+}
+command -v ffmpeg >/dev/null 2>&1 || {
+  echo "FFmpeg is required." >&2
+  exit 1
+}
+command -v ffprobe >/dev/null 2>&1 || {
+  echo "ffprobe is required." >&2
+  exit 1
+}
+
+cd "$PROJECT_DIR"
+npm ci
+npm run build:bundle
+npx --yes hyperframes@0.7.66 check
+mkdir -p "$CLIPS_DIR"
+npx --yes hyperframes@0.7.66 render \
+  -o "$MASTER" \
+  --fps 60 \
+  --quality high \
+  --workers "$WORKERS" \
+  --skill general-video \
+  --strict
+
+cut_clip() {
+  start="$1"
+  output="$2"
+  ffmpeg -hide_banner -loglevel error -y \
+    -ss "$start" \
+    -i "$MASTER" \
+    -t 6.4 \
+    -an \
+    -c:v libx264 \
+    -preset slow \
+    -crf 18 \
+    -pix_fmt yuv420p \
+    -profile:v high \
+    -movflags +faststart \
+    "$CLIPS_DIR/$output"
+}
+
+cut_clip 0 "01-string-touch.mp4"
+cut_clip 6.4 "02-crystal-mobile.mp4"
+cut_clip 12.8 "03-ball-lab.mp4"
+cut_clip 19.2 "04-football-kick.mp4"
+cut_clip 25.6 "05-shoe-splash.mp4"
+
+mkdir -p "$ROOT_DIR/docs/assets"
+ffmpeg -hide_banner -loglevel error -y \
+  -i "$CLIPS_DIR/01-string-touch.mp4" \
+  -filter_complex \
+  "[0:v]fps=12,scale=720:-1:flags=lanczos,split[s0][s1];[s0]palettegen=max_colors=96[p];[s1][p]paletteuse=dither=sierra2_4a" \
+  -loop 0 \
+  "$ROOT_DIR/docs/assets/oddlyalive-string-touch.gif"
+
+cd "$ROOT_DIR"
+npm run demos:verify
+
+echo
+echo "Demo package is ready for local review."
+echo "No Git, GitHub, release, or npm state was changed."

package/scripts/serve.js

@@ -0,0 +1,88 @@
+import { createReadStream, existsSync, statSync } from "node:fs";
+import { createServer } from "node:http";
+import { extname, join, normalize, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawn } from "node:child_process";
+
+const MIME_TYPES = {
+  ".css": "text/css; charset=utf-8",
+  ".html": "text/html; charset=utf-8",
+  ".gif": "image/gif",
+  ".js": "text/javascript; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".png": "image/png",
+  ".webp": "image/webp",
+  ".svg": "image/svg+xml"
+};
+
+function openBrowser(url) {
+  const command =
+    process.platform === "darwin"
+      ? ["open", [url]]
+      : process.platform === "win32"
+        ? ["cmd", ["/c", "start", "", url]]
+        : ["xdg-open", [url]];
+  const child = spawn(command[0], command[1], {
+    detached: true,
+    stdio: "ignore"
+  });
+  child.unref();
+}
+
+export function startServer({
+  root = process.cwd(),
+  port = 4173,
+  pathname = "/examples/string-touch/",
+  shouldOpen = true
+} = {}) {
+  const absoluteRoot = resolve(root);
+  const server = createServer((request, response) => {
+    const requestUrl = new URL(request.url ?? "/", "http://localhost");
+    const decodedPath = decodeURIComponent(requestUrl.pathname);
+    let safePath = normalize(decodedPath).replace(/^(\.\.[/\\])+/, "");
+    if (safePath.endsWith("/")) safePath += "index.html";
+    const filePath = join(absoluteRoot, safePath);
+
+    if (
+      !filePath.startsWith(absoluteRoot) ||
+      !existsSync(filePath) ||
+      !statSync(filePath).isFile()
+    ) {
+      response.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
+      response.end("Not found");
+      return;
+    }
+
+    response.writeHead(200, {
+      "cache-control": "no-store",
+      "content-type":
+        MIME_TYPES[extname(filePath)] ?? "application/octet-stream"
+    });
+    createReadStream(filePath).pipe(response);
+  });
+
+  return new Promise((resolvePromise, reject) => {
+    server.once("error", reject);
+    server.listen(port, "127.0.0.1", () => {
+      const url = `http://127.0.0.1:${port}${pathname}`;
+      console.log(`OddlyAlive is playing at ${url}`);
+      if (shouldOpen) openBrowser(url);
+      resolvePromise({ server, url });
+    });
+  });
+}
+
+const isDirect =
+  process.argv[1] &&
+  resolve(process.argv[1]) === resolve(fileURLToPath(import.meta.url));
+
+if (isDirect) {
+  const portIndex = process.argv.indexOf("--port");
+  const pathIndex = process.argv.indexOf("--path");
+  await startServer({
+    port: portIndex === -1 ? 4173 : Number(process.argv[portIndex + 1]),
+    pathname:
+      pathIndex === -1 ? "/examples/string-touch/" : process.argv[pathIndex + 1],
+    shouldOpen: !process.argv.includes("--no-open")
+  });
+}

package/scripts/update-visual-fixtures.mjs

@@ -0,0 +1,60 @@
+import { createHash } from "node:crypto";
+import { readFile, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { simulateScene, validateScene } from "../src/index.js";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const sceneNames = [
+  "string-touch",
+  "crystal-mobile",
+  "ball-lab",
+  "football-kick",
+  "shoe-splash"
+];
+const visualFiles = [
+  "assets/photoreal/baseball.png",
+  "assets/photoreal/basketball.png",
+  "assets/photoreal/crystal.png",
+  "assets/photoreal/kicking-cleat.png",
+  "assets/photoreal/letter-charm-square.png",
+  "assets/photoreal/letter-charm.png",
+  "assets/photoreal/sneaker.png",
+  "assets/photoreal/soccer-ball.png",
+  "src/crystal-renderer.js",
+  "src/rigid-renderer.js",
+  "src/svg-renderer.js",
+  "src/wave-renderer.js",
+  "videos/oddlyalive-demos/app.js",
+  "videos/oddlyalive-demos/index.html"
+];
+
+const sceneFingerprints = {};
+for (const name of sceneNames) {
+  const scene = validateScene(
+    JSON.parse(await readFile(resolve(root, `examples/${name}/scene.json`), "utf8"))
+  );
+  sceneFingerprints[name] = simulateScene(scene, {
+    includeFrames: false
+  }).fingerprint;
+}
+
+const fileSha256 = {};
+for (const path of visualFiles) {
+  fileSha256[path] = createHash("sha256")
+    .update(await readFile(resolve(root, path)))
+    .digest("hex");
+}
+
+const output = {
+  version: 1,
+  description:
+    "Approved deterministic motion and visual-source baselines. Update only after visual review.",
+  sceneFingerprints,
+  fileSha256
+};
+
+const outputPath = resolve(root, "tests/fixtures/visual-baselines.json");
+await writeFile(outputPath, `${JSON.stringify(output, null, 2)}\n`);
+console.log(`Updated ${outputPath}`);