volito 0.1.0 → 0.3.0

package/dist/chunks/chunk-QA4SEJCZ.js

@@ -0,0 +1,601 @@
+import {
+  BUILTIN_STYLES,
+  LIBRARY_NAMES,
+  MOODS,
+  MOTION_FORMAT,
+  MotionError,
+  TrueTypeFace,
+  customItem,
+  glyphTable,
+  makeItem,
+  normalizeMotion,
+  parseAspect,
+  registerLibrary,
+  resolveProps,
+  setGlyphSource
+} from "./chunk-CUQY6YI3.js";
+import {
+  fontsDir,
+  libsDir,
+  packsDir
+} from "./chunk-ZFG3X3DU.js";
+
+// src/node/packs.ts
+import { existsSync as existsSync2, readFileSync as readFileSync2, readdirSync, statSync } from "node:fs";
+import { basename, join as join2, resolve } from "node:path";
+
+// src/node/setup.ts
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+setGlyphSource((key, file) => {
+  const path = join(fontsDir(), file);
+  return existsSync(path) ? glyphTable(new TrueTypeFace(new Uint8Array(readFileSync(path))), key) : void 0;
+});
+for (const name of LIBRARY_NAMES) {
+  const file = join(libsDir(), `${name}.js`);
+  if (existsSync(file)) registerLibrary(name, () => readFileSync(file, "utf8"));
+}
+
+// src/node/packs.ts
+var readJson = (file) => {
+  try {
+    return JSON.parse(readFileSync2(file, "utf8"));
+  } catch (err) {
+    throw new MotionError(`${file}: ${err.message}`);
+  }
+};
+function loadPack(dir) {
+  const manifest = readJson(join2(dir, "pack.json"));
+  if (manifest.format !== MOTION_FORMAT) throw new MotionError(`${dir}: pack format ${manifest.format} \u2014 this version reads format ${MOTION_FORMAT}`);
+  const shared = manifest.shared ? readFileSync2(join2(dir, manifest.shared), "utf8") : "";
+  const entries = manifest.items.map((id) => {
+    const itemDir = join2(dir, id);
+    const m = readJson(join2(itemDir, "item.json"));
+    if (m.id !== id) throw new MotionError(`${itemDir}: item.json id "${m.id}" does not match its folder`);
+    return makeItem(manifest.id, m, readFileSync2(join2(itemDir, "frame.js"), "utf8"), shared);
+  });
+  return { ...manifest, entries };
+}
+var builtin = null;
+function builtinPacks() {
+  if (builtin) return builtin;
+  const dir = packsDir();
+  const order = ["essentials", "broadcast", "social", "data", "3d", "transitions", "annotate", "type", "backdrops", "promo", "ui", "effects"];
+  const rank = (d) => order.includes(d) ? order.indexOf(d) : order.length;
+  builtin = existsSync2(dir) ? readdirSync(dir).filter((d) => existsSync2(join2(dir, d, "pack.json"))).sort((a, b) => rank(a) - rank(b) || a.localeCompare(b)).map((d) => loadPack(join2(dir, d))) : [];
+  return builtin;
+}
+function packsIn(dirs) {
+  const out = [];
+  for (const raw of dirs) {
+    const dir = resolve(raw);
+    if (existsSync2(join2(dir, "pack.json"))) out.push(loadPack(dir));
+    else if (existsSync2(dir) && statSync(dir).isDirectory()) {
+      for (const d of readdirSync(dir).sort()) if (existsSync2(join2(dir, d, "pack.json"))) out.push(loadPack(join2(dir, d)));
+    }
+  }
+  return out;
+}
+function library(extraDirs = []) {
+  const env = (process.env.VOLITO_PACKS ?? process.env.MONARC_MOTION_PACKS ?? "").split(":").filter(Boolean);
+  const packs = [...builtinPacks(), ...packsIn([...env, ...extraDirs])];
+  const seen = /* @__PURE__ */ new Set();
+  for (const p of packs) {
+    if (seen.has(p.id)) throw new MotionError(`two packs are named "${p.id}"`);
+    seen.add(p.id);
+  }
+  return { packs, items: packs.flatMap((p) => p.entries) };
+}
+function findItem(name, lib = library()) {
+  const n = name.trim();
+  const byRef = lib.items.find((i) => i.ref === n);
+  if (byRef) return byRef;
+  const path = resolve(n);
+  if (existsSync2(path)) {
+    if (statSync(path).isDirectory() && existsSync2(join2(path, "item.json"))) {
+      const m = readJson(join2(path, "item.json"));
+      const shared = existsSync2(join2(path, "shared.js")) ? readFileSync2(join2(path, "shared.js"), "utf8") : "";
+      return makeItem("local", m, readFileSync2(join2(path, "frame.js"), "utf8"), shared);
+    }
+    if (/\.(m?js|txt)$/.test(path)) return customItem(readFileSync2(path, "utf8"), { id: basename(path).replace(/\.[^.]+$/, "").toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "") });
+  }
+  const byId = lib.items.filter((i) => i.id === n);
+  if (byId.length === 1) return byId[0];
+  if (byId.length > 1) throw new MotionError(`"${n}" is in more than one pack: ${byId.map((i) => i.ref).join(", ")}`);
+  const q = n.toLowerCase();
+  const score = (i) => i.id.startsWith(q) ? 0 : i.id.includes(q) || q.includes(i.id) ? 1 : i.name.toLowerCase().includes(q) ? 2 : (i.tags ?? []).some((t) => t.includes(q)) ? 3 : 9;
+  const near = lib.items.map((i) => ({ ref: i.ref, s: score(i) })).filter((r) => r.s < 9).sort((a, b) => a.s - b.s).map((r) => r.ref);
+  throw new MotionError(`no item "${n}"${near.length ? ` \u2014 did you mean ${near.slice(0, 4).join(", ")}?` : ""} (list them with: volito list)`);
+}
+function searchItems(q = {}, lib = library()) {
+  const words = (q.search ?? "").toLowerCase().split(/\s+/).filter(Boolean);
+  return lib.items.filter((i) => {
+    if (q.category && i.category !== q.category) return false;
+    if (q.pack && i.pack !== q.pack) return false;
+    if (q.placement && i.placement !== q.placement) return false;
+    if (!words.length) return true;
+    const hay = [i.id, i.name, i.description, i.category, ...i.tags ?? []].join(" ").toLowerCase();
+    return words.every((w) => hay.includes(w));
+  });
+}
+
+// src/spec.ts
+import { z } from "zod";
+var SPEC_VERSION = 1;
+var SPEC_SCHEMA_URL = "https://volito.dev/schema/graphic.v1.json";
+var SPEC_FORMATS = ["mov", "hevc", "webm", "mp4", "gif", "png"];
+var hex = z.string().regex(/^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/, "a hex colour like #FF6A3D");
+var SpecColorsSchema = z.object({
+  accent: hex,
+  accent2: hex,
+  ink: hex,
+  paper: hex,
+  surface: hex,
+  mode: z.enum(["dark", "light"]),
+  display: z.string().describe('A face as "Family:weight", e.g. "Fraunces:900"'),
+  text: z.string(),
+  mono: z.string()
+}).partial().strict();
+var SpecWordSchema = z.object({ w: z.string(), s: z.number(), e: z.number() }).strict();
+var GraphicSpecSchema = z.object({
+  $schema: z.string().optional(),
+  volito: z.literal(SPEC_VERSION).describe("The spec format's major version"),
+  name: z.string().optional().describe("A label for people; not used to render"),
+  item: z.string().optional().describe('A pack item: "essentials/lower-third", or its id "lower-third". Give item, program or code.'),
+  program: z.string().optional().describe("A path to your own frame(t, $) program (.js), relative to this file"),
+  code: z.string().optional().describe("Your own frame(t, $) program, inline"),
+  placement: z.enum(["overlay", "full"]).optional().describe("For a program: overlay (transparent) or full (draws its own ground)"),
+  props: z.record(z.string(), z.unknown()).optional().describe("The item's props; image props are paths relative to this file or URLs"),
+  style: z.string().optional().describe("A built-in style name, or a DESIGN.md path relative to this file"),
+  colors: SpecColorsSchema.optional().describe("Overrides on the style"),
+  aspect: z.string().optional().describe('"16:9", "9:16", "1:1", "4:5" or "WIDTHxHEIGHT"'),
+  duration: z.number().positive().max(600).optional().describe("Seconds; the item's default when omitted"),
+  fps: z.number().int().min(1).max(120).optional(),
+  width: z.number().int().min(16).max(8192).optional().describe("Output width in px; the height follows"),
+  background: z.string().optional().describe('"transparent" (default where the format has alpha) or a colour drawn under the graphic'),
+  words: z.union([z.array(SpecWordSchema), z.string()]).optional().describe("Spoken words with start/end seconds, or a transcript file ([{w,s,e}] or Whisper JSON) relative to this file"),
+  offset: z.number().optional().describe("Where the graphic starts in the transcript, in seconds"),
+  beats: z.record(z.string(), z.number()).optional().describe('Named moments, e.g. { "in": 0.4, "out": -0.6 }'),
+  motion: z.record(z.string(), z.record(z.string(), z.unknown())).optional().describe('How each part moves: { "*": { "ease": "bouncy" }, "name": { "in": "typewriter" } }'),
+  mood: z.enum(MOODS).optional(),
+  seed: z.number().optional(),
+  speed: z.number().positive().max(10).optional(),
+  sound: z.union([z.boolean(), z.object({ bed: z.string().optional(), level: z.number().min(0).max(2).optional() }).strict()]).optional().describe('true, or { bed: "Dm", level: 1 }: a track Volito synthesises, muxed into video'),
+  render: z.object({ format: z.enum(SPEC_FORMATS).optional(), out: z.string().optional().describe("Output path, relative to where you run it") }).strict().optional().describe("Defaults for volito render; command-line flags win")
+}).strict().superRefine((s, ctx) => {
+  const sources = [s.item, s.program, s.code].filter((x) => x !== void 0 && x !== "").length;
+  if (sources === 0) ctx.addIssue({ code: "custom", path: ["item"], message: "give item, program or code" });
+  if (sources > 1) ctx.addIssue({ code: "custom", path: ["item"], message: "give only one of item, program and code" });
+  if (s.placement && s.item) ctx.addIssue({ code: "custom", path: ["placement"], message: "placement is for a program or code; an item has its own" });
+});
+var pathOf = (p) => p.map(String).join(".");
+function parseSpec(input) {
+  if (!input || typeof input !== "object" || Array.isArray(input)) return { spec: null, errors: [{ path: "", message: "a spec is a JSON object" }] };
+  const v = input.volito;
+  if (v === void 0) return { spec: null, errors: [{ path: "volito", message: `missing "volito": ${SPEC_VERSION} \u2014 the spec format's version` }] };
+  if (v !== SPEC_VERSION) return { spec: null, errors: [{ path: "volito", message: `this Volito reads spec version ${SPEC_VERSION}; got ${JSON.stringify(v)}` }] };
+  const r = GraphicSpecSchema.safeParse(input);
+  if (r.success) return { spec: r.data, errors: [] };
+  return {
+    spec: null,
+    errors: r.error.issues.map((i) => {
+      const keys = i.keys;
+      if (i.code === "unrecognized_keys" && keys?.length) return { path: pathOf(i.path), message: `unknown field${keys.length > 1 ? "s" : ""} ${keys.map((k) => `"${k}"`).join(", ")}${suggest(keys[0])}` };
+      return { path: pathOf(i.path), message: i.message };
+    })
+  };
+}
+var FIELDS = ["$schema", "volito", "name", "item", "program", "code", "placement", "props", "style", "colors", "aspect", "duration", "fps", "width", "background", "words", "offset", "beats", "motion", "mood", "seed", "speed", "sound", "render"];
+function suggest(key) {
+  let best = "";
+  let dist = 3;
+  for (const f of FIELDS) {
+    const d = editDistance(key.toLowerCase(), f.toLowerCase());
+    if (d < dist) {
+      dist = d;
+      best = f;
+    }
+  }
+  return best ? ` \u2014 did you mean "${best}"?` : "";
+}
+function editDistance(a, b) {
+  const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    let prev = row[0];
+    row[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const cur = row[j];
+      row[j] = Math.min(row[j] + 1, row[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1));
+      prev = cur;
+    }
+  }
+  return row[b.length];
+}
+function specJsonSchema() {
+  const schema = z.toJSONSchema(GraphicSpecSchema, { target: "draft-2020-12", unrepresentable: "any" });
+  return { $id: SPEC_SCHEMA_URL, title: "Volito Graphic spec", description: "One motion graphic: the item or program, its props, brand, shape, timing, motion and sound.", ...schema };
+}
+
+// src/node/inputs.ts
+import { existsSync as existsSync3, readFileSync as readFileSync3 } from "node:fs";
+import { extname, resolve as resolve2 } from "node:path";
+var num = (v) => typeof v === "number" ? v : Number.parseFloat(String(v));
+function normalizeWords(input, offset = 0) {
+  const rows = Array.isArray(input) ? input : input && typeof input === "object" ? Array.isArray(input.words) ? input.words : Array.isArray(input.segments) ? input.segments.flatMap((s) => s.words ?? []) : [] : [];
+  const out = [];
+  for (const r of rows) {
+    const o = r ?? {};
+    const w = String(o.w ?? o.word ?? o.text ?? "").trim();
+    const s = num(o.s ?? o.start) - offset;
+    const e = num(o.e ?? o.end) - offset;
+    if (!w || !Number.isFinite(s)) continue;
+    if (s < -0.01) continue;
+    out.push({ w, s: Math.max(0, s), e: Number.isFinite(e) ? Math.max(s, e) : s + 0.3 });
+  }
+  return out.slice(0, 600);
+}
+function readWords(file, offset = 0) {
+  const path = resolve2(file);
+  if (!existsSync3(path)) throw new MotionError(`no transcript at ${path}`);
+  const words = normalizeWords(JSON.parse(readFileSync3(path, "utf8")), offset);
+  if (!words.length) throw new MotionError(`${path} has no timed words (expected [{w, s, e}] or Whisper JSON)`);
+  return words;
+}
+var MIME = { ".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp", ".gif": "image/gif", ".svg": "image/svg+xml" };
+async function loadImage(src) {
+  if (src.startsWith("data:image/")) return src;
+  if (/^https?:\/\//i.test(src)) {
+    const res = await fetch(src);
+    if (!res.ok) throw new MotionError(`${src}: HTTP ${res.status}`);
+    const type2 = res.headers.get("content-type")?.split(";")[0] ?? MIME[extname(new URL(src).pathname).toLowerCase()] ?? "image/png";
+    if (!type2.startsWith("image/")) throw new MotionError(`${src} is not an image (${type2})`);
+    return `data:${type2};base64,${Buffer.from(await res.arrayBuffer()).toString("base64")}`;
+  }
+  const path = resolve2(src);
+  if (!existsSync3(path)) throw new MotionError(`no picture at ${path}`);
+  const type = MIME[extname(path).toLowerCase()];
+  if (!type) throw new MotionError(`${path}: pictures are PNG, JPEG, WebP, GIF or SVG`);
+  return `data:${type};base64,${readFileSync3(path).toString("base64")}`;
+}
+async function loadMedia(item, props = {}) {
+  const out = {};
+  for (const [name, spec] of Object.entries(item.props)) {
+    const v = props[name] ?? spec.default;
+    if (spec.type !== "image" || typeof v !== "string" || !v.trim()) continue;
+    out[name] = await loadImage(v.trim());
+  }
+  return out;
+}
+function readStyleArg(arg) {
+  if (!arg) return void 0;
+  const path = resolve2(arg);
+  if (/\.(md|markdown|txt)$/i.test(arg) || existsSync3(path) && !/^[a-z0-9-]+$/i.test(arg)) {
+    if (!existsSync3(path)) throw new MotionError(`no style file at ${path}`);
+    return readFileSync3(path, "utf8");
+  }
+  return arg;
+}
+
+// src/node/spec.ts
+import { existsSync as existsSync4, readFileSync as readFileSync4, statSync as statSync2 } from "node:fs";
+import { basename as basename2, dirname, isAbsolute, resolve as resolve3 } from "node:path";
+function isSpecFile(path) {
+  if (!/\.json$/i.test(path)) return false;
+  const p = resolve3(path);
+  if (!existsSync4(p) || !statSync2(p).isFile()) return false;
+  try {
+    const doc = JSON.parse(readFileSync4(p, "utf8"));
+    return !!doc && typeof doc === "object" && !Array.isArray(doc) && "volito" in doc;
+  } catch {
+    return false;
+  }
+}
+function loadSpecFile(path) {
+  const file = resolve3(path);
+  let doc;
+  try {
+    doc = JSON.parse(readFileSync4(file, "utf8"));
+  } catch (e) {
+    throw new MotionError(`${path} is not valid JSON: ${e.message}`);
+  }
+  const { spec, errors } = parseSpec(doc);
+  if (!spec) throw new MotionError(`${path} is not a valid spec:
+${formatIssues(errors)}`);
+  return { spec, dir: dirname(file), file };
+}
+var at = (dir, p) => isAbsolute(p) ? p : resolve3(dir, p);
+var isUrl = (s) => /^(https?:|data:)/i.test(s);
+function itemOfSpec(loaded, lib = library()) {
+  const { spec, dir } = loaded;
+  if (spec.code?.trim()) return customItem(spec.code, { placement: spec.placement, duration: spec.duration, id: idFrom(spec.name ?? "graphic") });
+  if (spec.program) {
+    const p = at(dir, spec.program);
+    if (!existsSync4(p)) throw new MotionError(`program ${spec.program} not found (looked in ${p})`);
+    if (statSync2(p).isDirectory()) return findItem(p, lib);
+    return customItem(readFileSync4(p, "utf8"), { placement: spec.placement, duration: spec.duration, id: idFrom(basename2(p).replace(/\.[^.]+$/, "")) });
+  }
+  return findItem(spec.item, lib);
+}
+var idFrom = (s) => s.toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "") || "graphic";
+function specToOptions(loaded, item) {
+  const { spec, dir } = loaded;
+  const props = { ...spec.props ?? {} };
+  for (const [name, p] of Object.entries(item.props)) {
+    const v = props[name];
+    if (p.type === "image" && typeof v === "string" && v.trim() && !isUrl(v)) props[name] = at(dir, v.trim());
+  }
+  const style = spec.style ? /\.(md|markdown|txt)$/i.test(spec.style) ? readFileSync4(at(dir, spec.style), "utf8") : spec.style : void 0;
+  const words = spec.words === void 0 ? void 0 : typeof spec.words === "string" ? readWords(at(dir, spec.words), spec.offset ?? 0) : normalizeWords(spec.words, spec.offset ?? 0);
+  const sound = spec.sound;
+  return {
+    props,
+    ...spec.colors ? { colors: spec.colors } : {},
+    ...style ? { style } : {},
+    ...spec.aspect ? { aspect: parseAspect(spec.aspect) } : {},
+    ...spec.duration ? { duration: spec.duration } : {},
+    ...spec.fps ? { fps: spec.fps } : {},
+    ...spec.width ? { width: spec.width } : {},
+    ...spec.background ? { background: spec.background } : {},
+    ...words?.length ? { words } : {},
+    ...spec.beats ? { beats: spec.beats } : {},
+    ...spec.motion ? { motion: spec.motion } : {},
+    ...spec.mood ? { mood: spec.mood } : {},
+    ...spec.seed !== void 0 ? { seed: spec.seed } : {},
+    ...spec.speed ? { speed: spec.speed } : {},
+    ...sound ? { sound: typeof sound === "object" && sound.level !== void 0 ? { level: sound.level } : true } : {},
+    ...typeof sound === "object" && sound.bed ? { bed: sound.bed } : {}
+  };
+}
+function validateSpec(input, opts = {}) {
+  const dir = opts.dir ?? process.cwd();
+  const { spec, errors } = parseSpec(input);
+  if (!spec) return { ok: false, errors, warnings: [] };
+  const warnings = [];
+  const errs = [];
+  let item;
+  try {
+    item = itemOfSpec({ spec, dir }, opts.lib ?? library());
+  } catch (e) {
+    return { ok: false, errors: [{ path: spec.item ? "item" : spec.program ? "program" : "code", message: e.message }], warnings };
+  }
+  if (spec.style && /\.(md|markdown|txt)$/i.test(spec.style)) {
+    if (!existsSync4(at(dir, spec.style))) errs.push({ path: "style", message: `no DESIGN.md at ${spec.style} (relative to the spec)` });
+  } else if (spec.style && !BUILTIN_STYLES.some((s) => s.name === spec.style)) {
+    errs.push({ path: "style", message: `no built-in style "${spec.style}" \u2014 use one of ${BUILTIN_STYLES.map((s) => s.name).join(", ")}, or a path to a DESIGN.md` });
+  }
+  if (typeof spec.words === "string" && !existsSync4(at(dir, spec.words))) errs.push({ path: "words", message: `no transcript at ${spec.words} (relative to the spec)` });
+  if (spec.aspect) {
+    try {
+      const a = parseAspect(spec.aspect);
+      if (typeof a === "string" && item.aspects?.length && !item.aspects.includes(a)) warnings.push({ path: "aspect", message: `${item.ref} is designed for ${item.aspects.join(", ")}; ${a} may not lay out well` });
+    } catch (e) {
+      errs.push({ path: "aspect", message: e.message });
+    }
+  }
+  if (spec.duration && item.duration) {
+    const { min, max } = item.duration;
+    if (min !== void 0 && spec.duration < min || max !== void 0 && spec.duration > max) warnings.push({ path: "duration", message: `${item.ref} is designed for ${min ?? 0}\u2013${max ?? "\u221E"} s; ${spec.duration} s will be clamped or look rushed` });
+  }
+  const props = { ...spec.props ?? {} };
+  for (const [name, p] of Object.entries(item.props)) {
+    const v = props[name];
+    if (p.type === "image" && typeof v === "string" && v.trim() && !isUrl(v) && !existsSync4(at(dir, v))) errs.push({ path: `props.${name}`, message: `no image at ${v} (relative to the spec)` });
+  }
+  for (const w of resolveProps(item, props).warnings) warnings.push({ path: `props${propName(w)}`, message: w });
+  for (const w of normalizeMotion({ parts: spec.motion, mood: spec.mood, seed: spec.seed, speed: spec.speed }, Object.keys(item.parts ?? {})).warnings) warnings.push({ path: "motion", message: w });
+  return { ok: errs.length === 0, errors: errs, warnings, item: item.ref };
+}
+function propName(w) {
+  const m = /^unknown prop "([^"]+)"/.exec(w) ?? /^([A-Za-z0-9_]+) /.exec(w);
+  return m ? `.${m[1]}` : "";
+}
+function formatIssues(list, mark = "\u2717") {
+  return list.map((i) => `  ${mark} ${i.path ? `${i.path}: ` : ""}${i.message}`).join("\n");
+}
+function specFrom(fields) {
+  const out = { $schema: "https://volito.dev/schema/graphic.v1.json", volito: SPEC_VERSION };
+  for (const [k, v] of Object.entries(fields)) {
+    if (v === void 0) continue;
+    if (v && typeof v === "object" && !Array.isArray(v) && Object.keys(v).length === 0) continue;
+    out[k] = v;
+  }
+  return out;
+}
+
+// src/guide.ts
+var MOTION_GUIDE = `Motion: any part, any move
+
+Every graphic is made of named parts (volito info <item> lists them). Each part enters, may idle
+while it holds, may take emphasis hits, and leaves \u2014 and every one of those is yours to change:
+
+  in / out      any move (volito moves): rise, slam, wipe, iris, glitch, scramble, typewriter,
+                spin, swing, stretch, smear, blur, flip, bounce \u2026 An exit plays the move backwards.
+  ease          brand, out, inOut, expo, back, elastic, bounce, snappy, punchy, bouncy, calm, wobbly,
+                spring(freq, damping), steps(n), cubic(x1,y1,x2,y2)
+  from          the side a move comes from (left, right, up, down, up-left \u2026); outFrom for the exit
+  dur, delay    seconds; at / outAt replace the item's own times (outAt negative = from the end)
+  distance      how far it travels (px at 1080) \xB7 intensity 0\u20132 scales distance, size and rotation
+  blur          true: motion blur on the way in and out \xB7 origin: the pivot (center, top-left, bottom \u2026)
+  idle          a loop while it holds: float, bob, pulse, breathe, wiggle, sway, drift, jitter, spin, heartbeat, shimmer
+  emphasis      hits: "pulse@1.2, shake@now, jump@beatName" (a time, a beat, or a spoken word)
+  split         text by lines, words or letters \xB7 order forward | reverse | center | edges | random \xB7 stagger s
+  keys          your own keyframes: [{"t":0,"x":-300,"op":0},{"t":0.8,"x":0,"op":1,"ease":"bouncy"}]
+                (t in clip seconds, x/y px at 1080, s scale, r degrees, skx, op, blur) \u2014 any path you like
+
+Set them per part, or for every part with "*":
+  CLI   --motion name.in=typewriter --motion "*.ease=bouncy" --motion plate.out=wipe --motion role.emphasis=pulse@2
+  API   { motion: { "*": { ease: "bouncy" }, name: { in: "typewriter" } } }
+
+Or let a mood choreograph it: --mood energetic | elegant | playful | cinematic | glitchy | minimal | retro | kinetic,
+and --seed <n> for a new take every number (a seed alone picks a mood too). Your own settings still win.
+--speed 2 plays every move twice as fast.
+
+In your own code the same kit is there: const M = motion($, t);
+  M.part(name, { at, box: {x,y,w,h}, in, out, \u2026 }, ...markup)   a part, posed by its motion
+  M.text(name, { ...$.text options, at, in, split, \u2026 }, text)    text, whole or by unit
+  M.layout(text, textOptions, split) \u2192 { units: [{text, x, y, w, h, line, index, box}], box }
+  M.progress(name, { at, in, dur, ease }) \u2192 { in, out, at, end, outAt }  for things you draw yourself
+Give every part a box when you can: wipes, iris, shutter and blinds need it, and moods pick from more moves.`;
+var LIBRARY_GUIDE = `Libraries: layout, patterns, 3D and maps
+
+Layout (always there)
+  safeArea($) \u2192 {x, y, w, h, tall, square, wide}: the title-safe box (on 9:16 it clears the platforms' buttons)
+  fitFont($, str, role, size, maxW, extra) \u2192 a font in the brand's role, shrunk until str fits maxW
+  fitLines($, str, font, maxW, maxSize, minSize, maxLines) \u2192 {size, lines, font}: the biggest size that sets in \u2264 maxLines
+  landOn($, str, fallback, after) \u2192 when the first spoken word of str starts (0.08 s early), else fallback
+  widest($, lines, font) \xB7 avatar($, imageProp, cx, cy, r, {name, fill, ring}) \xB7 appIcon($, icon, x, y, size, {fill}) \xB7 initials(name)
+
+Patterns (always there) \u2014 sixteen animated grounds in the brand's colours, pure functions of t:
+  $.pattern(t, kind, {box, color, color2, a (strength), scale, speed, angle, at: [x, y], count, seed, r}) \u2192 markup
+  kinds: dots \xB7 plus \xB7 graph \xB7 hatch \xB7 stripes \xB7 checker \xB7 halftone \xB7 dither \xB7 waves \xB7 rings \xB7 mesh \xB7 confetti \xB7 bauhaus \xB7 tiles \xB7 pills \xB7 sunburst
+  A style whose texture names one draws it on every $.panel / $.texture ground. confetti, bauhaus and pills keep to the edges.
+
+Faces: Inter, Space Grotesk, Space Mono, Poppins, Playfair Display, Montserrat, Anton, Outfit, Gabarito, Caveat, Press Start 2P,
+  Permanent Marker, Patrick Hand, Fredoka, IM Fell English, Bebas Neue, DM Serif Display, Archivo Black, Syne, Unbounded,
+  Righteous, Orbitron, Pacifico, Fraunces, Bricolage Grotesque \u2014 name them "Family:weight" (e.g. "Fraunces:900", "Syne:800").
+
+3D \u2014 real depth, light and a camera, drawn as SVG paths (no GPU). Call it and the library comes with your program:
+  const S = scene3d($, { camera: { fov: 35, distance, yaw, pitch, roll, target: [x, y, z], x, y }, light: { dir: [x, y, z], ambient, spec, shine } });
+  Coordinates: x right, y down, z away from you, px at the target's depth (z = 0 draws at 1 px per unit by default).
+  Meshes: S.text(str, {face: $.font("display"), size, depth, color, side, back, anchor, ls, each: (i, n, ch) => ({rotate, offset, scale, hide})})
+          S.box(w, h, d, {color, side, back, radius}) \xB7 S.card(w, h, {depth, radius, color, back}) \xB7 S.disc(r, d, {...})
+          S.shape(loops | "M\u2026 path data", depth, {scale, color, side}) \xB7 S.sphere(r, {color}) (smooth) or {colorAt(lat, lon)}
+  Place: S.add(mesh, {position, rotate: [x\xB0, y\xB0, z\xB0], scale, parent: {position, rotate, parent}, opacity, flat, decal, twoSided})
+          \u2014 parent moves text with the card it is printed on; decal draws it over that card's face.
+  Also: S.line(points3d, {stroke, width}) \xB7 S.at(point3d, (x, y, scale) => markup) flat labels at 3D points \xB7 S.project(p) \u2192 {x, y, z, s}
+        S.measure(str, {face, size}) \xB7 S.clip(poly, normal, point)
+  Finish with: return S.render();   3D text uses the brand's display face (an item lists others in "faces3d").
+
+Maps (Natural Earth, 177 countries). Call one and the library comes with your program:
+  worldFind("India" | "UK" | "USA" | 356) \u2192 {name, id, c: [lon, lat], rings}
+  const m = worldMap($, { x, y, w, h, center: [lon, lat], zoom });  m.path(country | name) \u2192 path data \xB7 m.project(lon, lat) \u2192 [x, y]
+        m.countries \xB7 m.outline (the map's edge) \xB7 m.clipId() (clip to it) \xB7 m.ring(points)
+  worldGlobe(S, { r, spin, tilt, colorOf: (country) => colour }) countries on a 3D globe \xB7 worldOnSphere(lon, lat, r, spin, tilt) \u2192 a 3D point`;
+var SOUND_GUIDE = `Sound: every graphic can carry its own
+
+A render with --sound (API: sound: true, MCP: sound) gets a stereo track synthesised by Volito itself \u2014 no
+samples, no files to find \u2014 muxed into the .mp4 / .mov / .webm (PNG frames and GIF carry none; --sound-out
+file.wav writes the track alone, for an editor's timeline). Two sources, both deterministic:
+
+  1. The graphic's own motion. Every part's move leaves a mark the sound design reads: a spring pops, a move
+     across the frame whooshes (louder the further it travels), a slam hits, letters tick, a typewriter types,
+     a glitch zaps, a burst sparkles. Items nobody wrote sound for sound right out of the box.
+  2. A program's sound($). Beside frame(t, $) a program may define
+
+       function sound($) {
+         return {
+           cues: [
+             { at: 0.2, kind: "riser", dur: 1.1 },               // seconds into the clip; -1 counts from the end
+             { at: $.beat("in", 1.3), kind: "hit", level: 1.1 },  // lands with the motion: use the same times
+             { at: 1.5, kind: "shimmer", dur: 1.2, pan: 0.3 },
+             { at: 2.0, kind: "ding", note: "A5", level: 0.6 },
+           ],
+           bed: { key: "D", mode: "minor", from: 0.8, to: -0.4, level: 0.5, tone: 0.4 },  // a pad under it all (true, "Dm", or none)
+           auto: false,      // true adds the cues read from the motion on top (the default only when no cues are given)
+           level: 1,         // master, 0\u20132
+           room: 0.25,       // the reverb, 0 dry \u2026 1 wet
+         };
+       }
+
+     It runs once with $ at t = 0, so $.dur, $.beat(name), $.at(word), $.data and $.words are all there \u2014 time
+     the sound off the same beats the picture uses. Returning just an array of cues is fine too.
+
+Cues: { at, kind, dur, level (0\u20132, 1 = the kind's own), pitch (semitones), note ("A4", tone/chord/ding), pan (-1\u20261), seed }
+Kinds: whoosh (air past, dur .45) \xB7 hit (impact) \xB7 stamp (heavy slam) \xB7 pop (bubble) \xB7 tick (tiny click) \xB7 click (UI)
+       riser (climbs into a moment, dur 1) \xB7 fall (downlifter, dur .8) \xB7 sub (low drop) \xB7 shimmer (sparkle, dur 1.2)
+       ding (bell) \xB7 swell (soft air, dur .8) \xB7 zap (glitch, dur .28) \xB7 type (keys for dur) \xB7 scratch (pencil for dur)
+       tone (a note for dur) \xB7 chord (the bed's chord for dur)
+The bed steps back under every hit, stamp, sub and pop and comes back on its own. Keep a graphic's sound honest:
+one riser into its biggest moment, a hit or a sub when it lands, ticks for the small things, silence between.
+
+CLI   volito render <item> --sound [--bed Dm] [--sound-level 1.2] [--sound-out track.wav]
+      volito sound <item> --out track.wav     the track alone, with its cue list
+API   renderVideo(item, { sound: true, bed: "Dm" })  \xB7  renderSoundFile(item, { out: "track.wav" })`;
+var AUTHORING_GUIDE = `Writing Volito graphics
+
+A graphic is a program: plain JavaScript that defines function frame(t, $) and returns the SVG markup of
+one frame (no <svg> root). It is a pure function of t \u2014 any frame can be drawn alone, in any order \u2014 so it
+renders the same in MONARC PRO, in a browser and from this CLI.
+
+Props and moments
+  An item's props arrive as $.data (const p = $.data; p.name, p.role \u2026). Never hard-code text a creator
+  would change: make it a prop with a default and a maxLength the design can hold.
+  Named moments come from $.beat(name, fallback). Pack items read "in" (when the entrance starts) and
+  "out" (when the exit starts) so a creator can move them: --beat in=0.4 --beat out=-0.6.
+  When words are given (a transcript), land each element 0.04\u20130.12 s before the word that says it:
+  $.words.length ? $.atOr(firstWord, fallback) : fallback. Without words, use the beats.
+
+Parts
+  Draw each element through the motion kit (const M = motion($, t)) as a named part, with the item's own
+  motion as defaults: M.part("plate", { at, in: "wipe", box }, markup), M.text("name", { ...font, at, in: "rise" }, text).
+  List the parts in item.json ("parts": { "plate": "the card" }) so creators know what they can move.
+  Backgrounds (scrims, panels) pass vary: false so a mood leaves them still.
+
+Shape of a good item
+  - Enter in the first ~0.8 s, hold, leave in the last ~0.4 s (or hold to the end when out \u2265 duration).
+  - Lay out from $.W, $.H and scale every size by $.k (= min(W, H) / 1080): one design fits 16:9, 9:16, 1:1, 4:5.
+  - Keep text inside the title-safe area: ~5% of the width at the sides on 16:9; on 9:16 leave ~13% at the
+    top and ~22% at the bottom for platform UI (captions, buttons).
+  - Size text to fit: measure it ($.measure) and shrink the size until it fits the box it owns; wrap long
+    text with maxW. The check reports any line that runs off the frame.
+  - Colour comes from the brand: $.c.bg / $.c.fg for ground and text, $.c.accent for the one thing that
+    matters, $.c.accent2 for markers, $.c.surface for cards. Faces from $.font("display" | "text" | "mono").
+    $.case(str) applies the brand's case. Never invent colours \u2014 a creator's DESIGN.md re-skins the item.
+  - overlay items draw nothing behind themselves (footage shows through); put a $.scrim under text that sits
+    on footage. full items draw their own ground with $.panel(t, { box: { x: 0, y: 0, w: $.W, h: $.H } }).
+  - Escape any text you put in raw markup with $.esc(); $.text, $.chip and friends escape for you.
+
+An item on disk
+  my-item/item.json   { "id": "my-item", "name": "\u2026", "description": "\u2026", "category": "title",
+                        "placement": "overlay" | "full", "duration": { "default": 5, "min": 2, "max": 20 },
+                        "aspects": ["16:9", "9:16", "1:1", "4:5"],
+                        "props": { "title": { "type": "text", "default": "Hello", "maxLength": 28 } },
+                        "beats": { "in": 0.15, "out": -0.45 } }
+  my-item/frame.js    function frame(t, $) { const p = $.data; \u2026 return svg; }
+  Prop types: text, longtext (line breaks kept), number (min, max, step), boolean, choice (options),
+  color (#hex, "" = the brand's), list (rows of text, or of {field: "text" | "number"}; maxItems),
+  image (a path or URL the caller loads; draw it with $.image(propName, x, y, w, h)), icon (an icon name).
+
+A pack
+  my-pack/pack.json   { "format": 1, "id": "my-pack", "name": "\u2026", "version": "1.0.0", "description": "\u2026",
+                        "author": "\u2026", "license": "\u2026", "style": "ember", "shared": "shared.js",
+                        "items": ["my-item", \u2026] }
+  my-pack/shared.js   helpers prepended to every item's code (function declarations only).
+  Load extra packs with --packs <dir> or VOLITO_PACKS=<dir>.
+
+The loop
+  volito new my-item          a template to start from
+  volito check ./my-item      errors and warnings at every aspect
+  volito sheet ./my-item      frames across time in one PNG \u2014 look at it
+  volito render ./my-item --format mov
+  Agents: motion_check, then motion_preview, fix what you see, then motion_render.`;
+
+export {
+  loadPack,
+  builtinPacks,
+  packsIn,
+  library,
+  findItem,
+  searchItems,
+  SPEC_VERSION,
+  SPEC_SCHEMA_URL,
+  GraphicSpecSchema,
+  parseSpec,
+  specJsonSchema,
+  normalizeWords,
+  readWords,
+  loadImage,
+  loadMedia,
+  readStyleArg,
+  isSpecFile,
+  loadSpecFile,
+  itemOfSpec,
+  specToOptions,
+  validateSpec,
+  formatIssues,
+  specFrom,
+  MOTION_GUIDE,
+  LIBRARY_GUIDE,
+  SOUND_GUIDE,
+  AUTHORING_GUIDE
+};

package/dist/chunks/chunk-ZFG3X3DU.js

@@ -0,0 +1,67 @@
+// src/node/paths.ts
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+var PACKAGE_NAME = "volito";
+var root = null;
+function packageRoot() {
+  if (root) return root;
+  let dir = dirname(fileURLToPath(import.meta.url));
+  for (let i = 0; i < 6; i++) {
+    const pj = join(dir, "package.json");
+    if (existsSync(pj)) {
+      try {
+        if (JSON.parse(readFileSync(pj, "utf8")).name === PACKAGE_NAME) return root = dir;
+      } catch {
+      }
+    }
+    dir = dirname(dir);
+  }
+  throw new Error(`${PACKAGE_NAME}: cannot find its package folder from ${fileURLToPath(import.meta.url)}`);
+}
+var fontsDir = () => join(packageRoot(), "fonts");
+var packsDir = () => join(packageRoot(), "packs");
+var libsDir = () => join(packageRoot(), "libs");
+function packageVersion() {
+  return JSON.parse(readFileSync(join(packageRoot(), "package.json"), "utf8")).version;
+}
+
+// src/node/ffmpeg.ts
+import { execFileSync } from "node:child_process";
+var probed;
+function ffmpegPath() {
+  return process.env.VOLITO_FFMPEG || process.env.MONARC_MOTION_FFMPEG || "ffmpeg";
+}
+function probeFfmpeg() {
+  if (probed !== void 0) return probed;
+  const path = ffmpegPath();
+  try {
+    const out = execFileSync(path, ["-hide_banner", "-encoders"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], timeout: 15e3 });
+    const encoders = /* @__PURE__ */ new Set();
+    for (const line of out.split("\n")) {
+      const m = /^\s*[VAS][A-Z.]{5}\s+(\S+)/.exec(line);
+      if (m) encoders.add(m[1]);
+    }
+    probed = { path, encoders };
+  } catch {
+    probed = null;
+  }
+  return probed;
+}
+var FfmpegMissing = class extends Error {
+  constructor(what) {
+    super(`${what} needs ffmpeg \u2014 install it (macOS: brew install ffmpeg \xB7 Debian/Ubuntu: apt install ffmpeg \xB7 Windows: winget install ffmpeg) or set VOLITO_FFMPEG to its path. PNG sequences and stills need no ffmpeg.`);
+    this.name = "FfmpegMissing";
+  }
+};
+
+export {
+  packageRoot,
+  fontsDir,
+  packsDir,
+  libsDir,
+  packageVersion,
+  ffmpegPath,
+  probeFfmpeg,
+  FfmpegMissing
+};