volito 0.1.0 → 0.3.0

package/dist/mcp.js

@@ -1,6 +1,28 @@
 import {
-  ASPECT_NAMES,
+  loadAnySpec
+} from "./chunks/chunk-PM3PLI3X.js";
+import {
   AUTHORING_GUIDE,
+  LIBRARY_GUIDE,
+  MOTION_GUIDE,
+  SOUND_GUIDE,
+  findItem,
+  formatIssues,
+  itemOfSpec,
+  library,
+  loadMedia,
+  normalizeWords,
+  readWords,
+  searchItems,
+  specToOptions,
+  validateSpec
+} from "./chunks/chunk-QA4SEJCZ.js";
+import {
+  describeReview,
+  reviewItem
+} from "./chunks/chunk-ZHMWEZ4C.js";
+import {
+  ASPECT_NAMES,
   BUILTIN_STYLES,
   CATEGORIES,
   DIRECTIONS,
@@ -8,10 +30,8 @@ import {
   FORMAT_NOTES,
   HITS,
   IDLES,
-  LIBRARY_GUIDE,
   MG_API_REFERENCE,
   MOODS,
-  MOTION_GUIDE,
   MOVES,
   MOVE_NOTES,
   ORDERS,
@@ -20,31 +40,30 @@ import {
   VIDEO_FORMATS,
   checkItem,
   customItem,
+  describeCues,
   describeItem,
   describeReport,
-  findItem,
-  library,
-  loadMedia,
-  normalizeWords,
-  packageVersion,
   parseAspect,
-  readWords,
   renderSheet,
+  renderSoundFile,
   renderStill,
-  renderVideo,
-  searchItems
-} from "./chunks/chunk-CFDFWZAC.js";
+  renderVideo
+} from "./chunks/chunk-CUQY6YI3.js";
+import {
+  packageVersion
+} from "./chunks/chunk-ZFG3X3DU.js";
 
 // src/mcp.ts
 import { existsSync, readFileSync } from "node:fs";
-import { resolve } from "node:path";
+import { dirname, resolve } from "node:path";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 var source = {
   item: z.string().optional().describe('A pack item: "essentials/lower-third", or its id "lower-third" (motion_list shows them). Give this or `code`.'),
   code: z.string().optional().describe("Your own program: plain JavaScript defining function frame(t, $) that returns SVG markup (see motion_api). Give this or `item`."),
-  placement: z.enum(["overlay", "full"]).optional().describe("For `code`: overlay (transparent, over footage) or full (draws its own ground).")
+  placement: z.enum(["overlay", "full"]).optional().describe("For `code`: overlay (transparent, over footage) or full (draws its own ground)."),
+  spec: z.string().optional().describe('A Graphic spec file (.json with "volito": 1; motion_validate checks one) or a .volito bundle: its item and options are the base, and anything else given here wins. Give this instead of `item` or `code`.')
 };
 var look = {
   props: z.record(z.string(), z.unknown()).optional().describe("The item's props (motion_info lists them), e.g. { name: 'Priya Sharma', role: 'Product designer' }. For `code`, any data the program reads as $.data."),
@@ -61,6 +80,7 @@ var look = {
   speed: z.number().positive().optional().describe("Every move faster (2) or slower (0.5).")
 };
 function pick(lib, a) {
+  if (a.spec) return itemOfSpec(loadAnySpec(a.spec), lib);
   if (a.code?.trim()) return customItem(a.code, { placement: a.placement, duration: a.duration });
   if (!a.item) throw new Error("give `item` (see motion_list) or `code` (see motion_api)");
   return findItem(a.item, lib);
@@ -73,10 +93,13 @@ function styleOf(s) {
 }
 async function optionsOf(item, a) {
   const words = a.words?.length ? normalizeWords(a.words) : a.wordsFile ? readWords(a.wordsFile) : void 0;
+  const base = a.spec ? specToOptions(loadAnySpec(a.spec), item) : {};
+  const props = { ...base.props ?? {}, ...a.props ?? {} };
   return {
-    props: a.props ?? {},
+    ...base,
+    props,
     ...a.style ? { style: styleOf(a.style) } : {},
-    ...a.colors ? { colors: a.colors } : {},
+    ...a.colors ? { colors: { ...base.colors ?? {}, ...a.colors } } : {},
     ...a.aspect ? { aspect: parseAspect(a.aspect) } : {},
     ...a.duration ? { duration: a.duration } : {},
     ...words?.length ? { words } : {},
@@ -85,7 +108,7 @@ async function optionsOf(item, a) {
     ...a.mood ? { mood: a.mood } : {},
     ...a.seed !== void 0 ? { seed: a.seed } : {},
     ...a.speed ? { speed: a.speed } : {},
-    media: await loadMedia(item, a.props ?? {})
+    media: await loadMedia(item, props)
   };
 }
 var text = (t) => ({ content: [{ type: "text", text: t }] });
@@ -95,7 +118,7 @@ Warnings:
 ${w.map((x) => `- ${x}`).join("\n")}` : "";
 function createMcpServer(opts = {}) {
   const lib = () => library(opts.packs ?? []);
-  const server = new McpServer({ name: "volito", version: packageVersion() }, { instructions: "Volito renders brand-aware motion graphics (lower thirds, titles, CTAs, stats, lists, end cards\u2026) to video files with alpha. Find one with motion_list, read its props and parts with motion_info, look at it with motion_preview (a contact sheet image), then motion_render to a file. Motion is open-ended: any part takes any move, ease, idle, emphasis or keyframes (motion_moves lists them) through `motion`, and `mood` + `seed` give a new choreography for every seed. Packs: essentials, broadcast (lower thirds, tickers, score bugs), social (follow cards, notifications, chat), data (charts, maps, flight routes) and 3d (extruded logos and titles, card flips, globes). To make something no item covers, write a program against motion_api (it includes 3D scenes and world maps) and use the same tools with `code`." });
+  const server = new McpServer({ name: "volito", version: packageVersion() }, { instructions: "Volito renders brand-aware motion graphics (lower thirds, titles, CTAs, stats, lists, end cards\u2026) to video files with alpha. Find one with motion_list, read its props and parts with motion_info, look at it with motion_preview (a contact sheet image), then motion_render to a file. Motion is open-ended: any part takes any move, ease, idle, emphasis or keyframes (motion_moves lists them) through `motion`, and `mood` + `seed` give a new choreography for every seed. Packs: essentials, broadcast (lower thirds, tickers, score bugs), social (follow cards, notifications, chat), data (charts, maps, flight routes) and 3d (extruded logos and titles, card flips, globes). To make something no item covers, write a program against motion_api (it includes 3D scenes and world maps) and use the same tools with `code`. Every render can carry sound Volito synthesises itself (motion_render with sound: true, or motion_sound for the track alone): a program's own sound($) cues, else the right pops, whooshes, ticks and hits read from its motion." });
   server.registerTool(
     "motion_list",
     { title: "List motion graphics", description: "The graphics in the packs: ref, overlay or full frame, default length, what it is.", inputSchema: { search: z.string().optional().describe("Words to match (e.g. 'name', 'subscribe', 'chart')."), category: z.enum(CATEGORIES).optional() } },
@@ -186,6 +209,25 @@ ${it.code}` : ""}`);
       }
     }
   );
+  server.registerTool(
+    "motion_review",
+    {
+      title: "Review a motion graphic",
+      description: "Everything to look at before rendering, measured: the check at each aspect, when it settles and how long it holds still (with a warning when the entrance is slow or the hold too short to read its words), how much of an overlay sits under Reels', Shorts' and TikTok's own interface at 9:16, and a contact sheet per aspect (returned as images, written with a review.md to outDir).",
+      inputSchema: { ...source, ...look, outDir: z.string().optional().describe("Where to write the sheets and review.md. Default: volito-review/<id>.") }
+    },
+    async (a) => {
+      try {
+        const item = pick(lib(), a);
+        const opts2 = await optionsOf(item, a);
+        const rep = await reviewItem(item, { ...opts2, ...a.aspect ? { aspects: [parseAspect(a.aspect)] } : {}, outDir: a.outDir ?? `volito-review/${item.id}` });
+        const images = rep.aspects.filter((x) => x.sheet).slice(0, 2).map((x) => ({ type: "image", data: readFileSync(x.sheet).toString("base64"), mimeType: "image/png" }));
+        return { content: [...images, { type: "text", text: describeReview(rep) }] };
+      } catch (err) {
+        return failure(err);
+      }
+    }
+  );
   server.registerTool(
     "motion_render",
     {
@@ -198,17 +240,80 @@ ${it.code}` : ""}`);
         out: z.string().optional().describe("Output path (relative to the server's working folder). Default: motion-renders/<id>-<size>.<ext>."),
         fps: z.number().int().min(1).max(120).optional(),
         width: z.number().int().min(16).max(8192).optional().describe("Output width px (height follows)."),
-        background: z.string().optional().describe('"#000000" draws a ground under the graphic; "transparent" keeps alpha.')
+        background: z.string().optional().describe('"#000000" draws a ground under the graphic; "transparent" keeps alpha.'),
+        sound: z.boolean().optional().describe("Mux a sound track synthesised by Volito: the program's own sound($) cues, else cues read from its motion (pops, whooshes, ticks, hits). Not for png/gif."),
+        bed: z.string().optional().describe('A pad under it all, in a key: "Dm", "F major", "C#m".'),
+        soundOut: z.string().optional().describe("Also write the track alone to this .wav (for an editor's timeline).")
+      }
+    },
+    async (a) => {
+      try {
+        const item = pick(lib(), a);
+        const opts2 = await optionsOf(item, a);
+        const fromSpec = a.spec ? loadAnySpec(a.spec).spec.render : void 0;
+        const format = a.format ?? fromSpec?.format ?? "mov";
+        const out = a.out ?? fromSpec?.out;
+        const r = await renderVideo(item, {
+          ...opts2,
+          format,
+          ...out ? { out } : { outDir: "motion-renders" },
+          ...a.fps ? { fps: a.fps } : {},
+          ...a.width ? { width: a.width } : {},
+          ...a.background ? { background: a.background } : {},
+          ...a.sound || a.bed || a.soundOut ? { sound: true } : {},
+          ...a.bed ? { bed: a.bed } : {},
+          ...a.soundOut ? { soundOut: a.soundOut } : {}
+        });
+        return text(`Rendered ${r.file}
+${r.format} \xB7 ${r.width}\xD7${r.height} \xB7 ${r.fps} fps \xB7 ${r.duration.toFixed(2)} s \xB7 ${r.frames} frames${r.bytes ? ` \xB7 ${(r.bytes / 1e6).toFixed(1)} MB` : ""}${r.sound ? ` \xB7 sound: ${r.sound.cues.length} cues${r.sound.bed ? ` on a ${r.sound.bed.key} ${r.sound.bed.mode} bed` : ""}${r.sound.file ? ` \u2192 ${r.sound.file}` : ""}` : ""} \xB7 took ${(r.ms / 1e3).toFixed(1)} s${warnings(r.warnings)}`);
+      } catch (err) {
+        return failure(err);
+      }
+    }
+  );
+  server.registerTool(
+    "motion_sound",
+    {
+      title: "Sound design for a motion graphic",
+      description: "The graphic's sound alone, as a .wav, with its cue list: the program's own sound($) cues when it defines them, else cues read from its motion (a pop for every spring, a whoosh for every move across the frame, ticks for letters, a hit for a slam). Needs no ffmpeg. Use motion_render with sound: true to mux it into the video instead.",
+      inputSchema: {
+        ...source,
+        ...look,
+        bed: z.string().optional().describe('A pad under it all, in a key: "Dm", "F major".'),
+        out: z.string().optional().describe("Output .wav path. Default: motion-renders/<id>.wav.")
       }
     },
     async (a) => {
       try {
         const item = pick(lib(), a);
         const opts2 = await optionsOf(item, a);
-        const format = a.format ?? "mov";
-        const r = await renderVideo(item, { ...opts2, format, ...a.out ? { out: a.out } : { outDir: "motion-renders" }, ...a.fps ? { fps: a.fps } : {}, ...a.width ? { width: a.width } : {}, ...a.background ? { background: a.background } : {} });
+        const r = await renderSoundFile(item, { ...opts2, sound: true, ...a.bed ? { bed: a.bed } : {}, ...a.out ? { out: a.out } : { outDir: "motion-renders" } });
         return text(`Rendered ${r.file}
-${r.format} \xB7 ${r.width}\xD7${r.height} \xB7 ${r.fps} fps \xB7 ${r.duration.toFixed(2)} s \xB7 ${r.frames} frames${r.bytes ? ` \xB7 ${(r.bytes / 1e6).toFixed(1)} MB` : ""} \xB7 took ${(r.ms / 1e3).toFixed(1)} s${warnings(r.warnings)}`);
+${r.duration.toFixed(2)} s \xB7 ${r.cues.length} cues${r.bed ? ` \xB7 bed ${r.bed.key} ${r.bed.mode}` : ""} \xB7 peak ${r.peak.toFixed(2)}
+${describeCues(r.cues)}${warnings(r.warnings)}`);
+      } catch (err) {
+        return failure(err);
+      }
+    }
+  );
+  server.registerTool(
+    "motion_validate",
+    {
+      title: "Validate a Graphic spec",
+      description: 'Checks a Graphic spec before rendering: its shape, the item it names, files it points at, props against the item (lengths, types, choices), motion parts, aspect and length. A spec is one JSON document for one graphic: { "volito": 1, "item": "lower-third", "props": {\u2026}, "style": "ember", "aspect": "9:16", "motion": {\u2026}, "mood", "seed", "sound" }. Pass it inline or as a file path; then render it with motion_render { spec: "path" }.',
+      inputSchema: { spec: z.union([z.string(), z.record(z.string(), z.unknown())]).describe("A path to a .json spec, or the spec itself") }
+    },
+    async (a) => {
+      try {
+        const isPath = typeof a.spec === "string";
+        const doc = isPath ? JSON.parse(readFileSync(resolve(a.spec), "utf8")) : a.spec;
+        const rep = validateSpec(doc, { dir: isPath ? dirname(resolve(a.spec)) : process.cwd(), lib: lib() });
+        const lines = [rep.ok ? `Valid${rep.item ? ` \u2014 ${rep.item}` : ""}.` : "Not valid."];
+        if (rep.errors.length) lines.push(`Errors:
+${formatIssues(rep.errors, "-")}`);
+        if (rep.warnings.length) lines.push(`Warnings (it renders, but not as written):
+${formatIssues(rep.warnings, "-")}`);
+        return text(lines.join("\n"));
       } catch (err) {
         return failure(err);
       }
@@ -223,6 +328,8 @@ ${LIBRARY_GUIDE}
 
 ${MOTION_GUIDE}
 
+${SOUND_GUIDE}
+
 ${AUTHORING_GUIDE}`)
   );
   return server;