animl-cli 0.0.0-stage → 0.1.1

package/packages/cli/src/cli.js

@@ -0,0 +1,1532 @@
+import { documentFonts, installToolMeasurer } from "./font/document.js";
+import { ToolMeasurer } from "./font/measure.js";
+import { outlineSVG } from "./font/svg.js";
+import { browserTextPNG, embedFontCSS } from "./font/browser.js";
+import { importFont, googleFonts } from "./font/import.js";
+import { flattenText } from "./font/flatten.js";
+import { componentNames } from "animl/internal/modules/components/core/names.js";
+import { createScriptSession } from "animl/internal/packages/core/src/script.js";
+import { resolve, basename } from "node:path";
+import { findProject, projectSource, substituteConstants } from "./project.js";
+import { bundleBrowser } from "./bundle.js";
+import { doctor } from "./doctor.js";
+import { comparePNG } from "./compare-png.js";
+import { mixAudio } from "./audio.js";
+import { viewportSVG, probePNG } from "./render-options.js";
+import { wiringSummary } from "./inspect-summary.js";
+import { listState } from "animl/internal/modules/lists/core/index.js";
+import "animl/all";
+import { mkdirSync, cpSync, existsSync, readFileSync, writeFileSync } from "node:fs";
+import {
+  Player,
+  ScriptError,
+  load,
+  runScript,
+  staticSlots
+} from "animl";
+import { formatAni as format } from "animl";
+import { compile, decompile, formatMarkup } from "animl/markup";
+import { session } from "./session.js";
+import { bench } from "./bench.js";
+import { startPlayground } from "./playground.js";
+import { inspectGlyph } from "./glyphs.js";
+import { embedAssets, imageDimensions } from "./assets.js";
+import { buildHTML } from "./html.js";
+import { buildAssets } from "./build-assets.js";
+import { updateLibraries } from "./library.js";
+import { ImageEncoder } from "./encode.js";
+import { importSVG } from "./import-svg.js";
+import { importLottie } from "./import-lottie.js";
+import { lineCol, locate, syntaxErrorAt } from "./locate.js";
+import {
+  DARK,
+  LIGHT,
+  compareSVG,
+  comparisonSVG,
+  frameSVG,
+  sheetSVG,
+  toPNG
+} from "./render.js";
+import { nameFromFile, newDoc, readGlyphSVG, readGlyphy, sha256 } from "./scaffold.js";
+import { COMMANDS, GLOBAL } from "./commands.js";
+import { commandByName, commandHelp, helpJSON, overview } from "./help.js";
+import { resolveAlias, suggest } from "./suggest.js";
+import { completion } from "./completion.js";
+import * as discover from "./discover/api.js";
+import { filteredSchema, schema, schemaAll, schemaSearch, schemaTopic } from "./schema-view.js";
+import { docs, docsFull } from "./docs-view.js";
+class Usage extends Error {
+  issue;
+  constructor(message, issue) {
+    super(message);
+    this.issue = issue;
+  }
+}
+const ROOT = new URL("../../../", import.meta.url);
+const CLI_VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+const DEFAULT_DISCOVERY = {
+  search: discover.search,
+  features: discover.features,
+  examples: discover.examples
+};
+function wantsJSON(argv) {
+  return argv.some(
+    (arg, index) => arg === "--format=json" || arg === "--format" && argv[index + 1] === "json"
+  );
+}
+function usageHelp(command) {
+  return command ? `anima help ${command.name}` : "anima help";
+}
+function usageIssue(command, kind, word, candidates, message) {
+  return new Usage(message, {
+    kind,
+    word,
+    suggestions: suggest(word, candidates),
+    help: usageHelp(command)
+  });
+}
+function emitUsage(error, command, json, io) {
+  const suggestions = error.issue?.suggestions ?? [];
+  const help = error.issue?.help ?? usageHelp(command);
+  if (json) {
+    io.err(JSON.stringify({ error: error.message, suggestions, help }));
+    return 2;
+  }
+  io.err(`anima: ${error.message}`);
+  if (suggestions.length) {
+    if (error.issue?.kind === "command") {
+      io.err(
+        `${suggestions.length === 1 ? "The most similar command is" : "The most similar commands are"}
+${suggestions.map((item) => `  ${item}`).join("\n")}`
+      );
+    } else if (suggestions.length === 1) io.err(`Did you mean '${suggestions[0]}'?`);
+    else io.err(`Did you mean one of these?
+${suggestions.map((item) => `  ${item}`).join("\n")}`);
+  }
+  if (!error.message.includes(`See '${help}'`)) io.err(`See '${help}'.`);
+  return 2;
+}
+function optionsFor(command) {
+  return [...command.options, ...GLOBAL];
+}
+function setOption(values, option, value) {
+  if (option.multiple) {
+    const current = values[option.name];
+    values[option.name] = [...Array.isArray(current) ? current : [], String(value)];
+  } else values[option.name] = value;
+}
+function parseCommandArgs(argv, command) {
+  const options = optionsFor(command);
+  const byLong = new Map(options.map((option) => [option.name, option]));
+  const byShort = new Map(
+    options.flatMap((option) => option.short ? [[option.short, option]] : [])
+  );
+  const longCandidates = options.map((option) => `--${option.name}`);
+  const shortCandidates = options.flatMap((option) => option.short ? [`-${option.short}`] : []);
+  const values = { format: "text" };
+  const positionals = [];
+  let positionalOnly = false;
+  const accept = (option, raw, spelling) => {
+    if (!option.value) {
+      if (raw !== void 0)
+        throw new Usage(`option '${spelling}' does not take a value`, {
+          kind: "flag",
+          word: spelling,
+          suggestions: [],
+          help: usageHelp(command)
+        });
+      setOption(values, option, true);
+      return;
+    }
+    if (raw === void 0)
+      throw new Usage(`option '${spelling}' needs <${option.value}>`, {
+        kind: "flag",
+        word: spelling,
+        suggestions: [],
+        help: usageHelp(command)
+      });
+    if (option.choices && !option.choices.includes(raw))
+      throw usageIssue(
+        command,
+        "value",
+        raw,
+        option.choices,
+        `'${raw}' is not a valid value for '${spelling}'`
+      );
+    setOption(values, option, raw);
+  };
+  for (let index = 0; index < argv.length; index++) {
+    const token = argv[index];
+    if (positionalOnly) {
+      positionals.push(token);
+      continue;
+    }
+    if (token === "--") {
+      positionalOnly = true;
+      continue;
+    }
+    if (token.startsWith("--")) {
+      const equals = token.indexOf("=");
+      const name = token.slice(2, equals < 0 ? void 0 : equals);
+      const option = byLong.get(name);
+      if (!option)
+        throw usageIssue(command, "flag", token, longCandidates, `unknown option '${token}'`);
+      const inline = equals < 0 ? void 0 : token.slice(equals + 1);
+      if (option.value && inline === void 0) {
+        const next = argv[index + 1];
+        if (next === void 0)
+          throw new Usage(`option '--${name}' needs <${option.value}>`, {
+            kind: "flag",
+            word: token,
+            suggestions: [],
+            help: usageHelp(command)
+          });
+        index++;
+        accept(option, next, `--${name}`);
+      } else accept(option, inline, `--${name}`);
+      continue;
+    }
+    if (token.startsWith("-") && token !== "-") {
+      const short = token[1];
+      const option = byShort.get(short);
+      if (!option)
+        throw usageIssue(
+          command,
+          "flag",
+          token,
+          [...shortCandidates, ...longCandidates],
+          `unknown option '${token}'`
+        );
+      const attached = token.length > 2 ? token.slice(token[2] === "=" ? 3 : 2) : void 0;
+      if (option.value && attached === void 0) {
+        const next = argv[index + 1];
+        if (next === void 0)
+          throw new Usage(`option '-${short}' needs <${option.value}>`, {
+            kind: "flag",
+            word: token,
+            suggestions: [],
+            help: usageHelp(command)
+          });
+        index++;
+        accept(option, next, `-${short}`);
+      } else accept(option, attached, `-${short}`);
+      continue;
+    }
+    positionals.push(token);
+  }
+  if (command.subcommands?.length && positionals[0]) {
+    const candidates = command.subcommands.map(({ name }) => name);
+    if (!candidates.includes(positionals[0]))
+      throw usageIssue(
+        command,
+        "subcommand",
+        positionals[0],
+        candidates,
+        `'${positionals[0]}' is not an anima ${command.name} subcommand`
+      );
+  }
+  return { values, positionals };
+}
+function unavailable(error, json, io) {
+  if (!(error instanceof Error) || !/discover\..*not implemented/.test(error.message))
+    return void 0;
+  if (json) io.err(JSON.stringify({ error: "not available yet" }));
+  else io.err("not available yet");
+  return 1;
+}
+function featureText(info) {
+  const groups = /* @__PURE__ */ new Map();
+  for (const entry of info.provides)
+    groups.set(entry.kind, [...groups.get(entry.kind) ?? [], entry]);
+  const lines = [`${info.entry.name} \u2014 ${info.entry.summary}`];
+  if (groups.size) {
+    lines.push("Provides:");
+    for (const [kind, entries] of groups)
+      lines.push(`  ${kind}:`, ...entries.map((entry) => `    ${entry.name} \u2014 ${entry.summary}`));
+  }
+  lines.push(
+    `Docs: ${info.entry.docs?.join(", ") || "none"}`,
+    `Examples: ${info.entry.examples?.join(", ") || "none"}`,
+    `After: ${info.after.join(", ") || "none"}`
+  );
+  return lines.join("\n");
+}
+async function runFeatures(rest, json, io, discovery) {
+  if (rest.length > 1) throw new Usage("features takes at most one name");
+  try {
+    if (!rest[0]) {
+      const infos = discovery.features();
+      if (json) io.out(JSON.stringify({ features: infos }));
+      else for (const info2 of infos) io.out(`${info2.entry.name} \u2014 ${info2.entry.summary}`);
+      return 0;
+    }
+    const info = discovery.features(rest[0]);
+    if (!info)
+      throw usageIssue(
+        commandByName("features"),
+        "value",
+        rest[0],
+        discovery.features().map((f) => f.entry.name),
+        `unknown feature '${rest[0]}'`
+      );
+    if (json) io.out(JSON.stringify(info));
+    else io.out(featureText(info));
+    return 0;
+  } catch (error) {
+    const code = unavailable(error, json, io);
+    if (code !== void 0) return code;
+    throw error;
+  }
+}
+async function runSearch(rest, options, json, io, discovery) {
+  const query = rest.join(" ").trim();
+  if (!query) throw new Usage("search needs <words\u2026>");
+  const limit = options.limit === void 0 ? 10 : Number(options.limit);
+  if (!Number.isInteger(limit) || limit < 1) throw new Usage("--limit needs a positive integer");
+  try {
+    const results = discovery.search(query, {
+      kinds: options.kind,
+      limit
+    });
+    if (json) io.out(JSON.stringify({ results }));
+    else if (!results.length) io.out("No results.");
+    else {
+      for (const hit of results)
+        io.out(`${hit.entry.kind}  ${hit.entry.name}  ${hit.entry.summary}`);
+      const top = results[0].entry;
+      const next = top.docs?.[0] ? `anima docs ${top.docs[0]}` : top.schema ? `anima schema ${top.schema}` : void 0;
+      if (next) io.out(`Next: ${next}`);
+    }
+    return 0;
+  } catch (error) {
+    const code = unavailable(error, json, io);
+    if (code !== void 0) return code;
+    throw error;
+  }
+}
+async function runExamples(rest, options, json, io, discovery) {
+  if (rest.length > 1) throw new Usage("examples takes at most one topic or name");
+  if (options.print && options.out) throw new Usage("examples uses --print or -o dir, not both");
+  try {
+    const examples = discovery.examples(rest[0]);
+    if (!options.print && !options.out) {
+      if (json) io.out(JSON.stringify({ examples }));
+      else
+        for (const example2 of examples)
+          io.out(
+            `${example2.path} \u2014 ${example2.entry.summary} (requires ${example2.requires.join(", ") || "none"})`
+          );
+      return 0;
+    }
+    if (examples.length === 2 && examples[0].path.replace(/\.ani(ml)?$/, "") === examples[1].path.replace(/\.ani(ml)?$/, ""))
+      examples.splice(0, 2, examples.find((e) => e.path.endsWith(".animl")) ?? examples[0]);
+    if (examples.length !== 1)
+      throw new Usage(
+        examples.length ? "examples output needs one match; refine the topic or name" : "no matching example"
+      );
+    const example = examples[0];
+    const source = new URL(example.path, ROOT);
+    if (options.print) {
+      const text = readFileSync(source, "utf8");
+      if (json) io.out(JSON.stringify({ example, text }));
+      else if (io.write) io.write(text);
+      else io.out(text.trimEnd());
+      return 0;
+    }
+    const dir = String(options.out);
+    mkdirSync(dir, { recursive: true });
+    const wrote = resolve(dir, basename(example.path));
+    cpSync(source, wrote);
+    if (json) io.out(JSON.stringify({ example, wrote }));
+    else io.out(`wrote ${wrote}`);
+    return 0;
+  } catch (error) {
+    const code = unavailable(error, json, io);
+    if (code !== void 0) return code;
+    throw error;
+  }
+}
+async function run(argv, io, deps = {}) {
+  const jsonRequested = wantsJSON(argv);
+  const takesValue = /* @__PURE__ */ new Map();
+  for (const option of [...GLOBAL, ...COMMANDS.flatMap((c) => c.options)]) {
+    takesValue.set("--" + option.name, !!option.value);
+    if (option.short) takesValue.set("-" + option.short, !!option.value);
+  }
+  const leading = [];
+  let index = 0;
+  while (index < argv.length) {
+    const token = argv[index];
+    if (token === "--help" || token === "-h") {
+      io.out(overview());
+      return 0;
+    }
+    if (token === "--version") {
+      io.out(jsonRequested ? JSON.stringify({ version: CLI_VERSION }) : CLI_VERSION);
+      return 0;
+    }
+    if (!token.startsWith("-") || token === "-" || token === "--") break;
+    if (!token.startsWith("--") && token.length > 2 && takesValue.get(token.slice(0, 2))) {
+      leading.push(token);
+      index++;
+      continue;
+    }
+    const name = token.split("=")[0];
+    if (!takesValue.has(name)) break;
+    leading.push(token);
+    if (takesValue.get(name) && !token.includes("=")) {
+      const value = argv[index + 1];
+      if (value === void 0)
+        return emitUsage(new Usage(`option '${name}' needs a value`), void 0, jsonRequested, io);
+      leading.push(value);
+      index++;
+    }
+    index++;
+  }
+  const formats = leading.flatMap(
+    (t, i) => t === "--format" ? [leading[i + 1]] : t.startsWith("--format=") ? [t.slice(9)] : []
+  );
+  for (const value of formats)
+    if (value !== "text" && value !== "json")
+      return emitUsage(
+        usageIssue(
+          void 0,
+          "value",
+          value,
+          ["text", "json"],
+          `'${value}' is not a valid value for '--format'`
+        ),
+        void 0,
+        jsonRequested,
+        io
+      );
+  if (index >= argv.length) {
+    const stray = leading.find(
+      (token, i) => token.startsWith("-") && token !== "--format" && !token.startsWith("--format=") && leading[i - 1] !== "--format"
+    );
+    if (stray)
+      return emitUsage(
+        usageIssue(
+          void 0,
+          "flag",
+          stray,
+          ["--help", "--version", "--format"],
+          `option '${stray}' needs a command`
+        ),
+        void 0,
+        jsonRequested,
+        io
+      );
+    io.out(overview());
+    return 0;
+  }
+  const rawCommand = argv[index];
+  if (rawCommand.startsWith("-")) {
+    const error = usageIssue(
+      void 0,
+      "flag",
+      rawCommand,
+      ["--help", "-h", "--version", "--format"],
+      `unknown option '${rawCommand}'`
+    );
+    return emitUsage(error, void 0, jsonRequested, io);
+  }
+  const canonical = resolveAlias(rawCommand) ?? rawCommand;
+  const command = commandByName(canonical);
+  if (!command) {
+    const error = usageIssue(
+      void 0,
+      "command",
+      rawCommand,
+      COMMANDS.map(({ name }) => name),
+      `'${rawCommand}' is not an anima command. See 'anima help'.`
+    );
+    return emitUsage(error, void 0, jsonRequested, io);
+  }
+  let parsed;
+  try {
+    parsed = parseCommandArgs([...leading, ...argv.slice(index + 1)], command);
+  } catch (error) {
+    return emitUsage(error, command, jsonRequested, io);
+  }
+  const o = parsed.values;
+  const rest = parsed.positionals;
+  const json = o.format === "json";
+  if (o.help) {
+    io.out(commandHelp(command));
+    return 0;
+  }
+  const cmd = command.name;
+  const emit = (value) => io.out(JSON.stringify(value, null, json ? void 0 : 2));
+  const discovery = { ...DEFAULT_DISCOVERY, ...deps.discover };
+  try {
+    if (cmd === "help") {
+      if (o.json || json) return io.out(helpJSON()), 0;
+      if (rest.length > 1) throw new Usage("help takes at most one command");
+      if (!rest[0]) return io.out(overview(!!o.all)), 0;
+      const target = commandByName(resolveAlias(rest[0]) ?? rest[0]);
+      if (!target)
+        throw usageIssue(
+          command,
+          "command",
+          rest[0],
+          COMMANDS.map(({ name }) => name),
+          `'${rest[0]}' is not an anima command`
+        );
+      io.out(commandHelp(target));
+      return 0;
+    }
+    if (cmd === "version") {
+      if (rest.length) throw new Usage("version takes no positional arguments");
+      io.out(json ? JSON.stringify({ version: CLI_VERSION }) : CLI_VERSION);
+      return 0;
+    }
+    if (cmd === "completion") {
+      if (rest.length !== 1 || !["bash", "zsh", "fish"].includes(rest[0])) {
+        const word = rest[0] ?? "";
+        throw usageIssue(
+          command,
+          "value",
+          word,
+          ["bash", "zsh", "fish"],
+          word ? `'${word}' is not a supported shell` : "completion needs bash, zsh, or fish"
+        );
+      }
+      const script = completion(rest[0]);
+      io.out(json ? JSON.stringify({ shell: rest[0], script }) : script.trimEnd());
+      return 0;
+    }
+    if (cmd === "features") return await runFeatures(rest, json, io, discovery);
+    if (cmd === "search") return await runSearch(rest, o, json, io, discovery);
+    if (cmd === "examples") return await runExamples(rest, o, json, io, discovery);
+    let fonts = { measurer: new ToolMeasurer(), diagnostics: [] };
+    const prepareFonts = async () => {
+      fonts = { measurer: new ToolMeasurer(), diagnostics: [] };
+      const f = file(rest), source = projectSource(f);
+      let doc;
+      let sourceMap;
+      if (f.endsWith(".animl"))
+        ({ doc, map: sourceMap } = compile(source, {
+          file: f,
+          validate: false,
+          resolve: (path) => substituteConstants(readFileSync(path, "utf8"), findProject()?.constants)
+        }));
+      else {
+        try {
+          doc = JSON.parse(source);
+        } catch {
+        }
+      }
+      if (doc && typeof doc === "object" && (o.font?.length || "requires" in doc && Array.isArray(doc.requires) && doc.requires.some((r) => r === "text" || r === "fonts")))
+        fonts = documentFonts(doc, f, o.font, (pointer) => sourceMap?.get(pointer)?.file ?? f);
+      if (fonts.diagnostics.some((d) => d.severity === "error")) {
+        if (json) emit({ file: f, ok: false, diagnostics: fonts.diagnostics });
+        else report(f, fonts.diagnostics, io);
+        return false;
+      }
+      fonts.measurer.onDiagnostic = (diagnostic) => {
+        if (fonts.diagnostics.some((d) => d.code === diagnostic.code)) return;
+        fonts.diagnostics.push(diagnostic);
+        if (cmd !== "validate") report(f, [diagnostic], io);
+      };
+      await installToolMeasurer(fonts.measurer);
+      if (cmd !== "validate") report(f, fonts.diagnostics, io);
+      return true;
+    };
+    if (["sample", "validate", "render", "flatten", "build", "inspect", "bench"].includes(cmd) && !await prepareFonts())
+      return 1;
+    switch (cmd) {
+      case "bundle": {
+        if (rest.length) throw new Usage("bundle takes no positional arguments; use --modules");
+        const result = await bundleBrowser(o.modules, o.out ?? "anima.js", !!o.verbose);
+        if (json) emit(result);
+        else io.out(`${result.wrote}: ${result.min} B min; ${result.gzip} B gzip`);
+        return 0;
+      }
+      case "doctor": {
+        const result = await doctor();
+        if (json) emit(result);
+        else
+          for (const c of result.checks)
+            io.out(
+              `${c.pass ? "PASS" : "FAIL"} ${c.name}: ${c.message}${c.pass ? "" : "; hint: " + c.hint}`
+            );
+        return result.ok ? 0 : 1;
+      }
+      case "compare": {
+        if (rest.length !== 2 || !rest.every((path) => path.endsWith(".png")))
+          throw new Usage("compare needs two PNG files");
+        const tolerance = Number(o.tolerance ?? 0);
+        if (!Number.isInteger(tolerance) || tolerance < 0 || tolerance > 255)
+          throw new Usage("--tolerance must be an integer from 0 to 255");
+        if (o.out && !o.out.endsWith(".png")) throw new Usage("compare output must be .png");
+        const { diff, ...metrics } = comparePNG(
+          readFileSync(rest[0]),
+          readFileSync(rest[1]),
+          tolerance,
+          !!o.out
+        );
+        if (o.out) writeFileSync(o.out, diff);
+        emit({ ...metrics, tolerance, ...o.out ? { wrote: o.out } : {} });
+        return metrics.pass ? 0 : 1;
+      }
+      case "playground": {
+        if (rest.length > 1) throw new Usage("playground takes at most one .animl file");
+        const port = o.port === void 0 ? 4519 : Number(o.port);
+        if (!Number.isInteger(port) || port < 0 || port > 65535)
+          throw new Usage("--port takes an integer from 0 to 65535");
+        const host = await startPlayground({ file: rest[0] ?? findProject()?.entry, port });
+        if (json) emit({ url: host.url, writable: !!rest[0] });
+        else io.out(`Anima Playground: ${host.url}${rest[0] ? "" : " (example is read-only)"}`);
+        return 0;
+      }
+      case "library": {
+        if (rest[0] !== "update" || rest.length > 2)
+          throw new Usage("library update needs an AniML file");
+        try {
+          const updates = updateLibraries(file(rest.slice(1)), !!o.check);
+          if (json) emit({ updates });
+          else
+            for (const u of updates)
+              io.out(`${u.changed ? o.check ? "stale" : "updated" : "current"} ${u.file}`);
+          return o.check && updates.some((u) => u.changed) ? 1 : 0;
+        } catch (e) {
+          const error = e;
+          const diagnostic = {
+            code: error.code ?? "library-source",
+            pointer: error.pointer ?? "",
+            message: error.message,
+            hint: error.hint ?? "check local import src and source paths",
+            severity: "error"
+          };
+          if (json) emit({ diagnostics: [diagnostic] });
+          else
+            io.err(
+              `${diagnostic.code} ${diagnostic.pointer}: ${diagnostic.message}; ${diagnostic.hint}`
+            );
+          return 1;
+        }
+      }
+      case "validate":
+        return validate(file(rest), json, io, fonts.diagnostics);
+      case "inspect":
+        return inspect(file(rest), json, io, !!o.summary);
+      case "sample": {
+        const { model } = loaded(file(rest), io, json);
+        if (!model) return 1;
+        const script = scriptText(o.script, o.eval) ?? "snapshot";
+        const result = runScript(model, script, scriptOptions(o));
+        for (const item of result.output) io.out(JSON.stringify(item));
+        for (const d of result.diagnostics) io.err(JSON.stringify(d));
+        return result.diagnostics.length ? 1 : 0;
+      }
+      case "session": {
+        const f = file(rest);
+        if (rest.length !== 1) throw new Usage("session takes one file");
+        return await session(
+          async () => {
+            const next = check(f).model;
+            return next && await prepareFonts() ? next : void 0;
+          },
+          io,
+          scriptOptions(o)
+        );
+      }
+      case "bench": {
+        const f = file(rest);
+        const frames = o.frames === void 0 ? 600 : Number(o.frames);
+        if (rest.length !== 1 || !Number.isInteger(frames) || frames < 1 || frames > 1e6)
+          throw new Usage("bench --frames needs an integer from 1 to 1000000 and one file");
+        const result = bench(
+          () => loaded(f, io, json).model,
+          scriptText(o.script, o.eval) ?? "",
+          frames,
+          scriptOptions(o)
+        );
+        if (!result) return 1;
+        if (json || "diagnostics" in result) io.out(JSON.stringify(result));
+        else
+          io.out(
+            `compile ${result.compileMs.toFixed(3)} ms; ${result.frames} frames; step median ${result.step.median.toFixed(3)} \xB5s p95 ${result.step.p95.toFixed(3)} \xB5s; draw median ${result.draw.median.toFixed(3)} \xB5s p95 ${result.draw.p95.toFixed(3)} \xB5s; JS heap growth ${result.memory.growthBytes} B (${result.memory.bytesPerFrame.toFixed(2)} B/frame)`
+          );
+        return "diagnostics" in result ? 1 : 0;
+      }
+      case "render": {
+        const names = o.preset ?? [];
+        const presets = names.map((name) => {
+          const preset = findProject()?.presets?.[name];
+          if (!preset) throw new Usage("unknown render preset " + name);
+          return preset;
+        });
+        const explicit = Object.fromEntries(
+          Object.entries(o).filter(([, value]) => value !== void 0)
+        );
+        for (let i = 0; i < Math.max(1, presets.length); i++) {
+          const output = presets.length > 1 && o.out ? o.out.replace(/(\.[^.]+)$/, "-" + names[i] + "$1") : o.out;
+          const result = await render(
+            file(rest),
+            { ...presets[i], ...explicit, out: output },
+            json,
+            io,
+            fonts.measurer
+          );
+          if (result) return result;
+        }
+        return 0;
+      }
+      case "import-font": {
+        if (!o.out) throw new Usage("import-font needs -o local.ttf|otf");
+        if (o.google ? rest.length !== 0 : rest.length !== 1)
+          throw new Usage("import-font takes a font file or --google family:axes@values");
+        const assets = o.google ? await googleFonts(o.google, o.out, o.chars) : [importFont(file(rest), o.out, o.chars)];
+        emit({ assets });
+        return 0;
+      }
+      case "flatten": {
+        const f = file(rest), result = loaded(f, io, json);
+        if (!result.model) return 1;
+        const doc = flattenText(JSON.parse(result.text), fonts.measurer, o.node), text = format(doc);
+        if (o.out) writeFileSync(o.out, o.out.endsWith(".animl") ? decompile(text) : text);
+        else if (io.write) io.write(text);
+        else io.out(text);
+        if (json && o.out) emit({ wrote: o.out });
+        return 0;
+      }
+      case "build": {
+        const dir = o["out-dir"] ?? (!o.out ? findProject()?.out : void 0);
+        if (dir) return await exportProject(file(rest), dir, json, io);
+        return await build(file(rest), o.out, json, io, !!o.embed);
+      }
+      case "import": {
+        const f = file(rest);
+        const name = nameFromFile(f.replace(/\.(svg|json)$/i, ".svg")).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "imported";
+        const source = readFileSync(f, "utf8");
+        if (!/\.(svg|json)$/i.test(f)) throw new Usage("import needs a .svg or Lottie .json file");
+        let imported;
+        try {
+          imported = /\.svg$/i.test(f) ? importSVG(source, name) : importLottie(source, name);
+        } catch (error) {
+          const diagnostics2 = [
+            {
+              code: "import-invalid",
+              severity: "error",
+              pointer: "",
+              message: error instanceof Error ? error.message : "invalid source document",
+              hint: "provide a well-formed SVG or Lottie animation with a positive viewBox/frame rate"
+            }
+          ];
+          if (json) io.out(JSON.stringify({ file: f, ok: false, diagnostics: diagnostics2 }));
+          else report(f, diagnostics2, io);
+          return 1;
+        }
+        const checked = load(imported.doc);
+        const diagnostics = [...imported.diagnostics, ...checked.diagnostics];
+        if (diagnostics.some((d) => d.severity === "error")) {
+          if (json) io.out(JSON.stringify({ file: f, ok: false, diagnostics }));
+          else report(f, diagnostics, io);
+          return 1;
+        }
+        const text = decompile(format(imported.doc));
+        if (o.out) writeFileSync(o.out, text);
+        if (json)
+          io.out(
+            JSON.stringify({
+              file: f,
+              ok: true,
+              diagnostics,
+              ...o.out ? { wrote: o.out } : { text }
+            })
+          );
+        else {
+          report(f, diagnostics, io);
+          if (!o.out) io.out(text.trimEnd());
+        }
+        return 0;
+      }
+      case "decompile": {
+        const f = file(rest);
+        const result = loaded(f, io, json);
+        if (!result.model) return 1;
+        const text = decompile(result.text);
+        if (o.out) writeFileSync(o.out, text);
+        else io.out(text.trimEnd());
+        return 0;
+      }
+      case "fmt": {
+        const f = file(rest);
+        const text = readFileSync(f, "utf8");
+        let output;
+        if (f.endsWith(".animl")) {
+          const result = formatMarkup(text);
+          const diagnostics = result.diagnostics.map((d) => ({ ...d, file: f }));
+          if (!result.text) {
+            if (json) emit({ file: f, ok: false, diagnostics });
+            else report(f, diagnostics, io);
+            return 1;
+          }
+          output = result.text;
+        } else {
+          let doc;
+          try {
+            doc = JSON.parse(text);
+          } catch (error) {
+            io.err(`${f}: not JSON: ${error.message}`);
+            return 1;
+          }
+          output = format(doc);
+        }
+        if (o.check) {
+          if (json) emit({ file: f, formatted: output === text });
+          else
+            io.out(
+              output === text ? `${f}: formatted` : `${f}: not formatted (run anima fmt --write)`
+            );
+          return output === text ? 0 : 1;
+        }
+        if (o.write) {
+          writeFileSync(f, output);
+          if (json) emit({ wrote: f });
+          return 0;
+        }
+        io.out(output.trimEnd());
+        return 0;
+      }
+      case "new":
+        return o.sample ? sampleProject(rest, o, json, io) : scaffold(rest, o, json, io);
+      case "schema":
+        if (rest[0]) rest[0] = schemaTopic(rest[0]);
+        if (o.all && o["json-schema"])
+          throw new Usage("schema takes --all or --json-schema, not both");
+        if (o.search !== void 0 && !String(o.search).trim())
+          throw new Usage("--search needs at least one word");
+        if (o.animatable || o.bindable || o.inherited || o["editor-only"])
+          return filteredSchema(rest[0], o, json, io);
+        if (o.all && !rest[0] && !o.search) return schemaAll(json, io);
+        return o.search ? schemaSearch(o.search, json, io) : schema(rest[0], !!o["json-schema"], json, io);
+      case "docs":
+        return (o.full ? docsFull : docs)(rest[0], !!o.list, json, io, rest[1]);
+      default:
+        throw new Usage(`command '${cmd}' has no dispatcher`);
+    }
+  } catch (error) {
+    if (error instanceof Usage) return emitUsage(error, command, json, io);
+    if (error instanceof ScriptError) {
+      io.err(
+        JSON.stringify({
+          code: error.code,
+          pointer: error.pointer,
+          message: error.message,
+          hint: error.hint
+        })
+      );
+      return 2;
+    }
+    const detail = error;
+    if (detail.code) {
+      const diagnostic = {
+        code: detail.code,
+        pointer: detail.pointer ?? "",
+        message: detail.message,
+        hint: detail.hint ?? "check local files and browser installation"
+      };
+      if (json) emit({ diagnostics: [diagnostic] });
+      else
+        io.err(
+          `${diagnostic.code} ${diagnostic.pointer}: ${diagnostic.message}; hint: ${diagnostic.hint}`
+        );
+    } else io.err(detail.message);
+    return 1;
+  }
+}
+function file(rest) {
+  const f = rest[0] ?? findProject()?.entry;
+  if (!f) throw new Usage("missing <file>");
+  if (!existsSync(f)) throw new Usage(`no such file: ${f}`);
+  return f;
+}
+function scriptOptions(o) {
+  const seed = o.seed === void 0 ? void 0 : Number(o.seed);
+  if (seed !== void 0 && (!Number.isInteger(seed) || seed < 0 || seed > 4294967295))
+    throw new Usage("--seed needs a uint32 integer");
+  return { reducedMotion: !!o["reduced-motion"], all: !!o.all, semantics: !!o.semantics, seed };
+}
+function scriptText(file2, inline) {
+  if (file2 && inline) throw new Usage("use --script or -e, not both");
+  if (file2) return readFileSync(file2, "utf8");
+  return inline?.replace(/;/g, "\n");
+}
+function subtractionHints(diagnostics) {
+  const ambiguous = diagnostics.flatMap((d) => {
+    const match = d.code === "data-path" && /unknown data path (\$[\w:.-]+)-(\d+)$/.exec(d.message);
+    return match ? [{ diagnostic: d, path: match[1], number: match[2] }] : [];
+  });
+  return diagnostics.filter(
+    (d) => !ambiguous.some(
+      ({ diagnostic, path, number }) => d.code === "unknown-input" && d.pointer === diagnostic.pointer && d.message.includes(path + "-" + number)
+    )
+  ).map((d) => {
+    const entry = ambiguous.find(({ diagnostic }) => diagnostic === d);
+    return entry ? {
+      ...d,
+      hint: `write \`${entry.path} - ${entry.number}\` (spaces around the minus): names may contain hyphens`
+    } : d;
+  });
+}
+function check(f) {
+  const text = projectSource(f);
+  if (f.endsWith(".animl")) {
+    const c = compile(text, {
+      file: f,
+      resolve: (path) => substituteConstants(readFileSync(path, "utf8"), findProject()?.constants)
+    });
+    const diagnostics2 = subtractionHints(c.diagnostics);
+    if (c.doc) {
+      for (const d of glyphDiagnostics(c.doc)) {
+        let pointer = d.pointer;
+        while (!c.map.has(pointer) && pointer) pointer = pointer.slice(0, pointer.lastIndexOf("/"));
+        const pos = c.map.get(pointer);
+        diagnostics2.push({ ...d, file: f, line: pos?.line, column: pos?.col });
+      }
+    }
+    return { model: c.text ? load(c.text).model : void 0, diagnostics: diagnostics2, text: c.text ?? "" };
+  }
+  const r = load(text);
+  const diagnostics = subtractionHints(r.diagnostics);
+  let at = /* @__PURE__ */ new Map();
+  try {
+    JSON.parse(text);
+    const loc = locate(text);
+    at = loc.at;
+    for (const d of loc.duplicates)
+      diagnostics.unshift({
+        code: "duplicate-key",
+        severity: "error",
+        pointer: d.pointer,
+        message: "this key appears twice in its object; JSON parsers keep only the last",
+        hint: "remove or merge one of them"
+      });
+    const doc = JSON.parse(text);
+    diagnostics.push(...glyphDiagnostics(doc));
+  } catch {
+  }
+  for (const d of diagnostics) {
+    const off = d.code === "json-syntax" ? syntaxErrorAt(text) : at.get(d.pointer);
+    if (off !== void 0 && off !== null) [d.line, d.column] = lineCol(text, off);
+  }
+  const failed = diagnostics.some((d) => d.severity === "error");
+  return { model: failed ? void 0 : r.model, diagnostics, text };
+}
+function glyphDiagnostics(doc) {
+  const diagnostics = [];
+  for (const [name, g] of Object.entries(
+    doc?.glyphs ?? {}
+  ))
+    if (typeof g?.sha256 === "string" && typeof g.d === "string" && sha256(g.d) !== g.sha256)
+      diagnostics.push({
+        code: "hash-mismatch",
+        severity: "warning",
+        pointer: `/glyphs/${name}/sha256`,
+        message: `glyph "${name}" changed since its hash was taken`,
+        hint: "if it was re-traced, check that subpath indices still pick the right parts, then update sha256"
+      });
+  return diagnostics;
+}
+function loaded(f, io, json = false) {
+  const r = check(f);
+  if (!r.model) {
+    if (json && f.endsWith(".animl"))
+      io.out(JSON.stringify({ file: f, ok: false, diagnostics: r.diagnostics }));
+    else report(f, r.diagnostics, io);
+    io.err(`${f}: fix the errors above first (anima validate ${f})`);
+  }
+  return r;
+}
+function report(f, ds, io) {
+  for (const d of ds) {
+    const where = d.line ? `${d.file ?? f}:${d.line}:${d.column}` : d.file ?? f;
+    for (const r of d.related ?? [])
+      io.err(`  related: ${r.file ?? f}:${r.line}:${r.column}`);
+    if (d.file) {
+      io.err(`${where} ${d.severity} ${d.code} ${d.message}`);
+      if (d.hint) io.err(`  hint: ${d.hint}`);
+      continue;
+    }
+    io.err(
+      `${where} ${d.severity} ${d.code} ${d.pointer || "/"}: ${d.message}${d.hint ? ` \u2014 ${d.hint}` : ""}`
+    );
+  }
+}
+function validate(f, json, io, extra = []) {
+  const { model, diagnostics } = check(f);
+  diagnostics.push(...extra);
+  if (json) io.out(JSON.stringify({ file: f, ok: !!model, diagnostics }));
+  else {
+    report(f, diagnostics, io);
+    const errors = diagnostics.filter((d) => d.severity === "error").length;
+    const warnings = diagnostics.length - errors;
+    io.out(
+      model ? `${f}: ok${warnings ? ` (${warnings} warning${warnings > 1 ? "s" : ""})` : ""}` : `${f}: ${errors} error${errors > 1 ? "s" : ""}${warnings ? `, ${warnings} warning${warnings > 1 ? "s" : ""}` : ""}`
+    );
+  }
+  return model ? 0 : 1;
+}
+function inspect(f, json, io, summaryOnly = false) {
+  const { model, diagnostics } = loaded(f, io, json);
+  if (!model) return 1;
+  if (summaryOnly) {
+    const wiring = wiringSummary(model, diagnostics);
+    if (json) io.out(JSON.stringify({ wiring }));
+    else
+      io.out(
+        [
+          "code	pointer	message	hint",
+          ...wiring.map((d) => `${d.code}	${d.pointer}	${d.message}	${d.hint}`)
+        ].join("\n")
+      );
+    return 0;
+  }
+  const m = model;
+  const doc = m.doc;
+  const node = (i) => {
+    const n = m.nodes[i];
+    const animated = [...m.addrs.keys()].filter((a) => a.startsWith(n.id + ".")).map((a) => a.slice(n.id.length + 1));
+    return {
+      id: n.id,
+      type: n.type,
+      ...n.raw.component ? { component: n.raw.component } : {},
+      ...n.raw.glyph ? { glyph: n.raw.glyph, subpaths: n.raw.subpaths ?? "all" } : {},
+      ...n.raw.pivot ? { pivot: n.raw.pivot } : {},
+      ...animated.length ? { animated } : {},
+      ...n.raw.knockout !== void 0 ? { knockout: n.raw.knockout } : {},
+      ...n.children.length ? { children: n.children.map(node) } : {}
+    };
+  };
+  const writers = /* @__PURE__ */ new Map();
+  const layers = m.layers.map((l) => {
+    const writes = [...new Set(l.states.flatMap((s) => s.writes))];
+    for (const a of writes) writers.set(a, [...writers.get(a) ?? [], l.name]);
+    return {
+      name: l.name,
+      initial: l.states[l.initial].name,
+      writes,
+      states: l.states.map((s) => ({
+        name: s.name,
+        kind: doc.machine.layers[l.name].states[s.name].kind,
+        ...s.play !== void 0 ? { play: m.timelines[s.play].name } : {
+          pose: Object.fromEntries(
+            [...s.pose].map(([k, v]) => [
+              k,
+              Array.isArray(v) ? `#${v.map((c) => c.toString(16).padStart(2, "0")).join("")}` : v
+            ])
+          )
+        },
+        ...s.emit ? { emit: s.emit } : {},
+        on: (doc.machine.layers[l.name].states[s.name].on ?? []).map(
+          (t) => `${t.when} \u2192 ${t.to}${t.blend ? ` (${t.blend}s)` : ""}`
+        ),
+        ...s.on.length || l.states.some(
+          (a) => doc.machine.layers[l.name].states[a.name].kind === "any" && a.on.length
+        ) ? {} : { deadEnd: true }
+      }))
+    };
+  });
+  const preview = new Player(m);
+  preview.step(0);
+  const instances = preview.inspect().filter((l) => l.layer.includes("/"));
+  const slots = /* @__PURE__ */ new Map();
+  const inputs = (player, prefix = "") => {
+    const repeated = listState(player)?.runs ?? [];
+    const ids = repeated.map((r) => player.model.nodes[r.spec.node].id + ".");
+    for (const name of player.model.inputs.keys())
+      if (!(prefix && name.startsWith("$")) && !ids.some((id) => name.startsWith(id)))
+        slots.set(prefix + name, player.model.inputs.get(name).type);
+    for (const run2 of repeated) {
+      for (const item of run2.items)
+        inputs(
+          item.player,
+          prefix + player.model.nodes[run2.spec.node].id + "." + item.index + "."
+        );
+      const base = prefix + player.model.nodes[run2.spec.node].id + ".";
+      for (const name of slots.keys())
+        if (name.startsWith(base) && !run2.items.some((item) => name.startsWith(base + item.index + ".")))
+          slots.delete(name);
+    }
+    for (const [id, child] of player.nested?.players ?? [])
+      inputs(child, prefix + id + ".");
+  };
+  inputs(preview);
+  const summary = {
+    instances,
+    name: doc.name,
+    title: doc.title,
+    grid: m.grid,
+    viewBox: m.viewBox,
+    glyphs: Object.fromEntries(
+      Object.entries(doc.glyphs ?? {}).filter(([name]) => name !== "$comment").map(([name, g]) => [name, { subpaths: inspectGlyph(g.d) }])
+    ),
+    nodes: m.nodes.flatMap((n, i) => n.parent < 0 ? [node(i)] : []),
+    inputs: Object.fromEntries(slots),
+    timelines: m.timelines.map((t) => ({
+      name: t.name,
+      duration: t.duration,
+      loop: t.loop,
+      reducedMotion: t.reduced,
+      writes: t.tracks.map((x) => x.addr),
+      events: t.events.map((e) => e[1])
+    })),
+    layers,
+    bound: [
+      ...Object.keys(doc.bind ?? {}).filter((a) => a !== "$comment"),
+      ...m.nodes.flatMap(
+        (n) => Object.entries(n.raw.inputs ?? {}).filter(([, v]) => typeof v === "string").map(([key]) => n.id + "." + key)
+      )
+    ],
+    overlaps: [...writers].filter(([, ls]) => ls.length > 1).map(([a, ls]) => `${a} is written by ${ls.join(", ")} (the last one wins)`),
+    listeners: m.listeners.map(
+      (l, i) => `${l.on}${l.target >= 0 ? ` on ${m.nodes[l.target].id}` : ""} \u2192 ${[...l.fire.map((x) => `fire ${x}`), ...l.set.map(([k, v]) => `set ${k}=${v}`), ...l.toggle.map((x) => `toggle ${x}`), ...l.emit ? [`emit ${l.emit}`] : [], ...Object.entries(doc.listeners?.[i]?.write ?? {}).map(([field, input]) => `write ${field} \u2192 ${input}`)].join(", ")}`
+    ),
+    a11y: doc.a11y ?? null,
+    warnings: diagnostics.filter((d) => d.severity === "warning").map((d) => `${d.code} ${d.pointer}: ${d.message}`)
+  };
+  if (json) return io.out(JSON.stringify(summary)), 0;
+  const lines = [
+    `${doc.name}${doc.title ? ` \u2014 ${doc.title}` : ""} (grid ${m.grid}, viewBox ${m.viewBox.join(" ")})`,
+    "",
+    "glyphs (bbox: minX minY maxX maxY, grid units; hole hints use bbox containment only)"
+  ];
+  for (const [name, glyph] of Object.entries(summary.glyphs)) {
+    lines.push(`  ${name}`);
+    for (const sp of glyph.subpaths)
+      lines.push(
+        `    ${sp.index}: bbox ${sp.bbox.join(" ")}${sp.likelyHoleOf.length ? `; likely hole of ${sp.likelyHoleOf.join(", ")}` : ""}`
+      );
+  }
+  lines.push("", "nodes");
+  const tree = (n, d) => {
+    lines.push(
+      `${d}${n.id} (${n.type}${n.glyph ? ` ${n.glyph}[${n.subpaths}]` : ""})${n.pivot ? ` pivot ${n.pivot.join(",")}` : ""}${n.animated ? ` animates ${n.animated.join(", ")}` : ""}${n.knockout !== void 0 ? ` knockout ${n.knockout}` : ""}`
+    );
+    for (const c of n.children ?? []) tree(c, d + "  ");
+  };
+  for (const n of summary.nodes) tree(n, "  ");
+  lines.push(
+    "",
+    `inputs: ${Object.entries(summary.inputs).map(([k, v]) => `${k} (${v})`).join(", ") || "none"}`,
+    "",
+    "timelines"
+  );
+  for (const t of summary.timelines)
+    lines.push(
+      `  ${t.name}: ${t.duration}s ${t.loop}, reduced motion: ${t.reducedMotion}${t.events.length ? `, events ${t.events.join(", ")}` : ""}`,
+      `    writes ${t.writes.join(", ")}`
+    );
+  lines.push("", "machine");
+  for (const l of layers) {
+    lines.push(`  layer ${l.name} (writes ${l.writes.join(", ") || "nothing"})`);
+    for (const s of l.states)
+      lines.push(
+        `    ${s.name === l.initial ? "*" : " "}${s.name}: ${s.kind ? `${s.kind} state` : "play" in s ? `play ${s.play}` : `pose ${JSON.stringify(s.pose)}`}${s.emit ? `, emit ${s.emit}` : ""}${"deadEnd" in s && s.kind !== "any" ? " (no way out)" : ""}`,
+        ...s.on.map((t) => `        ${t}`)
+      );
+  }
+  if (instances.length)
+    lines.push("", "instances", ...instances.map((l) => `  ${l.layer}: ${l.state}`));
+  if (summary.bound.length) lines.push("", "bound", ...summary.bound.map((a) => `  ${a}`));
+  lines.push("", "listeners", ...summary.listeners.map((l) => `  ${l}`));
+  if (summary.overlaps.length) lines.push("", "overlaps", ...summary.overlaps.map((x) => `  ${x}`));
+  if (summary.warnings.length) lines.push("", "warnings", ...summary.warnings.map((x) => `  ${x}`));
+  io.out(lines.join("\n"));
+  return 0;
+}
+async function render(f, o, json, io, measurer) {
+  const drawFrame = (player2, look2, size2, id) => {
+    const svg2 = frameSVG(player2, look2, size2, id);
+    return o["browser-text"] ? embedFontCSS(svg2, measurer) : outlineSVG(svg2, measurer);
+  };
+  const rasterize = (svg2) => o["browser-text"] ? browserTextPNG(svg2, measurer) : Promise.resolve(toPNG(svg2));
+  const out = o.out;
+  const compare = o.compare;
+  if (!compare && !out && !o.probe && !o.audio || out && !/\.(svg|png|webm)$/.test(out))
+    throw new Usage("render needs -o <file>.svg|png|webm");
+  let { model } = loaded(f, io, json);
+  if (!model) return 1;
+  if (o.component) {
+    const names = componentNames(model.doc, String(o.component));
+    if (names.length > 1) throw new Usage("ambiguous-component: use " + names.join(" or "));
+    const name = names[0];
+    const definition = name && model.doc.components?.[name];
+    if (!definition) throw new Usage("unknown component " + o.component);
+    const doc = model.doc;
+    const selected = load({
+      anima: "0.1",
+      requires: doc.requires,
+      components: doc.components,
+      ...doc.meta ? { meta: doc.meta } : {},
+      ...doc.data ? { data: doc.data } : {},
+      ...doc.assets ? { assets: doc.assets } : {},
+      ...doc.converters ? { converters: doc.converters } : {},
+      name: name.replaceAll(":", "-"),
+      ...definition,
+      ...typeof definition.data === "string" ? { data: { ...doc.data, model: definition.data } } : {}
+    });
+    if (!selected.model) {
+      report(f, selected.diagnostics, io);
+      return 1;
+    }
+    model = selected.model;
+  }
+  try {
+    embedAssets(model.doc, f, true);
+    await imageDimensions(model.doc);
+  } catch {
+    const d = [
+      {
+        code: "asset-load",
+        severity: "error",
+        pointer: "/assets",
+        message: "cannot read or decode image asset",
+        hint: "check the source relative to the document"
+      }
+    ];
+    if (json) io.out(JSON.stringify({ file: f, ok: false, diagnostics: d }));
+    else report(f, d, io);
+    return 1;
+  }
+  const over = {};
+  for (const c of o.color ?? []) {
+    const [k, v] = c.split("=");
+    if (!k || !v) throw new Usage("--color takes slot=value");
+    over[k] = v;
+  }
+  const base = o.dark ? DARK : LIGHT;
+  const look = {
+    paint: staticSlots(over),
+    color: o.current ?? base.color,
+    background: o.background ?? base.background
+  };
+  const size = o.size ? Number(o.size) : compare ? 256 : 240;
+  if (!Number.isInteger(size) || size < 1) throw new Usage("--size takes a positive integer");
+  const tolerance = o.tolerance === void 0 ? 0 : Number(o.tolerance);
+  if (!Number.isInteger(tolerance) || tolerance < 0 || tolerance > 255)
+    throw new Usage("--tolerance must be an integer from 0 to 255");
+  const fit = String(o.fit ?? "contain");
+  if (!["contain", "cover", "fill", "none"].includes(fit))
+    throw new Usage("--fit takes contain|cover|fill|none");
+  if (o.viewport && !/^[1-9]\d*x[1-9]\d*$/.test(String(o.viewport)))
+    throw new Usage("--viewport takes WxH positive integers");
+  const [width, height] = o.viewport ? String(o.viewport).split("x").map(Number) : [size, size];
+  const scale = Number(o.scale ?? 1);
+  if (!Number.isFinite(scale) || scale <= 0 || scale > 1)
+    throw new Usage("--scale takes a number in (0,1]");
+  if (o.sheet && (o.viewport || o.scale || o.fit))
+    throw new Usage("viewport, scale and fit require a single frame");
+  if (o.at !== void 0 && (!Number.isFinite(Number(o.at)) || Number(o.at) < 0))
+    throw new Usage("--at takes nonnegative seconds");
+  const script = scriptText(o.script, o.eval) ?? "";
+  const audioEvents = [];
+  const session2 = createScriptSession(model, {
+    ...scriptOptions(o),
+    onEvents: (events) => audioEvents.push(...events)
+  });
+  const ran = session2.execute(script);
+  session2.finish();
+  for (const d of ran.diagnostics) io.err(JSON.stringify(d));
+  if (ran.diagnostics.length) return 1;
+  session2.execute("advance 0");
+  if (o.at) session2.execute("advance " + Number(o.at));
+  const player = session2.player;
+  if (compare) {
+    if (o.sheet || o.frames !== void 0 || o.probe || o.audio || o.viewport || o.scale || o.fit || out && !out.endsWith(".png"))
+      throw new Usage("--compare takes a single frame and optional -o diff.png");
+    const result = o["browser-text"] ? comparePNG(
+      await rasterize(drawFrame(player, { paint: look.paint, color: "#000" }, size)),
+      toPNG(comparisonSVG(readFileSync(compare, "utf8"), size), size),
+      tolerance,
+      !!out
+    ) : compareSVG(
+      drawFrame(player, { paint: look.paint, color: "#000" }, size),
+      readFileSync(compare, "utf8"),
+      size,
+      tolerance,
+      !!out
+    );
+    if (out) writeFileSync(out, result.diff);
+    const { diff, ...metrics } = result;
+    void diff;
+    const report2 = { ...metrics, size, tolerance, ...out ? { wrote: out } : {} };
+    if (json) io.out(JSON.stringify(report2));
+    else
+      io.out(
+        `${metrics.pass ? "PASS" : "FAIL"}: ${metrics.differingPixels} differing pixels, max channel difference ${metrics.maxChannelDifference}; ${metrics.pixelsBeyondTolerance} pixels beyond tolerance ${tolerance}${out ? `; wrote ${out}` : ""}`
+      );
+    return metrics.pass ? 0 : 1;
+  }
+  if (o.frames !== void 0 || out?.endsWith(".webm")) {
+    const n = Number(o.frames ?? 60), fps = Number(o.fps ?? 60);
+    if (!Number.isInteger(n) || n < 1 || n > 1e4 || !Number.isFinite(fps) || fps <= 0 || fps > 240 || o.sheet || compare || !out)
+      throw new Usage(
+        "sequences need --frames 1..10000, --fps (0,240], -o file.png|file.webm; no sheet or compare"
+      );
+    if (!/\.(png|webm)$/.test(out)) throw new Usage("sequences output PNG or WebM");
+    const images = [];
+    const wrote = [];
+    for (let i = 0; i < n; i++) {
+      if (i) session2.execute("advance " + 1 / fps);
+      const svg2 = viewportSVG(
+        drawFrame(player, look, size),
+        width,
+        height,
+        fit,
+        scale,
+        look.background
+      );
+      const png2 = await rasterize(svg2);
+      if (out.endsWith(".webm")) images.push(png2);
+      else {
+        const path = out.replace(/\.png$/, "-" + String(i).padStart(4, "0") + ".png");
+        writeFileSync(path, png2);
+        wrote.push(path);
+      }
+    }
+    if (out.endsWith(".webm")) {
+      const { encodeVideo } = await import("./video.js");
+      writeFileSync(out, await encodeVideo(images, fps));
+      wrote.push(out);
+    }
+    if (o.audio) {
+      writeFileSync(String(o.audio), await mixAudio(model, audioEvents, player.time, f));
+      wrote.push(String(o.audio));
+    }
+    io.out(json ? JSON.stringify({ wrote, frames: n, fps }) : "wrote " + wrote.join(", "));
+    return 0;
+  }
+  let svg;
+  if (o.sheet) {
+    const n = Number(o.sheet);
+    if (!Number.isInteger(n) || n < 2) throw new Usage("--sheet takes a frame count \u2265 2");
+    let span = o.over ? Number(o.over) : 0;
+    if (!span) {
+      const probe = runScript(model, script, scriptOptions(o)).player;
+      probe.step(0);
+      if (o.at) probe.step(Number(o.at));
+      while (span < 10) {
+        span += 1 / 60;
+        if (probe.step(1 / 60).settled) break;
+      }
+      span = Math.max(span, 0.5) + 1e-6;
+    }
+    const frames = [];
+    const t0 = player.time;
+    for (let k = 0; k < n; k++) {
+      if (k) player.step(span / (n - 1));
+      frames.push([
+        `t=${(player.time - t0).toFixed(3)}s`,
+        drawFrame(player, look, void 0, `f${k}`)
+      ]);
+    }
+    svg = sheetSVG(frames, look, size >= 240 ? 160 : size);
+  } else svg = drawFrame(player, look, size);
+  if (!o.sheet) svg = viewportSVG(svg, width, height, fit, scale, look.background);
+  const png = out?.endsWith(".png") || o.probe ? await rasterize(svg) : void 0;
+  let probes;
+  if (o.probe) {
+    try {
+      probes = probePNG(png, String(o.probe));
+    } catch (e) {
+      throw new Usage(e.message);
+    }
+  }
+  if (o.audio) writeFileSync(String(o.audio), await mixAudio(model, audioEvents, player.time, f));
+  if (out) writeFileSync(out, out.endsWith(".png") ? png : svg);
+  if (o.probe) {
+    io.out(JSON.stringify({ wrote: out, time: player.time, probes }));
+    return 0;
+  }
+  if (json) io.out(JSON.stringify({ wrote: out, time: player.time, states: player.states() }));
+  else io.out(`wrote ${out ?? o.audio}`);
+  return 0;
+}
+function scaffold(rest, o, json, io) {
+  const name = rest[0];
+  if (!name) throw new Usage("new needs a <name>");
+  if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(name) || /-\d+$/.test(name))
+    throw new Usage(`"${name}" must be kebab-case and not end in -<digits>`);
+  if (!!o.glyph === !!o.glyphy)
+    throw new Usage("new needs exactly one of --glyph <file.svg> or --glyphy <project-dir>");
+  const g = o.glyph ? readGlyphSVG(o.glyph) : readGlyphy(o.glyphy, name);
+  const doc = newDoc(name, g);
+  const out = o.out ?? `${name}.${o.ani ? "ani" : "animl"}`;
+  if (existsSync(out) && !o.force) {
+    io.err(`${out} exists (use --force to overwrite)`);
+    return 1;
+  }
+  const text = o.ani || out.endsWith(".ani") ? format(doc) : decompile(doc);
+  if (out.endsWith(".animl") && !o.ani) {
+    const c = compile(text, { file: out });
+    if (c.diagnostics.length) {
+      if (json) io.out(JSON.stringify({ file: out, ok: false, diagnostics: c.diagnostics }));
+      else report(out, c.diagnostics, io);
+      return 1;
+    }
+  }
+  writeFileSync(out, text);
+  if (json)
+    io.out(
+      JSON.stringify({
+        wrote: out,
+        glyph: o.glyph ? nameFromFile(o.glyph) : name,
+        subpaths: (g.d.match(/[Mm]/g) ?? []).length
+      })
+    );
+  else
+    io.out(
+      `wrote ${out} (${(g.d.match(/[Mm]/g) ?? []).length} subpaths; see them with: anima inspect ${out})`
+    );
+  return 0;
+}
+async function build(f, out, json, io, embed = false) {
+  const source = f.endsWith(".animl") ? projectSource(f) : readFileSync(f, "utf8");
+  let text;
+  let diagnostics;
+  let sourceMap;
+  if (/\.html?$/i.test(f)) ({ text, diagnostics } = buildHTML(source, f));
+  else if (f.endsWith(".animl"))
+    ({
+      text,
+      diagnostics,
+      map: sourceMap
+    } = compile(source, {
+      file: f,
+      resolve: (path) => substituteConstants(readFileSync(path, "utf8"), findProject()?.constants)
+    }));
+  else throw new Usage("build needs a .animl or .html file");
+  if (text !== void 0) {
+    const docs2 = [];
+    const maps = [];
+    if (/\.html?$/i.test(f))
+      buildHTML(source, f, (doc, map) => {
+        docs2.push(doc);
+        maps.push(map);
+      });
+    else {
+      docs2.push(JSON.parse(text));
+      maps.push(sourceMap);
+    }
+    const encoder = new ImageEncoder();
+    try {
+      for (const [i, doc] of docs2.entries())
+        diagnostics.push(
+          ...await buildAssets(
+            doc,
+            f,
+            embed,
+            encoder,
+            (pointer) => maps[i]?.get(pointer)?.file ?? f
+          )
+        );
+    } finally {
+      await encoder.close();
+    }
+    if (diagnostics.some((d) => d.severity === "error")) text = void 0;
+    else if (/\.html?$/i.test(f)) {
+      let i = 0;
+      ({ text } = buildHTML(source, f, (doc) => Object.assign(doc, docs2[i++])));
+    } else text = format(docs2[0]);
+  }
+  if (json && (text === void 0 || out))
+    io.out(
+      JSON.stringify({
+        file: f,
+        ok: text !== void 0,
+        diagnostics,
+        ...text !== void 0 && out ? { wrote: out } : {}
+      })
+    );
+  else if (json && diagnostics.length) io.err(JSON.stringify({ file: f, diagnostics }));
+  else report(f, diagnostics, io);
+  if (text === void 0) return 1;
+  if (out) writeFileSync(out, text);
+  else if (io.write) io.write(text);
+  else io.out(text);
+  return 0;
+}
+function sampleProject(rest, o, json, io) {
+  const sample = String(o.sample), target = o.out ?? rest[0];
+  if (!["bell", "moon", "progress"].includes(sample))
+    throw new Usage("--sample takes bell|moon|progress");
+  if (!target) throw new Usage("new --sample needs a destination directory");
+  if (existsSync(target)) {
+    io.err("sample destination already exists; choose a new directory");
+    return 1;
+  }
+  mkdirSync(target, { recursive: true });
+  cpSync(new URL(`examples/${sample}.animl`, ROOT), resolve(target, "main.animl"));
+  cpSync(new URL("examples/lib", ROOT), resolve(target, "lib"), { recursive: true });
+  writeFileSync(
+    resolve(target, "anima.json"),
+    JSON.stringify(
+      { entry: "main.animl", out: "dist", presets: { preview: { size: 240 } } },
+      null,
+      2
+    ) + "\n"
+  );
+  writeFileSync(
+    resolve(target, "AGENTS.md"),
+    "# Animation project\n\nRun `anima validate`, `anima render --preset preview -o preview.png`, and `anima build`.\nEdit main.animl; anima.json defines project defaults.\n"
+  );
+  if (json) io.out(JSON.stringify({ wrote: target, sample }));
+  else io.out(`created ${target}`);
+  return 0;
+}
+async function exportProject(file2, dir, json, io) {
+  const checked = loaded(file2, io, json);
+  if (!checked.model) return 1;
+  let doc = structuredClone(checked.model.doc);
+  if (file2.endsWith(".animl")) {
+    let compiled = "";
+    const result = await build(
+      file2,
+      void 0,
+      false,
+      {
+        out: (s) => {
+          compiled += s;
+        },
+        write: (s) => {
+          compiled += s;
+        },
+        err: (s) => io.err(s)
+      },
+      true
+    );
+    if (result) return result;
+    doc = JSON.parse(compiled);
+  } else embedAssets(doc, file2);
+  const { build: bundleRuntime } = await import("esbuild");
+  const localRuntime = new URL("../../web/src/all-modules.ts", import.meta.url);
+  const runtimeEntry = existsSync(localRuntime) ? localRuntime.pathname : new URL(import.meta.resolve("animl/internal/packages/web/src/all-modules.js")).pathname;
+  const runtime = await bundleRuntime({
+    entryPoints: [runtimeEntry],
+    bundle: true,
+    format: "esm",
+    target: "es2022",
+    write: false,
+    minify: true
+  });
+  mkdirSync(dir, { recursive: true });
+  const name = basename(file2).replace(/\.(animl|ani)$/, "") + ".ani";
+  writeFileSync(resolve(dir, name), format(doc));
+  writeFileSync(resolve(dir, "anima.js"), runtime.outputFiles[0].text);
+  writeFileSync(
+    resolve(dir, "index.html"),
+    `<!doctype html>
+<html lang="en"><meta charset="utf-8"><title>Anima export</title><script type="module" src="./anima.js"><\/script><anima-icon style="width:240px;height:240px"><script type="application/vnd.anima+json">${format(doc).replaceAll("<", "\\u003c")}<\/script></anima-icon></html>
+`
+  );
+  if (json) io.out(JSON.stringify({ wrote: dir, files: [name, "anima.js", "index.html"] }));
+  else io.out("wrote " + dir);
+  return 0;
+}
+export {
+  run
+};