animl-cli 0.0.0-stage → 0.1.0

package/modules/tooling/capabilities/tooling-headless-gamepad/example.animl

@@ -0,0 +1,13 @@
+<anima version="0.1" name="agent-tools" grid="20" requires="data input">
+  <model name="State">
+    <number name="count" default="0"/>
+    <string name="title" default="Hello"/>
+    <bool name="enabled"/>
+  </model>
+  <instance name="main" model="State" default="true"/>
+  <circle id="dot" cx="10" cy="10" r="3" fill="#000"/>
+  <listener on="down" target="dot" set="$count=5"/>
+  <listener on="key-down" target="dot" set="$count=7" key="Enter"/>
+  <listener on="scroll" target="dot" set="$count=9"/>
+  <listener on="gamepad-button" target="dot" set="$count=11" control="0"/>
+</anima>

package/modules/tooling/capabilities/tooling-headless-key/example.ani

@@ -0,0 +1,16 @@
+{
+  "anima": "0.1",
+  "name": "tooling-headless-key",
+  "grid": 20,
+  "nodes": [
+    {
+      "id": "probe",
+      "type": "circle",
+      "center": [10, 10],
+      "r": 1,
+      "fill": {
+        "color": "#000"
+      }
+    }
+  ]
+}

package/modules/tooling/capabilities/tooling-headless-key/example.animl

@@ -0,0 +1,13 @@
+<anima version="0.1" name="agent-tools" grid="20" requires="data input">
+  <model name="State">
+    <number name="count" default="0"/>
+    <string name="title" default="Hello"/>
+    <bool name="enabled"/>
+  </model>
+  <instance name="main" model="State" default="true"/>
+  <circle id="dot" cx="10" cy="10" r="3" fill="#000"/>
+  <listener on="down" target="dot" set="$count=5"/>
+  <listener on="key-down" target="dot" set="$count=7" key="Enter"/>
+  <listener on="scroll" target="dot" set="$count=9"/>
+  <listener on="gamepad-button" target="dot" set="$count=11" control="0"/>
+</anima>

package/modules/tooling/capabilities/tooling-headless-pointer/example.ani

@@ -0,0 +1,16 @@
+{
+  "anima": "0.1",
+  "name": "tooling-headless-pointer",
+  "grid": 20,
+  "nodes": [
+    {
+      "id": "probe",
+      "type": "circle",
+      "center": [10, 10],
+      "r": 1,
+      "fill": {
+        "color": "#000"
+      }
+    }
+  ]
+}

package/modules/tooling/capabilities/tooling-headless-pointer/example.animl

@@ -0,0 +1,13 @@
+<anima version="0.1" name="agent-tools" grid="20" requires="data input">
+  <model name="State">
+    <number name="count" default="0"/>
+    <string name="title" default="Hello"/>
+    <bool name="enabled"/>
+  </model>
+  <instance name="main" model="State" default="true"/>
+  <circle id="dot" cx="10" cy="10" r="3" fill="#000"/>
+  <listener on="down" target="dot" set="$count=5"/>
+  <listener on="key-down" target="dot" set="$count=7" key="Enter"/>
+  <listener on="scroll" target="dot" set="$count=9"/>
+  <listener on="gamepad-button" target="dot" set="$count=11" control="0"/>
+</anima>

package/modules/tooling/capabilities/tooling-headless-touch/example.ani

@@ -0,0 +1,16 @@
+{
+  "anima": "0.1",
+  "name": "tooling-headless-touch",
+  "grid": 20,
+  "nodes": [
+    {
+      "id": "probe",
+      "type": "circle",
+      "center": [10, 10],
+      "r": 1,
+      "fill": {
+        "color": "#000"
+      }
+    }
+  ]
+}

package/modules/tooling/capabilities/tooling-headless-touch/example.animl

@@ -0,0 +1,13 @@
+<anima version="0.1" name="agent-tools" grid="20" requires="data input">
+  <model name="State">
+    <number name="count" default="0"/>
+    <string name="title" default="Hello"/>
+    <bool name="enabled"/>
+  </model>
+  <instance name="main" model="State" default="true"/>
+  <circle id="dot" cx="10" cy="10" r="3" fill="#000"/>
+  <listener on="down" target="dot" set="$count=5"/>
+  <listener on="key-down" target="dot" set="$count=7" key="Enter"/>
+  <listener on="scroll" target="dot" set="$count=9"/>
+  <listener on="gamepad-button" target="dot" set="$count=11" control="0"/>
+</anima>

package/modules/tooling/capabilities/tooling-headless-wheel/example.ani

@@ -0,0 +1,16 @@
+{
+  "anima": "0.1",
+  "name": "tooling-headless-wheel",
+  "grid": 20,
+  "nodes": [
+    {
+      "id": "probe",
+      "type": "circle",
+      "center": [10, 10],
+      "r": 1,
+      "fill": {
+        "color": "#000"
+      }
+    }
+  ]
+}

package/modules/tooling/capabilities/tooling-headless-wheel/example.animl

@@ -0,0 +1,13 @@
+<anima version="0.1" name="agent-tools" grid="20" requires="data input">
+  <model name="State">
+    <number name="count" default="0"/>
+    <string name="title" default="Hello"/>
+    <bool name="enabled"/>
+  </model>
+  <instance name="main" model="State" default="true"/>
+  <circle id="dot" cx="10" cy="10" r="3" fill="#000"/>
+  <listener on="down" target="dot" set="$count=5"/>
+  <listener on="key-down" target="dot" set="$count=7" key="Enter"/>
+  <listener on="scroll" target="dot" set="$count=9"/>
+  <listener on="gamepad-button" target="dot" set="$count=11" control="0"/>
+</anima>

package/modules/tooling/capabilities/tooling-seed/example.ani

@@ -0,0 +1,76 @@
+{
+  "anima": "0.1",
+  "name": "seed-probe",
+  "grid": 20,
+  "requires": ["machine", "data", "bind", "convert"],
+  "nodes": [
+    {
+      "id": "dot",
+      "type": "circle",
+      "center": [10, 10],
+      "r": 1,
+      "fill": {
+        "color": "#000"
+      }
+    }
+  ],
+  "machine": {
+    "layers": {
+      "l": {
+        "initial": "a",
+        "states": {
+          "a": {
+            "pose": {},
+            "on": [
+              {
+                "when": "@after(0)",
+                "to": "b",
+                "weight": 1
+              },
+              {
+                "when": "@after(0)",
+                "to": "c",
+                "weight": 1
+              }
+            ],
+            "kind": "random"
+          },
+          "b": {
+            "pose": {
+              "dot.x": 5
+            }
+          },
+          "c": {
+            "pose": {
+              "dot.x": 10
+            }
+          }
+        }
+      }
+    }
+  },
+  "bind": {
+    "dot.y": {
+      "value": "$value",
+      "convert": "rng"
+    }
+  },
+  "machineSeed": 1000,
+  "data": {
+    "models": {
+      "State": {
+        "properties": {
+          "value": {
+            "type": "number"
+          }
+        }
+      }
+    }
+  },
+  "converters": {
+    "rng": {
+      "type": "formula",
+      "expression": "random()"
+    }
+  }
+}

package/modules/tooling/capabilities/tooling-seed/example.animl

@@ -0,0 +1,21 @@
+<anima version="0.1" name="seed-probe" grid="20" requires="machine data bind convert" machineSeed="1000">
+  <model name="State">
+    <number name="value"/>
+  </model>
+  <converter name="rng" type="formula" expression="random()"/>
+  <circle id="dot" cx="10" cy="10" r="1" fill="#000"/>
+  <bind target="dot.y" value="$value" convert="rng"/>
+  <layer name="l" initial="a">
+    <state name="a" kind="random">
+      <pose/>
+      <on when="@after(0)" to="b" weight="1"/>
+      <on when="@after(0)" to="c" weight="1"/>
+    </state>
+    <state name="b">
+      <pose dot.x="5"/>
+    </state>
+    <state name="c">
+      <pose dot.x="10"/>
+    </state>
+  </layer>
+</anima>

package/modules/tooling/capabilities/tooling-test-assertions/example.ani

@@ -0,0 +1,16 @@
+{
+  "anima": "0.1",
+  "name": "tooling-test-assertions",
+  "grid": 20,
+  "nodes": [
+    {
+      "id": "probe",
+      "type": "circle",
+      "center": [10, 10],
+      "r": 1,
+      "fill": {
+        "color": "#000"
+      }
+    }
+  ]
+}

package/modules/tooling/capabilities/tooling-test-assertions/example.animl

@@ -0,0 +1,13 @@
+<anima version="0.1" name="agent-tools" grid="20" requires="data input">
+  <model name="State">
+    <number name="count" default="0"/>
+    <string name="title" default="Hello"/>
+    <bool name="enabled"/>
+  </model>
+  <instance name="main" model="State" default="true"/>
+  <circle id="dot" cx="10" cy="10" r="3" fill="#000"/>
+  <listener on="down" target="dot" set="$count=5"/>
+  <listener on="key-down" target="dot" set="$count=7" key="Enter"/>
+  <listener on="scroll" target="dot" set="$count=9"/>
+  <listener on="gamepad-button" target="dot" set="$count=11" control="0"/>
+</anima>

package/modules/tooling/examples/agent-tools.ani

@@ -0,0 +1,75 @@
+{
+  "anima": "0.1",
+  "name": "agent-tools",
+  "grid": 20,
+  "requires": ["data", "input"],
+  "nodes": [
+    {
+      "id": "dot",
+      "type": "circle",
+      "center": [10, 10],
+      "r": 3,
+      "fill": {
+        "color": "#000"
+      }
+    }
+  ],
+  "listeners": [
+    {
+      "on": "down",
+      "target": "dot",
+      "set": {
+        "$count": 5
+      }
+    },
+    {
+      "on": "key-down",
+      "target": "dot",
+      "set": {
+        "$count": 7
+      },
+      "key": "Enter"
+    },
+    {
+      "on": "scroll",
+      "target": "dot",
+      "set": {
+        "$count": 9
+      }
+    },
+    {
+      "on": "gamepad-button",
+      "target": "dot",
+      "set": {
+        "$count": 11
+      },
+      "control": 0
+    }
+  ],
+  "data": {
+    "models": {
+      "State": {
+        "properties": {
+          "count": {
+            "type": "number",
+            "default": 0
+          },
+          "title": {
+            "type": "string",
+            "default": "Hello"
+          },
+          "enabled": {
+            "type": "bool"
+          }
+        }
+      }
+    },
+    "instances": {
+      "main": {
+        "model": "State",
+        "default": true,
+        "values": {}
+      }
+    }
+  }
+}

package/modules/tooling/examples/agent-tools.animl

@@ -0,0 +1,13 @@
+<anima version="0.1" name="agent-tools" grid="20" requires="data input">
+  <model name="State">
+    <number name="count" default="0"/>
+    <string name="title" default="Hello"/>
+    <bool name="enabled"/>
+  </model>
+  <instance name="main" model="State" default="true"/>
+  <circle id="dot" cx="10" cy="10" r="3" fill="#000"/>
+  <listener on="down" target="dot" set="$count=5"/>
+  <listener on="key-down" target="dot" set="$count=7" key="Enter"/>
+  <listener on="scroll" target="dot" set="$count=9"/>
+  <listener on="gamepad-button" target="dot" set="$count=11" control="0"/>
+</anima>

package/modules/tooling/manifest.source

@@ -0,0 +1,15 @@
+export default {
+  name: 'tooling',
+  summary: 'Authoring tool: shared CLI and headless helpers (not loaded by pages).',
+  after: [],
+  web: [],
+  adapters: {},
+  exports: {},
+  tests: [
+    'packages/cli/test/p3c-tooling.test.ts',
+    'packages/cli/test/agent-tools.test.ts',
+    'packages/cli/test/tooling-leftovers.test.ts',
+  ],
+  conformance: ['tooling-input-data', 'tooling-seed', 'tooling-legacy-random'],
+  docs: ['spec/SPEC.md', 'docs/AUTHORING.md'],
+};

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "animl-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "The anima command-line tool for Anima and AniML.",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MRoiban/anima.git"
+  },
+  "homepage": "https://github.com/MRoiban/anima#readme",
+  "bugs": {
+    "url": "https://github.com/MRoiban/anima/issues"
+  },
+  "keywords": [
+    "animation",
+    "interactive",
+    "web-component",
+    "svg",
+    "canvas",
+    "icons",
+    "state-machine",
+    "motion",
+    "ui",
+    "agents"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "bin": {
+    "anima": "packages/cli/src/main.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./packages/cli/src/index.d.ts",
+      "default": "./packages/cli/src/index.js"
+    }
+  },
+  "dependencies": {
+    "@resvg/resvg-js": "^2.6.2",
+    "esbuild": "^0.28.2",
+    "terser": "^5.51.2",
+    "animl": "0.1.0",
+    "playwright-core": "^1.64.1",
+    "pngjs": "^7.0.0"
+  },
+  "files": [
+    "packages",
+    "modules",
+    "docs",
+    "spec",
+    "examples",
+    "fixtures",
+    "llms.txt",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ]
+}

package/packages/cli/package.json

@@ -0,0 +1,4 @@
+{
+  "version": "0.1.0",
+  "type": "module"
+}

package/packages/cli/src/asset-info.d.ts

@@ -0,0 +1,8 @@
+export interface AssetInfo {
+    mime: string;
+    size: number;
+    width?: number;
+    height?: number;
+    duration?: number;
+}
+export declare function sniff(bytes: Buffer): AssetInfo;

package/packages/cli/src/asset-info.js

@@ -0,0 +1,122 @@
+function sniff(bytes) {
+  const info = { mime: "application/octet-stream", size: bytes.length };
+  if (bytes.subarray(0, 8).equals(Buffer.from([137, 80, 78, 71, 13, 10, 26, 10]))) {
+    if (bytes.length < 33 || bytes.toString("ascii", 12, 16) !== "IHDR")
+      throw Error("truncated PNG");
+    return {
+      ...info,
+      mime: "image/png",
+      width: bytes.readUInt32BE(16),
+      height: bytes.readUInt32BE(20)
+    };
+  }
+  if (["GIF87a", "GIF89a"].includes(bytes.toString("ascii", 0, 6))) {
+    if (bytes.length < 10) throw Error("truncated GIF");
+    return {
+      ...info,
+      mime: "image/gif",
+      width: bytes.readUInt16LE(6),
+      height: bytes.readUInt16LE(8)
+    };
+  }
+  if (bytes[0] === 255 && bytes[1] === 216) {
+    let p2 = 2;
+    while (p2 + 4 <= bytes.length) {
+      if (bytes[p2++] !== 255) throw Error("invalid JPEG marker");
+      while (bytes[p2] === 255) p2++;
+      const marker = bytes[p2++];
+      if (marker === 217 || marker === 218) break;
+      if (marker === 1 || marker >= 208 && marker <= 215) continue;
+      const length = bytes.readUInt16BE(p2);
+      if (length < 2 || p2 + length > bytes.length) throw Error("truncated JPEG");
+      if ([192, 193, 194, 195, 197, 198, 199, 201, 202, 203, 205, 206, 207].includes(marker)) {
+        if (length < 8) throw Error("invalid JPEG frame");
+        return {
+          ...info,
+          mime: "image/jpeg",
+          height: bytes.readUInt16BE(p2 + 3),
+          width: bytes.readUInt16BE(p2 + 5)
+        };
+      }
+      p2 += length;
+    }
+    throw Error("JPEG has no frame");
+  }
+  if (bytes.toString("ascii", 0, 4) === "RIFF") {
+    if (bytes.length < 12 || bytes.readUInt32LE(4) + 8 > bytes.length)
+      throw Error("truncated RIFF");
+    const type = bytes.toString("ascii", 8, 12);
+    if (type === "WEBP") {
+      const tag = bytes.toString("ascii", 12, 16);
+      if (tag === "VP8X" && bytes.length >= 30)
+        return {
+          ...info,
+          mime: "image/webp",
+          width: 1 + bytes.readUIntLE(24, 3),
+          height: 1 + bytes.readUIntLE(27, 3)
+        };
+      if (tag === "VP8L" && bytes.length >= 25 && bytes[20] === 47) {
+        const v = bytes.readUInt32LE(21);
+        return {
+          ...info,
+          mime: "image/webp",
+          width: 1 + (v & 16383),
+          height: 1 + (v >>> 14 & 16383)
+        };
+      }
+      if (tag === "VP8 " && bytes.length >= 30 && bytes.subarray(23, 26).equals(Buffer.from([157, 1, 42])))
+        return {
+          ...info,
+          mime: "image/webp",
+          width: bytes.readUInt16LE(26) & 16383,
+          height: bytes.readUInt16LE(28) & 16383
+        };
+      throw Error("unsupported or truncated WebP header");
+    }
+    if (type === "WAVE") {
+      let rate = 0, data = 0;
+      for (let p2 = 12; p2 + 8 <= bytes.length; ) {
+        const length = bytes.readUInt32LE(p2 + 4), end = p2 + 8 + length;
+        if (end > bytes.length) throw Error("truncated WAV chunk");
+        const tag = bytes.toString("ascii", p2, p2 + 4);
+        if (tag === "fmt " && length >= 16) rate = bytes.readUInt32LE(p2 + 16);
+        if (tag === "data") data += length;
+        p2 = end + length % 2;
+      }
+      if (!rate || !data) throw Error("WAV needs fmt and data");
+      return { ...info, mime: "audio/wav", duration: data / rate };
+    }
+  }
+  if (bytes.toString("ascii", 0, 4) === "fLaC") {
+    if (bytes.length < 42 || (bytes[4] & 127) !== 0 || bytes.readUIntBE(5, 3) !== 34)
+      throw Error("FLAC needs STREAMINFO");
+    const v = bytes.readBigUInt64BE(18), rate = Number(v >> 44n);
+    if (!rate) throw Error("invalid FLAC sample rate");
+    const samples = Number(v & 0xfffffffffn);
+    return { ...info, mime: "audio/flac", ...samples ? { duration: samples / rate } : {} };
+  }
+  let p = 0;
+  if (bytes.toString("ascii", 0, 3) === "ID3") {
+    if (bytes.length < 10 || bytes.subarray(6, 10).some((v) => v > 127))
+      throw Error("invalid ID3 header");
+    p = 10 + bytes.subarray(6, 10).reduce((n, v) => n * 128 + v, 0) + (bytes[5] & 16 ? 10 : 0);
+  }
+  let duration = 0;
+  while (p + 4 <= bytes.length && bytes[p] === 255 && (bytes[p + 1] & 224) === 224) {
+    const version = bytes[p + 1] >> 3 & 3, layer = bytes[p + 1] >> 1 & 3;
+    const bi = bytes[p + 2] >> 4, ri = bytes[p + 2] >> 2 & 3;
+    if (version === 1 || layer !== 1 || !bi || bi === 15 || ri === 3)
+      throw Error("invalid MP3 frame");
+    const rate = [44100, 48e3, 32e3][ri] / (version === 3 ? 1 : version === 2 ? 2 : 4);
+    const kbps = (version === 3 ? [0, 32, 40, 48, 56, 64, 80, 96, 112, 128, 160, 192, 224, 256, 320] : [0, 8, 16, 24, 32, 40, 48, 56, 64, 80, 96, 112, 128, 144, 160])[bi];
+    const length = Math.floor((version === 3 ? 144e3 : 72e3) * kbps / rate) + (bytes[p + 2] >> 1 & 1);
+    if (p + length > bytes.length) throw Error("truncated MP3 frame");
+    duration += (version === 3 ? 1152 : 576) / rate;
+    p += length;
+  }
+  if (duration) return { ...info, mime: "audio/mpeg", duration };
+  return info;
+}
+export {
+  sniff
+};

package/packages/cli/src/assets.d.ts

@@ -0,0 +1,8 @@
+import { type Asset } from 'animl/assets';
+type AssetDoc = {
+    assets?: Record<string, Asset>;
+    components?: Record<string, unknown>;
+};
+export declare function embedAssets(doc: AssetDoc, file: string, imagesOnly?: boolean): void;
+export declare function imageDimensions(doc: AssetDoc): Promise<void>;
+export {};

package/packages/cli/src/assets.js

@@ -0,0 +1,66 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { Resvg } from "@resvg/resvg-js";
+import { sniff } from "./asset-info.js";
+import { encodeImage, ImageEncoder } from "./encode.js";
+import { imagePixels } from "animl/assets";
+const catalogs = (doc) => [
+  ...Object.values(doc.assets ?? {}),
+  ...Object.values(doc.components ?? {}).flatMap(
+    (c) => c && typeof c === "object" ? catalogs(c) : []
+  )
+];
+function embedAssets(doc, file, imagesOnly = false) {
+  for (const a of catalogs(doc)) {
+    if (imagesOnly && a.type !== "image" || a.source.startsWith("data:")) continue;
+    const url = new URL(a.source, pathToFileURL(resolve(file)));
+    const bytes = readFileSync(url);
+    const ext = url.pathname.split(".").pop()?.toLowerCase();
+    const mime = {
+      png: "image/png",
+      jpg: "image/jpeg",
+      jpeg: "image/jpeg",
+      gif: "image/gif",
+      webp: "image/webp",
+      svg: "image/svg+xml",
+      woff: "font/woff",
+      woff2: "font/woff2",
+      ttf: "font/ttf",
+      mp3: "audio/mpeg",
+      wav: "audio/wav",
+      ogg: "audio/ogg",
+      flac: "audio/flac"
+    };
+    a.source = `data:${mime[ext ?? ""] ?? "application/octet-stream"};base64,${bytes.toString("base64")}`;
+    a.storage = "embedded";
+  }
+}
+async function imageDimensions(doc) {
+  const encoder = new ImageEncoder();
+  try {
+    for (const a of catalogs(doc)) {
+      if (a.type !== "image") continue;
+      if (a.source.startsWith("data:image/webp;")) {
+        const bytes = Buffer.from(a.source.slice(a.source.indexOf(",") + 1), "base64");
+        const png = await encodeImage(bytes, sniff(bytes), "png", void 0, encoder);
+        a.source = "data:image/png;base64," + png.toString("base64");
+      }
+      const escaped = a.source.replace(/&/g, "&amp;").replace(/"/g, "&quot;").replace(/</g, "&lt;");
+      const r = new Resvg(
+        `<svg xmlns="http://www.w3.org/2000/svg" width="1" height="1"><image href="${escaped}"/></svg>`
+      );
+      const box = r.getBBox();
+      if (!box) throw new Error("cannot decode image asset");
+      imagePixels.set(a, [box.width, box.height]);
+      a.width ??= box.width;
+      a.height ??= box.height;
+    }
+  } finally {
+    await encoder.close();
+  }
+}
+export {
+  embedAssets,
+  imageDimensions
+};

package/packages/cli/src/audio.d.ts

@@ -0,0 +1,3 @@
+import type { Model, AnimaEvent } from 'animl';
+/** Offline stereo, 48 kHz, signed 16-bit PCM. Events carry absolute player timestamps. */
+export declare function mixAudio(model: Model, events: AnimaEvent[], duration: number, file: string): Promise<Buffer>;