@depths/waves 0.1.0 → 0.3.0

package/dist/cli.mjs

@@ -3,15 +3,15 @@ import {
   WavesEngine,
   __wavesVersion,
   getPromptPayload
-} from "./chunk-WGQITADJ.mjs";
+} from "./chunk-QP54QRAP.mjs";
 import {
-  VideoIRSchema,
+  VideoIRv2AuthoringSchema,
   WavesRenderError,
   __require,
   globalRegistry,
   registerBuiltInComponents,
   zodSchemaToJsonSchema
-} from "./chunk-TGAL5RQN.mjs";
+} from "./chunk-YYS6AVTN.mjs";
 
 // src/cli.ts
 import fs from "fs/promises";
@@ -42,7 +42,7 @@ function parseArgs(argv) {
       const hasInlineValue = eq >= 0;
       const inlineValue = hasInlineValue ? arg.slice(eq + 1) : void 0;
       const next = argv[i + 1];
-      const isBoolean = key === "help" || key === "pretty";
+      const isBoolean = key === "help" || key === "pretty" || key === "includeInternal" || key === "debugBounds" || key === "debugLabels";
       if (isBoolean) {
         flags[key] = true;
         continue;
@@ -81,11 +81,13 @@ Usage:
   waves <command> [options]
 
 Commands:
+  catalog     Print the built-in component catalog
   prompt      Print an agent-ready system prompt + schema payload
   schema      Print JSON Schemas for IR/components
   write-ir    Write a starter IR JSON file
   validate    Validate an IR JSON file
   render      Render MP4 from an IR JSON file
+  stills      Render PNG/JPEG/WebP still frames from an IR JSON file
 
 Options:
   -h, --help       Show help
@@ -122,21 +124,9 @@ async function importRegistrationModules(modules) {
 function stringifyJSON(value, pretty) {
   return JSON.stringify(value, null, pretty ? 2 : 0) + "\n";
 }
-function collectComponentTypes(ir) {
-  const types = /* @__PURE__ */ new Set();
-  for (const scene of ir.scenes) {
-    walkComponent(scene, types);
-  }
-  return types;
-}
-function walkComponent(component, types) {
-  types.add(component.type);
-  const children = component.children;
-  if (children?.length) {
-    for (const child of children) {
-      walkComponent(child, types);
-    }
-  }
+function parseImageFormat(raw) {
+  if (raw === "png" || raw === "jpeg" || raw === "webp") return raw;
+  return null;
 }
 async function main(argv = process.argv.slice(2)) {
   const parsed = parseArgs(argv);
@@ -165,6 +155,66 @@ async function main(argv = process.argv.slice(2)) {
     return EXIT_USAGE;
   }
   registerBuiltInComponents();
+  if (parsed.command === "catalog") {
+    const format = (getFlagString(parsed.flags, "format") ?? "text").toLowerCase();
+    const includeInternal = Boolean(parsed.flags.includeInternal);
+    if (format !== "text" && format !== "json") {
+      process.stderr.write(`Invalid --format: ${format} (expected "text" or "json")
+`);
+      return EXIT_USAGE;
+    }
+    const types = includeInternal ? globalRegistry.getTypes().sort() : globalRegistry.getTypesForLLM().sort();
+    const byCategory = {};
+    const items = [];
+    for (const t of types) {
+      const reg = globalRegistry.get(t);
+      if (!reg) continue;
+      const cat = reg.metadata.category;
+      if (!byCategory[cat]) byCategory[cat] = [];
+      byCategory[cat].push(t);
+      items.push({ type: t, kind: reg.metadata.kind, category: cat, description: reg.metadata.description });
+    }
+    if (format === "json") {
+      const payload = { categories: byCategory, items };
+      const json = stringifyJSON(payload, pretty);
+      const writeErr2 = await tryWriteOut(outPath, json);
+      if (writeErr2) {
+        process.stderr.write(`Failed to write ${outPath}: ${writeErr2}
+`);
+        process.stdout.write(json);
+        return EXIT_IO;
+      }
+      process.stdout.write(json);
+      if (outPath) process.stderr.write(`Wrote ${outPath}
+`);
+      return EXIT_OK;
+    }
+    const categories = Object.keys(byCategory).sort();
+    const lines = [];
+    lines.push(`waves catalog (v${__wavesVersion})`);
+    lines.push("");
+    for (const c of categories) {
+      lines.push(`${c}:`);
+      for (const t of byCategory[c].sort()) {
+        lines.push(`- ${t}`);
+      }
+      lines.push("");
+    }
+    const text = lines.join("\n");
+    const writeErr = await tryWriteOut(outPath, text.endsWith("\n") ? text : `${text}
+`);
+    if (writeErr) {
+      process.stderr.write(`Failed to write ${outPath}: ${writeErr}
+`);
+      process.stdout.write(text);
+      return EXIT_IO;
+    }
+    process.stdout.write(text.endsWith("\n") ? text : `${text}
+`);
+    if (outPath) process.stderr.write(`Wrote ${outPath}
+`);
+    return EXIT_OK;
+  }
   if (parsed.command === "prompt") {
     const format = (getFlagString(parsed.flags, "format") ?? "text").toLowerCase();
     const maxCharsRaw = getFlagString(parsed.flags, "maxChars");
@@ -208,12 +258,12 @@ async function main(argv = process.argv.slice(2)) {
     const kind = (getFlagString(parsed.flags, "kind") ?? "all").toLowerCase();
     let output;
     if (kind === "video-ir") {
-      output = zodSchemaToJsonSchema(VideoIRSchema);
+      output = zodSchemaToJsonSchema(VideoIRv2AuthoringSchema);
     } else if (kind === "components") {
       output = globalRegistry.getJSONSchemaForLLM();
     } else if (kind === "all") {
       output = {
-        videoIR: zodSchemaToJsonSchema(VideoIRSchema),
+        videoIR: zodSchemaToJsonSchema(VideoIRv2AuthoringSchema),
         components: globalRegistry.getJSONSchemaForLLM()
       };
     } else {
@@ -242,33 +292,75 @@ async function main(argv = process.argv.slice(2)) {
       return EXIT_USAGE;
     }
     const ir = template === "basic" ? {
-      version: "1.0",
-      video: { id: "main", width: 1920, height: 1080, fps: 30, durationInFrames: 90 },
-      scenes: [
+      version: "2.0",
+      video: { id: "main", width: 1920, height: 1080, fps: 30, durationInFrames: 165 },
+      segments: [
         {
           id: "scene-1",
-          type: "Scene",
-          timing: { from: 0, durationInFrames: 90 },
-          props: { background: { type: "color", value: "#000000" } },
-          children: [
-            {
-              id: "title",
-              type: "Text",
-              timing: { from: 0, durationInFrames: 90 },
-              props: { content: "Hello Waves", fontSize: 72, animation: "fade" }
-            }
-          ]
+          durationInFrames: 90,
+          transitionToNext: { type: "FadeTransition", durationInFrames: 15 },
+          root: {
+            id: "root",
+            type: "Scene",
+            props: { background: { type: "color", value: "#000000" } },
+            children: [
+              {
+                id: "title",
+                type: "SplitText",
+                props: { content: "Waves v0.2.0", fontSize: 96, splitBy: "word", stagger: 3, animation: "slideUp" }
+              },
+              {
+                id: "subtitle",
+                type: "TypewriterText",
+                props: { content: "Composite components + hybrid IR", fontSize: 48, position: "bottom", speed: 1.5 }
+              },
+              {
+                id: "wm",
+                type: "Watermark",
+                props: { type: "text", text: "@depths.ai", position: "bottomRight", opacity: 0.4, size: 60 }
+              }
+            ]
+          }
+        },
+        {
+          id: "scene-2",
+          durationInFrames: 90,
+          root: {
+            id: "root-2",
+            type: "Scene",
+            props: { background: { type: "color", value: "#0B1220" } },
+            children: [
+              {
+                id: "lower-third",
+                type: "ThirdLowerBanner",
+                props: { name: "Waves", title: "v0.2.0 \u2014 Composites + transitions", accentColor: "#3B82F6" }
+              },
+              {
+                id: "count",
+                type: "AnimatedCounter",
+                props: { from: 0, to: 35, suffix: " components", fontSize: 96, color: "#FFFFFF" }
+              },
+              {
+                id: "wm-2",
+                type: "Watermark",
+                props: { type: "text", text: "waves", position: "topLeft", opacity: 0.25, size: 52 }
+              }
+            ]
+          }
         }
       ]
     } : template === "minimal" ? {
-      version: "1.0",
+      version: "2.0",
       video: { id: "main", width: 1920, height: 1080, fps: 30, durationInFrames: 60 },
-      scenes: [
+      segments: [
         {
           id: "scene-1",
-          type: "Scene",
-          timing: { from: 0, durationInFrames: 60 },
-          props: { background: { type: "color", value: "#000000" } }
+          durationInFrames: 60,
+          root: {
+            id: "root",
+            type: "Scene",
+            props: { background: { type: "color", value: "#000000" } }
+          }
         }
       ]
     } : null;
@@ -277,9 +369,9 @@ async function main(argv = process.argv.slice(2)) {
 `);
       return EXIT_USAGE;
     }
-    const schemaCheck = VideoIRSchema.safeParse(ir);
+    const schemaCheck = VideoIRv2AuthoringSchema.safeParse(ir);
     if (!schemaCheck.success) {
-      process.stderr.write("Internal error: generated template does not validate against VideoIRSchema\n");
+      process.stderr.write("Internal error: generated template does not validate against VideoIRv2AuthoringSchema\n");
       return EXIT_INTERNAL;
     }
     const json = stringifyJSON(ir, pretty);
@@ -333,20 +425,9 @@ async function main(argv = process.argv.slice(2)) {
       }
       return EXIT_VALIDATE;
     }
-    const validator = new IRValidator();
+    const validator = new IRValidator(globalRegistry);
     const result = validator.validate(json);
     const errors = result.success ? [] : result.errors;
-    if (result.success) {
-      const types = collectComponentTypes(result.data);
-      const unknownTypes = [...types].filter((t) => !globalRegistry.has(t)).sort();
-      for (const t of unknownTypes) {
-        errors.push({
-          path: ["components", t],
-          message: `Unknown component type: ${t}`,
-          code: "UNKNOWN_COMPONENT_TYPE"
-        });
-      }
-    }
     const ok = errors.length === 0;
     if (format === "json") {
       process.stdout.write(stringifyJSON(ok ? { success: true } : { success: false, errors }, pretty));
@@ -396,15 +477,19 @@ async function main(argv = process.argv.slice(2)) {
     const crfRaw = getFlagString(parsed.flags, "crf");
     const concurrencyRaw = getFlagString(parsed.flags, "concurrency");
     const publicDir = getFlagString(parsed.flags, "publicDir");
+    const debugBounds = Boolean(parsed.flags.debugBounds);
+    const debugLabels = Boolean(parsed.flags.debugLabels);
     const crf = crfRaw ? Number(crfRaw) : void 0;
     const concurrency = concurrencyRaw ? /^[0-9]+$/.test(concurrencyRaw) ? Number(concurrencyRaw) : concurrencyRaw : void 0;
-    const engine = new WavesEngine(globalRegistry, new IRValidator());
+    const engine = new WavesEngine(globalRegistry, new IRValidator(globalRegistry));
     try {
+      const inputProps = debugBounds || debugLabels ? { __wavesDebugBounds: debugBounds, __wavesDebugLabels: debugLabels } : void 0;
       const opts = { outputPath, registrationModules };
       if (publicDir) opts.publicDir = publicDir;
       if (codec) opts.codec = codec;
       if (Number.isFinite(crf ?? Number.NaN)) opts.crf = crf;
       if (concurrency !== void 0) opts.concurrency = concurrency;
+      if (inputProps) opts.inputProps = inputProps;
       await engine.render(json, opts);
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
@@ -419,6 +504,84 @@ async function main(argv = process.argv.slice(2)) {
 `);
     return EXIT_OK;
   }
+  if (parsed.command === "stills") {
+    const inputPath = getFlagString(parsed.flags, "in");
+    const outDir = getFlagString(parsed.flags, "outDir") ?? getFlagString(parsed.flags, "out");
+    if (!inputPath) {
+      process.stderr.write("Missing required --in <path>\n");
+      return EXIT_USAGE;
+    }
+    if (!outDir) {
+      process.stderr.write("Missing required --outDir <dir>\n");
+      return EXIT_USAGE;
+    }
+    let raw;
+    try {
+      raw = await fs.readFile(inputPath, "utf-8");
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      process.stderr.write(`Failed to read ${inputPath}: ${message}
+`);
+      return EXIT_IO;
+    }
+    let json;
+    try {
+      json = JSON.parse(raw);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      process.stderr.write(`Invalid JSON: ${message}
+`);
+      return EXIT_VALIDATE;
+    }
+    const framesRaw = getFlagString(parsed.flags, "frames") ?? "0";
+    const frames = framesRaw.split(/[,\s]+/g).map((v) => v.trim()).filter(Boolean).map((v) => Number(v)).filter((n) => Number.isFinite(n));
+    if (frames.length === 0) {
+      process.stderr.write('Invalid --frames (expected comma-separated frame numbers, e.g. "0,30,60")\n');
+      return EXIT_USAGE;
+    }
+    const imageFormatRaw = (getFlagString(parsed.flags, "imageFormat") ?? "png").toLowerCase();
+    const imageFormat = parseImageFormat(imageFormatRaw);
+    if (!imageFormat) {
+      process.stderr.write(`Invalid --imageFormat: ${imageFormatRaw} (expected png|jpeg|webp)
+`);
+      return EXIT_USAGE;
+    }
+    const scaleRaw = getFlagString(parsed.flags, "scale");
+    const jpegQualityRaw = getFlagString(parsed.flags, "jpegQuality");
+    const publicDir = getFlagString(parsed.flags, "publicDir");
+    const debugBounds = Boolean(parsed.flags.debugBounds);
+    const debugLabels = Boolean(parsed.flags.debugLabels);
+    const scale = scaleRaw ? Number(scaleRaw) : void 0;
+    const jpegQuality = jpegQualityRaw ? Number(jpegQualityRaw) : void 0;
+    const engine = new WavesEngine(globalRegistry, new IRValidator(globalRegistry));
+    try {
+      const inputProps = debugBounds || debugLabels ? { __wavesDebugBounds: debugBounds, __wavesDebugLabels: debugLabels } : void 0;
+      const opts = {
+        outputDir: outDir,
+        frames,
+        imageFormat,
+        registrationModules
+      };
+      if (publicDir) opts.publicDir = publicDir;
+      if (Number.isFinite(scale ?? Number.NaN)) opts.scale = scale;
+      if (Number.isFinite(jpegQuality ?? Number.NaN)) opts.jpegQuality = jpegQuality;
+      if (inputProps) opts.inputProps = inputProps;
+      const written = await engine.renderStills(json, opts);
+      for (const p of written) {
+        process.stderr.write(`Wrote ${p}
+`);
+      }
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      const context = err instanceof WavesRenderError ? err.context : void 0;
+      const payload = context ? stringifyJSON({ error: message, context }, pretty) : null;
+      process.stderr.write(`stills failed: ${message}
+`);
+      if (payload) process.stderr.write(payload);
+      return EXIT_RENDER;
+    }
+    return EXIT_OK;
+  }
   process.stderr.write(`Unknown command: ${parsed.command}
 `);
   process.stderr.write(`Run: waves --help

package/dist/index.d.mts

@@ -1,36 +1,41 @@
-import { V as VideoIR, C as ComponentRegistry } from './registry-hVIyqwS6.mjs';
-export { A as AssetPathSchema, a as AudioComponentIRSchema, b as AudioIR, B as BackgroundSpec, c as BackgroundSpecSchema, d as BaseComponentIR, e as BaseComponentIRSchema, f as ComponentIR, g as ComponentIRSchema, h as ComponentSchemas, S as SceneComponentIRSchema, i as SceneIR, T as TextComponentIRSchema, j as TextIR, k as TimingSpec, l as TimingSpecSchema, m as VideoIRSchema, n as globalRegistry, r as registerBuiltInComponents } from './registry-hVIyqwS6.mjs';
+import { C as ComponentRegistry, V as VideoIRv2, a as CompiledVideoIR, b as ComponentKind, c as ComponentCategory } from './registry-C6H9G0df.mjs';
+export { A as AssetPathSchema, B as BackgroundSpec, d as BackgroundSpecSchema, e as ComponentNode, f as ComponentNodeSchema, T as TimingSpec, g as TimingSpecSchema, h as TransitionSpec, i as TransitionSpecSchema, j as VideoIR, k as VideoIRSchema, l as VideoIRv2AuthoringSchema, m as VideoIRv2Schema, n as globalRegistry, r as registerBuiltInComponents } from './registry-C6H9G0df.mjs';
 import 'zod';
 import 'react';
 
-declare const __wavesVersion = "0.1.0";
+declare const __wavesVersion = "0.2.0";
 
 interface ValidationError {
     path: string[];
     message: string;
     code: string;
 }
-interface ValidationResult {
-    success: boolean;
-    errors?: ValidationError[];
-}
 declare class IRValidator {
+    private readonly registry?;
+    constructor(registry?: ComponentRegistry | undefined);
     validateSchema(ir: unknown): {
         success: true;
-        data: VideoIR;
+        data: VideoIRv2;
+    } | {
+        success: false;
+        errors: ValidationError[];
+    };
+    validateSemantics(latest: VideoIRv2): {
+        success: true;
+        data: CompiledVideoIR;
     } | {
         success: false;
         errors: ValidationError[];
     };
-    validateSemantics(ir: VideoIR): ValidationResult;
     validate(ir: unknown): {
         success: true;
-        data: VideoIR;
+        data: CompiledVideoIR;
     } | {
         success: false;
         errors: ValidationError[];
     };
     private validateComponentTimingRecursive;
+    private validateRegistryContracts;
 }
 
 interface RenderOptions {
@@ -41,12 +46,25 @@ interface RenderOptions {
     publicDir?: string;
     rootDir?: string;
     registrationModules?: string[];
+    inputProps?: Record<string, unknown>;
+}
+interface RenderStillsOptions {
+    outputDir: string;
+    frames: number[];
+    imageFormat?: 'png' | 'jpeg' | 'webp';
+    jpegQuality?: number;
+    scale?: number;
+    publicDir?: string;
+    rootDir?: string;
+    registrationModules?: string[];
+    inputProps?: Record<string, unknown>;
 }
 declare class WavesEngine {
     private readonly registry;
     private readonly validator;
     constructor(registry: ComponentRegistry, validator: IRValidator);
     render(ir: unknown, options: RenderOptions): Promise<void>;
+    renderStills(ir: unknown, options: RenderStillsOptions): Promise<string[]>;
 }
 
 declare class WavesError extends Error {
@@ -63,8 +81,18 @@ declare class WavesRenderError extends WavesError {
 type PromptPayload = {
     package: '@depths/waves';
     version: string;
-    irVersion: '1.0';
+    irVersion: '2.0';
     systemPrompt: string;
+    catalog: {
+        categories: Record<string, string[]>;
+        items: Array<{
+            type: string;
+            kind: ComponentKind;
+            category: ComponentCategory;
+            description: string;
+            llmGuidance?: string;
+        }>;
+    };
     schemas: {
         videoIR: Record<string, unknown>;
         components: Record<string, unknown>;
@@ -86,4 +114,4 @@ declare function renderVideo(ir: unknown, options: {
     publicDir?: string;
 }): Promise<void>;
 
-export { ComponentRegistry, IRValidator, type PromptPayload, VideoIR, WavesEngine, WavesError, WavesRenderError, WavesValidationError, __wavesVersion, getPromptPayload, getSystemPrompt, renderVideo };
+export { ComponentRegistry, IRValidator, type PromptPayload, VideoIRv2, WavesEngine, WavesError, WavesRenderError, WavesValidationError, __wavesVersion, getPromptPayload, getSystemPrompt, renderVideo };

package/dist/index.d.ts

@@ -1,36 +1,41 @@
-import { V as VideoIR, C as ComponentRegistry } from './registry-hVIyqwS6.js';
-export { A as AssetPathSchema, a as AudioComponentIRSchema, b as AudioIR, B as BackgroundSpec, c as BackgroundSpecSchema, d as BaseComponentIR, e as BaseComponentIRSchema, f as ComponentIR, g as ComponentIRSchema, h as ComponentSchemas, S as SceneComponentIRSchema, i as SceneIR, T as TextComponentIRSchema, j as TextIR, k as TimingSpec, l as TimingSpecSchema, m as VideoIRSchema, n as globalRegistry, r as registerBuiltInComponents } from './registry-hVIyqwS6.js';
+import { C as ComponentRegistry, V as VideoIRv2, a as CompiledVideoIR, b as ComponentKind, c as ComponentCategory } from './registry-C6H9G0df.js';
+export { A as AssetPathSchema, B as BackgroundSpec, d as BackgroundSpecSchema, e as ComponentNode, f as ComponentNodeSchema, T as TimingSpec, g as TimingSpecSchema, h as TransitionSpec, i as TransitionSpecSchema, j as VideoIR, k as VideoIRSchema, l as VideoIRv2AuthoringSchema, m as VideoIRv2Schema, n as globalRegistry, r as registerBuiltInComponents } from './registry-C6H9G0df.js';
 import 'zod';
 import 'react';
 
-declare const __wavesVersion = "0.1.0";
+declare const __wavesVersion = "0.2.0";
 
 interface ValidationError {
     path: string[];
     message: string;
     code: string;
 }
-interface ValidationResult {
-    success: boolean;
-    errors?: ValidationError[];
-}
 declare class IRValidator {
+    private readonly registry?;
+    constructor(registry?: ComponentRegistry | undefined);
     validateSchema(ir: unknown): {
         success: true;
-        data: VideoIR;
+        data: VideoIRv2;
+    } | {
+        success: false;
+        errors: ValidationError[];
+    };
+    validateSemantics(latest: VideoIRv2): {
+        success: true;
+        data: CompiledVideoIR;
     } | {
         success: false;
         errors: ValidationError[];
     };
-    validateSemantics(ir: VideoIR): ValidationResult;
     validate(ir: unknown): {
         success: true;
-        data: VideoIR;
+        data: CompiledVideoIR;
     } | {
         success: false;
         errors: ValidationError[];
     };
     private validateComponentTimingRecursive;
+    private validateRegistryContracts;
 }
 
 interface RenderOptions {
@@ -41,12 +46,25 @@ interface RenderOptions {
     publicDir?: string;
     rootDir?: string;
     registrationModules?: string[];
+    inputProps?: Record<string, unknown>;
+}
+interface RenderStillsOptions {
+    outputDir: string;
+    frames: number[];
+    imageFormat?: 'png' | 'jpeg' | 'webp';
+    jpegQuality?: number;
+    scale?: number;
+    publicDir?: string;
+    rootDir?: string;
+    registrationModules?: string[];
+    inputProps?: Record<string, unknown>;
 }
 declare class WavesEngine {
     private readonly registry;
     private readonly validator;
     constructor(registry: ComponentRegistry, validator: IRValidator);
     render(ir: unknown, options: RenderOptions): Promise<void>;
+    renderStills(ir: unknown, options: RenderStillsOptions): Promise<string[]>;
 }
 
 declare class WavesError extends Error {
@@ -63,8 +81,18 @@ declare class WavesRenderError extends WavesError {
 type PromptPayload = {
     package: '@depths/waves';
     version: string;
-    irVersion: '1.0';
+    irVersion: '2.0';
     systemPrompt: string;
+    catalog: {
+        categories: Record<string, string[]>;
+        items: Array<{
+            type: string;
+            kind: ComponentKind;
+            category: ComponentCategory;
+            description: string;
+            llmGuidance?: string;
+        }>;
+    };
     schemas: {
         videoIR: Record<string, unknown>;
         components: Record<string, unknown>;
@@ -86,4 +114,4 @@ declare function renderVideo(ir: unknown, options: {
     publicDir?: string;
 }): Promise<void>;
 
-export { ComponentRegistry, IRValidator, type PromptPayload, VideoIR, WavesEngine, WavesError, WavesRenderError, WavesValidationError, __wavesVersion, getPromptPayload, getSystemPrompt, renderVideo };
+export { ComponentRegistry, IRValidator, type PromptPayload, VideoIRv2, WavesEngine, WavesError, WavesRenderError, WavesValidationError, __wavesVersion, getPromptPayload, getSystemPrompt, renderVideo };