@depths/waves 0.2.0 → 0.3.0

package/README.md

@@ -1,4 +1,4 @@
-# @depths/waves (v0.2.0)
+# @depths/waves (v0.3.0)
 
 `@depths/waves` is a TypeScript-first library + CLI for rendering videos from a JSON "intermediate representation" (IR) using Remotion.
 
@@ -8,11 +8,18 @@ The intended workflow is:
 2. The IR is validated (schema + semantics + registry contracts).
 3. The IR is rendered to an output video file (MP4 by default) using Remotion.
 
-v0.2.0 adds a shadcn-like catalog of higher-level "composite" components and a hybrid IR that supports:
+v0.2.0 introduced a shadcn-like catalog of higher-level "composite" components and a hybrid IR that supports:
 
 - **Segments (recommended for agents):** sequential scenes with optional overlaps ("transitions")
 - **Timeline (escape hatch):** explicit timed nodes with overlaps allowed
 
+v0.3.0 focuses on **seamless alignment + overlays**:
+
+- **Layout-safe primitives:** components that use normal layout flow by default (no accidental `position: absolute`)
+- **Explicit layering primitives:** `Layers` + `Layer` for deterministic overlays (z-index, inset, opacity)
+- **Explicit positioning primitive:** `Frame` for deliberate `x/y/width/height` placement (breaking change: `Box` no longer supports `x/y`)
+- **Visual debugging workflow:** `waves stills` and `--debugBounds/--debugLabels` to inspect alignment issues without pixel tests
+
 ## Table of contents
 
 - [Concept (end-to-end)](#concept-end-to-end)
@@ -62,7 +69,7 @@ At render time, Waves is "just React + Remotion". The strictness lives earlier (
 The codebase has a small number of core concepts:
 
 - **Video IR (`VideoIRSchema`)**: the JSON document format you author.
-  - v0.2.0 targets `version: "2.0"` only.
+  - v0.3.0 targets `version: "2.0"` only.
   - You author exactly one of `segments[]` (recommended) or `timeline[]` (escape hatch).
 - **Component Registry (`ComponentRegistry`)**: a map from string `type` -> React component + Zod props schema + metadata.
   - Only registered components can render.
@@ -388,6 +395,8 @@ Flags:
 - `--codec h264|h265|vp8|vp9` (optional; default `h264`)
 - `--crf <n>` (optional; forwarded to Remotion renderer)
 - `--concurrency <n|string>` (optional; forwarded to Remotion renderer)
+- `--debugBounds` (optional; draws debug outlines for every rendered node)
+- `--debugLabels` (optional; labels debug outlines with `type#id`)
 - `--register <module>` (repeatable)
 - `--pretty` (only affects the formatting of error JSON when render fails)
 
@@ -396,11 +405,35 @@ Examples:
 ```bash
 npx waves render --in ./video.v2.json --out ./output.mp4 --codec h264 --crf 28 --concurrency 1
 npx waves render --in ./video.v2.json --out ./output.mp4 --publicDir ./public
+npx waves render --in ./video.v2.json --out ./output.mp4 --publicDir ./public --debugBounds --debugLabels
+```
+
+#### `waves stills`
+
+Renders a set of still images (single frames) from an IR JSON file. This is the recommended way to iterate on alignment and overlays without re-rendering full MP4s.
+
+Flags:
+
+- `--in <path>` (required)
+- `--outDir <path>` (required)
+- `--frames <csv>` (required; e.g. `"0,30,60"`)
+- `--publicDir <path>` (optional; required if your IR uses `/assets/...` paths)
+- `--imageFormat png|jpeg|webp` (optional; default `png`)
+- `--scale <n>` (optional; default `1`)
+- `--jpegQuality <n>` (optional; default `90`; only used when `--imageFormat jpeg`)
+- `--debugBounds` / `--debugLabels` (same as `waves render`)
+- `--register <module>` (repeatable)
+
+Examples:
+
+```bash
+npx waves stills --in ./video.v2.json --outDir ./examples/_stills --frames "0,45,90" --publicDir ./public
+npx waves stills --in ./video.v2.json --outDir ./examples/_stills --frames "0,45,90" --publicDir ./public --debugBounds --debugLabels
 ```
 
 ## IR v2.0 (authoring contract)
 
-v0.2.0 targets `version: "2.0"` only.
+v0.3.0 targets `version: "2.0"` only.
 
 ### Recommended: `segments[]` (high-level)
 
@@ -559,10 +592,13 @@ node scripts/generate-readme-components.mjs
 | `ImageSequence` | composite | image | no | no | Plays a numbered image sequence (frame-by-frame) |
 | `ImageWithCaption` | composite | image | no | no | Image with a caption strip (top/bottom) or overlay caption |
 | `KenBurnsImage` | composite | image | no | no | Slow zoom and pan (Ken Burns effect) for a still image |
-| `Box` | primitive | layout | yes | no | Positioned container box for layout and backgrounds |
+| `Box` | primitive | layout | yes | no | Flow container for layout and backgrounds (layout-safe) |
 | `CardStack` | composite | layout | no | no | Sequential stacked cards (2-5) with flip/slide/fade transitions |
+| `Frame` | primitive | layout | yes | no | Absolute-positioned container (x/y placement) |
 | `Grid` | primitive | layout | yes | no | Grid layout container with configurable rows/columns |
 | `GridLayout` | composite | layout | yes (1..∞) | no | Simple responsive grid layout for child components |
+| `Layer` | primitive | layout | yes (1..∞) | no | One overlay layer with explicit zIndex inside Layers |
+| `Layers` | primitive | layout | yes (1..∞) | no | Overlay container for stacking children (use Layer for zIndex) |
 | `Scene` | primitive | layout | yes | no | Scene container with a background and nested children |
 | `Segment` | primitive | layout | yes (1..1) | yes | Internal segment wrapper (used by v2 segments compiler) |
 | `Shape` | primitive | layout | no | no | Simple rect/circle shape for UI accents |
@@ -893,8 +929,8 @@ Props:
 - category: `layout`
 - internal: `false`
 - children: `yes`
-- description: Positioned container box for layout and backgrounds
-- llmGuidance: Use Box to position content by x/y and optionally constrain width/height. Prefer Box+Stack/Grid for layouts.
+- description: Flow container for layout and backgrounds (layout-safe)
+- llmGuidance: Use Box as a container inside Grid/Stack. Box participates in layout flow. For x/y positioning, use Frame.
 
 Props:
 
@@ -906,8 +942,6 @@ Props:
 | `opacity` | number | yes | 1 | min=0, max=1 |
 | `padding` | number | yes | 0 | min=0 |
 | `width` | number | no |  |  |
-| `x` | number | yes | 0 |  |
-| `y` | number | yes | 0 |  |
 
 ##### `CardStack`
 
@@ -926,6 +960,28 @@ Props:
 | `displayDuration` | integer | yes | 90 | min=30, max=150 |
 | `transition` | enum("flip" \| "slide" \| "fade") | yes | "flip" |  |
 
+##### `Frame`
+
+- kind: `primitive`
+- category: `layout`
+- internal: `false`
+- children: `yes`
+- description: Absolute-positioned container (x/y placement)
+- llmGuidance: Use Frame for precise pixel placement (x/y). Use Box for normal layout flow inside Grid/Stack.
+
+Props:
+
+| Prop | Type | Required | Default | Notes |
+| - | - | - | - | - |
+| `backgroundColor` | string | no |  |  |
+| `borderRadius` | number | yes | 0 | min=0 |
+| `height` | number | no |  |  |
+| `opacity` | number | yes | 1 | min=0, max=1 |
+| `padding` | number | yes | 0 | min=0 |
+| `width` | number | no |  |  |
+| `x` | number | yes | 0 |  |
+| `y` | number | yes | 0 |  |
+
 ##### `Grid`
 
 - kind: `primitive`
@@ -964,6 +1020,39 @@ Props:
 | `padding` | number | yes | 40 | min=0, max=100 |
 | `rows` | integer | yes | 2 | min=1, max=4 |
 
+##### `Layer`
+
+- kind: `primitive`
+- category: `layout`
+- internal: `false`
+- children: `yes (1..∞)`
+- description: One overlay layer with explicit zIndex inside Layers
+- llmGuidance: Use Layer inside Layers to control stacking. Put exactly one child in a Layer (recommended).
+
+Props:
+
+| Prop | Type | Required | Default | Notes |
+| - | - | - | - | - |
+| `inset` | number | yes | 0 | min=0 |
+| `opacity` | number | yes | 1 | min=0, max=1 |
+| `pointerEvents` | enum("none" \| "auto") | yes | "none" |  |
+| `zIndex` | integer | yes | 0 | min=-9007199254740991, max=9007199254740991 |
+
+##### `Layers`
+
+- kind: `primitive`
+- category: `layout`
+- internal: `false`
+- children: `yes (1..∞)`
+- description: Overlay container for stacking children (use Layer for zIndex)
+- llmGuidance: Use Layers to stack background/content/overlays. Prefer Layer children with explicit zIndex.
+
+Props:
+
+| Prop | Type | Required | Default | Notes |
+| - | - | - | - | - |
+| `overflow` | enum("visible" \| "hidden") | yes | "visible" |  |
+
 ##### `Scene`
 
 - kind: `primitive`
@@ -1174,7 +1263,9 @@ Props:
 | `color` | string | yes | "#FFFFFF" |  |
 | `fontSize` | number | yes | 48 | min=12, max=120 |
 | `highlightStyle` | enum("word" \| "bounce" \| "none") | yes | "word" |  |
+| `maxWidthPct` | number | yes | 0.92 | min=0.1, max=1 |
 | `position` | enum("center" \| "bottom") | yes | "center" |  |
+| `safeInsetPct` | number | yes | 0.06 | min=0, max=0.25 |
 | `strokeColor` | string | yes | "#000000" |  |
 | `strokeWidth` | number | yes | 3 | min=0, max=10 |
 | `text` | string | yes |  | maxLength=150 |
@@ -1329,7 +1420,9 @@ Props:
 | `content` | string | yes |  | maxLength=200 |
 | `fontFamily` | string | yes | "Inter" |  |
 | `fontSize` | number | yes | 48 | min=8, max=200 |
+| `maxWidthPct` | number | yes | 0.9 | min=0.1, max=1 |
 | `position` | enum("top" \| "center" \| "bottom") | yes | "center" |  |
+| `safeInsetPct` | number | yes | 0.06 | min=0, max=0.25 |
 | `splitBy` | enum("word" \| "letter") | yes | "word" |  |
 | `stagger` | integer | yes | 3 | min=1, max=10 |
 
@@ -1372,8 +1465,12 @@ Props:
 | `animation` | enum("none" \| "fade" \| "slide" \| "zoom") | yes | "fade" |  |
 | `color` | string | yes | "#FFFFFF" |  |
 | `content` | string | yes |  |  |
+| `fontFamily` | string | yes | "Inter" |  |
 | `fontSize` | number | yes | 48 |  |
+| `maxWidthPct` | number | yes | 0.9 | min=0.1, max=1 |
 | `position` | enum("top" \| "center" \| "bottom" \| "left" \| "right") | yes | "center" |  |
+| `safeInsetPct` | number | yes | 0.06 | min=0, max=0.25 |
+| `textAlign` | enum("left" \| "center" \| "right") | yes | "center" |  |
 
 ##### `TypewriterText`
 
@@ -1393,7 +1490,9 @@ Props:
 | `cursorColor` | string | yes | "#FFFFFF" |  |
 | `fontFamily` | string | yes | "Inter" |  |
 | `fontSize` | number | yes | 48 | min=8, max=200 |
+| `maxWidthPct` | number | yes | 0.9 | min=0.1, max=1 |
 | `position` | enum("top" \| "center" \| "bottom") | yes | "center" |  |
+| `safeInsetPct` | number | yes | 0.06 | min=0, max=0.25 |
 | `showCursor` | boolean | yes | true |  |
 | `speed` | number | yes | 2 | min=0.5, max=5 |
 
@@ -1557,7 +1656,7 @@ This is the default starter IR used by `waves write-ir --template basic`. It dem
             "id": "title",
             "type": "SplitText",
             "props": {
-              "content": "Waves v0.2.0",
+              "content": "Waves v0.3.0",
               "fontSize": 96,
               "splitBy": "word",
               "stagger": 3,
@@ -1568,7 +1667,7 @@ This is the default starter IR used by `waves write-ir --template basic`. It dem
             "id": "subtitle",
             "type": "TypewriterText",
             "props": {
-              "content": "Composite components + hybrid IR",
+              "content": "Seamless alignment + overlays",
               "fontSize": 48,
               "position": "bottom",
               "speed": 1.5
@@ -1601,7 +1700,7 @@ This is the default starter IR used by `waves write-ir --template basic`. It dem
           {
             "id": "lower-third",
             "type": "ThirdLowerBanner",
-            "props": { "name": "Waves", "title": "v0.2.0 - Composites + transitions", "accentColor": "#3B82F6" }
+            "props": { "name": "Waves", "title": "v0.3.0 - Alignment + overlays", "accentColor": "#3B82F6" }
           },
           {
             "id": "count",
@@ -1642,7 +1741,7 @@ This example uses only primitives: `Scene`, `Box`, `Grid`, `Shape`, `Text`.
           { "id": "accent", "type": "Shape", "props": { "shape": "rect", "x": 180, "y": 200, "width": 12, "height": 680, "fill": "#3B82F6", "opacity": 1 } },
           {
             "id": "panel",
-            "type": "Box",
+            "type": "Frame",
             "props": { "x": 192, "y": 200, "width": 1548, "height": 680, "padding": 0, "backgroundColor": "rgba(255,255,255,0.06)", "borderRadius": 36, "opacity": 1 },
             "children": [
               {
@@ -1653,7 +1752,7 @@ This example uses only primitives: `Scene`, `Box`, `Grid`, `Shape`, `Text`.
                   {
                     "id": "tile-1",
                     "type": "Box",
-                    "props": { "x": 0, "y": 0, "padding": 40, "backgroundColor": "rgba(255,255,255,0.07)", "borderRadius": 24 },
+                    "props": { "padding": 40, "backgroundColor": "rgba(255,255,255,0.07)", "borderRadius": 24 },
                     "children": [
                       { "id": "t1", "type": "Text", "props": { "content": "Primitives", "fontSize": 64, "position": "center", "animation": "fade" } }
                     ]
@@ -1661,7 +1760,7 @@ This example uses only primitives: `Scene`, `Box`, `Grid`, `Shape`, `Text`.
                   {
                     "id": "tile-2",
                     "type": "Box",
-                    "props": { "x": 0, "y": 0, "padding": 40, "backgroundColor": "rgba(255,255,255,0.07)", "borderRadius": 24 },
+                    "props": { "padding": 40, "backgroundColor": "rgba(255,255,255,0.07)", "borderRadius": 24 },
                     "children": [
                       { "id": "t2", "type": "Text", "props": { "content": "Box + Grid", "fontSize": 54, "position": "center", "animation": "slide" } }
                     ]
@@ -1669,7 +1768,7 @@ This example uses only primitives: `Scene`, `Box`, `Grid`, `Shape`, `Text`.
                   {
                     "id": "tile-3",
                     "type": "Box",
-                    "props": { "x": 0, "y": 0, "padding": 40, "backgroundColor": "rgba(255,255,255,0.07)", "borderRadius": 24 },
+                    "props": { "padding": 40, "backgroundColor": "rgba(255,255,255,0.07)", "borderRadius": 24 },
                     "children": [
                       { "id": "t3", "type": "Text", "props": { "content": "Shape", "fontSize": 54, "position": "center", "animation": "zoom" } }
                     ]
@@ -1677,7 +1776,7 @@ This example uses only primitives: `Scene`, `Box`, `Grid`, `Shape`, `Text`.
                   {
                     "id": "tile-4",
                     "type": "Box",
-                    "props": { "x": 0, "y": 0, "padding": 40, "backgroundColor": "rgba(255,255,255,0.07)", "borderRadius": 24 },
+                    "props": { "padding": 40, "backgroundColor": "rgba(255,255,255,0.07)", "borderRadius": 24 },
                     "children": [
                       { "id": "t4", "type": "Text", "props": { "content": "Text", "fontSize": 54, "position": "center", "animation": "fade" } }
                     ]
@@ -1885,7 +1984,7 @@ This example uses:
         "type": "Scene",
         "props": { "background": { "type": "color", "value": "#000000" } },
         "children": [
-          { "id": "ig", "type": "InstagramStory", "props": { "backgroundColor": "#0B1220", "username": "depths.ai", "text": "Waves v0.2.0 ships composites + hybrid IR", "sticker": "poll" } }
+          { "id": "ig", "type": "InstagramStory", "props": { "backgroundColor": "#0B1220", "username": "depths.ai", "text": "Waves v0.3.0 ships seamless alignment + overlays", "sticker": "poll" } }
         ]
       }
     },
@@ -1932,7 +2031,7 @@ It references `/assets/logo.svg` style paths; supply those files and pass `--pub
         "type": "Scene",
         "props": { "background": { "type": "color", "value": "#000000" } },
         "children": [
-          { "id": "intro", "type": "IntroScene", "props": { "logoSrc": "/assets/logo.svg", "companyName": "Depths AI", "tagline": "Waves v0.2.0", "backgroundColor": "#000000", "primaryColor": "#FFFFFF" } }
+          { "id": "intro", "type": "IntroScene", "props": { "logoSrc": "/assets/logo.svg", "companyName": "Depths AI", "tagline": "Waves v0.3.0", "backgroundColor": "#000000", "primaryColor": "#FFFFFF" } }
         ]
       }
     },

package/dist/{chunk-7QPNRHMW.mjs → chunk-QP54QRAP.mjs}

@@ -6,7 +6,7 @@ import {
   globalRegistry,
   registerBuiltInComponents,
   zodSchemaToJsonSchema
-} from "./chunk-PKLHVWMD.mjs";
+} from "./chunk-YYS6AVTN.mjs";
 
 // src/version.ts
 var __wavesVersion = "0.2.0";
@@ -362,7 +362,7 @@ function getMaxEnd(nodes) {
 
 // src/core/engine.ts
 import { bundle } from "@remotion/bundler";
-import { renderMedia, selectComposition } from "@remotion/renderer";
+import { renderMedia, renderStill, selectComposition } from "@remotion/renderer";
 import fs from "fs/promises";
 import path from "path";
 var WavesEngine = class {
@@ -400,14 +400,16 @@ var WavesEngine = class {
         onProgress: () => void 0
       });
       const compositionId = validatedIR.video.id ?? "main";
+      const inputProps = options.inputProps ?? {};
       const composition = await selectComposition({
         serveUrl: bundleLocation,
         id: compositionId,
-        inputProps: {}
+        inputProps
       });
       await renderMedia({
         composition,
         serveUrl: bundleLocation,
+        inputProps,
         codec: options.codec ?? "h264",
         outputLocation: options.outputPath,
         crf: options.crf ?? null,
@@ -420,6 +422,70 @@ var WavesEngine = class {
       await fs.rm(tmpDir, { recursive: true, force: true });
     }
   }
+  async renderStills(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(options.outputDir, { recursive: true });
+      const bundleLocation = await bundle({
+        entryPoint,
+        rootDir,
+        publicDir: options.publicDir ?? null,
+        onProgress: () => void 0
+      });
+      const compositionId = validatedIR.video.id ?? "main";
+      const inputProps = options.inputProps ?? {};
+      const composition = await selectComposition({
+        serveUrl: bundleLocation,
+        id: compositionId,
+        inputProps
+      });
+      const frames = Array.from(new Set(options.frames)).sort((a, b) => a - b);
+      const written = [];
+      for (const frame of frames) {
+        const clamped = Math.max(0, Math.min(composition.durationInFrames - 1, Math.floor(frame)));
+        const imageFormat = options.imageFormat ?? "png";
+        const filename = `${compositionId}-frame-${String(clamped).padStart(6, "0")}.${imageFormat}`;
+        const outPath = path.join(options.outputDir, filename);
+        const stillOptions = {
+          composition,
+          serveUrl: bundleLocation,
+          inputProps,
+          frame: clamped,
+          output: outPath,
+          imageFormat,
+          scale: options.scale ?? 1,
+          overwrite: true,
+          ...imageFormat === "jpeg" ? { jpegQuality: options.jpegQuality ?? 80 } : {}
+        };
+        await renderStill(stillOptions);
+        written.push(outPath);
+      }
+      return written;
+    } 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();
@@ -454,8 +520,10 @@ registerBuiltInComponents();
 const ir = ${JSON.stringify(ir, null, 2)};
 const compositionId = ${JSON.stringify(compositionId)};
 
-const Root = () => {
-  return <WavesComposition ir={ir} registry={globalRegistry} />;
+const Root = (props) => {
+  const debugBounds = Boolean(props?.__wavesDebugBounds);
+  const debugLabels = Boolean(props?.__wavesDebugLabels);
+  return <WavesComposition ir={ir} registry={globalRegistry} debug={{ bounds: debugBounds, labels: debugLabels }} />;
 };
 
 export const RemotionRoot = () => {