@depths/waves 0.1.0 → 0.2.0

package/dist/chunk-7QPNRHMW.mjs

@@ -0,0 +1,484 @@
+import {
+  VideoIRSchema,
+  VideoIRv2AuthoringSchema,
+  VideoIRv2Schema,
+  WavesRenderError,
+  globalRegistry,
+  registerBuiltInComponents,
+  zodSchemaToJsonSchema
+} from "./chunk-PKLHVWMD.mjs";
+
+// src/version.ts
+var __wavesVersion = "0.2.0";
+
+// src/llm/prompt.ts
+var RULES = {
+  timing: [
+    "All timing is in frames (integers).",
+    'Prefer authoring using "segments" (high-level). Each segment has { durationInFrames, root } and start times are derived by order.',
+    'Use "timeline" only for advanced cases (explicit timings, overlaps).',
+    "If you provide timing on nodes, timing is { from, durationInFrames } and children timing is relative to the parent duration.",
+    "Total duration must match video.durationInFrames."
+  ],
+  assets: [
+    'Asset paths must be either full URLs (http:// or https://) or absolute public paths starting with "/".',
+    'When using absolute public paths ("/assets/..."), the renderer resolves them relative to the --publicDir passed at render time.'
+  ],
+  ids: [
+    "Every component must have a stable string id.",
+    "Ids should be unique within the whole IR."
+  ],
+  output: [
+    "Return only a single JSON object (no markdown fences, no commentary).",
+    "The JSON must validate against the provided JSON Schemas.",
+    'Only use component "type" values that exist in schemas.components.'
+  ]
+};
+function getSystemPrompt(registeredTypes) {
+  const maxInline = 40;
+  const typesLine = registeredTypes.length <= maxInline ? registeredTypes.length ? registeredTypes.join(", ") : "(none)" : `${registeredTypes.length} types (see schemas.components keys). Example: ${registeredTypes.slice(0, 20).join(", ")}, ...`;
+  return [
+    "You generate JSON for @depths/waves Video IR (version 2.0).",
+    "",
+    "Goal:",
+    "- Produce a single JSON object that conforms to the provided Video IR JSON Schema and uses only registered component types.",
+    "",
+    "Registered component types:",
+    `- ${typesLine}`,
+    "",
+    "Authoring rules:",
+    ...RULES.output.map((r) => `- ${r}`),
+    ...RULES.timing.map((r) => `- ${r}`),
+    ...RULES.assets.map((r) => `- ${r}`),
+    ...RULES.ids.map((r) => `- ${r}`),
+    "",
+    "If you are unsure about an asset, prefer a solid color Scene background and omit optional props to use defaults.",
+    ""
+  ].join("\n");
+}
+function getPromptPayload(options) {
+  registerBuiltInComponents();
+  const registry = options?.registry ?? globalRegistry;
+  const types = registry.getTypesForLLM().sort();
+  const categories = {};
+  const items = [];
+  for (const t of types) {
+    const reg = registry.get(t);
+    if (!reg) continue;
+    const cat = reg.metadata.category;
+    if (!categories[cat]) categories[cat] = [];
+    categories[cat].push(t);
+    const llmGuidance = reg.metadata.llmGuidance;
+    items.push({
+      type: t,
+      kind: reg.metadata.kind,
+      category: cat,
+      description: reg.metadata.description,
+      ...typeof llmGuidance === "string" ? { llmGuidance } : {}
+    });
+  }
+  return {
+    package: "@depths/waves",
+    version: __wavesVersion,
+    irVersion: "2.0",
+    systemPrompt: getSystemPrompt(types),
+    catalog: {
+      categories,
+      items
+    },
+    schemas: {
+      videoIR: zodSchemaToJsonSchema(VideoIRv2AuthoringSchema),
+      components: registry.getJSONSchemaForLLM()
+    },
+    rules: {
+      timing: [...RULES.timing],
+      assets: [...RULES.assets],
+      ids: [...RULES.ids],
+      output: [...RULES.output]
+    }
+  };
+}
+
+// src/ir/migrations.ts
+function fillNodeTiming(node, parentDurationInFrames) {
+  const timing = node.timing ?? { from: 0, durationInFrames: parentDurationInFrames };
+  const children = node.children?.map((c) => fillNodeTiming(c, timing.durationInFrames));
+  return {
+    id: node.id,
+    type: node.type,
+    timing,
+    props: node.props,
+    metadata: node.metadata,
+    children: children && children.length ? children : void 0
+  };
+}
+function compileToRenderGraph(v2) {
+  const parsed = VideoIRv2Schema.parse(v2);
+  if (parsed.timeline) {
+    const timeline2 = parsed.timeline.map((n) => {
+      const timing = n.timing ?? { from: 0, durationInFrames: parsed.video.durationInFrames };
+      return fillNodeTiming({ ...n, timing }, parsed.video.durationInFrames);
+    });
+    return {
+      version: "2.0",
+      video: parsed.video,
+      audio: parsed.audio,
+      timeline: timeline2
+    };
+  }
+  const segments = parsed.segments ?? [];
+  const timeline = [];
+  let start = 0;
+  let pendingEnter;
+  for (let i = 0; i < segments.length; i++) {
+    const seg = segments[i];
+    const hasNext = i < segments.length - 1;
+    const exit = hasNext ? seg.transitionToNext : void 0;
+    const enter = pendingEnter;
+    const rootFilled = fillNodeTiming(seg.root, seg.durationInFrames);
+    timeline.push({
+      id: `segment:${seg.id}`,
+      type: "Segment",
+      timing: { from: start, durationInFrames: seg.durationInFrames },
+      props: {
+        enterTransition: enter,
+        exitTransition: exit
+      },
+      children: [rootFilled]
+    });
+    pendingEnter = exit;
+    const overlap = exit?.durationInFrames ?? 0;
+    start += seg.durationInFrames - overlap;
+  }
+  return {
+    version: "2.0",
+    video: parsed.video,
+    audio: parsed.audio,
+    timeline
+  };
+}
+
+// src/core/validator.ts
+var IRValidator = class {
+  constructor(registry) {
+    this.registry = registry;
+  }
+  validateSchema(ir) {
+    const result = VideoIRSchema.safeParse(ir);
+    if (!result.success) {
+      return {
+        success: false,
+        errors: result.error.issues.map((issue) => ({
+          path: issue.path.map((p) => String(p)),
+          message: issue.message,
+          code: issue.code
+        }))
+      };
+    }
+    return { success: true, data: result.data };
+  }
+  validateSemantics(latest) {
+    const errors = [];
+    if (latest.segments) {
+      for (const [i, seg] of latest.segments.entries()) {
+        const exit = seg.transitionToNext;
+        const overlap = exit?.durationInFrames ?? 0;
+        if (exit && i === latest.segments.length - 1) {
+          errors.push({
+            path: ["segments", String(i), "transitionToNext"],
+            message: "transitionToNext is not allowed on the last segment",
+            code: "TRANSITION_ON_LAST_SEGMENT"
+          });
+          continue;
+        }
+        if (overlap > 0 && i < latest.segments.length - 1) {
+          const next = latest.segments[i + 1];
+          if (overlap > seg.durationInFrames) {
+            errors.push({
+              path: ["segments", String(i), "transitionToNext", "durationInFrames"],
+              message: `Transition overlap (${overlap}) exceeds segment duration (${seg.durationInFrames})`,
+              code: "TRANSITION_OVERLAP_TOO_LARGE"
+            });
+          }
+          if (overlap > next.durationInFrames) {
+            errors.push({
+              path: ["segments", String(i + 1), "durationInFrames"],
+              message: `Transition overlap (${overlap}) exceeds next segment duration (${next.durationInFrames})`,
+              code: "TRANSITION_OVERLAP_TOO_LARGE"
+            });
+          }
+        }
+      }
+    }
+    const compiled = compileToRenderGraph(latest);
+    const maxEnd = getMaxEnd(compiled.timeline);
+    if (maxEnd !== compiled.video.durationInFrames) {
+      errors.push({
+        path: ["video", "durationInFrames"],
+        message: `Max timeline end (${maxEnd}) does not match video duration (${compiled.video.durationInFrames})`,
+        code: "DURATION_MISMATCH"
+      });
+    }
+    for (const [i, root] of compiled.timeline.entries()) {
+      const end = root.timing.from + root.timing.durationInFrames;
+      if (root.timing.from < 0 || root.timing.durationInFrames <= 0) {
+        errors.push({
+          path: ["timeline", String(i), "timing"],
+          message: "Timing must have from>=0 and durationInFrames>0",
+          code: "INVALID_TIMING"
+        });
+      }
+      if (end > compiled.video.durationInFrames) {
+        errors.push({
+          path: ["timeline", String(i), "timing"],
+          message: `Root node exceeds video duration (${end} > ${compiled.video.durationInFrames})`,
+          code: "COMPONENT_EXCEEDS_VIDEO"
+        });
+      }
+      if (root.children?.length) {
+        this.validateComponentTimingRecursive(root.children, root.timing.durationInFrames, ["timeline", String(i)], errors);
+      }
+    }
+    if (this.registry) {
+      this.validateRegistryContracts(compiled, errors);
+    }
+    if (errors.length > 0) {
+      return { success: false, errors };
+    }
+    return { success: true, data: compiled };
+  }
+  validate(ir) {
+    const schemaResult = this.validateSchema(ir);
+    if (!schemaResult.success) {
+      return schemaResult;
+    }
+    const semanticsResult = this.validateSemantics(schemaResult.data);
+    if (!semanticsResult.success) {
+      return { success: false, errors: semanticsResult.errors ?? [] };
+    }
+    return semanticsResult;
+  }
+  validateComponentTimingRecursive(components, parentDuration, pathPrefix, errors) {
+    for (const [i, component] of components.entries()) {
+      const componentEnd = component.timing.from + component.timing.durationInFrames;
+      if (componentEnd > parentDuration) {
+        errors.push({
+          path: [...pathPrefix, "children", String(i), "timing"],
+          message: `Component extends beyond parent duration (${componentEnd} > ${parentDuration})`,
+          code: "COMPONENT_EXCEEDS_PARENT"
+        });
+      }
+      if (component.children && component.children.length > 0) {
+        this.validateComponentTimingRecursive(
+          component.children,
+          component.timing.durationInFrames,
+          [...pathPrefix, "children", String(i)],
+          errors
+        );
+      }
+    }
+  }
+  validateRegistryContracts(compiled, errors) {
+    const registry = this.registry;
+    const stack = compiled.timeline.map((n, i) => ({
+      node: n,
+      path: ["timeline", String(i)]
+    }));
+    while (stack.length) {
+      const { node, path: path2 } = stack.pop();
+      const reg = registry.get(node.type);
+      if (!reg) {
+        errors.push({
+          path: [...path2, "type"],
+          message: `Unknown component type: ${node.type}`,
+          code: "UNKNOWN_COMPONENT_TYPE"
+        });
+        continue;
+      }
+      const rawProps = node.props ?? {};
+      if (rawProps === null || typeof rawProps !== "object") {
+        errors.push({
+          path: [...path2, "props"],
+          message: "Component props must be an object",
+          code: "PROPS_NOT_OBJECT"
+        });
+      } else {
+        const propsValidation = registry.validateProps(node.type, rawProps);
+        if (!propsValidation.success) {
+          for (const issue of propsValidation.error.issues) {
+            errors.push({
+              path: [...path2, "props", ...issue.path.map((p) => String(p))],
+              message: issue.message,
+              code: "PROPS_INVALID"
+            });
+          }
+        } else {
+          node.props = propsValidation.data;
+        }
+      }
+      const childCount = node.children?.length ?? 0;
+      const meta = reg.metadata;
+      const acceptsChildren = Boolean(meta.acceptsChildren);
+      if (childCount > 0 && !acceptsChildren) {
+        errors.push({
+          path: [...path2, "children"],
+          message: `Component type "${node.type}" does not accept children`,
+          code: "CHILDREN_NOT_ALLOWED"
+        });
+      }
+      if (typeof meta.minChildren === "number" && childCount < meta.minChildren) {
+        errors.push({
+          path: [...path2, "children"],
+          message: `Component requires at least ${meta.minChildren} children`,
+          code: "TOO_FEW_CHILDREN"
+        });
+      }
+      if (typeof meta.maxChildren === "number" && childCount > meta.maxChildren) {
+        errors.push({
+          path: [...path2, "children"],
+          message: `Component allows at most ${meta.maxChildren} children`,
+          code: "TOO_MANY_CHILDREN"
+        });
+      }
+      if (node.children?.length) {
+        for (let i = 0; i < node.children.length; i++) {
+          stack.push({ node: node.children[i], path: [...path2, "children", String(i)] });
+        }
+      }
+    }
+  }
+};
+function getMaxEnd(nodes) {
+  let max = 0;
+  const stack = [...nodes];
+  while (stack.length) {
+    const n = stack.pop();
+    const end = n.timing.from + n.timing.durationInFrames;
+    if (end > max) max = end;
+    if (n.children?.length) stack.push(...n.children);
+  }
+  return max;
+}
+
+// src/core/engine.ts
+import { bundle } from "@remotion/bundler";
+import { renderMedia, selectComposition } from "@remotion/renderer";
+import fs from "fs/promises";
+import path from "path";
+var WavesEngine = class {
+  constructor(registry, validator) {
+    this.registry = registry;
+    this.validator = validator;
+  }
+  async render(ir, options) {
+    if (this.registry !== globalRegistry) {
+      throw new WavesRenderError("WavesEngine currently requires using globalRegistry", {
+        hint: "Use `registerBuiltInComponents()` + `globalRegistry` for both validation and rendering."
+      });
+    }
+    const validationResult = this.validator.validate(ir);
+    if (!validationResult.success) {
+      throw new WavesRenderError("IR validation failed", { errors: validationResult.errors });
+    }
+    const validatedIR = validationResult.data;
+    const requiredTypes = collectComponentTypes(validatedIR);
+    for (const type of requiredTypes) {
+      if (!this.registry.has(type)) {
+        throw new WavesRenderError("Unknown component type", { type });
+      }
+    }
+    const rootDir = options.rootDir ?? process.cwd();
+    const tmpDir = await fs.mkdtemp(path.join(rootDir, ".waves-tmp-"));
+    const entryPoint = path.join(tmpDir, "entry.tsx");
+    try {
+      await fs.writeFile(entryPoint, generateEntryPoint(validatedIR, options), "utf-8");
+      await fs.mkdir(path.dirname(options.outputPath), { recursive: true });
+      const bundleLocation = await bundle({
+        entryPoint,
+        rootDir,
+        publicDir: options.publicDir ?? null,
+        onProgress: () => void 0
+      });
+      const compositionId = validatedIR.video.id ?? "main";
+      const composition = await selectComposition({
+        serveUrl: bundleLocation,
+        id: compositionId,
+        inputProps: {}
+      });
+      await renderMedia({
+        composition,
+        serveUrl: bundleLocation,
+        codec: options.codec ?? "h264",
+        outputLocation: options.outputPath,
+        crf: options.crf ?? null,
+        concurrency: options.concurrency ?? null,
+        overwrite: true
+      });
+    } catch (error) {
+      throw new WavesRenderError("Rendering failed", { originalError: error });
+    } finally {
+      await fs.rm(tmpDir, { recursive: true, force: true });
+    }
+  }
+};
+function collectComponentTypes(ir) {
+  const types = /* @__PURE__ */ new Set();
+  for (const node of ir.timeline) {
+    walkComponent(node, types);
+  }
+  return types;
+}
+function walkComponent(component, types) {
+  types.add(component.type);
+  const children = component.children;
+  if (children) {
+    for (const child of children) {
+      walkComponent(child, types);
+    }
+  }
+}
+function generateEntryPoint(ir, options) {
+  const compositionId = ir.video.id ?? "main";
+  const width = ir.video.width;
+  const height = ir.video.height;
+  const fps = ir.video.fps ?? 30;
+  const durationInFrames = ir.video.durationInFrames;
+  const registrationImports = (options.registrationModules ?? []).map((m) => `import ${JSON.stringify(m)};`).join("\n");
+  return `import React from 'react';
+import { Composition, registerRoot } from 'remotion';
+import { WavesComposition, globalRegistry, registerBuiltInComponents } from '@depths/waves/remotion';
+${registrationImports}
+
+registerBuiltInComponents();
+
+const ir = ${JSON.stringify(ir, null, 2)};
+const compositionId = ${JSON.stringify(compositionId)};
+
+const Root = () => {
+  return <WavesComposition ir={ir} registry={globalRegistry} />;
+};
+
+export const RemotionRoot = () => {
+  return (
+    <Composition
+      id={compositionId}
+      component={Root}
+      durationInFrames={${durationInFrames}}
+      fps={${fps}}
+      width={${width}}
+      height={${height}}
+    />
+  );
+};
+
+registerRoot(RemotionRoot);
+`;
+}
+
+export {
+  __wavesVersion,
+  getSystemPrompt,
+  getPromptPayload,
+  IRValidator,
+  WavesEngine
+};