animl-cli 0.0.0-stage → 0.1.1

package/packages/cli/src/project.js

@@ -0,0 +1,160 @@
+import { parseXml } from "animl/internal/packages/markup/src/xml.js";
+import { existsSync, readFileSync } from "node:fs";
+import { matchesGlob, relative, dirname, resolve } from "node:path";
+function projectError(pointer, message) {
+  return Object.assign(new Error(message), {
+    code: "project-configuration",
+    pointer,
+    hint: "check anima.json: entry, sources, exclude, constants, presets and out; paths are relative to the project file"
+  });
+}
+function findProject(cwd = process.cwd()) {
+  let dir = resolve(cwd);
+  for (; ; ) {
+    const file = resolve(dir, "anima.json");
+    if (existsSync(file)) {
+      let p;
+      try {
+        p = JSON.parse(readFileSync(file, "utf8"));
+      } catch {
+        throw projectError("", "invalid anima.json JSON");
+      }
+      if (!p || typeof p !== "object" || Array.isArray(p))
+        throw projectError("", "project must be an object");
+      const value = p;
+      for (const key of Object.keys(value))
+        if (!["entry", "sources", "exclude", "constants", "presets", "out"].includes(key))
+          throw projectError("/" + key, "unknown project field " + key);
+      for (const key of ["entry", "out"])
+        if (value[key] !== void 0 && (typeof value[key] !== "string" || !value[key]))
+          throw projectError("/" + key, key + " must be a nonempty path");
+      if (value.sources !== void 0 && (!Array.isArray(value.sources) || value.sources.some((s) => typeof s !== "string" || !s.endsWith(".animl"))))
+        throw projectError("/sources", "sources must be AniML library paths");
+      if (value.exclude !== void 0 && (!Array.isArray(value.exclude) || value.exclude.some((s) => typeof s !== "string" || !s)))
+        throw projectError("/exclude", "exclude must be an array of nonempty globs");
+      if (value.constants !== void 0) {
+        if (!value.constants || typeof value.constants !== "object" || Array.isArray(value.constants))
+          throw projectError("/constants", "constants must be an object");
+        for (const [name, v] of Object.entries(value.constants))
+          if (!/^[a-zA-Z][\w-]*$/.test(name) || !["string", "number", "boolean"].includes(typeof v) || typeof v === "number" && !Number.isFinite(v))
+            throw projectError(
+              "/constants/" + name.replaceAll("~", "~0").replaceAll("/", "~1"),
+              "constant must have a name and a scalar value"
+            );
+      }
+      const allowed = /* @__PURE__ */ new Set([
+        "frames",
+        "fps",
+        "component",
+        "fit",
+        "viewport",
+        "scale",
+        "size",
+        "at",
+        "dark",
+        "color",
+        "current",
+        "background",
+        "sheet",
+        "over",
+        "reduced-motion"
+      ]);
+      if (value.presets !== void 0) {
+        if (!value.presets || typeof value.presets !== "object" || Array.isArray(value.presets))
+          throw projectError("/presets", "presets must be an object");
+        for (const [name, preset] of Object.entries(value.presets)) {
+          if (!/^[a-zA-Z0-9_-]+$/.test(name))
+            throw projectError(
+              "/presets",
+              "preset names must contain only letters, digits, underscores or hyphens"
+            );
+          if (!preset || typeof preset !== "object" || Array.isArray(preset))
+            throw projectError("/presets/" + name, "preset must be an object");
+          for (const [key, v] of Object.entries(preset)) {
+            const valid = ["dark", "reduced-motion"].includes(key) ? typeof v === "boolean" : key === "color" ? Array.isArray(v) && v.every((x) => typeof x === "string") : typeof v === "string" || typeof v === "number" && Number.isFinite(v);
+            if (!allowed.has(key) || !valid)
+              throw projectError("/presets/" + name + "/" + key, "invalid render preset option");
+          }
+        }
+      }
+      return {
+        ...value,
+        file,
+        entry: value.entry ? resolve(dir, value.entry) : void 0,
+        sources: value.sources?.filter(
+          (s) => !value.exclude?.some((glob) => matchesGlob(s, glob))
+        ).map((s) => resolve(dir, s)),
+        out: value.out ? resolve(dir, value.out) : void 0
+      };
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return;
+    dir = parent;
+  }
+}
+function projectSource(file) {
+  const p = findProject();
+  if (p?.exclude?.some((glob) => matchesGlob(relative(dirname(p.file), resolve(file)), glob)))
+    throw projectError("/exclude", "input is excluded from this project");
+  const raw = readFileSync(file, "utf8");
+  const text = file.endsWith(".animl") ? substituteConstants(raw, p?.constants) : raw;
+  if (p?.entry !== resolve(file) || !p.sources?.length) return text;
+  if (!file.endsWith(".animl"))
+    throw projectError("/sources", "multi-file projects require an AniML entry");
+  const imports = p.sources.map((source) => {
+    const lib = substituteConstants(readFileSync(source, "utf8"), p.constants);
+    const root2 = parseXml(lib).doc.root;
+    const name = root2?.name === "library" ? root2.attrs.find((a) => a.name === "name")?.value : void 0;
+    if (!name || !/^[a-zA-Z][\w-]*$/.test(name))
+      throw projectError("/sources", "source must be a named AniML library");
+    const escaped = source.replaceAll("&", "&").replaceAll('"', """);
+    return `<import src="${escaped}" as="${name}"/>`;
+  }).join("\n");
+  const root = parseXml(text).doc.root;
+  if (root?.name !== "anima") throw projectError("/entry", "project entry must have an anima root");
+  let end = root.at.offset, quote = "";
+  for (; end < text.length; end++) {
+    const c = text[end];
+    if (quote) {
+      if (c === quote) quote = "";
+    } else if (c === '"' || c === "'") quote = c;
+    else if (c === ">") break;
+  }
+  const tag = text.slice(root.at.offset, end + 1);
+  if (tag.endsWith("/>"))
+    return text.slice(0, root.at.offset) + tag.slice(0, -2) + ">" + imports + "</anima>" + text.slice(end + 1);
+  return text.slice(0, end + 1) + "\n" + imports + text.slice(end + 1);
+}
+function substituteConstants(text, constants) {
+  const replacements = [];
+  const visit = (node) => {
+    for (const attr of node.attrs) {
+      const value = attr.value.replace(/\{\{([a-zA-Z][\w-]*)\}\}/g, (_, name) => {
+        if (!constants || !Object.hasOwn(constants, name))
+          throw projectError(
+            "/constants/" + name.replaceAll("~", "~0").replaceAll("/", "~1"),
+            "unknown build constant " + name
+          );
+        return String(constants[name]);
+      });
+      if (value !== attr.value)
+        replacements.push({
+          start: attr.valueAt.offset,
+          end: text.indexOf(text[attr.valueAt.offset - 1], attr.valueAt.offset),
+          value: value.replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("'", "&apos;").replaceAll("<", "&lt;")
+        });
+    }
+    for (const child of node.children) if (child.kind === "element") visit(child);
+  };
+  const root = parseXml(text).doc.root;
+  if (root) visit(root);
+  for (const r of replacements.sort((a, b) => b.start - a.start))
+    text = text.slice(0, r.start) + r.value + text.slice(r.end);
+  return text;
+}
+export {
+  findProject,
+  projectError,
+  projectSource,
+  substituteConstants
+};

package/packages/cli/src/render-options.d.ts

@@ -0,0 +1,6 @@
+export declare function viewportSVG(svg: string, width: number, height: number, fit: string, scale: number, background?: string): string;
+export declare function probePNG(bytes: Buffer, points: string): {
+    x: number;
+    y: number;
+    rgba: number[];
+}[];

package/packages/cli/src/render-options.js

@@ -0,0 +1,40 @@
+import { PNG } from "pngjs";
+function viewportSVG(svg, width, height, fit, scale, background) {
+  const fitted = svg.replace(/<svg\b([^>]*)>/, (_, raw) => {
+    let attrs = raw.replace(/\s(?:width|height|preserveAspectRatio)="[^"]*"/g, "");
+    if (fit === "none") {
+      const box = /viewBox="([^"]+)"/.exec(attrs)?.[1]?.split(/\s+/).map(Number) ?? [
+        0,
+        0,
+        width,
+        height
+      ];
+      attrs = attrs.replace(
+        /viewBox="[^"]*"/,
+        `viewBox="${box[0] + box[2] / 2 - width / 2} ${box[1] + box[3] / 2 - height / 2} ${width} ${height}"`
+      );
+    }
+    return `<svg${attrs} width="${Math.max(1, Math.round(width * scale))}" height="${Math.max(1, Math.round(height * scale))}" preserveAspectRatio="${fit === "fill" || fit === "none" ? "none" : fit === "cover" ? "xMidYMid slice" : "xMidYMid meet"}">`;
+  });
+  if (!background) return fitted;
+  const w = Math.max(1, Math.round(width * scale)), h = Math.max(1, Math.round(height * scale));
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="${h}" viewBox="0 0 ${w} ${h}"><rect width="${w}" height="${h}" fill="${background.replaceAll("&", "&amp;").replaceAll('"', "&quot;")}"/>${fitted}</svg>`;
+}
+function probePNG(bytes, points) {
+  const image = PNG.sync.read(bytes);
+  return points.split(";").map((pair) => {
+    if (!/^\d+,\d+$/.test(pair)) throw Error("--probe takes x,y[;x,y\u2026] in output pixels");
+    const [x, y] = pair.split(",").map(Number);
+    if (x >= image.width || y >= image.height)
+      throw Error("--probe point is outside the output image");
+    return {
+      x,
+      y,
+      rgba: [...image.data.subarray((y * image.width + x) * 4, (y * image.width + x) * 4 + 4)]
+    };
+  });
+}
+export {
+  probePNG,
+  viewportSVG
+};

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

@@ -0,0 +1,30 @@
+import { type Paint, type Player } from 'animl';
+export interface Look {
+    paint: Paint;
+    /** CSS colour `currentColor` resolves to. */
+    color: string;
+    background?: string;
+}
+/** The fixture convention for comparing with the Rive frames: ink #f0eee6 on #1d1d1d. */
+export declare const DARK: Look;
+export declare const LIGHT: Look;
+/** One frame as a standalone SVG. */
+export declare function frameSVG(p: Player, look: Look, size?: number, id?: string): string;
+/** A labelled grid of frames: `frames` are [label, svg] pairs (SVGs from `frameSVG` without a size). */
+export declare function sheetSVG(frames: [string, string][], look: Look, cell?: number): string;
+export declare function toPNG(svg: string, width?: number): Buffer;
+/** Decoded RGBA pixels, for pixel comparisons. */
+export declare function pixels(svg: string, width: number): Uint8Array;
+/** Normalize viewport and ink before rasterizing both documents with the PNG renderer. */
+export declare function comparisonSVG(svg: string, size: number): string;
+/** Absolute RGBA differences; a diff image shows the largest channel delta as grayscale. */
+export declare function compareSVG(a: string, b: string, size: number, tolerance?: number, diff?: boolean): {
+    diff?: Buffer<ArrayBufferLike> | undefined;
+    width: number;
+    height: number;
+    differingPixels: number;
+    pixelsBeyondTolerance: number;
+    maxChannelDifference: number;
+    meanChannelDifference: number;
+    pass: boolean;
+};

package/packages/cli/src/render.js

@@ -0,0 +1,90 @@
+import { compareRGBA } from "./compare-png.js";
+import { staticSlots } from "animl";
+import { toSVG } from "animl/internal/modules/mesh/core/static.js";
+import { Resvg } from "@resvg/resvg-js";
+const DARK = { paint: staticSlots(), color: "#f0eee6", background: "#1d1d1d" };
+const LIGHT = { paint: staticSlots(), color: "#141413" };
+function frameSVG(p, look, size, id = "a") {
+  const svg = toSVG(p, {
+    staticLengths: true,
+    meshTriangles: true,
+    paint: look.paint,
+    background: look.background,
+    width: size,
+    height: size,
+    id
+  });
+  return svg.replace("<svg ", `<svg color="${look.color}" `);
+}
+function sheetSVG(frames, look, cell = 160) {
+  const cols = Math.min(frames.length, Math.ceil(Math.sqrt(frames.length * 1.5)));
+  const rows = Math.ceil(frames.length / cols);
+  const label = 18;
+  const w = cols * cell;
+  const h = rows * (cell + label);
+  const fg = look.background ? look.color : "#141413";
+  const cells = frames.map(([text, svg], k) => {
+    const x = k % cols * cell;
+    const y = Math.floor(k / cols) * (cell + label);
+    const inner = svg.replace(
+      "<svg ",
+      `<svg x="${x}" y="${y}" width="${cell}" height="${cell}" `
+    );
+    return `${inner}<text x="${x + cell / 2}" y="${y + cell + 13}" text-anchor="middle" font-family="monospace" font-size="12" fill="${fg}">${text}</text>`;
+  }).join("");
+  const bg = look.background ?? "#ffffff";
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="${h}" viewBox="0 0 ${w} ${h}"><rect width="${w}" height="${h}" fill="${bg}"/>${cells}</svg>`;
+}
+const rasterSVG = (svg) => svg.replaceAll('image-rendering="pixelated"', 'image-rendering="optimizeSpeed"');
+function toPNG(svg, width) {
+  return new Resvg(rasterSVG(svg), {
+    fitTo: width ? { mode: "width", value: width } : { mode: "original" },
+    font: { loadSystemFonts: true }
+  }).render().asPng();
+}
+function pixels(svg, width) {
+  const img = new Resvg(rasterSVG(svg), { fitTo: { mode: "width", value: width } }).render();
+  return img.pixels;
+}
+function comparisonSVG(svg, size) {
+  const prolog = /^(?:\s+|<\?[\s\S]*?\?>|<!--[\s\S]*?-->|<!DOCTYPE(?:[^[>]|\[[\s\S]*?\])*>)*/i.exec(
+    svg
+  )[0];
+  const root = svg.slice(prolog.length).replace(
+    /^<((?:[\w.-]+:)?svg)\b((?:[^>"']|"[^"]*"|'[^']*')*?)(\/?)>/i,
+    (_, name, attrs, end) => {
+      let style = "";
+      const own = {};
+      const kept = (attrs.trimEnd().match(/\s+[^\s=]+\s*=\s*(?:"[^"]*"|'[^']*')/g) ?? []).filter(
+        (a) => {
+          const [, key, value] = /^\s+([^\s=]+)\s*=\s*["']([\s\S]*)["']$/.exec(a);
+          own[key] = value;
+          if (/^style$/i.test(key)) style = value.replaceAll('"', "&quot;");
+          return !/^(?:width|height|color|style)$/i.test(key);
+        }
+      );
+      const [w, h] = [own.width, own.height].map((v) => {
+        const n = /^\s*([+-]?(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?)(?:px)?\s*$/i.exec(v ?? "");
+        return n && Number(n[1]) > 0 && Number.isFinite(Number(n[1])) ? Number(n[1]) : 0;
+      });
+      if (!("viewBox" in own) && w && h) kept.push(` viewBox="0 0 ${w} ${h}"`);
+      return `<${name}${kept.join("")} width="${size}" height="${size}" color="#000" style="${style};color:#000!important;width:${size}px!important;height:${size}px!important"${end}>`;
+    }
+  );
+  return prolog + root;
+}
+function compareSVG(a, b, size, tolerance = 0, diff = false) {
+  const left = pixels(comparisonSVG(a, size), size);
+  const right = pixels(comparisonSVG(b, size), size);
+  return compareRGBA(left, right, size, size, tolerance, diff);
+}
+export {
+  DARK,
+  LIGHT,
+  compareSVG,
+  comparisonSVG,
+  frameSVG,
+  pixels,
+  sheetSVG,
+  toPNG
+};

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

@@ -0,0 +1,17 @@
+export declare const sha256: (s: string) => string;
+export interface GlyphSource {
+    d: string;
+    grid: number;
+    meta: Record<string, unknown>;
+    pick?: string;
+    source: string;
+}
+/** Read a Glyphy-style glyph SVG: one path, square viewBox from 0. */
+export declare function readGlyphSVG(file: string): GlyphSource;
+/** Just enough TOML for glyphy.toml: [sections], key = string | number | bool | [array]. */
+export declare function parseToml(text: string): Record<string, Record<string, unknown>>;
+/** Read a glyph from a Glyphy project directory (glyphy.toml + its picked glyphs folder). */
+export declare function readGlyphy(dir: string, name: string): GlyphSource;
+/** A minimal document: the glyph as one path, ink = currentColor, no motion yet. */
+export declare function newDoc(name: string, g: GlyphSource): Record<string, unknown>;
+export declare const nameFromFile: (file: string) => string;

package/packages/cli/src/scaffold.js

@@ -0,0 +1,96 @@
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+const sha256 = (s) => createHash("sha256").update(s, "utf8").digest("hex");
+function readGlyphSVG(file) {
+  const text = readFileSync(file, "utf8");
+  const paths = [...text.matchAll(/<path\b[^>]*\sd="([^"]+)"/g)];
+  if (paths.length !== 1)
+    throw new Error(`${file}: expected exactly one <path>, found ${paths.length}`);
+  const vb = /viewBox="([^"]+)"/.exec(text)?.[1]?.trim().split(/[\s,]+/).map(Number);
+  if (!vb || vb.length !== 4 || vb[0] !== 0 || vb[1] !== 0 || vb[2] !== vb[3])
+    throw new Error(`${file}: expected a square viewBox from 0 0 (a glyph grid)`);
+  return { d: paths[0][1], grid: vb[2], meta: {}, source: "svg" };
+}
+function parseToml(text) {
+  const out = { "": {} };
+  let sec = out[""];
+  const lines = text.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    let line = lines[i].replace(/(^|\s)#.*$/, "").trim();
+    if (!line) continue;
+    const s = /^\[([^\]]+)\]$/.exec(line);
+    if (s) {
+      sec = out[s[1].trim()] ??= {};
+      continue;
+    }
+    const eq = line.indexOf("=");
+    if (eq < 0) continue;
+    const key = line.slice(0, eq).trim().replace(/^"|"$/g, "");
+    let raw = line.slice(eq + 1).trim();
+    while (raw.startsWith("[") && !raw.endsWith("]") && i + 1 < lines.length)
+      raw += " " + lines[++i].replace(/#.*$/, "").trim();
+    line = raw.replace(/,\s*]$/, "]");
+    try {
+      sec[key] = JSON.parse(line.replace(/'/g, '"'));
+    } catch {
+      sec[key] = line;
+    }
+  }
+  return out;
+}
+function readGlyphy(dir, name) {
+  const tomlFile = join(dir, "glyphy.toml");
+  if (!existsSync(tomlFile)) throw new Error(`${dir}: no glyphy.toml`);
+  const toml = parseToml(readFileSync(tomlFile, "utf8"));
+  const picked = toml.paths?.picked ?? "glyphs";
+  const candidates = [
+    join(dir, picked, `${name}.svg`),
+    join(dir, "glyphs", `${name}.svg`),
+    join(dir, `${name}.svg`)
+  ];
+  const file = candidates.find(existsSync);
+  if (!file) throw new Error(`${dir}: no ${name}.svg in ${picked}/`);
+  const g = readGlyphSVG(file);
+  const grid = toml.style?.grid ?? g.grid;
+  if (grid !== g.grid)
+    throw new Error(`${file}: viewBox ${g.grid} does not match style.grid ${grid}`);
+  const info = toml[`glyphs.${name}`] ?? {};
+  const meta = {
+    glyphy: {
+      ...info.concept ? { concept: info.concept } : {},
+      ...info.kind ? { kind: info.kind } : {},
+      ...toml.style?.stroke ? { stroke: toml.style.stroke } : {}
+    }
+  };
+  const pick = toml.picks?.[name];
+  return { ...g, grid, meta, pick, source: "glyphy" };
+}
+function newDoc(name, g) {
+  const glyph = {
+    source: g.source,
+    ...g.pick ? { pick: g.pick } : {},
+    sha256: sha256(g.d),
+    d: g.d
+  };
+  const key = /^[a-z]/.test(name) ? name : "glyph-" + name;
+  return {
+    anima: "0.1",
+    name,
+    title: name.replace(/-/g, " ").replace(/^./, (c) => c.toUpperCase()),
+    grid: g.grid,
+    ...Object.keys(g.meta).length ? { meta: g.meta } : {},
+    colors: { ink: "currentColor" },
+    glyphs: { [key]: glyph },
+    nodes: [{ id: "glyph", type: "path", glyph: key, fill: { color: "ink", rule: "evenodd" } }]
+  };
+}
+const nameFromFile = (file) => basename(file).replace(/\.svg$/, "");
+export {
+  nameFromFile,
+  newDoc,
+  parseToml,
+  readGlyphSVG,
+  readGlyphy,
+  sha256
+};

package/packages/cli/src/schema-view.d.ts

@@ -0,0 +1,9 @@
+import 'animl/all';
+import type { IO } from './cli.js';
+export declare function distance(a: string, b: string): number;
+export declare function lookupTopic(topic: string | undefined, topics: string[], _command: string): string | undefined;
+export declare function schemaTopic(topic: string | undefined): string | undefined;
+export declare function schema(topic: string | undefined, full: boolean, json: boolean, io: IO): number;
+export declare function schemaAll(json: boolean, io: IO): number;
+export declare function schemaSearch(words: string, json: boolean, io: IO): number;
+export declare function filteredSchema(topic: string | undefined, options: Record<string, unknown>, json: boolean, io: IO): number;