animl-cli 0.0.0-stage → 0.1.0

package/packages/cli/src/audio.js

@@ -0,0 +1,77 @@
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { eventSource } from "animl/internal/packages/core/src/event-capture.js";
+import { ImageEncoder } from "./encode.js";
+async function mixAudio(model, events, duration, file) {
+  const encoder = new ImageEncoder();
+  try {
+    const page = await (await encoder.browser()).newPage();
+    const clips = events.filter((e) => e.audio).map((e) => {
+      const scope = e[eventSource] ?? model;
+      const a = scope.doc.assets?.[e.audio];
+      if (!a || a.type !== "audio") throw Error("cannot resolve audio asset " + e.audio);
+      if (/^[a-z][a-z\d+.-]*:/i.test(a.source) && !a.source.startsWith("data:"))
+        throw Error("offline audio requires local or data URI assets");
+      const bytes = a.source.startsWith("data:") ? Buffer.from(a.source.split(",")[1], "base64") : readFileSync(resolve(dirname(file), a.source));
+      return {
+        bytes: [...bytes],
+        time: e.time,
+        start: a.start ?? 0,
+        end: a.end,
+        volume: (e.volume ?? 1) * (scope.doc.audioVolumes?.[e.audio] ?? 1)
+      };
+    });
+    const channels = await page.evaluate(
+      async ({ clips: clips2, duration: duration2 }) => {
+        const ctx = new OfflineAudioContext(2, Math.max(1, Math.ceil(duration2 * 48e3)), 48e3);
+        for (const clip of clips2) {
+          const decoded = await ctx.decodeAudioData(new Uint8Array(clip.bytes).buffer);
+          const end = clip.end ?? decoded.duration;
+          if (clip.start < 0 || end > decoded.duration || end <= clip.start)
+            throw Error("invalid audio clip bounds");
+          const source = ctx.createBufferSource();
+          source.buffer = decoded;
+          const gain = ctx.createGain();
+          gain.gain.value = clip.volume;
+          source.connect(gain);
+          gain.connect(ctx.destination);
+          source.start(clip.time, clip.start, end - clip.start);
+        }
+        const mixed = await ctx.startRendering();
+        return [Array.from(mixed.getChannelData(0)), Array.from(mixed.getChannelData(1))];
+      },
+      { clips, duration }
+    );
+    const n = channels[0].length, wav = Buffer.alloc(44 + n * 4);
+    wav.write("RIFF", 0);
+    wav.writeUInt32LE(36 + n * 4, 4);
+    wav.write("WAVEfmt ", 8);
+    wav.writeUInt32LE(16, 16);
+    wav.writeUInt16LE(1, 20);
+    wav.writeUInt16LE(2, 22);
+    wav.writeUInt32LE(48e3, 24);
+    wav.writeUInt32LE(192e3, 28);
+    wav.writeUInt16LE(4, 32);
+    wav.writeUInt16LE(16, 34);
+    wav.write("data", 36);
+    wav.writeUInt32LE(n * 4, 40);
+    for (let i = 0; i < n; i++)
+      for (let c = 0; c < 2; c++) {
+        const v = Math.max(-1, Math.min(1, channels[c][i]));
+        wav.writeInt16LE(Math.round(v * (v < 0 ? 32768 : 32767)), 44 + i * 4 + c * 2);
+      }
+    return wav;
+  } catch (error) {
+    if (error.code === "build-encoder-unavailable") throw error;
+    throw Object.assign(new Error(error.message), {
+      code: "event-audio-load",
+      pointer: "/assets",
+      hint: "check local/base64 audio source, clip bounds and declaring asset scope"
+    });
+  } finally {
+    await encoder.close();
+  }
+}
+export {
+  mixAudio
+};

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

@@ -0,0 +1,32 @@
+import { type Model } from 'animl';
+import { type ScriptOptions } from 'animl/internal/packages/core/src/script.js';
+/** Same renderer-neutral step/draw path as tools/perf.ts; costs exclude I/O and script setup. */
+export declare function bench(load: () => Model | undefined, script: string, frames: number, opts?: ScriptOptions): {
+    diagnostics: import("animl/internal/packages/core/src/script.js").ScriptDiagnostic[];
+    memory?: undefined;
+    frames?: undefined;
+    compileMs?: undefined;
+    unit?: undefined;
+    step?: undefined;
+    draw?: undefined;
+} | {
+    memory: {
+        kind: string;
+        beforeBytes: number;
+        afterBytes: number;
+        growthBytes: number;
+        bytesPerFrame: number;
+    };
+    frames: number;
+    compileMs: number;
+    unit: string;
+    step: {
+        median: number;
+        p95: number;
+    };
+    draw: {
+        median: number;
+        p95: number;
+    };
+    diagnostics?: undefined;
+} | undefined;

package/packages/cli/src/bench.js

@@ -0,0 +1,46 @@
+import { drawFrame } from "animl";
+import { runScript } from "animl/internal/packages/core/src/script.js";
+const percentile = (xs, p) => xs.sort((a, b) => a - b)[Math.min(xs.length - 1, Math.floor(xs.length * p))];
+function bench(load, script, frames, opts = {}) {
+  const start = performance.now();
+  const model = load();
+  const compileMs = performance.now() - start;
+  if (!model) return void 0;
+  const run = runScript(model, script, opts);
+  if (run.diagnostics.length || run.stopped) return { diagnostics: run.diagnostics };
+  const player = run.player;
+  const warm = runScript(model, script, opts).player;
+  for (let i = 0; i < 50; i++) {
+    warm.step(1 / 60);
+    drawFrame(warm);
+  }
+  const step = [], draw = [];
+  const heapBefore = process.memoryUsage().heapUsed;
+  for (let i = 0; i < frames; i++) {
+    const t0 = performance.now();
+    player.step(1 / 60);
+    const t1 = performance.now();
+    drawFrame(player);
+    const t2 = performance.now();
+    step.push((t1 - t0) * 1e3);
+    draw.push((t2 - t1) * 1e3);
+  }
+  const heapAfter = process.memoryUsage().heapUsed;
+  return {
+    memory: {
+      kind: "js-heap",
+      beforeBytes: heapBefore,
+      afterBytes: heapAfter,
+      growthBytes: heapAfter - heapBefore,
+      bytesPerFrame: (heapAfter - heapBefore) / frames
+    },
+    frames,
+    compileMs,
+    unit: "\xB5s",
+    step: { median: percentile(step, 0.5), p95: percentile(step, 0.95) },
+    draw: { median: percentile(draw, 0.5), p95: percentile(draw, 0.95) }
+  };
+}
+export {
+  bench
+};

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

@@ -0,0 +1,10 @@
+import { type FontDocument } from './font/document.js';
+import type { Asset } from 'animl/assets';
+import type { Diagnostic } from 'animl';
+import { ImageEncoder } from './encode.js';
+export interface AssetDocument {
+    requires?: string[];
+    assets?: Record<string, Asset>;
+    components?: Record<string, AssetDocument>;
+}
+export declare function buildAssets(doc: AssetDocument, file: string, embed: boolean, encoder?: ImageEncoder, sourceFile?: (pointer: string) => string, base?: string, fontRoot?: FontDocument): Promise<Diagnostic[]>;

package/packages/cli/src/build-assets.js

@@ -0,0 +1,139 @@
+import { buildFont } from "./font/document.js";
+import { readFileSync } from "node:fs";
+import { resolve, extname } from "node:path";
+import { pathToFileURL } from "node:url";
+import { Resvg } from "@resvg/resvg-js";
+import { sniff } from "./asset-info.js";
+import { encodeImage, validateWebP, ImageEncoder } from "./encode.js";
+async function buildAssets(doc, file, embed, encoder, sourceFile = () => file, base = "", fontRoot = doc) {
+  if (!encoder) {
+    const owned = new ImageEncoder();
+    try {
+      return await buildAssets(doc, file, embed, owned, sourceFile, base, fontRoot);
+    } finally {
+      await owned.close();
+    }
+  }
+  const diagnostics = [];
+  for (const [name, asset] of Object.entries(doc.assets ?? {})) {
+    if (asset.export === false) {
+      if (/^\s*data:/i.test(asset.source)) {
+        asset.source = "anima:" + name;
+        asset.storage = "referenced";
+      }
+      continue;
+    }
+    const pointer = base + "/assets/" + name.replaceAll("~", "~0").replaceAll("/", "~1");
+    let field = "/source";
+    try {
+      if (asset.type === "font" && ("glyphs" in asset || doc.requires?.includes("fonts")))
+        buildFont(asset, fontRoot, sourceFile(pointer + "/source"));
+      const url = new URL(asset.source, pathToFileURL(resolve(sourceFile(pointer + "/source"))));
+      if (!["file:", "data:"].includes(url.protocol)) {
+        if (embed || asset.encode) throw Error("disk build cannot fetch remote assets");
+        continue;
+      }
+      let bytes;
+      if (url.protocol === "data:") {
+        const comma = asset.source.indexOf(",");
+        bytes = asset.source.slice(0, comma).endsWith(";base64") ? Buffer.from(asset.source.slice(comma + 1), "base64") : Buffer.concat(
+          [...asset.source.slice(comma + 1).matchAll(/%([0-9a-fA-F]{2})|([^%]+)/g)].map(
+            (m) => m[1] ? Buffer.from([parseInt(m[1], 16)]) : Buffer.from(m[2])
+          )
+        );
+      } else bytes = readFileSync(url);
+      let info = asset.type === "blob" ? { mime: asset.mime ?? "application/octet-stream", size: bytes.length } : sniff(bytes);
+      const expected = {
+        ".png": "image/png",
+        ".jpg": "image/jpeg",
+        ".jpeg": "image/jpeg",
+        ".webp": "image/webp",
+        ".wav": "audio/wav",
+        ".mp3": "audio/mpeg",
+        ".flac": "audio/flac",
+        ".gif": "image/gif",
+        ".svg": "image/svg+xml",
+        ".woff": "font/woff",
+        ".woff2": "font/woff2",
+        ".ttf": "font/ttf",
+        ".otf": "font/otf"
+      };
+      const mime = url.protocol === "data:" ? /^data:([^;,]+)/.exec(asset.source)?.[1] : expected[extname(url.pathname).toLowerCase()];
+      if (asset.type === "blob") info.mime = asset.mime ?? mime ?? info.mime;
+      if (info.mime === "application/octet-stream" && asset.type === "font")
+        info = { ...info, mime: asset.mime ?? mime ?? "application/octet-stream" };
+      if (asset.type === "image" && info.mime === "application/octet-stream" && mime === "image/svg+xml" && /<svg(?:\s|>)/.test(bytes.toString("utf8")))
+        info = { ...info, mime: "image/svg+xml" };
+      if (asset.type !== "blob" && (mime && expected[extname(url.pathname).toLowerCase()] && mime !== info.mime || mime && /^(image\/(png|jpeg|webp)|audio\/(wav|mpeg|flac))$/.test(mime) && mime !== info.mime || asset.mime && asset.mime !== info.mime))
+        throw Object.assign(Error("asset MIME/extension disagrees with its bytes"), {
+          code: "asset-format"
+        });
+      if (asset.type === "image" && info.mime.startsWith("image/") && info.mime !== "image/svg+xml") {
+        if (!info.width || !info.height) throw Error("image dimensions must be positive");
+        const uri = `data:${info.mime};base64,${bytes.toString("base64")}`;
+        const box = info.mime === "image/gif" ? true : info.mime === "image/webp" ? (await validateWebP(bytes, info, encoder), true) : new Resvg(
+          `<svg xmlns="http://www.w3.org/2000/svg"><image href="${uri}"/></svg>`
+        ).getBBox();
+        if (!box) throw Error("cannot decode image pixels");
+      } else if (asset.type === "image" && info.mime !== "image/svg+xml")
+        throw Object.assign(Error("image source has no supported image signature"), {
+          code: "asset-format"
+        });
+      if (asset.type === "audio" && !info.mime.startsWith("audio/"))
+        throw Object.assign(Error("audio source has no supported audio signature"), {
+          code: "asset-format"
+        });
+      if (info.duration !== void 0 && (asset.end !== void 0 && asset.end > info.duration || (asset.start ?? 0) >= info.duration)) {
+        field = asset.end !== void 0 && asset.end > info.duration ? "/end" : "/start";
+        throw Object.assign(Error("audio clip exceeds inspected source duration"), {
+          code: "asset-clip"
+        });
+      }
+      if (asset.encode) {
+        field = "/encode";
+        if (asset.type !== "image" || !["image/png", "image/jpeg", "image/webp"].includes(info.mime))
+          throw Object.assign(Error("encode needs a PNG/JPEG/WebP image"), {
+            code: "asset-format"
+          });
+        bytes = await encodeImage(bytes, info, asset.encode, asset.quality, encoder);
+        info = sniff(bytes);
+      }
+      Object.assign(
+        asset,
+        { mime: info.mime, size: info.size },
+        asset.type !== "audio" || info.duration === void 0 ? {} : { duration: info.duration }
+      );
+      if (embed || asset.encode) {
+        asset.source = `data:${info.mime};base64,${bytes.toString("base64")}`;
+        asset.storage = "embedded";
+      }
+    } catch (error) {
+      const code = error.code;
+      diagnostics.push({
+        code: code?.startsWith("font-") || code === "build-encoder-unavailable" || code === "asset-format" || code === "asset-clip" ? code : "asset-load",
+        severity: "error",
+        pointer: pointer + field,
+        message: error instanceof Error ? error.message : "cannot build asset",
+        hint: code === "build-encoder-unavailable" ? "set CHROMIUM_PATH to the cached headless Chromium executable" : "check source bytes, MIME, extension and encoding options relative to the document"
+      });
+    }
+  }
+  for (const [name, component] of Object.entries(doc.components ?? {})) {
+    if (name === "$comment") continue;
+    diagnostics.push(
+      ...await buildAssets(
+        component,
+        file,
+        embed,
+        encoder,
+        sourceFile,
+        base + "/components/" + name.replaceAll("~", "~0").replaceAll("/", "~1"),
+        fontRoot
+      )
+    );
+  }
+  return diagnostics;
+}
+export {
+  buildAssets
+};

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

@@ -0,0 +1,7 @@
+export declare function bundleBrowser(names: string | undefined, output: string, verbose: boolean): Promise<{
+    wrote: string;
+    modules: string[];
+    verbose: boolean;
+    min: number;
+    gzip: number;
+}>;

package/packages/cli/src/bundle.js

@@ -0,0 +1,53 @@
+import { existsSync, writeFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { gzipSync } from "node:zlib";
+import { bundle } from "animl/internal/tools/browser-build.js";
+import { webOwners } from "animl/internal/tools/modules.generated.js";
+const root = new URL("../../../", import.meta.url);
+const entries = Object.keys(webOwners);
+function distance(a, b) {
+  let row = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 0; i < a.length; i++) {
+    const next = [i + 1];
+    for (let j = 0; j < b.length; j++)
+      next.push(Math.min(next[j] + 1, row[j + 1] + 1, row[j] + Number(a[i] !== b[j])));
+    row = next;
+  }
+  return row[b.length];
+}
+async function bundleBrowser(names, output, verbose) {
+  const requested = names === void 0 ? [] : names.split(",").map((name) => name.trim());
+  for (const [index, name] of requested.entries()) {
+    if (Object.hasOwn(webOwners, name)) continue;
+    const suggestion = [...entries].sort((a, b) => distance(name, a) - distance(name, b))[0];
+    throw Object.assign(new Error(`unknown browser module "${name}"`), {
+      code: "bundle-module",
+      pointer: `/modules/${index}`,
+      hint: `did you mean "${suggestion}"? Valid names: ${entries.join(", ")}`
+    });
+  }
+  const modules = entries.filter((name) => requested.includes(name));
+  const entry = (name) => {
+    const source2 = new URL(`packages/web/src/${name}.ts`, root);
+    if (existsSync(source2)) return fileURLToPath(source2);
+    const specifier = name === "index" ? "animl/web" : `animl/web/${name}`;
+    return fileURLToPath(import.meta.resolve(specifier));
+  };
+  const source = modules.length <= 1 ? entry(modules[0] ?? "index") : {
+    contents: modules.map((name) => `export * from ${JSON.stringify(entry(name))};`).join("\n"),
+    resolveDir: fileURLToPath(root),
+    loader: "ts"
+  };
+  const code = await bundle(source, verbose);
+  writeFileSync(output, code);
+  return {
+    wrote: output,
+    modules,
+    verbose,
+    min: Buffer.byteLength(code),
+    gzip: gzipSync(code).length
+  };
+}
+export {
+  bundleBrowser
+};

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

@@ -0,0 +1,19 @@
+import 'animl/all';
+import type { ExampleInfo, FeatureInfo, Hit, SearchOptions } from './discover/api.js';
+export interface IO {
+    out(s: string): void;
+    err(s: string): void;
+    /** Exact stdout bytes for compiled artifacts (out is line-oriented). */
+    write?(s: string): void;
+    input?: AsyncIterable<string>;
+}
+interface DiscoveryAPI {
+    search(query: string, options?: SearchOptions): Hit[];
+    features(name?: string): FeatureInfo[] | FeatureInfo | undefined;
+    examples(filter?: string): ExampleInfo[];
+}
+export interface RunDeps {
+    discover?: Partial<DiscoveryAPI>;
+}
+export declare function run(argv: string[], io: IO, deps?: RunDeps): Promise<number>;
+export {};