volito 0.1.0 → 0.3.0

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import { z } from 'zod';
+
 /** The pixel sprites the runtime has built in ($.sprite(name, …)), read from its source. */
 declare const MG_SPRITE_NAMES: string[];
 /** The icon names the runtime draws ($.icon(name, …)), read from its source so the two never drift. */
@@ -260,6 +262,33 @@ declare function normalizeMotion(cfg: {
 /** "name.in=pop", "in=pop" (every part), "*.ease=bouncy", or a JSON object → overrides. */
 declare function parseMotionArgs(args: string[]): MotionInput;
 
+/**
+ * Interactive states for <volito-player>: a graphic's timeline cut into named stretches — idle, hover,
+ * press, loading, success — that page events and code switch between. Each state plays its stretch once
+ * (then stays on its last frame, or moves on to `next`), loops it, or holds one frame. Times are seconds or
+ * the item's beat names, so an item that names its beats ("hover", "press") declares its states in
+ * item.json and works with no setup:
+ *
+ *   "states": { "idle": { "from": "idle", "to": "hover", "play": "loop" },
+ *               "hover": { "from": "hover", "to": "press", "play": "once" },
+ *               "press": { "from": "press", "to": "loading", "play": "once", "next": "loading" } },
+ *   "on": "pointerenter(idle): hover; pointerleave(hover): idle; click: press"
+ *
+ * Pure functions: parsed and resolved here, played by the element.
+ */
+declare const STATE_PLAYS: readonly ["once", "loop", "hold"];
+type StatePlay = (typeof STATE_PLAYS)[number];
+interface StateDef {
+    /** Where the stretch starts: seconds, a beat name, "start" or "end". Default: the start. */
+    from?: number | string;
+    /** Where it ends: seconds, a beat name, "start" or "end". Default: the end. */
+    to?: number | string;
+    /** once: play it and stay on its last frame (or go to `next`); loop: repeat it; hold: show `from` and stay. */
+    play?: StatePlay;
+    /** The state to go to when a `once` stretch finishes. */
+    next?: string;
+}
+
 /**
  * Packs and items: the library format. A pack is a folder of items that share a look and a
  * helper file; an item is one motion graphic — `item.json` (what it is, the props it takes,
@@ -338,6 +367,13 @@ interface ItemManifest {
     libs?: LibraryName[];
     /** Faces whose glyphs 3D text is built from: brand roles ("display") or specs ("Anton:400"). Default: display. */
     faces3d?: string[];
+    /**
+     * Interactive states for <volito-player>: named stretches of the timeline (beat names or seconds), each
+     * played once, looped or held — { "idle": { "from": "idle", "to": "hover", "play": "loop" }, … }.
+     */
+    states?: Record<string, StateDef>;
+    /** The page events that switch states by default: "pointerenter(idle): hover; click: press". */
+    on?: string;
 }
 interface PackManifest {
     format: number;
@@ -483,6 +519,102 @@ interface ItemQuery {
 }
 declare function searchItems(q?: ItemQuery, lib?: Library): MotionItem[];
 
+/**
+ * The Graphic spec: one JSON document that says everything about one graphic — which item (or program),
+ * its words, brand, shape, timing, motion and sound. The CLI, the Node API and the MCP server read it, and
+ * the same spec renders the same frames anywhere. A recipe you can keep in a repo, diff, review and hand
+ * to an agent or a teammate.
+ *
+ *   { "volito": 1, "item": "essentials/lower-third", "props": { "name": "Priya Sharma" }, "style": "ember", "aspect": "9:16" }
+ *
+ * "volito" is the format's major version: a new major only comes with a migration, and minor changes only
+ * add optional fields. This module is pure (no Node APIs) so the browser player and editors can use it.
+ */
+
+declare const SPEC_VERSION = 1;
+declare const SPEC_SCHEMA_URL = "https://volito.dev/schema/graphic.v1.json";
+declare const GraphicSpecSchema: z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
+    volito: z.ZodLiteral<1>;
+    name: z.ZodOptional<z.ZodString>;
+    item: z.ZodOptional<z.ZodString>;
+    program: z.ZodOptional<z.ZodString>;
+    code: z.ZodOptional<z.ZodString>;
+    placement: z.ZodOptional<z.ZodEnum<{
+        overlay: "overlay";
+        full: "full";
+    }>>;
+    props: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    style: z.ZodOptional<z.ZodString>;
+    colors: z.ZodOptional<z.ZodObject<{
+        accent: z.ZodOptional<z.ZodString>;
+        accent2: z.ZodOptional<z.ZodString>;
+        ink: z.ZodOptional<z.ZodString>;
+        paper: z.ZodOptional<z.ZodString>;
+        surface: z.ZodOptional<z.ZodString>;
+        mode: z.ZodOptional<z.ZodEnum<{
+            dark: "dark";
+            light: "light";
+        }>>;
+        display: z.ZodOptional<z.ZodString>;
+        text: z.ZodOptional<z.ZodString>;
+        mono: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    aspect: z.ZodOptional<z.ZodString>;
+    duration: z.ZodOptional<z.ZodNumber>;
+    fps: z.ZodOptional<z.ZodNumber>;
+    width: z.ZodOptional<z.ZodNumber>;
+    background: z.ZodOptional<z.ZodString>;
+    words: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodObject<{
+        w: z.ZodString;
+        s: z.ZodNumber;
+        e: z.ZodNumber;
+    }, z.core.$strict>>, z.ZodString]>>;
+    offset: z.ZodOptional<z.ZodNumber>;
+    beats: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodNumber>>;
+    motion: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    mood: z.ZodOptional<z.ZodEnum<{
+        retro: "retro";
+        energetic: "energetic";
+        elegant: "elegant";
+        playful: "playful";
+        cinematic: "cinematic";
+        glitchy: "glitchy";
+        minimal: "minimal";
+        kinetic: "kinetic";
+    }>>;
+    seed: z.ZodOptional<z.ZodNumber>;
+    speed: z.ZodOptional<z.ZodNumber>;
+    sound: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodObject<{
+        bed: z.ZodOptional<z.ZodString>;
+        level: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>]>>;
+    render: z.ZodOptional<z.ZodObject<{
+        format: z.ZodOptional<z.ZodEnum<{
+            mov: "mov";
+            webm: "webm";
+            mp4: "mp4";
+            hevc: "hevc";
+            gif: "gif";
+            png: "png";
+        }>>;
+        out: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+type GraphicSpec = z.infer<typeof GraphicSpecSchema>;
+interface SpecIssue {
+    /** Where in the spec, as a JSON path ("props.name", "motion.plate.in"); "" for the whole document. */
+    path: string;
+    message: string;
+}
+/** Parse and check the shape of a spec (not the item it names). */
+declare function parseSpec(input: unknown): {
+    spec: GraphicSpec | null;
+    errors: SpecIssue[];
+};
+/** The spec format as a JSON Schema (draft 2020-12), for editors and other languages. */
+declare function specJsonSchema(): Record<string, unknown>;
+
 interface ProgramFrame {
     svg: string;
     defs: string;
@@ -494,6 +626,8 @@ declare class ProgramError extends Error {
     readonly line?: number;
     constructor(message: string, line?: number | null);
 }
+/** Whether this engine's worker source still has the line the sound hook patches (a test keeps it true). */
+declare function soundHookAvailable(): boolean;
 declare class ProgramRunner {
     private readonly ctx;
     private readonly codeLine;
@@ -515,6 +649,14 @@ declare class ProgramRunner {
     private sendSync;
     /** The SVG body of the frame at clip time `t`. Throws a ProgramError when the program fails. */
     frame(t: number, timeoutMs?: number): ProgramFrame;
+    /**
+     * The program's own sound design: what `function sound($)` returns, read once with `$` at t = 0 ($.dur,
+     * $.beat, $.at and $.data are there). `spec` is null when the program defines none; `error` when it threw.
+     */
+    sound(timeoutMs?: number): {
+        spec: unknown;
+        error?: string;
+    };
     /** Every frame run once with the runtime's trace on: when each element pops, slides, stamps or types in. */
     trace(fps: number, timeoutMs?: number): {
         marks: unknown[];
@@ -523,6 +665,107 @@ declare class ProgramRunner {
     };
 }
 
+/**
+ * Sound design for Volito graphics — synthesised here, from nothing: no samples, no dependencies.
+ *
+ * A render carries sound two ways. Any program may define `function sound($)` and return cues
+ * (`{ at, kind, dur, level, pitch, pan }`) and, if it wants one, a tonal bed in a key; and every
+ * graphic is read through the runtime's motion trace (when each part pops, slides, stamps, types
+ * or bursts in), so `--sound` gives the right whoosh, pop or tick to an item nobody wrote cues for.
+ * Both end in `renderSound`: cues become stereo PCM through small synths (filtered noise for air
+ * and sweeps, sine drops for impacts, inharmonic partials for bells, detuned saws for a pad), a
+ * room (a Schroeder reverb), ducking of the bed under hits, a limiter, and a WAV ffmpeg muxes.
+ *
+ * Pure TypeScript, deterministic: the same cues render the same bytes every time.
+ */
+declare const SOUND_KINDS: readonly ["whoosh", "hit", "stamp", "pop", "tick", "click", "riser", "fall", "sub", "shimmer", "ding", "swell", "zap", "type", "scratch", "tone", "chord"];
+type SoundKind = (typeof SOUND_KINDS)[number];
+/** One line per kind, for help text and agents. */
+declare const SOUND_NOTES: Record<SoundKind, string>;
+interface SoundCue {
+    /** Clip seconds. */
+    at: number;
+    kind: SoundKind;
+    /** Seconds, for the kinds that last. */
+    dur?: number;
+    /** 0–2; 1 is the kind's own level. */
+    level?: number;
+    /** Semitones up or down from the kind's own pitch. */
+    pitch?: number;
+    /** A note for tone / chord ("A4", "D#3", "Bb2"). */
+    note?: string;
+    /** -1 left … 1 right (0 centre). */
+    pan?: number;
+    /** A different take of the same sound. */
+    seed?: number;
+}
+interface SoundBed {
+    /** "D", "F#", "Bb" — the key (A by default). */
+    key?: string;
+    mode?: "major" | "minor";
+    /** Clip seconds it plays between (the whole clip by default). */
+    from?: number;
+    to?: number;
+    /** 0–1 (0.5). */
+    level?: number;
+    /** 0 dark … 1 open (0.4). */
+    tone?: number;
+}
+interface SoundSpec {
+    cues?: SoundCue[];
+    /** A pad under everything: a bed object, true for one in A minor, or a key ("Dm", "F major"). */
+    bed?: SoundBed | boolean | string;
+    /** Also take cues from the graphic's own motion (true when the program gives no cues). */
+    auto?: boolean;
+    /** Master level, 0–2 (1). */
+    level?: number;
+    /** The room: 0 dry … 1 wet (0.25). */
+    room?: number;
+}
+/** A mark the runtime's trace left: [kind, seconds, a, b, count]. */
+type TraceMark = [string, number, number | null, number | null, number];
+interface RenderedSound {
+    left: Float32Array;
+    right: Float32Array;
+    sampleRate: number;
+    /** The cues that were rendered (after clamping and thinning). */
+    cues: SoundCue[];
+    /** Peak sample after the limiter, 0–1. */
+    peak: number;
+    bed: SoundBed | null;
+    warnings: string[];
+}
+/** "A4" → 440, "D#3", "Bb2"; null when it is not a note. */
+declare function noteHz(note: string): number | null;
+/** "Dm", "F# minor", "Bb", "C major" → the root as semitones from A and the mode. */
+declare function parseKey(key: string | undefined): {
+    root: number;
+    mode: "major" | "minor";
+};
+/** A spec as a program (or an agent) returned it, cleaned: unknown kinds dropped with a warning, numbers read. */
+declare function normalizeSoundSpec(raw: unknown, duration: number): {
+    spec: SoundSpec;
+    warnings: string[];
+};
+/** The bed a spec asks for, in full, or null. */
+declare function bedOf(b: SoundSpec["bed"], duration: number): SoundBed | null;
+/**
+ * Cues for a graphic nobody wrote sound for, from the runtime's trace: a pop for each spring, a
+ * whoosh for each move across the frame (louder the further it travels), ticks for letters and
+ * words, typing for a typewriter, an impact for a slam or a stamp, a zap for a glitch, sparkle for a
+ * burst. Dense runs (letters staggering in, bars growing one after another) become one soft run of
+ * ticks instead of a dozen pops.
+ */
+declare function cuesFromMarks(marks: TraceMark[], duration: number): SoundCue[];
+/** Mix cues and a bed into stereo PCM, duration seconds long, at 48 kHz. */
+declare function renderSound(spec: SoundSpec, duration: number, opts?: {
+    sampleRate?: number;
+}): RenderedSound;
+/** 16-bit stereo PCM WAV. */
+declare function wavEncode(left: Float32Array, right: Float32Array, sampleRate: number): Uint8Array;
+/** One line per cue, for a terminal or an agent. */
+declare function describeCues(cues: SoundCue[]): string;
+
 declare const VIDEO_FORMATS: readonly ["mov", "webm", "mp4", "hevc", "gif", "png"];
 type VideoFormat = (typeof VIDEO_FORMATS)[number];
 type StillFormat = "png" | "svg";
@@ -540,6 +783,26 @@ interface RenderOptions extends BuildOptions {
     /** Bound on one frame's program run, ms. */
     frameTimeoutMs?: number;
     onProgress?: (done: number, total: number) => void;
+    /**
+     * Sound, synthesised by Volito and muxed into the video: true for the program's own sound($) (or, when it has
+     * none, cues read from its motion); a SoundSpec adds cues and sets the bed, level and room on top.
+     */
+    sound?: boolean | SoundSpec;
+    /** A pad under everything in a key ("Dm", "F major"), a bed object, or false for none — over what the program asks. */
+    bed?: string | SoundBed | false;
+    /** Also write the sound alone to this .wav (an editor's timeline wants it next to a ProRes overlay). */
+    soundOut?: string;
+}
+interface SoundResult {
+    /** The cues rendered, in time order. */
+    cues: SoundCue[];
+    bed: SoundBed | null;
+    /** Peak after the limiter, 0–1. */
+    peak: number;
+    duration: number;
+    /** The .wav written, when one was asked for. */
+    file?: string;
+    warnings: string[];
 }
 interface Session {
     item: MotionItem;
@@ -609,7 +872,22 @@ interface VideoResult {
     bytes: number;
     ms: number;
     warnings: string[];
+    /** The sound track, when one was rendered. */
+    sound?: SoundResult;
 }
+/**
+ * The sound of a graphic: the program's own sound($) when it defines one, cues read from its motion trace
+ * (always when it defines none, or when it asks with auto: true), and the bed, level and room the caller sets.
+ */
+declare function designSound(s: Session, opts: Pick<RenderOptions, "sound" | "bed">, duration?: number): {
+    spec: SoundSpec;
+    warnings: string[];
+};
+/** Render a graphic's sound alone, to a .wav (no ffmpeg needed). */
+declare function renderSoundFile(item: MotionItem, opts?: RenderOptions & {
+    out?: string;
+    outDir?: string;
+}): Promise<SoundResult>;
 /** The format a file name asks for (".mov" → ProRes, ".webm", ".mp4", ".gif", a folder → PNG frames). */
 declare function formatFromPath(path: string): VideoFormat | null;
 declare function defaultOutput(item: MotionItem, format: VideoFormat, s: {
@@ -626,6 +904,38 @@ declare function renderVideo(item: MotionItem, opts?: RenderOptions & {
     outDir?: string;
 }): Promise<VideoResult>;
 
+interface LoadedSpec {
+    spec: GraphicSpec;
+    /** The folder its paths are relative to. */
+    dir: string;
+    file?: string;
+}
+/** A path that holds a Volito spec: a .json file whose top level has "volito". */
+declare function isSpecFile(path: string): boolean;
+/** Read and shape-check a spec file; throws with every problem listed. */
+declare function loadSpecFile(path: string): LoadedSpec;
+/** The item a spec draws: a pack item, a program file or inline code. */
+declare function itemOfSpec(loaded: LoadedSpec, lib?: Library): MotionItem;
+/** Render options from a spec (media not loaded yet: image props are resolved to absolute paths or URLs). */
+declare function specToOptions(loaded: LoadedSpec, item: MotionItem): RenderOptions;
+interface SpecReport {
+    ok: boolean;
+    errors: SpecIssue[];
+    warnings: SpecIssue[];
+    item?: string;
+}
+/**
+ * Everything wrong with a spec, before anything renders: its shape, the item it names, files it points at,
+ * props against the item's manifest, motion parts, the aspect and the length. Errors stop a render;
+ * warnings would render but not as written (a name cut to fit, a part that does not exist).
+ */
+declare function validateSpec(input: unknown, opts?: {
+    dir?: string;
+    lib?: Library;
+}): SpecReport;
+/** A spec from the options a command line gave (the reverse of specToOptions), for `volito spec`. */
+declare function specFrom(fields: Omit<GraphicSpec, "volito" | "$schema">): GraphicSpec;
+
 interface AspectReport {
     aspect: string;
     ok: boolean;
@@ -716,8 +1026,10 @@ declare const PATTERN_NAMES: PatternName[];
 declare const MOTION_GUIDE = "Motion: any part, any move\n\nEvery graphic is made of named parts (volito info <item> lists them). Each part enters, may idle\nwhile it holds, may take emphasis hits, and leaves \u2014 and every one of those is yours to change:\n\n  in / out      any move (volito moves): rise, slam, wipe, iris, glitch, scramble, typewriter,\n                spin, swing, stretch, smear, blur, flip, bounce \u2026 An exit plays the move backwards.\n  ease          brand, out, inOut, expo, back, elastic, bounce, snappy, punchy, bouncy, calm, wobbly,\n                spring(freq, damping), steps(n), cubic(x1,y1,x2,y2)\n  from          the side a move comes from (left, right, up, down, up-left \u2026); outFrom for the exit\n  dur, delay    seconds; at / outAt replace the item's own times (outAt negative = from the end)\n  distance      how far it travels (px at 1080) \u00B7 intensity 0\u20132 scales distance, size and rotation\n  blur          true: motion blur on the way in and out \u00B7 origin: the pivot (center, top-left, bottom \u2026)\n  idle          a loop while it holds: float, bob, pulse, breathe, wiggle, sway, drift, jitter, spin, heartbeat, shimmer\n  emphasis      hits: \"pulse@1.2, shake@now, jump@beatName\" (a time, a beat, or a spoken word)\n  split         text by lines, words or letters \u00B7 order forward | reverse | center | edges | random \u00B7 stagger s\n  keys          your own keyframes: [{\"t\":0,\"x\":-300,\"op\":0},{\"t\":0.8,\"x\":0,\"op\":1,\"ease\":\"bouncy\"}]\n                (t in clip seconds, x/y px at 1080, s scale, r degrees, skx, op, blur) \u2014 any path you like\n\nSet them per part, or for every part with \"*\":\n  CLI   --motion name.in=typewriter --motion \"*.ease=bouncy\" --motion plate.out=wipe --motion role.emphasis=pulse@2\n  API   { motion: { \"*\": { ease: \"bouncy\" }, name: { in: \"typewriter\" } } }\n\nOr let a mood choreograph it: --mood energetic | elegant | playful | cinematic | glitchy | minimal | retro | kinetic,\nand --seed <n> for a new take every number (a seed alone picks a mood too). Your own settings still win.\n--speed 2 plays every move twice as fast.\n\nIn your own code the same kit is there: const M = motion($, t);\n  M.part(name, { at, box: {x,y,w,h}, in, out, \u2026 }, ...markup)   a part, posed by its motion\n  M.text(name, { ...$.text options, at, in, split, \u2026 }, text)    text, whole or by unit\n  M.layout(text, textOptions, split) \u2192 { units: [{text, x, y, w, h, line, index, box}], box }\n  M.progress(name, { at, in, dur, ease }) \u2192 { in, out, at, end, outAt }  for things you draw yourself\nGive every part a box when you can: wipes, iris, shutter and blinds need it, and moods pick from more moves.";
 /** The libraries and helpers every program can use besides the $ runtime. */
 declare const LIBRARY_GUIDE = "Libraries: layout, patterns, 3D and maps\n\nLayout (always there)\n  safeArea($) \u2192 {x, y, w, h, tall, square, wide}: the title-safe box (on 9:16 it clears the platforms' buttons)\n  fitFont($, str, role, size, maxW, extra) \u2192 a font in the brand's role, shrunk until str fits maxW\n  fitLines($, str, font, maxW, maxSize, minSize, maxLines) \u2192 {size, lines, font}: the biggest size that sets in \u2264 maxLines\n  landOn($, str, fallback, after) \u2192 when the first spoken word of str starts (0.08 s early), else fallback\n  widest($, lines, font) \u00B7 avatar($, imageProp, cx, cy, r, {name, fill, ring}) \u00B7 appIcon($, icon, x, y, size, {fill}) \u00B7 initials(name)\n\nPatterns (always there) \u2014 sixteen animated grounds in the brand's colours, pure functions of t:\n  $.pattern(t, kind, {box, color, color2, a (strength), scale, speed, angle, at: [x, y], count, seed, r}) \u2192 markup\n  kinds: dots \u00B7 plus \u00B7 graph \u00B7 hatch \u00B7 stripes \u00B7 checker \u00B7 halftone \u00B7 dither \u00B7 waves \u00B7 rings \u00B7 mesh \u00B7 confetti \u00B7 bauhaus \u00B7 tiles \u00B7 pills \u00B7 sunburst\n  A style whose texture names one draws it on every $.panel / $.texture ground. confetti, bauhaus and pills keep to the edges.\n\nFaces: Inter, Space Grotesk, Space Mono, Poppins, Playfair Display, Montserrat, Anton, Outfit, Gabarito, Caveat, Press Start 2P,\n  Permanent Marker, Patrick Hand, Fredoka, IM Fell English, Bebas Neue, DM Serif Display, Archivo Black, Syne, Unbounded,\n  Righteous, Orbitron, Pacifico, Fraunces, Bricolage Grotesque \u2014 name them \"Family:weight\" (e.g. \"Fraunces:900\", \"Syne:800\").\n\n3D \u2014 real depth, light and a camera, drawn as SVG paths (no GPU). Call it and the library comes with your program:\n  const S = scene3d($, { camera: { fov: 35, distance, yaw, pitch, roll, target: [x, y, z], x, y }, light: { dir: [x, y, z], ambient, spec, shine } });\n  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).\n  Meshes: S.text(str, {face: $.font(\"display\"), size, depth, color, side, back, anchor, ls, each: (i, n, ch) => ({rotate, offset, scale, hide})})\n          S.box(w, h, d, {color, side, back, radius}) \u00B7 S.card(w, h, {depth, radius, color, back}) \u00B7 S.disc(r, d, {...})\n          S.shape(loops | \"M\u2026 path data\", depth, {scale, color, side}) \u00B7 S.sphere(r, {color}) (smooth) or {colorAt(lat, lon)}\n  Place: S.add(mesh, {position, rotate: [x\u00B0, y\u00B0, z\u00B0], scale, parent: {position, rotate, parent}, opacity, flat, decal, twoSided})\n          \u2014 parent moves text with the card it is printed on; decal draws it over that card's face.\n  Also: S.line(points3d, {stroke, width}) \u00B7 S.at(point3d, (x, y, scale) => markup) flat labels at 3D points \u00B7 S.project(p) \u2192 {x, y, z, s}\n        S.measure(str, {face, size}) \u00B7 S.clip(poly, normal, point)\n  Finish with: return S.render();   3D text uses the brand's display face (an item lists others in \"faces3d\").\n\nMaps (Natural Earth, 177 countries). Call one and the library comes with your program:\n  worldFind(\"India\" | \"UK\" | \"USA\" | 356) \u2192 {name, id, c: [lon, lat], rings}\n  const m = worldMap($, { x, y, w, h, center: [lon, lat], zoom });  m.path(country | name) \u2192 path data \u00B7 m.project(lon, lat) \u2192 [x, y]\n        m.countries \u00B7 m.outline (the map's edge) \u00B7 m.clipId() (clip to it) \u00B7 m.ring(points)\n  worldGlobe(S, { r, spin, tilt, colorOf: (country) => colour }) countries on a 3D globe \u00B7 worldOnSphere(lon, lat, r, spin, tilt) \u2192 a 3D point";
+/** Sound design: what a program may return from sound($), and what --sound does to a graphic that returns none. */
+declare const SOUND_GUIDE = "Sound: every graphic can carry its own\n\nA render with --sound (API: sound: true, MCP: sound) gets a stereo track synthesised by Volito itself \u2014 no\nsamples, no files to find \u2014 muxed into the .mp4 / .mov / .webm (PNG frames and GIF carry none; --sound-out\nfile.wav writes the track alone, for an editor's timeline). Two sources, both deterministic:\n\n  1. The graphic's own motion. Every part's move leaves a mark the sound design reads: a spring pops, a move\n     across the frame whooshes (louder the further it travels), a slam hits, letters tick, a typewriter types,\n     a glitch zaps, a burst sparkles. Items nobody wrote sound for sound right out of the box.\n  2. A program's sound($). Beside frame(t, $) a program may define\n\n       function sound($) {\n         return {\n           cues: [\n             { at: 0.2, kind: \"riser\", dur: 1.1 },               // seconds into the clip; -1 counts from the end\n             { at: $.beat(\"in\", 1.3), kind: \"hit\", level: 1.1 },  // lands with the motion: use the same times\n             { at: 1.5, kind: \"shimmer\", dur: 1.2, pan: 0.3 },\n             { at: 2.0, kind: \"ding\", note: \"A5\", level: 0.6 },\n           ],\n           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)\n           auto: false,      // true adds the cues read from the motion on top (the default only when no cues are given)\n           level: 1,         // master, 0\u20132\n           room: 0.25,       // the reverb, 0 dry \u2026 1 wet\n         };\n       }\n\n     It runs once with $ at t = 0, so $.dur, $.beat(name), $.at(word), $.data and $.words are all there \u2014 time\n     the sound off the same beats the picture uses. Returning just an array of cues is fine too.\n\nCues: { at, kind, dur, level (0\u20132, 1 = the kind's own), pitch (semitones), note (\"A4\", tone/chord/ding), pan (-1\u20261), seed }\nKinds: whoosh (air past, dur .45) \u00B7 hit (impact) \u00B7 stamp (heavy slam) \u00B7 pop (bubble) \u00B7 tick (tiny click) \u00B7 click (UI)\n       riser (climbs into a moment, dur 1) \u00B7 fall (downlifter, dur .8) \u00B7 sub (low drop) \u00B7 shimmer (sparkle, dur 1.2)\n       ding (bell) \u00B7 swell (soft air, dur .8) \u00B7 zap (glitch, dur .28) \u00B7 type (keys for dur) \u00B7 scratch (pencil for dur)\n       tone (a note for dur) \u00B7 chord (the bed's chord for dur)\nThe bed steps back under every hit, stamp, sub and pop and comes back on its own. Keep a graphic's sound honest:\none riser into its biggest moment, a hit or a sub when it lands, ticks for the small things, silence between.\n\nCLI   volito render <item> --sound [--bed Dm] [--sound-level 1.2] [--sound-out track.wav]\n      volito sound <item> --out track.wav     the track alone, with its cue list\nAPI   renderVideo(item, { sound: true, bed: \"Dm\" })  \u00B7  renderSoundFile(item, { out: \"track.wav\" })";
 /** How Volito items and packs are written — what `volito guide` and the MCP motion_api tool print after the API. */
 declare const AUTHORING_GUIDE = "Writing Volito graphics\n\nA graphic is a program: plain JavaScript that defines function frame(t, $) and returns the SVG markup of\none frame (no <svg> root). It is a pure function of t \u2014 any frame can be drawn alone, in any order \u2014 so it\nrenders the same in MONARC PRO, in a browser and from this CLI.\n\nProps and moments\n  An item's props arrive as $.data (const p = $.data; p.name, p.role \u2026). Never hard-code text a creator\n  would change: make it a prop with a default and a maxLength the design can hold.\n  Named moments come from $.beat(name, fallback). Pack items read \"in\" (when the entrance starts) and\n  \"out\" (when the exit starts) so a creator can move them: --beat in=0.4 --beat out=-0.6.\n  When words are given (a transcript), land each element 0.04\u20130.12 s before the word that says it:\n  $.words.length ? $.atOr(firstWord, fallback) : fallback. Without words, use the beats.\n\nParts\n  Draw each element through the motion kit (const M = motion($, t)) as a named part, with the item's own\n  motion as defaults: M.part(\"plate\", { at, in: \"wipe\", box }, markup), M.text(\"name\", { ...font, at, in: \"rise\" }, text).\n  List the parts in item.json (\"parts\": { \"plate\": \"the card\" }) so creators know what they can move.\n  Backgrounds (scrims, panels) pass vary: false so a mood leaves them still.\n\nShape of a good item\n  - Enter in the first ~0.8 s, hold, leave in the last ~0.4 s (or hold to the end when out \u2265 duration).\n  - 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.\n  - Keep text inside the title-safe area: ~5% of the width at the sides on 16:9; on 9:16 leave ~13% at the\n    top and ~22% at the bottom for platform UI (captions, buttons).\n  - Size text to fit: measure it ($.measure) and shrink the size until it fits the box it owns; wrap long\n    text with maxW. The check reports any line that runs off the frame.\n  - Colour comes from the brand: $.c.bg / $.c.fg for ground and text, $.c.accent for the one thing that\n    matters, $.c.accent2 for markers, $.c.surface for cards. Faces from $.font(\"display\" | \"text\" | \"mono\").\n    $.case(str) applies the brand's case. Never invent colours \u2014 a creator's DESIGN.md re-skins the item.\n  - overlay items draw nothing behind themselves (footage shows through); put a $.scrim under text that sits\n    on footage. full items draw their own ground with $.panel(t, { box: { x: 0, y: 0, w: $.W, h: $.H } }).\n  - Escape any text you put in raw markup with $.esc(); $.text, $.chip and friends escape for you.\n\nAn item on disk\n  my-item/item.json   { \"id\": \"my-item\", \"name\": \"\u2026\", \"description\": \"\u2026\", \"category\": \"title\",\n                        \"placement\": \"overlay\" | \"full\", \"duration\": { \"default\": 5, \"min\": 2, \"max\": 20 },\n                        \"aspects\": [\"16:9\", \"9:16\", \"1:1\", \"4:5\"],\n                        \"props\": { \"title\": { \"type\": \"text\", \"default\": \"Hello\", \"maxLength\": 28 } },\n                        \"beats\": { \"in\": 0.15, \"out\": -0.45 } }\n  my-item/frame.js    function frame(t, $) { const p = $.data; \u2026 return svg; }\n  Prop types: text, longtext (line breaks kept), number (min, max, step), boolean, choice (options),\n  color (#hex, \"\" = the brand's), list (rows of text, or of {field: \"text\" | \"number\"}; maxItems),\n  image (a path or URL the caller loads; draw it with $.image(propName, x, y, w, h)), icon (an icon name).\n\nA pack\n  my-pack/pack.json   { \"format\": 1, \"id\": \"my-pack\", \"name\": \"\u2026\", \"version\": \"1.0.0\", \"description\": \"\u2026\",\n                        \"author\": \"\u2026\", \"license\": \"\u2026\", \"style\": \"ember\", \"shared\": \"shared.js\",\n                        \"items\": [\"my-item\", \u2026] }\n  my-pack/shared.js   helpers prepended to every item's code (function declarations only).\n  Load extra packs with --packs <dir> or VOLITO_PACKS=<dir>.\n\nThe loop\n  volito new my-item          a template to start from\n  volito check ./my-item      errors and warnings at every aspect\n  volito sheet ./my-item      frames across time in one PNG \u2014 look at it\n  volito render ./my-item --format mov\n  Agents: motion_check, then motion_preview, fix what you see, then motion_render.";
 
-export { ASPECTS, ASPECT_NAMES, AUTHORING_GUIDE, BUILTIN_STYLES, CATEGORIES, DIRECTIONS, EASES, EDITOR_STYLES, FORMAT_NOTES, FfmpegMissing, HITS, IDLES, LIBRARY_GUIDE, MG_API_REFERENCE, MG_ICON_NAMES, MG_SPRITE_NAMES, MOODS, MOTION_FORMAT, MOTION_GUIDE, MOVES, MOVE_NOTES, MotionError, ORDERS, ORIGINS, PATTERN_NAMES, PATTERN_WORDS, ProgramError, ProgramRunner, SPLITS, VIDEO_FORMATS, buildProgram, builtinPacks, canvasFor, checkItem, composeDesignMd, customItem, defaultOutput, describeItem, describeReport, findItem, fontsDir, formatFromPath, frameDocument, library, loadImage, loadMedia, loadPack, makeItem, manifestProblems, normalizeMotion, normalizeWords, openSession, packageVersion, packsIn, parseAspect, parseDesignMd, parseMotionArgs, probeFfmpeg, readStyleArg, readWords, renderSheet, renderStill, renderVideo, resolveProps, resolveStyle, searchItems, sheetTimes };
-export type { Aspect, AspectReport, BuildOptions, BuiltProgram, Category, CheckReport, ItemManifest, ItemQuery, Library, MotionConfig, MotionInput, MotionItem, MotionOverrides, MotionPack, MotionSpec, PackManifest, PatternName, Placement, PropSpec, PropType, RenderOptions, StillFormat, StillResult, StyleInput, StyleOverrides, VideoFormat, VideoResult };
+export { ASPECTS, ASPECT_NAMES, AUTHORING_GUIDE, BUILTIN_STYLES, CATEGORIES, DIRECTIONS, EASES, EDITOR_STYLES, FORMAT_NOTES, FfmpegMissing, GraphicSpecSchema, HITS, IDLES, LIBRARY_GUIDE, MG_API_REFERENCE, MG_ICON_NAMES, MG_SPRITE_NAMES, MOODS, MOTION_FORMAT, MOTION_GUIDE, MOVES, MOVE_NOTES, MotionError, ORDERS, ORIGINS, PATTERN_NAMES, PATTERN_WORDS, ProgramError, ProgramRunner, SOUND_GUIDE, SOUND_KINDS, SOUND_NOTES, SPEC_SCHEMA_URL, SPEC_VERSION, SPLITS, VIDEO_FORMATS, bedOf, buildProgram, builtinPacks, canvasFor, checkItem, composeDesignMd, cuesFromMarks, customItem, defaultOutput, describeCues, describeItem, describeReport, designSound, findItem, fontsDir, formatFromPath, frameDocument, isSpecFile, itemOfSpec, library, loadImage, loadMedia, loadPack, loadSpecFile, makeItem, manifestProblems, normalizeMotion, normalizeSoundSpec, normalizeWords, noteHz, openSession, packageVersion, packsIn, parseAspect, parseDesignMd, parseKey, parseMotionArgs, parseSpec, probeFfmpeg, readStyleArg, readWords, renderSheet, renderSound, renderSoundFile, renderStill, renderVideo, resolveProps, resolveStyle, searchItems, sheetTimes, soundHookAvailable, specFrom, specJsonSchema, specToOptions, validateSpec, wavEncode };
+export type { Aspect, AspectReport, BuildOptions, BuiltProgram, Category, CheckReport, GraphicSpec, ItemManifest, ItemQuery, Library, LoadedSpec, MotionConfig, MotionInput, MotionItem, MotionOverrides, MotionPack, MotionSpec, PackManifest, PatternName, Placement, PropSpec, PropType, RenderOptions, RenderedSound, SoundBed, SoundCue, SoundKind, SoundResult, SoundSpec, SpecIssue, SpecReport, StillFormat, StillResult, StyleInput, StyleOverrides, TraceMark, VideoFormat, VideoResult };

package/dist/index.js

@@ -1,23 +1,47 @@
+import {
+  AUTHORING_GUIDE,
+  GraphicSpecSchema,
+  LIBRARY_GUIDE,
+  MOTION_GUIDE,
+  SOUND_GUIDE,
+  SPEC_SCHEMA_URL,
+  SPEC_VERSION,
+  builtinPacks,
+  findItem,
+  isSpecFile,
+  itemOfSpec,
+  library,
+  loadImage,
+  loadMedia,
+  loadPack,
+  loadSpecFile,
+  normalizeWords,
+  packsIn,
+  parseSpec,
+  readStyleArg,
+  readWords,
+  searchItems,
+  specFrom,
+  specJsonSchema,
+  specToOptions,
+  validateSpec
+} from "./chunks/chunk-QA4SEJCZ.js";
 import {
   ASPECTS,
   ASPECT_NAMES,
-  AUTHORING_GUIDE,
   BUILTIN_STYLES,
   CATEGORIES,
   DIRECTIONS,
   EASES,
   EDITOR_STYLES,
   FORMAT_NOTES,
-  FfmpegMissing,
   HITS,
   IDLES,
-  LIBRARY_GUIDE,
   MG_API_REFERENCE,
   MG_ICON_NAMES,
   MG_SPRITE_NAMES,
   MOODS,
   MOTION_FORMAT,
-  MOTION_GUIDE,
   MOVES,
   MOVE_NOTES,
   MotionError,
@@ -27,46 +51,51 @@ import {
   PATTERN_WORDS,
   ProgramError,
   ProgramRunner,
+  SOUND_KINDS,
+  SOUND_NOTES,
   SPLITS,
   VIDEO_FORMATS,
+  bedOf,
   buildProgram,
-  builtinPacks,
   canvasFor,
   checkItem,
   composeDesignMd,
+  cuesFromMarks,
   customItem,
   defaultOutput,
+  describeCues,
   describeItem,
   describeReport,
-  findItem,
-  fontsDir,
+  designSound,
   formatFromPath,
   frameDocument,
-  library,
-  loadImage,
-  loadMedia,
-  loadPack,
   makeItem,
   manifestProblems,
   normalizeMotion,
-  normalizeWords,
+  normalizeSoundSpec,
+  noteHz,
   openSession,
-  packageVersion,
-  packsIn,
   parseAspect,
   parseDesignMd,
+  parseKey,
   parseMotionArgs,
-  probeFfmpeg,
-  readStyleArg,
-  readWords,
   renderSheet,
+  renderSound,
+  renderSoundFile,
   renderStill,
   renderVideo,
   resolveProps,
   resolveStyle,
-  searchItems,
-  sheetTimes
-} from "./chunks/chunk-CFDFWZAC.js";
+  sheetTimes,
+  soundHookAvailable,
+  wavEncode
+} from "./chunks/chunk-CUQY6YI3.js";
+import {
+  FfmpegMissing,
+  fontsDir,
+  packageVersion,
+  probeFfmpeg
+} from "./chunks/chunk-ZFG3X3DU.js";
 export {
   ASPECTS,
   ASPECT_NAMES,
@@ -78,6 +107,7 @@ export {
   EDITOR_STYLES,
   FORMAT_NOTES,
   FfmpegMissing,
+  GraphicSpecSchema,
   HITS,
   IDLES,
   LIBRARY_GUIDE,
@@ -96,43 +126,67 @@ export {
   PATTERN_WORDS,
   ProgramError,
   ProgramRunner,
+  SOUND_GUIDE,
+  SOUND_KINDS,
+  SOUND_NOTES,
+  SPEC_SCHEMA_URL,
+  SPEC_VERSION,
   SPLITS,
   VIDEO_FORMATS,
+  bedOf,
   buildProgram,
   builtinPacks,
   canvasFor,
   checkItem,
   composeDesignMd,
+  cuesFromMarks,
   customItem,
   defaultOutput,
+  describeCues,
   describeItem,
   describeReport,
+  designSound,
   findItem,
   fontsDir,
   formatFromPath,
   frameDocument,
+  isSpecFile,
+  itemOfSpec,
   library,
   loadImage,
   loadMedia,
   loadPack,
+  loadSpecFile,
   makeItem,
   manifestProblems,
   normalizeMotion,
+  normalizeSoundSpec,
   normalizeWords,
+  noteHz,
   openSession,
   packageVersion,
   packsIn,
   parseAspect,
   parseDesignMd,
+  parseKey,
   parseMotionArgs,
+  parseSpec,
   probeFfmpeg,
   readStyleArg,
   readWords,
   renderSheet,
+  renderSound,
+  renderSoundFile,
   renderStill,
   renderVideo,
   resolveProps,
   resolveStyle,
   searchItems,
-  sheetTimes
+  sheetTimes,
+  soundHookAvailable,
+  specFrom,
+  specJsonSchema,
+  specToOptions,
+  validateSpec,
+  wavEncode
 };